Skip to content

Commit 07f082e

Browse files
committed
docs(release): assert latest on the bootstrap with the registry's own definition, and pin every preparation trigger
A packument's dist-tags are an object with at least one key, latest (npm/registry REGISTRY-API.md), so a first publish carries latest whatever --tag asked for; the docs, the setup step, and the stable verdict's comment say so with that citation, replacing the two-outcome hedge. The bootstrap step gains the dist-tag check and drops the prepare script from the manifest as both CI publishers do. PREPARATION_SCRIPTS is exported and the test fixture carries one of each trigger, so dropping any of the six from the list fails the suite; the planter predicate is named for what it decides. AGENTS.md's bundle sentence places the release's packaged commit on the build chain (a child of the previous tip or a root), never as a child of the release commit.
1 parent 16828d3 commit 07f082e

5 files changed

Lines changed: 46 additions & 32 deletions

File tree

‎.github/scripts/release-pipeline.ts‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -275,7 +275,14 @@ const MANIFEST = "package.json";
275275

276276
/** The scripts npm's git fetcher (pacote) takes as a signal to run `npm install --include=dev` and the prepare
277277
* lifecycle in a `github:` dependency's checkout; the packaged commit ships the build already. */
278-
const PREPARATION_SCRIPTS = ["prepare", "prepack", "build", "preinstall", "install", "postinstall"];
278+
export const PREPARATION_SCRIPTS = [
279+
"prepare",
280+
"prepack",
281+
"build",
282+
"preinstall",
283+
"install",
284+
"postinstall",
285+
];
279286

280287
/** sourceSha's package.json without its preparation scripts, written to the object store; null when it has none. */
281288
function strippedManifestBlob(cwd: string, sourceSha: string): string | null {
@@ -1290,9 +1297,9 @@ export function stablePublishVerdict(version: string, packument: Packument | nul
12901297
return { publish: false, version, reason: `${version} is already on the registry` };
12911298
}
12921299
const latest = packument["dist-tags"].latest;
1293-
// A pre-release on latest is a state the hand bootstrap can leave behind (npm's docs are silent on what a
1294-
// package's FIRST publish under --tag does to latest). A release must take latest over from it, so only a newer
1295-
// RELEASE holds one back; an absent latest publishes too.
1300+
// The hand bootstrap leaves a pre-release on latest: a packument always carries that key (npm/registry
1301+
// REGISTRY-API.md, "dist-tags: an object with at least one key, latest"), so a first publish gets it whatever
1302+
// --tag asked for. A release must take latest over from it, so only a newer RELEASE holds one back.
12961303
if (
12971304
latest !== undefined &&
12981305
parseMinted(latest).pre === null &&

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ GitHub Settings as Code: GitHub Action applying declarative repository settings:
3434
<!-- Add project-specific instructions below the END marker; they are this repository's own and survive every sync. -->
3535
<!-- END REPO-PLATFORM MANAGED -->
3636

37-
- `lib/settings.schema.json` is the COMMITTED JSON Schema for settings.yml, generated from the zod slices in `src/sections/<key>/schema.ts` as composed into the settings document by `src/schema.ts`. Each slice is ONE declaration that produces its config type (z.infer), the section's tolerant runtime shape (the section module derives `loosen(<slice>)` itself; the factory-minted families - secrets, variables, the two setup sections, and the list sections on `listSection` - get it from their shared factory in `src/sections/shared/`, which does that derivation once), and its part of the published schema (`.meta({id})` names its definitions; the descriptions come from the `schema:` map in the section's `<key>.docs.yml`, keyed `Definition.field`, which the generator attaches and fails on when a site or a key is unmatched); `src/schema.ts` adds only the document-level wrappers and pins each property to its slice with a lockstep type. Regenerate the schema with `bun run build:schema` after a schema-affecting `src/` change - CI's schema-check job fails when it drifts. `lib/index.js`, the bundled entrypoint the action runs (node24), is NOT committed on main: every workflow that executes the action builds it first (`bun run build:bundle`), the e2e runner builds it to a temp path, and a release builds and commits it on a packaged child of the release commit, which is what every `vX.Y.Z` tag and the moving major point at (main itself stays source-only). `lib/` is exempt from the typography check (third-party unicode in the bundle; the schema descriptions are checked at source) and excluded from [biome](https://biomejs.dev).
37+
- `lib/settings.schema.json` is the COMMITTED JSON Schema for settings.yml, generated from the zod slices in `src/sections/<key>/schema.ts` as composed into the settings document by `src/schema.ts`. Each slice is ONE declaration that produces its config type (z.infer), the section's tolerant runtime shape (the section module derives `loosen(<slice>)` itself; the factory-minted families - secrets, variables, the two setup sections, and the list sections on `listSection` - get it from their shared factory in `src/sections/shared/`, which does that derivation once), and its part of the published schema (`.meta({id})` names its definitions; the descriptions come from the `schema:` map in the section's `<key>.docs.yml`, keyed `Definition.field`, which the generator attaches and fails on when a site or a key is unmatched); `src/schema.ts` adds only the document-level wrappers and pins each property to its slice with a lockstep type. Regenerate the schema with `bun run build:schema` after a schema-affecting `src/` change - CI's schema-check job fails when it drifts. `lib/index.js`, the bundled entrypoint the action runs (node24), is NOT committed on main: every workflow that executes the action builds it first (`bun run build:bundle`), the e2e runner builds it to a temp path, and a release builds and commits it on the `build` branch's chain commit for the release commit (a child of the previous chain tip, or a root; never a child of the release commit), which is what every `vX.Y.Z` tag and the moving major point at (main itself stays source-only). `lib/` is exempt from the typography check (third-party unicode in the bundle; the schema descriptions are checked at source) and excluded from [biome](https://biomejs.dev).
3838
- The npm library (`@vivswan/github-settings-as-code`, built into `lib/pkg/` by `bun run build:lib`, never committed) is described in docs/reference/library.md. One rule the tooling cannot infer: a type a section module exposes must be exported from its home module, or the bundled declarations cannot reach it and the package-smoke job fails.
3939
- `src/cli/` is the command line, a consumer of the public entry like the action: a capability it needs is exported from `src/index.ts` first, never imported across. Guide: docs/start/cli.md.
4040
- The import layering of `src/` is declared in `architecture.yml` and enforced by `bun run lint:arch`, so a new cross-layer import is a deliberate edit to that file; the module map in `docs/reference/architecture.md` is generated from it.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ The [getting started guide](docs/start/getting-started.md) walks the same steps
6161

6262
## Library
6363

64-
The same engine is the npm package `@vivswan/github-settings-as-code` (ESM, Node 22.14 or newer): validate, merge, check, and apply from your own code. Every green push to `main` publishes a pre-release: `npm install @vivswan/github-settings-as-code@next` (or `bun add`), the install line that always resolves. The plain `npm install @vivswan/github-settings-as-code` gives the released version once one exists; before that it resolves to the bootstrap pre-release or to nothing, depending on what the bootstrap left on `latest`. The [library reference](docs/reference/library.md) has the API by group and the versioning rules.
64+
The same engine is the npm package `@vivswan/github-settings-as-code` (ESM, Node 22.14 or newer): validate, merge, check, and apply from your own code. Every green push to `main` publishes a pre-release: `npm install @vivswan/github-settings-as-code@next` (or `bun add`). The plain `npm install @vivswan/github-settings-as-code` gives the released version once one exists, and the bootstrap pre-release until then (a first publish carries `latest` whatever tag it asked for). The [library reference](docs/reference/library.md) has the API by group and the versioning rules.
6565

6666
The package is also a command: `npx @vivswan/github-settings-as-code@next check --repository o/r --settings-file .github/settings.yml` runs the action's check from a terminal; the [command line guide](docs/start/cli.md) has every command.
6767

‎docs/reference/library.md‎

Lines changed: 9 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -168,7 +168,7 @@ The package and the action share one version, the one in `.release-please-manife
168168
| npm dist-tag | Publishes on | Version | Install |
169169
|---|---|---|---|
170170
| `next` | Every green push to `main` | The manifest's next patch, then `-main.<run number>.g<sha7>`: `2.0.1-main.412.gb8df084` | `npm install @vivswan/github-settings-as-code@next` |
171-
| `latest` | Every release cut | The released version: `2.1.0`. Before the first release, whatever the bootstrap left on `latest`: the pre-release, or nothing (see the setup section) | `npm install @vivswan/github-settings-as-code` |
171+
| `latest` | Every release cut | The released version: `2.1.0`. Until the first release it names the bootstrap pre-release: a packument always carries `latest` (npm/registry REGISTRY-API.md, "dist-tags: an object with at least one key, latest"), so a first publish gets it whatever `--tag` asked for | `npm install @vivswan/github-settings-as-code` |
172172
| none | Every packaged commit on the `build` branch since the library joined it | The commit itself | `npm install github:Vivswan/github-settings-as-code#<packaged sha>` |
173173

174174
The npm dist-tag `latest` is not the git tag `latest`: the git tag names the newest packaged commit on the `build` branch (every green push moves it), the dist-tag names the newest release on the registry.
@@ -183,25 +183,18 @@ The npm dist-tag `latest` is not the git tag `latest`: the git tag names the new
183183

184184
For the owner, once. npm adds a trusted publisher only to a package that already exists, so the first version is published by hand from a maintainer machine with two-factor authentication; it is the only publish a person ever makes.
185185

186-
1. From a clean checkout of `main`, build the library (the tarball ships `lib/pkg/`, which is built, not committed), stamp the bootstrap pre-release version, and publish it under `next`, never `latest` by request:
186+
1. From a clean checkout of `main`, build the library (the tarball ships `lib/pkg/`, which is built, not committed), stamp the bootstrap pre-release version, drop the `prepare` script from the manifest as both CI publishers do, and publish under the `next` dist-tag:
187187

188188
```bash
189189
bun install --frozen-lockfile && bun run build:lib
190190
version="$(GITHUB_SHA="$(git rev-parse HEAD)" GITHUB_RUN_NUMBER=0 bun .github/scripts/release-pipeline.ts prerelease-version)"
191-
npm version "$version" --no-git-tag-version && npm publish --access public --tag next
192-
git checkout package.json
191+
npm version "$version" --no-git-tag-version && npm pkg delete scripts.prepare
192+
npm publish --access public --tag next
193+
git checkout -- package.json
193194
```
194195

195-
Then `npm dist-tag ls @vivswan/github-settings-as-code` shows one of two states; npm's documentation says publishing sets `latest` unless `--tag` is used and is silent on a package's first publish, so neither is promised:
196+
2. Check the dist-tags: `npm dist-tag ls @vivswan/github-settings-as-code` names the bootstrap version under both `next` and `latest`. The registry gives a package's first publish `latest` whatever `--tag` asked for, because a packument always carries that key (npm/registry REGISTRY-API.md, "dist-tags: an object with at least one key, latest"); the first release takes it over, since the stable publish job yields only to a newer release.
197+
3. On npmjs.com, on the package's settings page, add a trusted publisher: GitHub Actions, owner `Vivswan`, repository `github-settings-as-code`, workflow filename `ci.yml` (the caller of both hooks), no environment.
198+
4. Under publishing access, choose "Require two-factor authentication and disallow tokens", so the workflow's OIDC identity is the only thing that can publish.
196199

197-
| Dist-tags after the bootstrap | Plain `npm install @vivswan/github-settings-as-code` until the first release |
198-
|---|---|
199-
| `next` and `latest`, both on the pre-release | Resolves to the bootstrap pre-release |
200-
| `next` alone | Fails; `@next` is the install line |
201-
202-
The stable publish job handles both: it yields only to a newer release, so the first release takes `latest` from the pre-release or creates it.
203-
204-
2. On npmjs.com, on the package's settings page, add a trusted publisher: GitHub Actions, owner `Vivswan`, repository `github-settings-as-code`, workflow filename `ci.yml` (the caller of both hooks), no environment.
205-
3. Under publishing access, choose "Require two-factor authentication and disallow tokens", so the workflow's OIDC identity is the only thing that can publish.
206-
207-
Until step 2 is done, the release hook's `publish-npm` job fails and the GitHub release stays a draft, and `publish-next` fails the same way on the next green push; re-run the failed jobs once the publisher exists.
200+
Until step 3 is done, the release hook's `publish-npm` job fails and the GitHub release stays a draft, and `publish-next` fails the same way on the next green push; re-run the failed jobs once the publisher exists.

‎test/scripts/release-pipeline.test.ts‎

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ import {
2525
nextPublishVerdict,
2626
npmVerdict,
2727
type Packument,
28+
PREPARATION_SCRIPTS,
2829
type PublishVerdict,
2930
packageRelease,
3031
prereleaseVersion,
@@ -154,13 +155,12 @@ function stageBuild(cwd: string): void {
154155
git(cwd, "add", "-f", "--", "lib/index.js", "lib/pkg");
155156
}
156157

157-
/** The fixture's package.json as the real one is shaped: preparation scripts (prepare, build) beside one that is not. */
158+
/** The fixture's package.json: one of each script pacote takes as a preparation trigger, beside one that is not. */
158159
function manifestJson(version: string, scripts: Record<string, string> = FIXTURE_SCRIPTS): string {
159160
return `${JSON.stringify({ name: "@scope/pkg", version, scripts }, null, 2)}\n`;
160161
}
161162
const FIXTURE_SCRIPTS = {
162-
prepare: "lefthook install || true",
163-
build: "bun run build:lib",
163+
...Object.fromEntries(PREPARATION_SCRIPTS.map((name) => [name, `echo ${name}`])),
164164
test: "bun test",
165165
};
166166
/** FIXTURE_SCRIPTS after the pipeline's strip: the preparation scripts gone, the rest kept. */
@@ -171,15 +171,16 @@ function stripPrepare(cwd: string): void {
171171
const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")) as {
172172
scripts?: Record<string, string>;
173173
};
174-
delete pkg.scripts?.prepare;
175-
delete pkg.scripts?.build;
174+
for (const name of PREPARATION_SCRIPTS) {
175+
delete pkg.scripts?.[name];
176+
}
176177
write(cwd, "package.json", `${JSON.stringify(pkg, null, 2)}\n`);
177178
git(cwd, "add", "package.json");
178179
}
179180

180-
/** Whether planted files include the library build, which only commits minted after the prepare strip carry; a
181-
* planted package.json says what the manifest is instead. */
182-
function carriesLibrary(files: Record<string, unknown>): boolean {
181+
/** Whether a planter should strip the manifest as the pipeline does: the files include the library build (only
182+
* commits minted after the strip carry it) and no explicit package.json says what the manifest is instead. */
183+
function shouldStripManifest(files: Record<string, unknown>): boolean {
183184
return (
184185
Object.keys(files).some((file) => file.startsWith("lib/pkg/")) && !("package.json" in files)
185186
);
@@ -746,7 +747,7 @@ describe("packageRelease", () => {
746747
write(planter, file, content);
747748
git(planter, "add", "-f", file);
748749
}
749-
if (carriesLibrary(files)) {
750+
if (shouldStripManifest(files)) {
750751
stripPrepare(planter);
751752
}
752753
git(planter, "commit", "--quiet", "--allow-empty", ...message.flatMap((m) => ["-m", m]));
@@ -1957,7 +1958,7 @@ describe("advanceBuild", () => {
19571958
}
19581959
git(planter, "add", "-f", file);
19591960
}
1960-
if (carriesLibrary(files)) {
1961+
if (shouldStripManifest(files)) {
19611962
stripPrepare(planter);
19621963
}
19631964
const paragraphs = message.flatMap((paragraph) => ["-m", paragraph]);
@@ -2246,6 +2247,19 @@ describe("advanceBuild", () => {
22462247
expect(remoteRef(fx, "refs/tags/latest")).toBe(latestBefore);
22472248
});
22482249

2250+
test("the preparation triggers are the six pacote reads before it prepares a git dependency", () => {
2251+
// Pinned as a literal: the fixture derives from the exported list, so a name dropped there would vanish
2252+
// from the fixture too and the manifest test below could not see it go.
2253+
expect(PREPARATION_SCRIPTS).toEqual([
2254+
"prepare",
2255+
"prepack",
2256+
"build",
2257+
"preinstall",
2258+
"install",
2259+
"postinstall",
2260+
]);
2261+
});
2262+
22492263
test("a chain commit's package.json is the source's without its preparation scripts, and a rerun holds it there", () => {
22502264
const fx = seedFixture();
22512265
const tip = advanceBuild({ cwd: fx.work, sourceSha: fx.mergeSha }).buildSha;

0 commit comments

Comments
 (0)