@intentius/chant 0.124.14 → 0.124.16

package/dist/ci-jobs.js

@@ -0,0 +1,448 @@
+/**
+ * The job primitives chant's three CI generators share (#3765): the scheduled
+ * Op pipeline (`generateOpsPipeline`), the Op waves pipeline
+ * (`generateOpWavesPipeline`) and the component pipeline (`chant build
+ * --components --generate`, with `--pr-loop`, `--wave-gate` and
+ * `--promote-to`). Each forge lexicon builds its documents from these, so a
+ * trigger, a token, a permission rule or an image default is decided once:
+ *
+ *  - the image a generated job runs in, {@link CI_IMAGE};
+ *  - the branches a trigger filters on, {@link triggerBranches};
+ *  - the job token and secret expressions of GitHub Actions and Forgejo
+ *    Actions, {@link GITHUB_JOB_TOKEN} and {@link githubSecret};
+ *  - the `permissions:` a finding-mode needs and the rules for adding to it,
+ *    {@link permissionsFor} and {@link mergePermissions};
+ *  - the `setup` steps and `environment` a job may carry, checked once per
+ *    forge ({@link assertSetupSteps}, {@link assertEnvironment},
+ *    {@link gitlabSetupScript}, {@link assertGitlabEnvironment});
+ *  - GitLab's `rules:` expressions and `id_tokens:` declaration.
+ *
+ * The Forgejo dialect (action refs, dropped `permissions:` and
+ * `environment:`, the header note naming what was dropped) is the forgejo
+ * lexicon's, in its `components/ci-jobs.ts`, since the transform it applies
+ * lives there.
+ */
+// ── Every forge ─────────────────────────────────────────────────────────────
+/**
+ * The image every generated job runs in unless the caller names another. It
+ * carries node and npm, which `chant` needs, and git, which a job that reads
+ * the base commit or pushes to `chant/lifecycle` needs (#3789).
+ */
+export const CI_IMAGE = "node:22";
+/**
+ * The branch a `push` trigger filters on when it names none. A generator
+ * works from a spec, not a checkout, so it cannot read a project's real
+ * default branch; a project on another one names it.
+ */
+export const DEFAULT_BRANCH = "main";
+/**
+ * The branches a push trigger filters on: the ones given, or
+ * {@link DEFAULT_BRANCH} when none are. An empty list is none, on every
+ * forge.
+ */
+export function pushBranches(branches) {
+    return branches && branches.length > 0 ? [...branches] : [DEFAULT_BRANCH];
+}
+/**
+ * The branches a trigger filters on: a `pull_request` trigger's list, or
+ * undefined for every branch; a `push` trigger's, with {@link pushBranches}'
+ * default; none for `cron`.
+ */
+export function triggerBranches(trigger) {
+    switch (trigger.kind) {
+        case "cron":
+            return undefined;
+        case "pull_request":
+            return trigger.branches && trigger.branches.length > 0 ? [...trigger.branches] : undefined;
+        case "push":
+            return pushBranches(trigger.branches);
+    }
+}
+/** A job id every forge accepts, from a kebab- or camel-cased name. */
+export function ciJobName(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/** A command template with each `{name}` part filled in. */
+export function fillCommand(template, name) {
+    return template.map((part) => part.replace("{name}", name));
+}
+/** `{ [key]: map }` when the map has an entry, else `{}`: for spreading an optional mapping into a document. */
+export function nonEmpty(key, map) {
+    return map && Object.keys(map).length > 0 ? { [key]: map } : {};
+}
+/**
+ * A job's `environment:` mapping. Always the mapping form, never the string
+ * shorthand, so adding a `url` later is a new key rather than a reshaped
+ * value. GitHub and GitLab read the same two keys.
+ */
+export function environmentDoc(environment) {
+    return { name: environment.name, ...(environment.url === undefined ? {} : { url: environment.url }) };
+}
+/** The directory part of a relative path, `.` when there is none. */
+export function dirnameOf(path) {
+    const i = path.lastIndexOf("/");
+    return i <= 0 ? "." : path.slice(0, i);
+}
+// ── GitHub Actions and Forgejo Actions ──────────────────────────────────────
+/** The runner label a generated job asks for; the Forgejo dialect rewrites it to the project's label. */
+export const GITHUB_RUNNER = "ubuntu-latest";
+/** The job token, which GitHub and Forgejo both mint for every run. */
+export const GITHUB_JOB_TOKEN = "${{ github.token }}";
+/** A repository secret, by name. */
+export function githubSecret(name) {
+    return `\${{ secrets.${name} }}`;
+}
+/**
+ * A repository secret, or the job token when the secret is unset (#3624). An
+ * unset secret reads as the empty string, so a workflow generated for a
+ * production token still runs in a fork or a fresh repository, with what the
+ * job token may do.
+ */
+export function githubSecretOrJobToken(name) {
+    return `\${{ secrets.${name} || github.token }}`;
+}
+/** Each name mapped from the repository secret of the same name. */
+export function githubSecretEnv(names) {
+    return Object.fromEntries(names.map((n) => [n, githubSecret(n)]));
+}
+/**
+ * Least-privilege `permissions:` for a finding-mode. `report` needs no write
+ * access; `issue` needs only `issues: write`; `pull-request` (and
+ * `merge-request`, generated the same way when a GitLab-authored spec is
+ * targeted at github) needs `contents: write` to push the reconcile branch
+ * plus `pull-requests: write` to open the PR. `comment` changes nothing in
+ * the repository, so its whole scope is `{ contents: read, pull-requests:
+ * write }`.
+ */
+export function permissionsForMode(mode) {
+    switch (mode) {
+        case "issue":
+            return { contents: "read", issues: "write" };
+        case "comment":
+            return { contents: "read", "pull-requests": "write" };
+        case "pull-request":
+        case "merge-request":
+            return { contents: "write", "pull-requests": "write" };
+        case "report":
+            return { contents: "read" };
+    }
+}
+/**
+ * {@link permissionsForMode} on a trigger. A `pull_request` trigger reports
+ * its finding as a comment on the triggering PR itself (#2084): any mode but
+ * `report` posts something to act on a finding, so on that trigger every
+ * such mode also gets `pull-requests: write` for the comment.
+ */
+export function permissionsFor(mode, trigger) {
+    const base = permissionsForMode(mode);
+    if (trigger.kind === "pull_request" && mode !== "report")
+        return { ...base, "pull-requests": "write" };
+    return base;
+}
+/**
+ * Every scope `GITHUB_TOKEN` accepts in a workflow's `permissions:` mapping,
+ * kebab-cased as GitHub spells them. An additive scope outside this set is
+ * refused by name rather than emitted: GitHub ignores an unknown key, so
+ * `id_token` or `idToken` would generate a workflow that looks like it grants
+ * OIDC and hands the run no token at all.
+ */
+export const GITHUB_TOKEN_SCOPES = new Set([
+    "actions",
+    "attestations",
+    "checks",
+    "contents",
+    "deployments",
+    "discussions",
+    "id-token",
+    "issues",
+    "models",
+    "packages",
+    "pages",
+    "pull-requests",
+    "repository-projects",
+    "security-events",
+    "statuses",
+]);
+/**
+ * Merge a spec's additive `permissions` over the finding-mode's own set
+ * (#2242), refusing by name anything that is not strictly additive:
+ *
+ *  - a blanket `write-all`/`read-all`, in either the key or the value
+ *    position, which is the exact thing {@link permissionsForMode} exists to
+ *    avoid;
+ *  - a scope GitHub does not define ({@link GITHUB_TOKEN_SCOPES}), because
+ *    GitHub ignores the key and the run silently gets nothing;
+ *  - a scope the mode already grants, at any value — additive means additive,
+ *    so this can neither downgrade `contents: write` to read nor restate it.
+ *    A mode whose set is wrong is fixed by changing the mode, where the
+ *    scope and the behavior that spends it stay together;
+ *  - `pull-requests: write` on a trigger with no pull request. Pull-request
+ *    access is what the finding-modes own: `pull-request` grants it together
+ *    with the `contents: write` needed to push the branch first, and
+ *    `comment` grants it on the one trigger that carries a pull request to
+ *    comment on. Adding it beside a mode that posts nothing, on a cron or
+ *    push run, grants write access no step in the generated job can spend.
+ */
+export function mergePermissions(name, base, additive, trigger) {
+    const merged = { ...base };
+    for (const [rawScope, value] of Object.entries(additive)) {
+        const scope = rawScope.trim();
+        const where = `Scheduled Op "${name}" adds permission "${scope}: ${value}"`;
+        if (scope === "write-all" || scope === "read-all" || String(value).endsWith("-all")) {
+            throw new Error(`${where}, a blanket grant. \`permissions\` on a scheduled Op is additive over the ` +
+                `least-privilege set its finding-mode needs, one named scope at a time. Name the scopes the ` +
+                `job actually spends (e.g. { "id-token": "write" }).`);
+        }
+        if (!GITHUB_TOKEN_SCOPES.has(scope)) {
+            throw new Error(`${where}, which is not a GITHUB_TOKEN permission scope. GitHub ignores an unrecognized key, so ` +
+                `this would emit a workflow that reads as granted and hands the run nothing. Known scopes: ` +
+                `${[...GITHUB_TOKEN_SCOPES].sort().join(", ")}.`);
+        }
+        if (scope in base) {
+            throw new Error(`${where}, but its finding-mode already grants "${scope}: ${base[scope]}". These permissions are ` +
+                `additive only — they never replace, widen or downgrade a scope the mode computed. Change the ` +
+                `Op's findingMode if that set is wrong, and add only scopes no mode grants (e.g. "id-token").`);
+        }
+        if (scope === "pull-requests" && trigger.kind !== "pull_request") {
+            throw new Error(`${where}, but this Op's trigger is "${trigger.kind}", which carries no pull request. Pull-request ` +
+                `write access belongs to a finding-mode: "pull-request" grants it with the contents: write its ` +
+                `branch push needs, and "comment" grants it on the pull_request trigger. Set findingMode instead ` +
+                `of adding the scope here.`);
+        }
+        merged[scope] = value;
+    }
+    return merged;
+}
+/**
+ * Refs that name an action repository's own default branch. A generated
+ * workflow is committed once and then re-run unattended, often over a cloud
+ * role, so "whatever was pushed to that repo last" is not a version — the
+ * code that assumes the role can change between the run somebody reviewed and
+ * the next one. A release channel the action's author cuts deliberately (`v6`,
+ * `v6.2.4`, `stable`) or a commit sha is a version, and both pass.
+ */
+const DEFAULT_BRANCH_REFS = new Set(["main", "master", "head", "default"]);
+/** `owner/repo` or `owner/repo/subpath`, then `@ref`. */
+const USES_PATTERN = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)((?:\/[A-Za-z0-9_.-]+)*)@([^\s@]+)$/;
+/**
+ * Validate a `setup` list for GitHub or Forgejo Actions (#2242). A `run`
+ * entry needs a non-empty line and nothing else. A `uses` entry has to be a
+ * pinned `owner/repo[/subpath]@ref`: no bare `owner/repo`, since an unpinned
+ * action resolves to its default branch, and no ref in
+ * {@link DEFAULT_BRANCH_REFS} for the same reason spelled out loud. Local
+ * (`./path`) and container (`docker://`) refs are refused too — they are
+ * legal GitHub Actions, but the generator emits a workflow into a repository
+ * it has never seen, so it cannot know a local path resolves there.
+ */
+export function assertSetupSteps(name, setup) {
+    setup.forEach((step, index) => {
+        const where = `Scheduled Op "${name}" setup step ${index + 1}`;
+        if ("uses" in step) {
+            const ref = step.uses.trim();
+            const match = USES_PATTERN.exec(ref);
+            if (!match) {
+                throw new Error(`${where} has \`uses: "${step.uses}"\`, which is not a pinned action reference. ` +
+                    `Write it as owner/repo@ref (optionally owner/repo/subpath@ref), e.g. ` +
+                    `"aws-actions/configure-aws-credentials@v6". A local "./path" or "docker://" ref is not ` +
+                    `accepted here: this generator emits a workflow into a repository it cannot inspect, so it ` +
+                    `has no way to tell whether such a ref resolves there.`);
+            }
+            const gitRef = match[4];
+            if (DEFAULT_BRANCH_REFS.has(gitRef.toLowerCase())) {
+                throw new Error(`${where} pins \`uses: "${step.uses}"\` to "${gitRef}", the action repository's own default ` +
+                    `branch, which names whatever was pushed there last rather than a version. A generated ` +
+                    `workflow is committed once and re-run unattended, often over a cloud role, so pin a release ` +
+                    `tag or a commit sha instead (e.g. "${match[1]}/${match[2]}@v1" or "@<40-char sha>").`);
+            }
+            return;
+        }
+        if (step.run.trim() === "") {
+            throw new Error(`${where} has an empty \`run\` line. Give it a command, or drop the entry.`);
+        }
+    });
+}
+/** One setup entry as a GitHub Actions step: `with:` and `env:` only when they hold something. */
+export function setupStepDoc(step) {
+    if ("uses" in step) {
+        return {
+            uses: step.uses,
+            ...nonEmpty("with", step.with),
+            ...nonEmpty("env", step.env),
+        };
+    }
+    return { run: step.run, ...nonEmpty("env", step.env) };
+}
+/**
+ * Validate an `environment` for GitHub Actions (#2257). GitHub creates an
+ * environment it has never seen on first use rather than failing the run,
+ * and an environment created that way carries no protection rules at all —
+ * so a job can name one and read as gated while being gated by nothing.
+ * Neither the generator nor GitHub can tell those apart at build time, which
+ * is why what is refused here is only the shape that could never bind: a
+ * name that is blank, and a `url` that is neither absolute nor an expression
+ * the forge resolves.
+ */
+export function assertEnvironment(name, environment) {
+    const where = `Scheduled Op "${name}" environment`;
+    if (environment.name.trim() === "") {
+        throw new Error(`${where} has an empty \`name\`. An environment is named repository configuration — the ` +
+            `protection rules and reviewers live on the environment, not in this workflow — so there is ` +
+            `nothing for a blank name to resolve to. Give it the environment's name, or drop the option.`);
+    }
+    if (environment.url === undefined)
+        return;
+    const url = environment.url.trim();
+    if (url === "") {
+        throw new Error(`${where} "${environment.name}" has an empty \`url\`. Omit the field rather than setting it to "".`);
+    }
+    if (!/^https?:\/\//.test(url) && !url.includes("${{")) {
+        throw new Error(`${where} "${environment.name}" has \`url: "${environment.url}"\`, which is neither an absolute ` +
+            `http(s) URL nor a \${{ }} expression. GitHub renders this value as the deployment's own link, ` +
+            `so a relative path becomes a dead link on the environment page rather than an error anywhere. ` +
+            `Write the full URL, or an expression the run resolves to one.`);
+    }
+}
+// ── GitLab CI ───────────────────────────────────────────────────────────────
+/** The pipeline source GitLab reports for a merge-request pipeline. */
+export const GITLAB_MERGE_REQUEST_SOURCE = '$CI_PIPELINE_SOURCE == "merge_request_event"';
+/** The pipeline source GitLab reports for a pipeline schedule. */
+export const GITLAB_SCHEDULE_SOURCE = '$CI_PIPELINE_SOURCE == "schedule"';
+/** A job variable that makes the runner clone the whole history, which a job reading the base commit needs. */
+export const GITLAB_FULL_HISTORY = { GIT_DEPTH: "0" };
+/** The `rules:` if-expression for a push to `branch`, a quoted name or an expression such as `$CI_DEFAULT_BRANCH`. */
+export function gitlabPushRule(branch) {
+    return `$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == ${branch}`;
+}
+/**
+ * Refuse a branch name that cannot be interpolated into a `rules:`
+ * if-expression. The expression is a string GitLab parses, so a `"` would end
+ * it early and a `$` would expand as a variable — either one silently changes
+ * which pipelines match the job, which is worse than not generating it.
+ * `subject` names what filters, such as `Scheduled Op "apply"`.
+ */
+export function assertGitlabBranch(subject, branch) {
+    if (branch.trim() === "") {
+        throw new Error(`${subject} has an empty branch filter. Name a branch, or drop the filter.`);
+    }
+    if (/["$\\]/.test(branch)) {
+        throw new Error(`${subject} filters on branch "${branch}", which carries a character this generator ` +
+            `cannot put in a GitLab \`rules:\` expression: a quote would end the expression early and a "$" ` +
+            `would expand as a CI/CD variable, either of which silently changes which pipelines run the job. ` +
+            `Name a branch without \`"\`, \`$\` or \`\\\`.`);
+    }
+}
+/**
+ * One `rules:` entry per branch a trigger filters on, each checked by
+ * {@link assertGitlabBranch}. Two or more branches are two or more entries:
+ * `rules:` is an OR over its list, which is how GitLab spells the alternation
+ * github expresses as a `branches:` array. A cron trigger is selected by
+ * `selector`, the CI/CD variable a pipeline schedule sets, and the Op's name.
+ */
+export function gitlabRules(subject, trigger, selector) {
+    switch (trigger.kind) {
+        case "cron":
+            return [{ if: `${GITLAB_SCHEDULE_SOURCE} && $${selector.variable} == "${selector.value}"` }];
+        case "pull_request": {
+            const branches = triggerBranches(trigger);
+            if (!branches)
+                return [{ if: GITLAB_MERGE_REQUEST_SOURCE }];
+            return branches.map((branch) => {
+                assertGitlabBranch(subject, branch);
+                return { if: `${GITLAB_MERGE_REQUEST_SOURCE} && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "${branch}"` };
+            });
+        }
+        case "push":
+            return pushBranches(trigger.branches).map((branch) => {
+                assertGitlabBranch(subject, branch);
+                return { if: gitlabPushRule(JSON.stringify(branch)) };
+            });
+    }
+}
+/**
+ * The `id_tokens:` entry an `id-token: write` spec gets. The name is the
+ * environment variable the JWT lands in, which the job's own setup line reads
+ * (`aws sts assume-role-with-web-identity --web-identity-token
+ * "$CHANT_ID_TOKEN"`, or the provider's equivalent).
+ *
+ * `$CI_SERVER_URL` as the audience is GitLab's own documented default: an
+ * identity provider federated to a GitLab instance is registered with that
+ * instance's URL as its audience, and the variable expands to exactly that on
+ * gitlab.com and on a self-managed instance alike.
+ */
+export const GITLAB_ID_TOKEN_NAME = "CHANT_ID_TOKEN";
+export const GITLAB_ID_TOKEN_AUDIENCE = "$CI_SERVER_URL";
+/**
+ * Turn additive `permissions` (#2242) into the one GitLab declaration that
+ * carries the same meaning, refusing everything else by name.
+ *
+ * `id-token: write` is that one: GitLab's OIDC surface is `id_tokens:`, a
+ * per-job declaration of a JWT the job exchanges for cloud credentials
+ * itself. `id-token: read` is refused rather than mapped, because GitLab
+ * either mints the token into the job or does not. Every other scope is
+ * refused: GitLab has no per-job token-scope mapping at all, and a scope
+ * quietly dropped would emit a job that reads as granted and runs with
+ * nothing.
+ */
+export function gitlabIdTokens(name, permissions) {
+    let wantsIdToken = false;
+    for (const [rawScope, value] of Object.entries(permissions ?? {})) {
+        const scope = rawScope.trim();
+        if (scope === "id-token") {
+            if (value !== "write") {
+                throw new Error(`Scheduled Op "${name}" adds permission "id-token: ${value}", but GitLab either mints an ` +
+                    `OIDC token into a job or does not — there is no read-only half of an \`id_tokens:\` ` +
+                    `declaration. Ask for { "id-token": "write" }, or drop the option.`);
+            }
+            wantsIdToken = true;
+            continue;
+        }
+        throw new Error(`Scheduled Op "${name}" adds permission "${scope}: ${value}", but GitLab CI has no per-job ` +
+            `token-scope mapping — there is no \`permissions:\` key to add it to (#2242). The one scope that ` +
+            `does cross over is "id-token": "write", which becomes an \`id_tokens:\` declaration. Drop the ` +
+            `option here, or generate this Op for github.`);
+    }
+    return wantsIdToken ? { [GITLAB_ID_TOKEN_NAME]: { aud: GITLAB_ID_TOKEN_AUDIENCE } } : undefined;
+}
+/**
+ * A `setup` list as GitLab `script:` lines. A `uses` entry is a GitHub
+ * Actions marketplace action, which GitLab has no shape for, so it is refused
+ * by name rather than dropped. `subject` names whose setup it is, such as
+ * `Scheduled Op "apply"`.
+ */
+export function gitlabSetupScript(subject, setup) {
+    return (setup ?? []).map((step, index) => {
+        if ("uses" in step) {
+            throw new Error(`${subject} setup step ${index + 1} is \`uses: "${step.uses}"\`, a GitHub Actions ` +
+                `marketplace action. GitLab CI jobs run \`script\` lines only, so there is nothing to translate it ` +
+                `into (#2242). Express the setup as a \`{ run }\` entry, or generate it for github/forgejo.`);
+        }
+        return step.run;
+    });
+}
+/**
+ * Validate an `environment` on GitLab's own terms (#2257). A GitLab job
+ * naming an environment that does not exist creates an unprotected one on
+ * first deploy rather than failing, so the only shapes worth refusing at
+ * build time are the ones that could never bind: a blank name, and a `url`
+ * that is neither absolute nor a variable expression GitLab expands, which
+ * would render as a dead "View deployment" link.
+ */
+export function assertGitlabEnvironment(name, environment) {
+    const where = `Scheduled Op "${name}" environment`;
+    if (environment.name.trim() === "") {
+        throw new Error(`${where} has an empty \`name\`. A GitLab environment is a project object, and its approval ` +
+            `rules live on that object rather than in this file, so a blank name resolves to nothing. ` +
+            `Give it the environment's name, or drop the option.`);
+    }
+    if (environment.url === undefined)
+        return;
+    const url = environment.url.trim();
+    if (url === "") {
+        throw new Error(`${where} "${environment.name}" has an empty \`url\`. Omit the field rather than setting it to "".`);
+    }
+    if (!/^https?:\/\//.test(url) && !url.includes("$")) {
+        throw new Error(`${where} "${environment.name}" has \`url: "${environment.url}"\`, which is neither an absolute ` +
+            `http(s) URL nor a variable expression GitLab expands. It becomes the environment's own link, ` +
+            `so a relative path is a dead link on the environment page rather than an error anywhere.`);
+    }
+}

package/dist/cli/flush.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Exiting without truncating piped output, shared by the full CLI (`./main.ts`)
+ * and the slim wave-job runtime (`../wave-runtime.ts`, #3896).
+ */
+/**
+ * Wait until a writable stream has flushed its buffer. `process.exit()` discards
+ * data still buffered for an async sink (a pipe or file), truncating large output
+ * at the ~64 KB pipe buffer — so `chant graph --format ir` piped into a consumer
+ * loses everything past 64 KB and its JSON won't parse. A TTY writes
+ * synchronously (`writableLength` stays 0), so this is a no-op there. Resolves on
+ * `error`/`close` too, so a reader that closes early (EPIPE) can't hang exit.
+ */
+export declare function waitForStreamDrain(stream: NodeJS.WriteStream): Promise<void>;
+/** Flush stdout+stderr, then exit — so a large piped payload isn't truncated. */
+export declare function flushAndExit(code: number): Promise<never>;
+//# sourceMappingURL=flush.d.ts.map

package/dist/cli/flush.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush.d.ts","sourceRoot":"","sources":["../../src/cli/flush.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB5E;AAED,iFAAiF;AACjF,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAI/D"}

package/dist/cli/flush.js

@@ -0,0 +1,42 @@
+/**
+ * Exiting without truncating piped output, shared by the full CLI (`./main.ts`)
+ * and the slim wave-job runtime (`../wave-runtime.ts`, #3896).
+ */
+/**
+ * Wait until a writable stream has flushed its buffer. `process.exit()` discards
+ * data still buffered for an async sink (a pipe or file), truncating large output
+ * at the ~64 KB pipe buffer — so `chant graph --format ir` piped into a consumer
+ * loses everything past 64 KB and its JSON won't parse. A TTY writes
+ * synchronously (`writableLength` stays 0), so this is a no-op there. Resolves on
+ * `error`/`close` too, so a reader that closes early (EPIPE) can't hang exit.
+ */
+export function waitForStreamDrain(stream) {
+    return new Promise((resolve) => {
+        const tick = () => {
+            if (stream.writableLength === 0 || stream.writableEnded || stream.destroyed) {
+                cleanup();
+                resolve();
+                return;
+            }
+            stream.once("drain", tick);
+        };
+        const stop = () => {
+            cleanup();
+            resolve();
+        };
+        const cleanup = () => {
+            stream.off("drain", tick);
+            stream.off("error", stop);
+            stream.off("close", stop);
+        };
+        stream.once("error", stop);
+        stream.once("close", stop);
+        tick();
+    });
+}
+/** Flush stdout+stderr, then exit — so a large piped payload isn't truncated. */
+export async function flushAndExit(code) {
+    await waitForStreamDrain(process.stdout);
+    await waitForStreamDrain(process.stderr);
+    process.exit(code);
+}

package/dist/cli/handlers/approve.d.ts

@@ -0,0 +1,98 @@
+import type { GateResolutionRecord, PendingGateRecord } from "../../lifecycle/gate-ledger.js";
+import { type GateOrigin } from "../../lifecycle/gate-origin.js";
+import { type GatePolicyEvaluator, type ResolvedGateApproval } from "../../op/gate-approval.js";
+import type { CommandContext } from "../registry.js";
+export declare function runApprove(ctx: CommandContext): Promise<number>;
+/** What a caller supplies alongside the op and gate names. */
+export interface GateApprovalOptions {
+    /**
+     * The channel this resolution arrived on (chant#2384). Defaults to the
+     * process's own — `"cli"` unless an entry point declared otherwise — and is
+     * a parameter only so a caller that knows better can say so.
+     */
+    origin?: GateOrigin;
+    /**
+     * Record a resolution that the same-origin rule would refuse (chant#2384).
+     *
+     * There is a legitimate case: a single operator driving an agent, who wants
+     * the model's run resolved from the same session and accepts what that
+     * means. The override exists so that is a deliberate act with a trace on the
+     * record, rather than the default.
+     */
+    allowSameOrigin?: boolean;
+    /** `--actor`/`--approver`; falls back to the CI or shell identity. */
+    actor?: string;
+    /** `--note` — free-text prose. */
+    note?: string;
+    /**
+     * `--relayed-by <principal>` (#3402): who carried this approval to chant for
+     * the approver, such as a follower program relaying a person's approval.
+     * Recorded as `relayedBy` on the resolution line and covered by `--sign`.
+     * The approver is still `--actor`; the relay is not an approver.
+     */
+    relayedBy?: string;
+    /** `--url` — the approval surface, validated as absolute http/https. */
+    url?: string;
+    /**
+     * `--plan <digest>` (#2300) — the plan this approval is for. Omitted, the
+     * digest is read off the gate's standing pending fact, so the common path
+     * stays one command: run, read what it planned, approve it.
+     */
+    plan?: string;
+    /**
+     * `--env <env>` (#2574) — which environment's pending fact a component gate
+     * approval answers. A component's gate ledger holds every environment's
+     * facts, so without it the newest one is approved. Ignored for a gate whose
+     * pending facts record no environment (every Op gate).
+     */
+    environment?: string;
+    /** `--role` (#2508) — roles the approver claims. */
+    roles?: string[];
+    /**
+     * `--agent` (#2508) — record this as an agent's approval. On a
+     * model-authored channel it is one whether or not this is set.
+     */
+    agent?: boolean;
+    /**
+     * `--sign [<key file>]` (#3163, ws-080): seal the approval with an ssh key,
+     * a key file or true for git's `user.signingkey`. The seal attests the
+     * approver when the signers file at base lists the key for them, and a gate
+     * the declaration's `identity.gates` names counts only sealed approvals.
+     */
+    sign?: string | true;
+    /** Where the workspace and the key file are looked up from. Defaults to the process's directory. */
+    cwd?: string;
+    /** Replaces the lexicon evaluator a gate policy is loaded from. For tests. */
+    evaluator?: GatePolicyEvaluator;
+}
+export type GateApprovalOutcome = {
+    ok: true;
+    record: GateResolutionRecord;
+    pushed: boolean;
+} | {
+    ok: false;
+};
+/**
+ * The ledger write behind `chant approve` — extracted so `chant run approve`
+ * (#2121) records the identical fact before waking the runtime that hosts the
+ * gated run, instead of growing a second, drifting writer.
+ *
+ * Prints the same warning for an undiscovered op and the same success line as
+ * `chant approve` always did; the caller adds whatever it does next.
+ *
+ * Since #2300 the resolution names the plan it approves. By default that is
+ * the standing pending fact's plan — the one the gated run produced — so the
+ * common path is still `chant run`, read, `chant approve`. With no pending
+ * fact and no `--plan`, this refuses: there is nothing on the ledger saying
+ * what would be approved, and writing a resolution anyway is what made an
+ * approval mean "the next run" instead of "this plan".
+ */
+export declare function recordGateApproval(opName: string, gate: string, opts: GateApprovalOptions): Promise<GateApprovalOutcome>;
+/**
+ * What a just-recorded approval did to a gate with an `approval` block
+ * (#2508): the policy's decision and whether it binds, then the quorum count
+ * for this plan. The run decides the gate from the ledger; these lines only
+ * say what it will find.
+ */
+export declare function describeApprovalProgress(approval: ResolvedGateApproval, record: GateResolutionRecord, prior: GateResolutionRecord[], standing: PendingGateRecord | undefined, pending?: readonly PendingGateRecord[]): string[];
+//# sourceMappingURL=approve.d.ts.map

package/dist/cli/handlers/approve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approve.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/approve.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAC3F,OAAO,EACuE,KAAK,UAAU,EAC5F,MAAM,6BAA6B,CAAC;AAOrC,OAAO,EAEuC,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAChG,MAAM,wBAAwB,CAAC;AAOhC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAkDlD,wBAAsB,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuGrE;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,oGAAoG;IACpG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC3D;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AAElB;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAiT9B;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,oBAAoB,EAAE,EAC7B,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EACvC,OAAO,GAAE,SAAS,iBAAiB,EAA+B,GACjE,MAAM,EAAE,CA8BV"}