@intentius/chant 0.124.28 → 0.124.29

package/dist/flag-params.js

@@ -0,0 +1,130 @@
+/**
+ * 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.js";
+import { flagGateRefusal } from "./build-params.js";
+import { echoBuildParams, resolveCliBuildParams } from "./cli/build-params-cli.js";
+import { formatError } from "./cli/format.js";
+/** 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, env) {
+    if (!env)
+        return { flags: undefined, errors: [] };
+    const found = findWorkspaceRoot(projectDir);
+    if (!found)
+        return { flags: undefined, errors: [] };
+    const { memberFlagBindings } = await import("./workspace/flags-read.js");
+    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.js");
+        const { RecordReadError } = await import("./workspace/records.js");
+        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, flags) {
+    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, provenance) {
+    const { discoverComponents } = await import("./components/discover.js");
+    const { withoutDisabled } = await import("./components/cli-support.js");
+    const { gateNamesOf } = await import("./components/release-gate.js");
+    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 }));
+        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, buildParamsConfig, args, env) {
+    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) => 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/dist/lifecycle/__fixtures__/publish-fakes.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ */
+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 declare function startFakeRegistry(creds: {
+    username: string;
+    password: string;
+    token: string;
+}): Promise<FakeRegistry>;
+/** Write a one-image OCI layout at `dir`, returning the manifest's and the config's digests. */
+export declare function writeOciLayout(dir: string, content?: string): {
+    digest: string;
+    configDigest: string;
+};
+/** 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 declare const fakeNpmRegistryFile: (log: string) => string;
+/** Read the fake npm's registry. */
+export declare function readFakeNpmRegistry(log: string): FakeNpmRegistry;
+/** Seed the fake npm's registry, such as with an earlier version as `latest`. */
+export declare function seedFakeNpmRegistry(log: string, registry: FakeNpmRegistry): void;
+/**
+ * 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 declare function writeFakeNpm(binDir: string, log: string): string;
+/** 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 declare function startFakeForge(forge: "github" | "forgejo" | "gitlab", api: string, repo: string, releases?: FakeForgeRelease[]): FakeForge;
+/** A small SPDX document, as `npm sbom --sbom-format spdx` writes one. */
+export declare function spdxDocument(name: string): string;
+/** Write an npm package directory, with an `sbom.spdx.json` at its root unless `sbom` is false (#4049). */
+export declare function writePackage(dir: string, name: string, version: string, sbom?: boolean): void;
+/** Write a `package-lock.json` at `dir`, which the OCI and forge targets write their SBOM from (#4049). */
+export declare function writeLockfile(dir: string): void;
+//# sourceMappingURL=publish-fakes.d.ts.map

package/dist/lifecycle/__fixtures__/publish-fakes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-fakes.d.ts","sourceRoot":"","sources":["../../../src/lifecycle/__fixtures__/publish-fakes.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/__fixtures__/publish-fakes.js

@@ -0,0 +1,304 @@
+/**
+ * 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 } from "node:http";
+import { join } from "node:path";
+const sha = (b) => `sha256:${createHash("sha256").update(b).digest("hex")}`;
+/** A registry fake with a Bearer token service that accepts `username` and `password`. */
+export async function startFakeRegistry(creds) {
+    const blobs = new Map();
+    const manifests = new Map();
+    const requests = [];
+    const state = { uploads: 0, port: 0 };
+    const read = (req) => new Promise((res) => {
+        const parts = [];
+        req.on("data", (c) => parts.push(c));
+        req.on("end", () => res(Buffer.concat(parts)));
+    });
+    const server = createServer(async (req, res) => {
+        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, headers = {}, 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"));
+            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((r) => server.listen(0, "127.0.0.1", () => r()));
+    state.port = server.address().port;
+    return {
+        host: `127.0.0.1:${state.port}`,
+        blobs,
+        manifests,
+        requests,
+        get uploads() {
+            return state.uploads;
+        },
+        close: () => new Promise((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, content = "layer bytes") {
+    const blobsDir = join(dir, "blobs", "sha256");
+    mkdirSync(blobsDir, { recursive: true });
+    const put = (bytes) => {
+        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 };
+}
+/** The registry file a fake npm writing calls to `log` keeps its state in. */
+export const fakeNpmRegistryFile = (log) => `${log}.registry.json`;
+/** Read the fake npm's registry. */
+export function readFakeNpmRegistry(log) {
+    const file = fakeNpmRegistryFile(log);
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf-8")) : { packages: {} };
+}
+/** Seed the fake npm's registry, such as with an earlier version as `latest`. */
+export function seedFakeNpmRegistry(log, registry) {
+    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, log) {
+    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 fake at `api` for `repo`, which holds `releases` to begin with. */
+export function startFakeForge(forge, api, repo, releases = []) {
+    const calls = [];
+    const packages = new Map();
+    const failures = [];
+    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, body) => ({ ok: status < 300, status, headers: { get: () => null }, text: async () => (body === undefined ? "" : JSON.stringify(body)) });
+    const view = (r) => 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) => (b === undefined ? "" : typeof b === "string" ? b : Buffer.from(b).toString("utf-8"));
+    const 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));
+                if (releases.some((x) => x.tag_name === b.tag_name))
+                    return json(409, { message: "Release already exists" });
+                const r = { 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));
+            const r = { 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));
+            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) {
+    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, name, version, sbom = true) {
+    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) {
+    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/dist/lifecycle/change-set-store.d.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 { type ChangeSetDocument } from "../change-set.js";
 import { type LedgerLocation } from "./git.js";

package/dist/lifecycle/change-set-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"change-set-store.d.ts","sourceRoot":"","sources":["../../src/lifecycle/change-set-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAoE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACzH,OAAO,EAAmF,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAE7H,wEAAwE;AACxE,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAE9C,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,2HAA2H;AAC3H,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,iBAAiB,EACtB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAsBtD;AAED,gDAAgD;AAChD,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE,GAChD;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE;AACvB,kHAAkH;GAChH;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,mBAAmB,CActF;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAI7G"}
+{"version":3,"file":"change-set-store.d.ts","sourceRoot":"","sources":["../../src/lifecycle/change-set-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAoE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACzH,OAAO,EAAmF,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAE7H,wEAAwE;AACxE,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAE9C,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,2HAA2H;AAC3H,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,iBAAiB,EACtB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAsBtD;AAED,gDAAgD;AAChD,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE,GAChD;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE;AACvB,kHAAkH;GAChH;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,mBAAmB,CActF;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAI7G"}

package/dist/lifecycle/change-set-store.js

@@ -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.js";
 import { CHANGE_SET_CONTRACT, CHANGE_SET_SCHEMA_ID, verifyChangeSetDigest } from "../change-set.js";