@intentius/chant 0.124.28 → 0.124.30

package/src/flag-params.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Build-time parameters from workspace flags (#4024): what a build for an
+ * environment resolves in a member with flags, and the precedence rule that a
+ * flag-backed parameter can't be overridden where the environment has a gate.
+ * On the fixture in `workspace/__fixtures__/flag-workspace.ts`, where member
+ * `shop`'s component declares a gate and member `blog`'s does not.
+ */
+
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
+import { buildCommand } from "./cli/commands/build";
+import type { Serializer } from "./serializer";
+import type { BuildParamsConfig } from "./build-params";
+import { loadBuildParamFlags, resolveFlaggedBuildParams } from "./flag-params";
+import { cleanScratch, scratchDir } from "./workspace/__fixtures__/contract-repo";
+import { flagWorkspace } from "./workspace/__fixtures__/flag-workspace";
+
+const SHOP: BuildParamsConfig = { newCheckout: { type: "boolean", default: false }, tier: { type: "string", default: "small" } };
+const BLOG: BuildParamsConfig = { banner: { type: "boolean", default: false } };
+
+let root: string;
+beforeAll(() => {
+  root = flagWorkspace();
+});
+afterAll(cleanScratch);
+
+const quiet = { echo: false } as const;
+
+describe("loadBuildParamFlags", () => {
+  test("outside a workspace, and without an environment, there are no flags", async () => {
+    const plain = scratchDir("chant-flags-plain-");
+    expect(await loadBuildParamFlags(plain, "prod")).toEqual({ flags: undefined, errors: [] });
+    expect(await loadBuildParamFlags(join(root, "shop"), undefined)).toEqual({ flags: undefined, errors: [] });
+  });
+
+  test("in a member, each flag-backed parameter with the flag's value for the environment", async () => {
+    expect(await loadBuildParamFlags(join(root, "shop"), "dev")).toEqual({
+      flags: { env: "dev", byParam: { newCheckout: { flag: "new-checkout", value: true } } },
+      errors: [],
+    });
+  });
+
+  test("a flag kind that can't be read stops the build rather than building without its flags", async () => {
+    const dir = flagWorkspace({ "flags/flag.schema.json": "{ not json" });
+    const loaded = await loadBuildParamFlags(join(dir, "shop"), "prod");
+    expect(loaded.flags).toBeUndefined();
+    expect(loaded.errors[0]).toMatch(/the workspace's flag records can't be read/);
+  });
+});
+
+describe("resolveFlaggedBuildParams", () => {
+  test("records the flag as the parameter's source, per environment", async () => {
+    const prod = await resolveFlaggedBuildParams(join(root, "shop"), SHOP, quiet, "prod");
+    expect(prod).toEqual({
+      success: true,
+      errors: [],
+      provenance: [
+        { name: "newCheckout", value: false, source: "flag:new-checkout" },
+        { name: "tier", value: "small", source: "default" },
+      ],
+    });
+    const dev = await resolveFlaggedBuildParams(join(root, "shop"), SHOP, quiet, "dev");
+    expect(dev.provenance[0]).toEqual({ name: "newCheckout", value: true, source: "flag:new-checkout" });
+    // staging: the record gives no value, so the declared default applies.
+    expect((await resolveFlaggedBuildParams(join(root, "shop"), SHOP, quiet, "staging")).provenance[0]).toEqual({ name: "newCheckout", value: false, source: "default" });
+  });
+
+  test("--param can't override a flag in an environment with a gate: the build refuses", async () => {
+    const refused = await resolveFlaggedBuildParams(join(root, "shop"), SHOP, { ...quiet, cli: { newCheckout: "true" } }, "prod");
+    expect(refused.success).toBe(false);
+    expect(refused.provenance).toEqual([]);
+    expect(refused.errors).toHaveLength(1);
+    expect(refused.errors[0]).toMatch(/build parameter "newCheckout" is backed by the flag "new-checkout", and "prod" has a gate, so --param can't set it/);
+    expect(refused.errors[0]).toMatch(/gates: prod-release/);
+  });
+
+  test("--params-file can't either, and a parameter no flag backs still can", async () => {
+    const file = join(scratchDir("chant-flags-file-"), "params.json");
+    writeFileSync(file, JSON.stringify({ newCheckout: true }));
+    const refused = await resolveFlaggedBuildParams(join(root, "shop"), SHOP, { ...quiet, paramsFile: file }, "prod");
+    expect(refused.success).toBe(false);
+    expect(refused.errors[0]).toMatch(/so --params-file can't set it/);
+    const tier = await resolveFlaggedBuildParams(join(root, "shop"), SHOP, { ...quiet, cli: { tier: "large" } }, "prod");
+    expect(tier.success).toBe(true);
+    expect(tier.provenance).toContainEqual({ name: "tier", value: "large", source: "cli" });
+  });
+
+  test("where no component declares a gate, --param still overrides the flag", async () => {
+    const r = await resolveFlaggedBuildParams(join(root, "blog"), BLOG, { ...quiet, cli: { banner: "false" } }, "prod");
+    expect(r.success).toBe(true);
+    expect(r.provenance).toEqual([{ name: "banner", value: false, source: "cli" }]);
+  });
+
+  test("components that can't be read refuse an override, since the gate can't be ruled out", async () => {
+    const dir = flagWorkspace({ "shop/broken.component.ts": "export const = ;\n" });
+    const r = await resolveFlaggedBuildParams(join(dir, "shop"), SHOP, { ...quiet, cli: { newCheckout: "true" } }, "prod");
+    expect(r.success).toBe(false);
+    expect(r.errors[0]).toMatch(/whether "prod" has a gate can't be told/);
+  });
+});
+
+describe("chant build --env in a member with flags", () => {
+  const runtime = join(import.meta.dirname, "runtime");
+  const paramsModule = join(import.meta.dirname, "params");
+  const serializer: Serializer = {
+    name: "aws",
+    rulePrefix: "TEST",
+    serialize: (entities) => JSON.stringify([...entities.values()].map((e) => (e as unknown as { props: unknown }).props)),
+  };
+  const shopFiles = {
+    "shop/chant.config.ts": `export default { environments: ["dev", "staging", "prod"], buildParams: { newCheckout: { type: "boolean", default: false } } };\n`,
+    "shop/main.ts":
+      `import { createResource } from ${JSON.stringify(runtime)};\n` +
+      `import { params } from ${JSON.stringify(paramsModule)};\n` +
+      `const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });\n` +
+      `export const bucket = new Bucket({ checkout: params.newCheckout ? "new" : "old" });\n`,
+  };
+
+  test("records the flag on BuildResult.buildParams and builds with its value", async () => {
+    const dir = flagWorkspace(shopFiles);
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await buildCommand({ path: join(dir, "shop"), format: "json", serializers: [serializer], env: "dev" });
+      expect(result.errors).toEqual([]);
+      expect(result.buildParams).toEqual([{ name: "newCheckout", value: true, source: "flag:new-checkout" }]);
+      expect(spy.mock.calls.map((c) => String(c[0])).some((l) => l.includes("1 build parameter resolved (1 from flags)"))).toBe(true);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  test("refuses --param for a flag-backed parameter in an environment with a gate", async () => {
+    const dir = flagWorkspace(shopFiles);
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await buildCommand({ path: join(dir, "shop"), format: "json", serializers: [serializer], env: "prod", params: { newCheckout: "true" } });
+      expect(result.success).toBe(false);
+      expect(result.errors.join("\n")).toMatch(/"newCheckout" is backed by the flag "new-checkout", and "prod" has a gate, so --param can't set it/);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

package/src/flag-params.ts

@@ -0,0 +1,134 @@
+/**
+ * Build-time parameters from workspace flags (#4024, decided in #4016).
+ *
+ * A member of a workspace may have flag records: records of a kind with a
+ * `flag` block, each naming the member, one of its declared build
+ * parameters and a value per environment (`workspace/flags.ts`). A build
+ * for an environment (`chant build --env <env>`, `chant run --components
+ * --env <env>`, and each environment a release cut compiles) reads them, and
+ * a flag-backed parameter takes the flag's value for that environment,
+ * recorded as `source: "flag:<name>"` on `BuildResult.buildParams` and on the
+ * release target's `params`.
+ *
+ * The precedence rule: where the environment has a gate, `--param`,
+ * `--params-file` and the parameter's env var can't set a flag-backed
+ * parameter, and the build refuses. An environment has a gate when a
+ * component enabled in it declares a gate step, the same test `components
+ * promote --release` uses to bind a release gate. The test runs only when one
+ * of those sources did set a flag-backed parameter, since it imports the
+ * member's components; a project with no components has no gate.
+ *
+ * Level 0 pays one upward `existsSync` walk here and nothing more. Workspace
+ * code is imported only once a declaration is found (#2525 rule 5, pinned by
+ * #2526's goldens).
+ */
+
+import { findWorkspaceRoot } from "./project-root";
+import { flagGateRefusal, type BuildParamFlags, type BuildParamsConfig } from "./build-params";
+import type { BuildParamProvenance } from "./provenance";
+import { echoBuildParams, resolveCliBuildParams, type CliBuildParamsArgs, type CliBuildParamsResolution } from "./cli/build-params-cli";
+import { formatError } from "./cli/format";
+
+/** The flags backing parameters of the member at `projectDir` in `env`, or why they can't be read. `flags` is undefined outside a workspace, without an environment, or when no flag names the member. */
+export async function loadBuildParamFlags(projectDir: string, env: string | undefined): Promise<{ flags: BuildParamFlags | undefined; errors: string[] }> {
+  if (!env) return { flags: undefined, errors: [] };
+  const found = findWorkspaceRoot(projectDir);
+  if (!found) return { flags: undefined, errors: [] };
+  const { memberFlagBindings } = await import("./workspace/flags-read");
+  try {
+    const bindings = await memberFlagBindings(found.dir, projectDir, env);
+    if (!bindings) return { flags: undefined, errors: [] };
+    if (bindings.errors.length > 0) return { flags: undefined, errors: bindings.errors };
+    if (Object.keys(bindings.byParam).length === 0) return { flags: undefined, errors: [] };
+    return { flags: { env, byParam: bindings.byParam }, errors: [] };
+  } catch (err) {
+    const { WorkspaceReadError } = await import("./workspace/declaration");
+    const { RecordReadError } = await import("./workspace/records");
+    if (err instanceof WorkspaceReadError || err instanceof RecordReadError) {
+      return { flags: undefined, errors: [`the workspace's flag records can't be read, so this build can't tell which parameters they set: ${err.message}`] };
+    }
+    throw err;
+  }
+}
+
+/** The parameters a flag backs that `--param`, `--params-file` or an env var set instead. */
+export function overriddenFlagParams(provenance: readonly BuildParamProvenance[], flags: BuildParamFlags | undefined): BuildParamProvenance[] {
+  if (!flags) return [];
+  return provenance.filter((p) => flags.byParam[p.name] !== undefined && (p.source === "cli" || p.source === "params-file" || p.source === "env"));
+}
+
+/**
+ * The gates the member's components declare in the environment the process
+ * builds for (`CHANT_ENV`), with the parameters as resolved, or why the
+ * components can't be read. Only components enabled under those parameters
+ * count.
+ */
+export async function environmentGates(projectDir: string, provenance: BuildParamProvenance[]): Promise<{ gates: string[] } | { error: string }> {
+  const { discoverComponents } = await import("./components/discover");
+  const { withoutDisabled } = await import("./components/cli-support");
+  const { gateNamesOf } = await import("./components/release-gate");
+  try {
+    const discovered = await discoverComponents(projectDir, { buildParams: provenance });
+    if (discovered.errors.length > 0) return { error: discovered.errors.map((e) => e.message).join("; ") };
+    const all = [...discovered.components.values()].map((d) => d.component);
+    const plain = all.map((c) => ({ name: c.name, dependsOn: c.dependsOn, deploy: c.deploy as never }));
+    return { gates: gateNamesOf(withoutDisabled(all, plain)) };
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Resolve the build parameters of the project at `projectDir` for `env`,
+ * with the workspace's flags, as `resolveCliBuildParams` does without them.
+ * Refuses when a flag record can't be read, and when `--param`,
+ * `--params-file` or an env var sets a flag-backed parameter in an
+ * environment with a gate. Prints the summary line only on success.
+ */
+export async function resolveFlaggedBuildParams(
+  projectDir: string,
+  buildParamsConfig: BuildParamsConfig | undefined,
+  args: CliBuildParamsArgs,
+  env: string | undefined,
+): Promise<CliBuildParamsResolution> {
+  const loaded = await loadBuildParamFlags(projectDir, env);
+  if (loaded.errors.length > 0) {
+    return { success: false, provenance: [], errors: loaded.errors.map((message) => formatError({ message })) };
+  }
+  const { flags } = loaded;
+  const resolution = resolveCliBuildParams(buildParamsConfig, { ...args, ...(flags ? { flags } : {}), echo: false });
+  if (!resolution.success || !flags) {
+    if (resolution.success && args.echo !== false) echoBuildParams(resolution.provenance, args.verbose);
+    return resolution;
+  }
+  const overridden = overriddenFlagParams(resolution.provenance, flags);
+  if (overridden.length > 0) {
+    const found = await environmentGates(projectDir, resolution.provenance);
+    if ("error" in found) {
+      return {
+        success: false,
+        provenance: [],
+        errors: [
+          formatError({
+            message:
+              `${overridden.map((p) => `"${p.name}"`).join(", ")} ${overridden.length === 1 ? "is" : "are"} backed by a flag and set by ${[...new Set(overridden.map((p) => p.source))].join(", ")}, ` +
+              `and whether "${flags.env}" has a gate can't be told, because its components can't be read: ${found.error}`,
+          }),
+        ],
+      };
+    }
+    if (found.gates.length > 0) {
+      const around = (p: BuildParamProvenance): string =>
+        p.source === "cli" ? "--param" : p.source === "params-file" ? "--params-file" : `the env var ${buildParamsConfig?.[p.name]?.env ?? "(unknown)"}`;
+      return {
+        success: false,
+        provenance: [],
+        errors: overridden.map((p) =>
+          formatError({ message: `${flagGateRefusal(p.name, flags.byParam[p.name].flag, flags.env, around(p))} (gates: ${found.gates.join(", ")})` }),
+        ),
+      };
+    }
+  }
+  if (args.echo !== false) echoBuildParams(resolution.provenance, args.verbose);
+  return resolution;
+}

package/src/lifecycle/__fixtures__/publish-fakes.ts

@@ -0,0 +1,351 @@
+/**
+ * Test stand-ins for the publish targets (#4047): an OCI registry fake that
+ * listens on 127.0.0.1 inside the test process and answers with a Bearer
+ * challenge as GHCR and Docker Hub do, an OCI image layout writer, a fake
+ * `npm` that records each call and keeps a registry with dist-tags in a file,
+ * and a forge fake with draft releases (#4048). Nothing here reaches a network or a real
+ * registry, and every server a test starts is closed by it.
+ */
+
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { join } from "node:path";
+
+const sha = (b: Uint8Array | string) => `sha256:${createHash("sha256").update(b).digest("hex")}`;
+
+export interface FakeRegistry {
+  /** `127.0.0.1:<port>`, for a repository reference. */
+  host: string;
+  blobs: Map<string, Buffer>;
+  manifests: Map<string, { name: string; type: string; bytes: Buffer }>;
+  /** Each request: method, path and the authorization header it carried. */
+  requests: Array<{ method: string; path: string; authorization: string | null }>;
+  uploads: number;
+  close(): Promise<void>;
+}
+
+/** A registry fake with a Bearer token service that accepts `username` and `password`. */
+export async function startFakeRegistry(creds: { username: string; password: string; token: string }): Promise<FakeRegistry> {
+  const blobs = new Map<string, Buffer>();
+  const manifests = new Map<string, { name: string; type: string; bytes: Buffer }>();
+  const requests: FakeRegistry["requests"] = [];
+  const state = { uploads: 0, port: 0 };
+  const read = (req: IncomingMessage) =>
+    new Promise<Buffer>((res) => {
+      const parts: Buffer[] = [];
+      req.on("data", (c: Buffer) => parts.push(c));
+      req.on("end", () => res(Buffer.concat(parts)));
+    });
+  const server = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+    const url = new URL(req.url ?? "/", `http://127.0.0.1:${state.port}`);
+    const body = await read(req);
+    requests.push({ method: req.method ?? "", path: url.pathname, authorization: req.headers.authorization ?? null });
+    const send = (status: number, headers: Record<string, string> = {}, text = "") => {
+      res.writeHead(status, headers);
+      res.end(text);
+    };
+    if (url.pathname === "/token") {
+      const basic = `Basic ${Buffer.from(`${creds.username}:${creds.password}`).toString("base64")}`;
+      if (req.headers.authorization !== basic) return send(401, {}, "bad credentials");
+      return send(200, { "content-type": "application/json" }, JSON.stringify({ token: creds.token }));
+    }
+    if (req.headers.authorization !== `Bearer ${creds.token}`) {
+      return send(401, { "www-authenticate": `Bearer realm="http://127.0.0.1:${state.port}/token",service="fake-registry"` }, "unauthorized");
+    }
+    let m = url.pathname.match(/^\/v2\/(.+)\/blobs\/uploads\/(.*)$/);
+    if (m) {
+      if (req.method === "POST") return send(202, { location: `/v2/${m[1]}/blobs/uploads/u${requests.length}?_state=s` });
+      const digest = url.searchParams.get("digest") ?? "";
+      if (req.method === "PUT" && sha(body) === digest && url.searchParams.get("_state") === "s") {
+        blobs.set(digest, body);
+        state.uploads++;
+        return send(201, { "docker-content-digest": digest });
+      }
+      return send(400, {}, "digest invalid");
+    }
+    m = url.pathname.match(/^\/v2\/(.+)\/blobs\/(sha256:[0-9a-f]+)$/);
+    if (m && req.method === "HEAD") return send(blobs.has(m[2]!) ? 200 : 404);
+    m = url.pathname.match(/^\/v2\/(.+)\/manifests\/(.+)$/);
+    if (m && (req.method === "HEAD" || req.method === "GET")) {
+      const found = manifests.get(m[2]!);
+      return found ? send(200, { "content-type": found.type, "docker-content-digest": sha(found.bytes) }, req.method === "GET" ? found.bytes.toString("utf-8") : "") : send(404);
+    }
+    if (m && req.method === "PUT") {
+      const ref = m[2]!;
+      if (ref.startsWith("sha256:") && sha(body) !== ref) return send(400, {}, "manifest digest invalid");
+      const parsed = JSON.parse(body.toString("utf-8")) as { config?: { digest: string }; layers?: Array<{ digest: string }> };
+      for (const d of [parsed.config, ...(parsed.layers ?? [])]) if (d && !blobs.has(d.digest)) return send(400, {}, `blob unknown ${d.digest}`);
+      manifests.set(ref, { name: m[1]!, type: String(req.headers["content-type"]), bytes: body });
+      return send(201, { "docker-content-digest": sha(body) });
+    }
+    return send(404, {}, "not found");
+  });
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", () => r()));
+  state.port = (server.address() as AddressInfo).port;
+  return {
+    host: `127.0.0.1:${state.port}`,
+    blobs,
+    manifests,
+    requests,
+    get uploads() {
+      return state.uploads;
+    },
+    close: () => new Promise<void>((r) => server.close(() => r())),
+  };
+}
+
+/** Write a one-image OCI layout at `dir`, returning the manifest's and the config's digests. */
+export function writeOciLayout(dir: string, content = "layer bytes"): { digest: string; configDigest: string } {
+  const blobsDir = join(dir, "blobs", "sha256");
+  mkdirSync(blobsDir, { recursive: true });
+  const put = (bytes: string) => {
+    const d = sha(bytes);
+    writeFileSync(join(blobsDir, d.slice(7)), bytes);
+    return { digest: d, size: Buffer.byteLength(bytes) };
+  };
+  const layer = put(content);
+  const config = put(JSON.stringify({ architecture: "amd64", os: "linux", rootfs: { type: "layers", diff_ids: [layer.digest] } }));
+  const manifest = put(
+    JSON.stringify({
+      schemaVersion: 2,
+      mediaType: "application/vnd.oci.image.manifest.v1+json",
+      config: { mediaType: "application/vnd.oci.image.config.v1+json", ...config },
+      layers: [{ mediaType: "application/vnd.oci.image.layer.v1.tar", ...layer }],
+    }),
+  );
+  writeFileSync(join(dir, "oci-layout"), JSON.stringify({ imageLayoutVersion: "1.0.0" }));
+  writeFileSync(join(dir, "index.json"), JSON.stringify({ schemaVersion: 2, manifests: [{ mediaType: "application/vnd.oci.image.manifest.v1+json", ...manifest }] }));
+  return { digest: manifest.digest, configDigest: config.digest };
+}
+
+/** What the fake npm's registry holds: each package's versions and dist-tags. */
+export interface FakeNpmRegistry {
+  packages: Record<string, { versions: string[]; distTags: Record<string, string> }>;
+}
+
+/** The registry file a fake npm writing calls to `log` keeps its state in. */
+export const fakeNpmRegistryFile = (log: string) => `${log}.registry.json`;
+
+/** Read the fake npm's registry. */
+export function readFakeNpmRegistry(log: string): FakeNpmRegistry {
+  const file = fakeNpmRegistryFile(log);
+  return existsSync(file) ? (JSON.parse(readFileSync(file, "utf-8")) as FakeNpmRegistry) : { packages: {} };
+}
+
+/** Seed the fake npm's registry, such as with an earlier version as `latest`. */
+export function seedFakeNpmRegistry(log: string, registry: FakeNpmRegistry): void {
+  writeFileSync(fakeNpmRegistryFile(log), JSON.stringify(registry));
+}
+
+/**
+ * Write a fake `npm` at `<binDir>/npm` that appends `{ args, tokenSet }` to
+ * `log` for each call and prints the token it was given (so a test can show
+ * it is masked). It keeps a registry in `<log>.registry.json`, as npm's does:
+ *
+ * - `publish <dir|tgz> [--tag <t>]` adds the version under `<t>` (default
+ *   `latest`), and refuses a version already there with a 403. As npm's
+ *   registry does, a package's first version is also `latest`. It exits 1
+ *   when the package path contains `$FAKE_NPM_FAIL`.
+ * - `view <name>@<version> version` prints the version when it is there.
+ * - `dist-tag add <name>@<version> <tag>` points the tag at a version that is
+ *   there. It exits 1 when the name contains `$FAKE_NPM_FAIL_TAG`.
+ * - `install` (#4049) checks that every dependency in `./package.json` is in
+ *   its registry at that version, and installs nothing.
+ * - `audit signatures` (#4049) prints what npm prints for verified
+ *   signatures and attestations, and exits 1 when `$FAKE_NPM_AUDIT_FAIL` is set.
+ */
+export function writeFakeNpm(binDir: string, log: string): string {
+  mkdirSync(binDir, { recursive: true });
+  const file = join(binDir, "npm");
+  writeFileSync(
+    file,
+    `#!${process.execPath}
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const args = process.argv.slice(2);
+const token = process.env.NODE_AUTH_TOKEN || "";
+const regFile = ${JSON.stringify(log)} + ".registry.json";
+fs.appendFileSync(${JSON.stringify(log)}, JSON.stringify({ args, tokenSet: token !== "" }) + "\\n");
+console.log("npm notice using //registry.example/:_authToken=" + token);
+console.error("npm notice token " + token);
+const reg = fs.existsSync(regFile) ? JSON.parse(fs.readFileSync(regFile, "utf-8")) : { packages: {} };
+const save = () => fs.writeFileSync(regFile, JSON.stringify(reg));
+const flag = (name) => { const i = args.indexOf(name); return i < 0 ? null : args[i + 1]; };
+const split = (spec) => { const at = spec.lastIndexOf("@"); return [spec.slice(0, at), spec.slice(at + 1)]; };
+if (args[0] === "publish") {
+  if (process.env.FAKE_NPM_FAIL && args[1] && args[1].includes(process.env.FAKE_NPM_FAIL)) { console.error("npm error 403 Forbidden"); process.exit(1); }
+  const text = fs.statSync(args[1]).isDirectory() ? fs.readFileSync(path.join(args[1], "package.json"), "utf-8") : execFileSync("tar", ["-xzOf", args[1], "package/package.json"], { encoding: "utf-8" });
+  const { name, version } = JSON.parse(text);
+  const p = reg.packages[name] || (reg.packages[name] = { versions: [], distTags: {} });
+  if (p.versions.includes(version)) { console.error("npm error 403 You cannot publish over the previously published versions: " + version); process.exit(1); }
+  p.versions.push(version);
+  p.distTags[flag("--tag") || "latest"] = version;
+  if (!p.distTags.latest) p.distTags.latest = version;
+  save();
+  console.log("+ " + name + "@" + version);
+} else if (args[0] === "view") {
+  const [name, version] = split(args[1]);
+  const p = reg.packages[name];
+  if (!p) { console.error("npm error 404 Not Found - " + name); process.exit(1); }
+  if (p.versions.includes(version)) console.log(version);
+} else if (args[0] === "dist-tag" && args[1] === "add") {
+  const [name, version] = split(args[2]);
+  if (process.env.FAKE_NPM_FAIL_TAG && name.includes(process.env.FAKE_NPM_FAIL_TAG)) { console.error("npm error 403 Forbidden - no permission to change dist-tags"); process.exit(1); }
+  const p = reg.packages[name];
+  if (!p || !p.versions.includes(version)) { console.error("npm error 404 " + args[2] + " is not in the npm registry"); process.exit(1); }
+  p.distTags[args[3]] = version;
+  save();
+  console.log("+" + args[3] + ": " + args[2]);
+} else if (args[0] === "install") {
+  const deps = JSON.parse(fs.readFileSync("package.json", "utf-8")).dependencies || {};
+  for (const [name, version] of Object.entries(deps)) {
+    const p = reg.packages[name];
+    if (!p || !p.versions.includes(version)) { console.error("npm error 404 " + name + "@" + version + " is not in this registry"); process.exit(1); }
+  }
+  console.log("added " + Object.keys(deps).length + " packages");
+} else if (args[0] === "audit" && args[1] === "signatures") {
+  const n = Object.keys(JSON.parse(fs.readFileSync("package.json", "utf-8")).dependencies || {}).length;
+  if (process.env.FAKE_NPM_AUDIT_FAIL) { console.error(n + " packages have invalid attestations"); process.exit(1); }
+  console.log("audited " + n + " packages");
+  console.log(n + " packages have verified registry signatures");
+  console.log(n + " packages have verified attestations");
+} else {
+  console.error("fake npm: unknown command " + args.join(" ")); process.exit(2);
+}
+`,
+  );
+  chmodSync(file, 0o755);
+  return file;
+}
+
+/** A forge release as {@link startFakeForge} keeps it. */
+export interface FakeForgeRelease {
+  id: number;
+  tag_name: string;
+  draft: boolean;
+  target: string;
+  assets: Array<{ name: string; digest: string | null; bytes: string }>;
+}
+
+/** A forge fake answering through `fetch`: GitHub or Forgejo with draft releases, or GitLab with releases, links and a generic package registry. */
+export interface FakeForge {
+  fetch: (url: string, init: { method: string; headers: Record<string, string>; body?: Uint8Array | string }) => Promise<{ ok: boolean; status: number; headers: { get(name: string): string | null }; text(): Promise<string> }>;
+  calls: Array<{ method: string; url: string; headers: Record<string, string>; body?: Uint8Array | string }>;
+  releases: FakeForgeRelease[];
+  /** GitLab: the package registry's files, by URL. */
+  packages: Map<string, string>;
+  /** The releases a consumer sees: published (not draft) ones, with their asset names. */
+  visible(): Array<{ tag: string; assets: string[] }>;
+  /** Make the next request whose `METHOD url` starts with `prefix` answer 500. */
+  failOnce(prefix: string): void;
+}
+
+/** A forge fake at `api` for `repo`, which holds `releases` to begin with. */
+export function startFakeForge(forge: "github" | "forgejo" | "gitlab", api: string, repo: string, releases: FakeForgeRelease[] = []): FakeForge {
+  const calls: FakeForge["calls"] = [];
+  const packages = new Map<string, string>();
+  const failures: string[] = [];
+  let nextId = 100 + releases.length;
+  const root = forge === "gitlab" ? `${api}/projects/${encodeURIComponent(repo)}` : `${api}/repos/${repo}`;
+  const uploads = forge === "github" ? "https://uploads.forge.test" : api;
+  const json = (status: number, body: unknown) => ({ ok: status < 300, status, headers: { get: () => null }, text: async () => (body === undefined ? "" : JSON.stringify(body)) });
+  const view = (r: FakeForgeRelease) =>
+    forge === "gitlab"
+      ? { tag_name: r.tag_name, assets: { links: r.assets.map((a) => ({ name: a.name })) } }
+      : { id: r.id, tag_name: r.tag_name, draft: r.draft, upload_url: `${uploads}/repos/${repo}/releases/${r.id}/assets{?name,label}`, assets: r.assets.map((a) => ({ name: a.name, ...(forge === "github" ? { digest: a.digest } : {}) })) };
+  const text = (b: Uint8Array | string | undefined) => (b === undefined ? "" : typeof b === "string" ? b : Buffer.from(b).toString("utf-8"));
+  const fetch: FakeForge["fetch"] = async (url, init) => {
+    calls.push({ method: init.method, url, headers: init.headers, ...(init.body !== undefined ? { body: init.body } : {}) });
+    const key = `${init.method} ${url}`;
+    const f = failures.findIndex((p) => key.startsWith(p));
+    if (f >= 0) {
+      failures.splice(f, 1);
+      return json(500, { message: "Internal Server Error" });
+    }
+    const u = new URL(url);
+    const path = url.split("?")[0]!;
+    if (forge === "gitlab") {
+      if (init.method === "PUT" && path.startsWith(`${root}/packages/generic/`)) {
+        packages.set(path, text(init.body));
+        return json(201, { message: "201 Created" });
+      }
+      const byTag = path.startsWith(`${root}/releases/`) ? decodeURIComponent(path.slice(`${root}/releases/`.length)) : null;
+      if (init.method === "GET" && byTag !== null) {
+        const r = releases.find((x) => x.tag_name === byTag);
+        return r ? json(200, view(r)) : json(404, { message: "404 Not Found" });
+      }
+      if (init.method === "POST" && path === `${root}/releases`) {
+        const b = JSON.parse(text(init.body)) as { tag_name: string; ref: string; assets?: { links?: Array<{ name: string; url: string }> } };
+        if (releases.some((x) => x.tag_name === b.tag_name)) return json(409, { message: "Release already exists" });
+        const r: FakeForgeRelease = { id: nextId++, tag_name: b.tag_name, draft: false, target: b.ref, assets: (b.assets?.links ?? []).map((l) => ({ name: l.name, digest: null, bytes: packages.get(l.url) ?? "" })) };
+        releases.push(r);
+        return json(201, view(r));
+      }
+      return json(404, { message: "404 Not Found" });
+    }
+    if (init.method === "GET" && path.startsWith(`${root}/releases/tags/`)) {
+      const tag = decodeURIComponent(path.slice(`${root}/releases/tags/`.length));
+      const r = releases.find((x) => x.tag_name === tag && !x.draft);
+      return r ? json(200, view(r)) : json(404, { message: "Not Found" });
+    }
+    if (init.method === "GET" && path === `${root}/releases`) return json(200, releases.map(view));
+    if (init.method === "POST" && path === `${root}/releases`) {
+      const b = JSON.parse(text(init.body)) as { tag_name: string; target_commitish: string; draft?: boolean };
+      const r: FakeForgeRelease = { id: nextId++, tag_name: b.tag_name, draft: b.draft === true, target: b.target_commitish, assets: [] };
+      releases.push(r);
+      return json(201, view(r));
+    }
+    const asset = path.match(/\/releases\/(\d+)\/assets$/);
+    if (init.method === "POST" && asset && (path.startsWith(uploads) || path.startsWith(root))) {
+      const r = releases.find((x) => x.id === Number(asset[1]));
+      const name = u.searchParams.get("name") ?? "";
+      if (!r) return json(404, { message: "Not Found" });
+      if (r.assets.some((a) => a.name === name)) return json(422, { message: "already_exists" });
+      let bytes = text(init.body);
+      if (forge === "forgejo") bytes = bytes.split("\r\n\r\n")[1]?.split("\r\n--")[0] ?? "";
+      r.assets.push({ name, digest: sha(bytes), bytes });
+      return json(201, { name, browser_download_url: `https://forge.test/${repo}/releases/download/${r.tag_name}/${name}` });
+    }
+    const edit = path.match(/\/releases\/(\d+)$/);
+    if (init.method === "PATCH" && edit) {
+      const r = releases.find((x) => x.id === Number(edit[1]));
+      if (!r) return json(404, { message: "Not Found" });
+      const b = JSON.parse(text(init.body)) as { draft?: boolean };
+      if (b.draft === false) r.draft = false;
+      return json(200, view(r));
+    }
+    return json(404, { message: "Not Found" });
+  };
+  return {
+    fetch,
+    calls,
+    releases,
+    packages,
+    visible: () => releases.filter((r) => !r.draft).map((r) => ({ tag: r.tag_name, assets: r.assets.map((a) => a.name) })),
+    failOnce: (prefix) => void failures.push(prefix),
+  };
+}
+
+/** A small SPDX document, as `npm sbom --sbom-format spdx` writes one. */
+export function spdxDocument(name: string): string {
+  return `${JSON.stringify({ spdxVersion: "SPDX-2.3", dataLicense: "CC0-1.0", SPDXID: "SPDXRef-DOCUMENT", name, documentNamespace: `https://example.test/${name}`, creationInfo: { created: "2026-10-17T00:00:00Z", creators: ["Tool: npm"] }, packages: [] }, null, 2)}\n`;
+}
+
+/** Write an npm package directory, with an `sbom.spdx.json` at its root unless `sbom` is false (#4049). */
+export function writePackage(dir: string, name: string, version: string, sbom = true): void {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "package.json"), JSON.stringify({ name, version }, null, 2));
+  if (sbom) writeFileSync(join(dir, "sbom.spdx.json"), spdxDocument(name));
+}
+
+/** Write a `package-lock.json` at `dir`, which the OCI and forge targets write their SBOM from (#4049). */
+export function writeLockfile(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "package-lock.json"),
+    JSON.stringify({ name: "acme", lockfileVersion: 3, packages: { "": { name: "acme" }, "node_modules/left-pad": { version: "1.3.0" } } }, null, 2),
+  );
+}

package/src/lifecycle/change-set-store.ts

@@ -21,7 +21,8 @@
  * component gate in a plain `run --components` binds a lifecycle-plan digest
  * and stores nothing here.
  *
- * How long a stored change set is kept is #4036's retention policy.
+ * `chant lifecycle gc` removes a stored change set from the branch's tree
+ * once #4036's retention policy lets it go (./retention.ts); history keeps it.
  */
 
 import { sortedJsonReplacer } from "../utils";