Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/config.jsonc
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@
"ci": {
"local": {
"cloudOnly": {
"release.yml": "publishes @lntt/create to npm with the OIDC token of a published GitHub Release",
"release.yml": "publishes the @lntt packages to npm with the OIDC token of a published GitHub Release",
"candidate.yml": "moves pull requests and edits the candidate with the GitHub App's token"
}
}
Expand Down
19 changes: 13 additions & 6 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ name: Release the @lntt packages
# gh release create vX.Y.Z --generate-notes
# Every published package under packages/ shares one version, and the tag must match
# it (docs/process/delivery.md). A release marked as pre-release is a dry run: every
# check runs and `npm publish --dry-run` packs each package, nothing reaches npm.
# check runs, pnpm packs each package and `npm publish --dry-run` reads the
# tarball, nothing reaches npm.
on:
release:
types: [published]
Expand Down Expand Up @@ -46,13 +47,16 @@ jobs:
SCAFFOLD_SMOKE: '1'

# Auth is OIDC via the trusted publisher configured on npmjs.com for each
# package, this repo and this workflow: no NPM_TOKEN secret. `prepack` builds
# what ships compiled (docs/adr/cli-runtime-and-publishing.md); --provenance is
# automatic under trusted publishing. A version already on npm is skipped, so a
# run that failed half-way can be re-run.
# package, this repo and this workflow: no NPM_TOKEN secret. Each package is
# packed by pnpm, which runs `prepack` (it builds what ships compiled) and applies
# publishConfig's `bin` and `exports`, pointing a package the repo runs from
# source at dist/ (docs/adr/cli-runtime-and-publishing.md); npm publishes the
# tarball. --provenance is automatic under trusted publishing. A version already
# on npm is skipped, so a run that failed half-way can be re-run.
- name: Publish
run: |
VERSION="${GITHUB_REF_NAME#v}"
tarballs="$RUNNER_TEMP/tarballs"
# On its own line: a failing list inside `for … in $(…)` would publish
# nothing and leave the step green.
dirs="$(node scripts/packages-version.mts list)"
Expand All @@ -62,6 +66,9 @@ jobs:
echo "$name@$VERSION is already on npm: skipped"
continue
fi
rm -rf "$tarballs" && mkdir -p "$tarballs"
(cd "$dir" && pnpm pack --pack-destination "$tarballs")
# An absolute path: npm reads a bare file name as a git spec.
# shellcheck disable=SC2086 # DRY_RUN holds several flags, or none
(cd "$dir" && npm publish --provenance --access public $DRY_RUN)
npm publish "$(ls "$tarballs"/*.tgz)" --provenance --access public $DRY_RUN
done
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,9 @@ it by itself in a folder it already trusts.

What every project must keep current lives in `packages/`, to be published by the
release flow and consumed by version: `@lntt/biome-config`, `@lntt/typescript-config`,
`@lntt/stylelint-config`, `@lntt/playwright-config`, `@lntt/test-utils`. The CLI never
rewrites the `@lntt` scope ([scaffolding contract](./docs/adr/scaffolding-contract.md)).
`@lntt/stylelint-config`, `@lntt/playwright-config`, `@lntt/test-utils`, and the
`lntt` command, `@lntt/lntt`. The CLI never rewrites the `@lntt` scope
([scaffolding contract](./docs/adr/scaffolding-contract.md)).
Each package's README says how a project installs and uses it.

## Develop
Expand Down
31 changes: 23 additions & 8 deletions docs/adr/cli-runtime-and-publishing.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,16 +47,24 @@ it ships:

The packages published from `packages/` besides the CLI follow the same rule.

- **A package whose code Node runs** (`@lntt/playwright-config`, `@lntt/test-utils`)
is authored in TypeScript and published compiled: `tsconfig.build.json` emits
`src/` to `dist/` with declarations, `exports` and `bin` point at `dist/`,
`prepack` builds, `files` ships `dist`. Its tests import the sources, and at least
one imports it by name from a `node_modules`, built.
- **A package whose code Node runs** (`@lntt/playwright-config`, `@lntt/test-utils`,
`@lntt/lntt`) is authored in TypeScript and published compiled: `tsconfig.build.json`
emits its sources to `dist/` with declarations, the published `exports` and `bin`
point at `dist/`, `prepack` builds, `files` ships `dist`. Files its code reads at run
time ship next to it (`@lntt/lntt` copies `agents/` to `dist/agents`). Its tests
import the sources, and at least one imports it by name from a `node_modules`, built.
- **A package this repo runs from source through the workspace** (`@lntt/lntt`: the
root's `lntt`, the git hooks, `commitlint.config.mjs`, the CI workflows) keeps
`bin` and `exports` on its `.ts` sources and declares the published ones, on
`dist/`, in `publishConfig`. pnpm applies those overrides when it packs; npm does
not, so the release packs every package with `pnpm pack` and publishes the tarball
with `npm publish`.
- **A config package** (`@lntt/biome-config`, `@lntt/typescript-config`,
`@lntt/stylelint-config`) ships its files as they are, listed in `files` and
`exports`.
- **The tool a package configures is a peer dependency** (`@biomejs/biome`,
`typescript`, `stylelint`, `@playwright/test`): the project installs it once, at
`typescript`, `stylelint`, `@playwright/test`, `@commitlint/config-conventional`
for `@lntt/lntt`'s commitlint configuration): the project installs it once, at
the version it chooses within the range.
- **Tests consume a package by its published name** from a `node_modules`, the way a
project does. The scaffold smoke installs every published package from its
Expand All @@ -76,8 +84,8 @@ the whole set, which the template depends on as one.
- **Publishing is CI only**, from `.github/workflows/release.yml`, through npm OIDC
trusted publishing (`--provenance`, no npm token). A version already on npm is
skipped, so a failed run can be re-run.
- **A release marked as pre-release is a dry run**: every check, then
`npm publish --dry-run`; nothing reaches npm.
- **A release marked as pre-release is a dry run**: every check runs and nothing
reaches npm.
- **The one exception: a new package's first publish is by hand**, once, as a
`0.0.0` placeholder. npm configures a trusted publisher only on a package that
already exists (npm/cli#8544); the placeholder exists so the first CI release can
Expand Down Expand Up @@ -149,6 +157,13 @@ written for the projects; the divergence is intentional.
tool too, to run it; two declared copies at different versions mean two runners
(Playwright refuses a second `@playwright/test`) or a config validated against a
tool the project does not run.
- **`bin` and `exports` on `dist/` in the manifest itself**, for a package the repo
runs from source. Every in-repo use (the git hooks, commitlint, `pnpm exec lntt`
in CI) would need a build first, and a stale `dist/` would run instead of the code
under review.
- **`npm publish` of the package directory.** npm ignores `publishConfig.bin` and
`publishConfig.exports`, so it would publish the source entries, which fail under
`node_modules`.
- **A token for the first publish of a new package** (an npm automation token as a
repository secret, used once by the workflow). It puts a long-lived publish token
in the repository for a step that happens once per package, and npm still needs
Expand Down
10 changes: 8 additions & 2 deletions docs/process/delivery.md
Original file line number Diff line number Diff line change
Expand Up @@ -216,12 +216,14 @@ ends.
Publishing the GitHub Release starts `.github/workflows/release.yml`: it checks that
the tag is every package's version, runs lint, typecheck and the tests with the
scaffold smoke, and publishes each package through npm trusted publishing (OIDC,
`--provenance`, no npm token), skipping a version npm already has.
`--provenance`, no npm token), skipping a version npm already has. Each package is
packed with `pnpm pack`, so its `publishConfig` applies, and npm publishes the tarball.

**A dry run** is a pre-release: set a pre-release version on a branch
(`node scripts/packages-version.mts set X.Y.Z-rc.N`, commit, push), then
`gh release create vX.Y.Z-rc.N --prerelease --target <branch>`. The workflow runs every
check and `npm publish --dry-run`; nothing reaches npm. Delete the pre-release, its
check, packs each package and passes the tarball to `npm publish --dry-run`; nothing
reaches npm. Delete the pre-release, its
tag and the branch afterwards.

Promoting a pre-release to a full release publishes nothing: the promotion fires
Expand All @@ -233,6 +235,10 @@ because npm configures a trusted publisher only on a package that exists:
1. Publish a `0.0.0` placeholder from the package directory, logged in to npm with
publish rights on the `@lntt` scope:
`npm version 0.0.0 --no-git-tag-version && npm publish --access public && git checkout package.json`.
The placeholder only reserves the name and is never installed: published from the
directory, npm ignores `publishConfig.bin` and `publishConfig.exports`, so a package
that points its published `bin` and `exports` at `dist/` there ships its source
entries in the placeholder.
It is the only publish ever made from a machine
([CLI runtime and publishing](../adr/cli-runtime-and-publishing.md)); the version
set by the release bump is untouched.
Expand Down
10 changes: 10 additions & 0 deletions packages/create/test/scaffold-smoke.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,16 @@ const adopt: Record<string, () => void> = {
assert.equal(execFileSync('node', [probe], { cwd: app, encoding: 'utf8' }).trim(), 'http://localhost:4321')
rmSync(probe)
},
// The command the project's tooling and the plugin's skills call: the installed bin
// reads the configuration the scaffolder wrote.
'@lntt/lntt': () => {
const lntt = join(app, 'node_modules/.bin/lntt')
run(lntt, ['--help'], app)
assert.equal(
execFileSync(lntt, ['get', 'lunette.template'], { cwd: app, encoding: 'utf8' }).trim(),
'"react-router"',
)
},
}

// The packages a generated project installs from npm, installed here from the
Expand Down
21 changes: 21 additions & 0 deletions packages/lntt/LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 Lunette

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
13 changes: 11 additions & 2 deletions packages/lntt/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -464,5 +464,14 @@ CircleCI projects need the `circleci` CLI; container mode needs Docker and `act`

## Requirements

Node ≥ 24. The package is private and runs from source until it is published with the
other shared packages.
Node ≥ 24. A project installs it as a development dependency, with
`@commitlint/config-conventional` as a peer when its commitlint configuration uses
`commitlintConfig`:

```sh
pnpm add -D @lntt/lntt @commitlint/config-conventional
```

The configuration's `$schema` can point at the installed schema,
`node_modules/@lntt/lntt/schema/config.schema.json`. In the starter the package runs
from its sources through the workspace; the published package is compiled to `dist/`.
42 changes: 40 additions & 2 deletions packages/lntt/package.json
Original file line number Diff line number Diff line change
@@ -1,10 +1,16 @@
{
"name": "@lntt/lntt",
"version": "0.0.0",
"private": true,
"version": "0.6.1",
"description": "The lntt command: a Lunette project's configuration and operator profile, the managed block of AGENTS.md, the checks and reviews of a change, and its CI run on the local machine with the candidate automation",
"type": "module",
"license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/LunetteOrg/starter.git",
"directory": "packages/lntt"
},
"homepage": "https://github.com/LunetteOrg/starter/tree/main/packages/lntt#readme",
"bugs": "https://github.com/LunetteOrg/starter/issues",
"exports": {
".": "./src/index.ts",
"./ci": "./src/ci/index.ts",
Expand All @@ -14,20 +20,52 @@
"bin": {
"lntt": "bin/lntt.ts"
},
"files": [
"dist",
"schema"
],
"scripts": {
"build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && node -e \"require('node:fs').cpSync('agents','dist/agents',{recursive:true})\"",
"prepack": "pnpm run build",
"test": "node --test test/*.test.ts test/ci/*.test.ts",
"typecheck": "tsc --noEmit"
},
"engines": {
"node": ">=24"
},
"publishConfig": {
"access": "public",
"bin": {
"lntt": "dist/bin/lntt.js"
},
"exports": {
".": {
"types": "./dist/src/index.d.ts",
"default": "./dist/src/index.js"
},
"./ci": {
"types": "./dist/src/ci/index.d.ts",
"default": "./dist/src/ci/index.js"
},
"./schema.json": "./schema/config.schema.json",
"./operator-schema.json": "./schema/operator.schema.json"
}
},
"dependencies": {
"@actions/expressions": "0.3.61",
"@actions/workflow-parser": "0.3.61",
"ajv": "^8.20.0",
"jsonc-parser": "^3.3.1",
"yaml": "^2.9.1"
},
"peerDependencies": {
"@commitlint/config-conventional": "^21.2.0"
},
"peerDependenciesMeta": {
"@commitlint/config-conventional": {
"optional": true
}
},
"devDependencies": {
"@commitlint/config-conventional": "^21.2.0",
"@commitlint/lint": "^21.2.0",
Expand Down
6 changes: 6 additions & 0 deletions packages/lntt/src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,12 @@ export function main(args: string[]): void {

function run(command: string | undefined, key: string | undefined, raw: string | undefined): void {
switch (command) {
// Asked for, the usage is the answer: stdout, exit 0 (`npx @lntt/lntt --help`).
case '--help':
case '-h':
case 'help':
stdout.write(`${USAGE}\n`)
break
case 'path':
stdout.write(`${findConfig(cwd()).path}\n`)
break
Expand Down
8 changes: 8 additions & 0 deletions packages/lntt/test/config.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,14 @@ describe('the command line', () => {
test('a usage error exits 2', () => {
assert.equal(spawnSync('node', [BIN, 'frobnicate'], { cwd: root }).status, 2)
})

for (const ask of ['--help', '-h', 'help']) {
test(`${ask} prints the usage on stdout and exits 0, with no configuration`, () => {
const run = spawnSync('node', [BIN, ask], { cwd: root, encoding: 'utf8' })
assert.equal(run.status, 0)
assert.match(run.stdout, /^usage: lntt /)
})
}
})

describe('the local section', () => {
Expand Down
Loading
Loading