@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/checks.js

@@ -0,0 +1,426 @@
+/**
+ * Declaration checks (#2535; #2524 D16, ws-028).
+ *
+ * A {@link WorkspaceCheck} looks at the declaration, the tree it describes
+ * and the kinds the workspace can read, and returns findings in the
+ * post-synth diagnostic shape with a `WSP` id. `chant workspace check` runs
+ * them and prints the findings through lint's reporters, so `--format json`
+ * and `--format sarif` come for free. `chant lint` never loads this module.
+ *
+ * The declaration sets the severity of a check through `checks`, and
+ * suppresses a check for one entry through that entry's `suppress`. Some
+ * checks are fixed: an unknown kind, a tie between probes and a probe that
+ * claims an `other` directory always fail (#2524 D3), and a declaration that
+ * can't be read has no settings to apply.
+ *
+ * Checks that need more than the declaration and the tree read facts
+ * gathered before any check runs ({@link WorkspaceFacts}): member ledgers
+ * (./checks/ledgers.ts), recorded pipelines (./checks/pipelines.ts) and
+ * generated files (./checks/generated.ts). All of them share one id range
+ * (#2641):
+ *
+ * | Ids | Checks |
+ * |---|---|
+ * | WSP001 to WSP011 | the declaration and member kinds (this file) |
+ * | WSP071, WSP072 | member ledgers |
+ * | WSP081 to WSP083 | recorded pipelines |
+ * | WSP091 to WSP098 | member links (#2539, #2558) |
+ * | WSP101 to WSP106 | generated files |
+ * | WSP111 to WSP114 | records read with `--kind` (#2549) |
+ * | WSP115 | the record kinds the declaration names (#2680) |
+ * | WSP116 | the decision points file of each declared answer kind (ws-058) |
+ * | WSP117 | a done work item's acceptance criteria all met (#2772) |
+ * | WSP121, WSP122 | boxes: no literal credential, every capability brokered (#2726) |
+ * | WSP123, WSP124 | box isolation: no shared port, state path or cookie, no literal machine path (#2727) |
+ * | WSP125 | boxes: a fountain Box declares the callback token fountain gives its sandbox (#2780) |
+ * | WSP126, WSP127 | box intent: the decision record a box names exists, and constrains a member or path of this workspace (#2850, #2857) |
+ * | WSP141, WSP142 | member links resolved against a live read, with `--live` (#2549) |
+ * | WSP131 to WSP133 | diagram artifacts: source and render exist, a recorded source hash still matches (#2764) |
+ */
+import { realpathSync } from "node:fs";
+import { relative, sep } from "node:path";
+import { readDeclaration, resolveGroups, WorkspaceReadError } from "./declaration.js";
+import { parseJsonText, pointerToken } from "./jsonc.js";
+import { loadKindRegistry, probeKind, resolveKind, resolveMemberFields } from "./kinds.js";
+import { coreClassRegistry, loadClassRegistry, unknownScopeClasses } from "./principal-classes.js";
+import { gitTop, workingTree } from "./tree.js";
+import { LINK_CHECKS, linkTable } from "./checks/links.js";
+import { gatherGeneratedFacts, GENERATED_CHECKS } from "./checks/generated.js";
+import { gatherLedgerFacts, LEDGER_CHECKS } from "./checks/ledgers.js";
+import { gatherPipelineFacts, PIPELINE_CHECKS } from "./checks/pipelines.js";
+import { gatherLiveLinkFacts, LIVE_CHECKS } from "./checks/live.js";
+import { RECORD_CHECKS } from "./checks/records.js";
+import { BOX_CHECKS } from "./checks/boxes.js";
+import { DIAGRAM_CHECKS } from "./checks/diagrams.js";
+import { loadDeclaredKinds } from "./declared-kinds.js";
+import { resolveBoxIntents } from "./box-intent.js";
+const HELP = "https://intentius.io/chant/cli/workspace-check/#declaration-checks";
+const memberDir = (dir) => (dir === "." ? "" : dir);
+function entryFinding(check, entry, field, message) {
+    return {
+        checkId: check.id,
+        severity: check.severity,
+        message,
+        entity: entry.name,
+        pointer: field ? `${entry.pointer}/${field}` : entry.pointer,
+    };
+}
+/** The dir exists and the kind is known: the members every probe check reads. */
+function readableMembers(ctx) {
+    return ctx.declaration.members.filter((m) => ctx.tree.stat(memberDir(m.dir)) === "dir" && ctx.kinds.get(m.kind) !== undefined);
+}
+/** The first id of the read failure, used by {@link runDeclarationChecks} when the declaration can't be read. */
+export const UNREADABLE_CHECK_ID = "WSP001";
+export const WORKSPACE_CHECKS = [
+    {
+        id: "WSP001",
+        name: "declaration-unreadable",
+        description: "The declaration can be read: it parses, matches the schema and keeps the placement rules.",
+        severity: "error",
+        configurable: false,
+        // Reported by runDeclarationChecks, since a declaration that can't be read gives no context.
+        check: () => [],
+    },
+    {
+        id: "WSP002",
+        name: "kinds-unreadable",
+        description: "Every pinned package's kinds and principal classes can be read: it is installed at the pinned version, its ./workspace-kinds file is valid kind data, and its ./workspace-principals file is valid class data.",
+        severity: "error",
+        configurable: false,
+        check(ctx) {
+            // A pin that can't be read is a problem for both loaders; report it once.
+            const seen = new Set();
+            return [...ctx.kindProblems, ...(ctx.classProblems ?? [])]
+                .filter((p) => {
+                const key = `${p.pin}\0${p.message}`;
+                if (seen.has(key))
+                    return false;
+                seen.add(key);
+                return true;
+            })
+                .map((p) => ({ checkId: this.id, severity: this.severity, message: p.message, pointer: `/pins/${p.pin}` }));
+        },
+    },
+    {
+        id: "WSP003",
+        name: "kind-unknown",
+        description: "Every member's kind is built in or supplied by a pinned package, and so is every principal class writeScope names (#3080). Unknown kinds and classes fail closed.",
+        severity: "error",
+        configurable: false,
+        check(ctx) {
+            const members = ctx.declaration.members
+                .filter((m) => ctx.kinds.get(m.kind) === undefined)
+                .map((m) => entryFinding(this, m, "kind", `member ${m.name} has kind ${m.kind}, which no built-in kind or pinned package supplies; known kinds: ${ctx.kinds.names().join(", ")}`));
+            const classes = ctx.classes ?? coreClassRegistry();
+            const scope = unknownScopeClasses(ctx.declaration.writeScope, classes).map((c) => ({
+                checkId: this.id,
+                severity: this.severity,
+                message: `writeScope names the principal class ${c}, which no core class or pinned package supplies, so a writer judged human is refused with write-scope-class-unknown; known classes: ${classes.names().join(", ")}`,
+                entity: c,
+                pointer: `/writeScope/${pointerToken(c)}`,
+            }));
+            return [...members, ...scope];
+        },
+    },
+    {
+        id: "WSP004",
+        name: "member-dir-missing",
+        description: "Every member's directory exists.",
+        severity: "error",
+        configurable: true,
+        check(ctx) {
+            return ctx.declaration.members
+                .filter((m) => ctx.tree.stat(memberDir(m.dir)) !== "dir")
+                .map((m) => entryFinding(this, m, "dir", `member ${m.name}'s directory ${m.dir} does not exist${ctx.tree.label}`));
+        },
+    },
+    {
+        id: "WSP005",
+        name: "kind-probe-failed",
+        description: "Every member's directory is what its kind reads, such as a chant config for a chant member, and its fields are ones its kind declares, of the declared types (#3151).",
+        severity: "error",
+        configurable: true,
+        check(ctx) {
+            const probes = readableMembers(ctx)
+                .filter((m) => !probeKind(ctx.kinds.get(m.kind), ctx.tree, memberDir(m.dir)))
+                .map((m) => entryFinding(this, m, "kind", `member ${m.name} (${m.dir}) is not ${ctx.kinds.get(m.kind).description}`));
+            // A member's fields (#3151): checked whether or not its directory exists, since they are the entry's own.
+            const fields = ctx.declaration.members.flatMap((m) => resolveMemberFields(ctx.kinds.get(m.kind), m.fields).problems.map((p) => entryFinding(this, m, p.path === "" ? "fields" : `fields/${p.path.split("/").map(pointerToken).join("/")}`, `member ${m.name}: ${p.message}`)));
+            return [...probes, ...fields];
+        },
+    },
+    {
+        id: "WSP006",
+        name: "kind-probe-tie",
+        description: "No directory is claimed by two kinds of the same highest precedence. Ties fail.",
+        severity: "error",
+        configurable: false,
+        check(ctx) {
+            const out = [];
+            for (const m of readableMembers(ctx)) {
+                const { tie } = resolveKind(ctx.kinds, ctx.tree, memberDir(m.dir), m.dir === "." ? ["workspace"] : []);
+                if (tie.length === 0)
+                    continue;
+                const names = tie.map((k) => `${k.name} (${k.source})`).join(" and ");
+                out.push(entryFinding(this, m, "kind", `the probes of ${names} all claim ${m.dir} with precedence ${tie[0].precedence}; a tie fails, so one of those kinds needs a different precedence`));
+            }
+            return out;
+        },
+    },
+    {
+        id: "WSP007",
+        name: "kind-outranked",
+        description: "When several kinds claim a member's directory, the declared kind is the one the precedence order picks.",
+        severity: "error",
+        configurable: true,
+        check(ctx) {
+            const out = [];
+            for (const m of readableMembers(ctx)) {
+                if (m.kind === "other")
+                    continue;
+                const { winner } = resolveKind(ctx.kinds, ctx.tree, memberDir(m.dir), m.dir === "." ? ["workspace"] : []);
+                if (!winner || winner.name === m.kind)
+                    continue;
+                out.push(entryFinding(this, m, "kind", `member ${m.name} is declared ${m.kind}, and kind ${winner.name} (precedence ${winner.precedence}) claims ${m.dir} first; declare it as ${winner.name}`));
+            }
+            return out;
+        },
+    },
+    {
+        id: "WSP008",
+        name: "other-claimed",
+        description: "No other member's directory is claimed by a registered kind's probe.",
+        severity: "error",
+        configurable: false,
+        check(ctx) {
+            const out = [];
+            for (const m of readableMembers(ctx)) {
+                if (m.kind !== "other")
+                    continue;
+                const { claims } = resolveKind(ctx.kinds, ctx.tree, memberDir(m.dir), m.dir === "." ? ["workspace"] : []);
+                if (claims.length === 0)
+                    continue;
+                out.push(entryFinding(this, m, "kind", `member ${m.name} is declared other, and kind ${claims[0].name} claims ${m.dir}: it is ${claims[0].description}; declare it as ${claims[0].name}`));
+            }
+            return out;
+        },
+    },
+    {
+        id: "WSP009",
+        name: "other-member",
+        description: "A member of kind other is one chant does not read. It is reported so that it stays a decision.",
+        severity: "warning",
+        configurable: true,
+        check(ctx) {
+            return ctx.declaration.members
+                .filter((m) => m.kind === "other")
+                .map((m) => entryFinding(this, m, null, `member ${m.name} (${m.dir}) is kind other, which chant does not read: ${m.because}`));
+        },
+    },
+    {
+        id: "WSP010",
+        name: "group-empty",
+        description: "Every example group matches at least one chant project.",
+        severity: "warning",
+        configurable: true,
+        check(ctx) {
+            return ctx.groups
+                .filter((g) => g.matches.length === 0)
+                .map((g) => entryFinding(this, g.group, "glob", `example group ${g.group.name} matches no chant project${ctx.tree.label}`));
+        },
+    },
+    {
+        id: "WSP011",
+        name: "check-settings-invalid",
+        description: "The declaration's checks and suppress settings name known, configurable WSP ids.",
+        severity: "error",
+        configurable: false,
+        check(ctx) {
+            const out = [];
+            for (const id of Object.keys(ctx.declaration.checks)) {
+                const problem = settingProblem(id);
+                if (problem)
+                    out.push({ checkId: this.id, severity: this.severity, message: `checks sets ${id}, which ${problem}`, pointer: `/checks/${pointerToken(id)}` });
+            }
+            for (const e of ctx.declaration.entries) {
+                e.suppress.forEach((s, i) => {
+                    const problem = settingProblem(s.check);
+                    if (problem)
+                        out.push(entryFinding(this, e, `suppress/${i}/check`, `${e.name} suppresses ${s.check}, which ${problem}`));
+                });
+            }
+            return out;
+        },
+    },
+    // Member ledgers (#2538).
+    ...LEDGER_CHECKS,
+    // Recorded pipelines (#2542).
+    ...PIPELINE_CHECKS,
+    // Member links (#2539, #2558), WSP091 to WSP098.
+    ...LINK_CHECKS,
+    // Generated files (#2541).
+    ...GENERATED_CHECKS,
+    // Records read with --kind (#2549).
+    ...RECORD_CHECKS,
+    // Boxes and their brokered capabilities (#2726).
+    ...BOX_CHECKS,
+    // Diagram artifacts (#2764).
+    ...DIAGRAM_CHECKS,
+    // Links resolved against a live read, with --live (#2549), WSP141 and WSP142.
+    ...LIVE_CHECKS,
+];
+const BY_ID = new Map(WORKSPACE_CHECKS.map((c) => [c.id, c]));
+function settingProblem(id) {
+    const check = BY_ID.get(id);
+    if (!check)
+        return `is not a declaration check; known checks: ${WORKSPACE_CHECKS.map((c) => c.id).join(", ")}`;
+    if (!check.configurable)
+        return `is fixed: it can't be turned down or suppressed`;
+    return undefined;
+}
+/**
+ * The checks' metadata as lint rules, for the SARIF reporter's rule list.
+ * They are never run as lint rules.
+ */
+export function workspaceCheckRules() {
+    return WORKSPACE_CHECKS.map((c) => ({
+        id: c.id,
+        severity: c.severity,
+        category: "correctness",
+        description: `${c.name}: ${c.description}`,
+        helpUri: HELP,
+        check: () => [],
+    }));
+}
+/** Run every check over a readable declaration. The settings are not applied yet. */
+export function runWorkspaceChecks(ctx) {
+    return WORKSPACE_CHECKS.flatMap((c) => c.check(ctx));
+}
+/**
+ * Apply the declaration's `checks` severities and entries' `suppress` to the
+ * findings. Fixed checks keep their severity and can't be suppressed; a
+ * setting that tries is itself a WSP011 finding.
+ */
+export function applyCheckSettings(declaration, findings) {
+    const active = [];
+    const suppressed = [];
+    const byName = new Map(declaration.entries.map((e) => [e.name, e]));
+    for (const f of findings) {
+        const check = BY_ID.get(f.checkId);
+        if (!check?.configurable) {
+            active.push(f);
+            continue;
+        }
+        const setting = declaration.checks[f.checkId];
+        if (setting === "off")
+            continue;
+        const finding = setting ? { ...f, severity: setting } : f;
+        const suppression = f.entity !== undefined ? byName.get(f.entity)?.suppress.find((s) => s.check === f.checkId) : undefined;
+        if (suppression)
+            suppressed.push({ ...finding, reason: suppression.because });
+        else
+            active.push(finding);
+    }
+    return { active, suppressed };
+}
+/**
+ * Gather {@link WorkspaceFacts} for the declaration in `root`. Member
+ * configs are read statically, never run: the ledger facts read `ownership`
+ * and `environments`, and the generated-file facts read `lexicons`. Declared
+ * generators run only when `runGenerators` says so, and they are the only
+ * member code this runs.
+ */
+export async function gatherWorkspaceFacts(root, declaration, options = {}) {
+    // Pipeline records hold paths relative to the repository root.
+    const top = gitTop(root);
+    const prefix = top ? relative(realpath(top), realpath(root)).split(sep).join("/") || "." : ".";
+    return {
+        ledgers: await gatherLedgerFacts(root, declaration),
+        pipelines: gatherPipelineFacts(root, declaration, prefix),
+        generated: await gatherGeneratedFacts(root, declaration, { runGenerators: options.runGenerators === true }),
+    };
+}
+function realpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * Read the declaration in `root` (an absolute directory holding one, or the
+ * files of `options.tree` when given, such as a revision's), load the kinds
+ * its pins supply from `root`, gather the facts the member checks read, run
+ * every check and apply the declaration's settings. `file` in the findings
+ * is the declaration's path as `display` says, relative to where the
+ * command runs. Never throws a {@link WorkspaceReadError}: a declaration that
+ * can't be read is one WSP001 finding.
+ */
+export async function runDeclarationChecks(root, display = (f) => f, options = {}) {
+    const tree = options.tree ?? workingTree(root);
+    let declaration;
+    let groups;
+    try {
+        declaration = readDeclaration(tree, "", { rootChant: true });
+        groups = resolveGroups(declaration, tree);
+    }
+    catch (err) {
+        if (!(err instanceof WorkspaceReadError))
+            throw err;
+        const location = err.location ?? { file: "chant.workspace.json", line: 1, column: 1 };
+        const diagnostic = {
+            file: display(location.file),
+            line: location.line,
+            column: location.column,
+            ruleId: UNREADABLE_CHECK_ID,
+            severity: "error",
+            message: `${err.code}: ${err.message}`,
+            code: err.code,
+        };
+        return { file: display(location.file), diagnostics: [diagnostic], suppressed: [], links: [], ok: false };
+    }
+    const { registry, problems } = loadKindRegistry(declaration.pins, root);
+    const classes = loadClassRegistry(declaration.pins, root, { tree });
+    const gathered = options.gather === false || options.tree ? {} : await gatherWorkspaceFacts(root, declaration, options);
+    // The declared record kinds load from the working tree; under --at only whether each exists at the revision is checked (#2680).
+    // A declared work kind's acceptance criteria are counted in the working tree too (#2772).
+    const declaredKinds = options.gather === false ? undefined : await loadDeclaredKinds(declaration, tree, root, { load: !options.tree, acceptance: !options.tree });
+    // A box's intent is read from the working tree's records, so not under --at (#2850).
+    const boxIntents = declaredKinds && !options.tree ? await resolveBoxIntents(declaration, root, declaredKinds) : undefined;
+    const facts = {
+        ...gathered,
+        ...(options.records ? { records: options.records } : {}),
+        ...(declaredKinds ? { declaredKinds } : {}),
+        ...(boxIntents ? { boxIntents } : {}),
+        ...(options.live && !options.tree ? { live: await gatherLiveLinkFacts(root, declaration, registry, options.live.env, options.live.onStderr) } : {}),
+    };
+    const ctx = { declaration, tree, groups, kinds: registry, kindProblems: problems, classes: classes.registry, classProblems: classes.problems, facts };
+    const findings = runWorkspaceChecks(ctx);
+    const { active, suppressed } = applyCheckSettings(declaration, findings);
+    const parsed = parseJsonText(tree.read(declaration.file), { jsonc: declaration.file.endsWith(".jsonc") });
+    const locate = (pointer) => (parsed.ok ? parsed.locate(pointer) : { line: 1, column: 1 });
+    const file = display(declaration.file);
+    const toFinding = (d) => ({
+        ...(d.treeFile !== undefined
+            ? { file: display(d.treeFile), line: d.line ?? 1, column: d.column ?? 1 }
+            : d.file !== undefined
+                ? { file: display(relative(root, d.file).split(sep).join("/")), line: 1, column: 1 }
+                : { file, ...locate(d.pointer) }),
+        ruleId: d.checkId,
+        severity: d.severity,
+        message: d.message,
+        ...(d.entity !== undefined ? { entity: d.entity } : {}),
+        ...(d.code !== undefined ? { code: d.code } : {}),
+    });
+    const order = (a, b) => a.line - b.line || a.column - b.column || (a.ruleId < b.ruleId ? -1 : a.ruleId > b.ruleId ? 1 : 0);
+    const diagnostics = active.map(toFinding).sort(order);
+    return {
+        file,
+        diagnostics,
+        suppressed: suppressed.map((s) => ({ ...toFinding(s), reason: s.reason })).sort(order),
+        links: linkTable(ctx),
+        ...(facts.live ? { live: { env: facts.live.env, links: facts.live.rows } } : {}),
+        ok: !diagnostics.some((d) => d.severity === "error"),
+    };
+}

package/dist/workspace/ci-green-cli.js

@@ -0,0 +1,125 @@
+/**
+ * `chant ci` (#3573, ws-103): which commits passed CI.
+ *
+ *   ci last-green [--json]               the newest commit on the branch with a green tag and no revoked tag
+ *   ci tick [--dry-run] [--forge github] tag the commits that turned green, revoke the ones that turned red
+ *   ci workflow [--workflow <name>]... [--output <file>] [--chant <command>] [--install <command>]
+ *               [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]
+ *                                        write the root CI file that runs the tick
+ *
+ * `last-green --json` prints `ci-last-green.schema.json`. The tick and the
+ * workflow print text.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { formatError } from "../cli/format.js";
+import { findWorkspaceRoot } from "../project-root.js";
+import { ciTick, CiGreenError, formatTick, lastGreen } from "./ci-green.js";
+import { ciForgeFromEnv } from "./ci-green-forge.js";
+import { ACTIONS_NAME, CI_GREEN_WORKFLOW_FILE, ciGreenHeader, readWorkflowSources, renderCiGreenWorkflow, workflowsHolding, writeWorkflowFile } from "./ci-green-workflow.js";
+import { readDeclaration, readerVersion, WorkspaceReadError } from "./declaration.js";
+import { recordGeneratedFiles, resolveMemberContext, shellArg } from "./member-pipeline.js";
+import { gitTop, workingTree } from "./tree.js";
+const USAGE = "chant ci last-green [--json] | ci tick [--dry-run] [--forge github] | ci workflow [--workflow <name>]... [--output <file>] [--chant <command>] [--install <command>] [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]";
+export async function runCiLastGreen(ctx) {
+    const doc = lastGreen({ cwd: process.cwd() });
+    if (ctx.args.json) {
+        console.log(JSON.stringify(doc, null, 2));
+        return "error" in doc ? 1 : 0;
+    }
+    if ("error" in doc) {
+        console.error(formatError({ message: doc.error.message, hint: USAGE }));
+        return 1;
+    }
+    if (!doc.commit) {
+        console.error(`No first-parent commit of ${doc.ref} has a ci/green tag without a ci/revoked one. Fetch the tags first: git fetch origin --tags`);
+        return 1;
+    }
+    console.log(doc.commit.sha);
+    return 0;
+}
+const describe = (err) => (err instanceof WorkspaceReadError ? err.describe() : err instanceof Error ? err.message : String(err));
+export async function runCiTick(ctx) {
+    try {
+        const forge = ciForgeFromEnv(ctx.args.forge ?? "github");
+        const result = await ciTick({ cwd: process.cwd(), forge, dryRun: ctx.args.dryRun === true });
+        console.log(formatTick(result, ctx.args.dryRun === true));
+        return 0;
+    }
+    catch (err) {
+        console.error(formatError({ message: `chant ci tick: ${describe(err)}`, hint: USAGE }));
+        return 1;
+    }
+}
+/** The push token the flags ask for, or none for the Actions token. Throws on a half-given or clashing pair. */
+function pushToken(args) {
+    const { ciTokenSecret: secret, ciAppIdVar: appIdVar, ciAppKeySecret: appKeySecret } = args;
+    for (const [flag, name] of [["--token-secret", secret], ["--app-id-var", appIdVar], ["--app-key-secret", appKeySecret]]) {
+        if (name !== undefined && !ACTIONS_NAME.test(name))
+            throw new Error(`${flag} takes a secret or variable name, letters, digits and underscores, not ${JSON.stringify(name)}`);
+    }
+    if (secret !== undefined && (appIdVar !== undefined || appKeySecret !== undefined))
+        throw new Error("--token-secret and --app-id-var/--app-key-secret each name the push token; pass one or the other");
+    if ((appIdVar === undefined) !== (appKeySecret === undefined))
+        throw new Error("a GitHub App token needs both the App's id and its key: --app-id-var <VAR> --app-key-secret <NAME>");
+    if (secret !== undefined)
+        return { secret };
+    if (appIdVar !== undefined && appKeySecret !== undefined)
+        return { appIdVar, appKeySecret };
+    return undefined;
+}
+export async function runCiWorkflow(ctx) {
+    const cwd = process.cwd();
+    try {
+        const push = pushToken(ctx.args);
+        const found = findWorkspaceRoot(cwd);
+        if (!found)
+            throw new WorkspaceReadError("declaration-missing", "no chant.workspace.json or .jsonc between this directory and the git root");
+        const declaration = readDeclaration(workingTree(found.dir));
+        const green = declaration.ci?.green;
+        if (!green)
+            throw new CiGreenError("ci-green-undeclared", `${declaration.file} declares no ci.green, so there is nothing for the workflow to run`);
+        // git reports its top with symlinks resolved (/private/var on macOS), so resolve the root too.
+        const root = realpathSync(found.dir);
+        const repoRoot = gitTop(root) ?? root;
+        const member = resolveMemberContext(cwd, found);
+        const target = ctx.args.output ? resolve(realpathSync(cwd), ctx.args.output) : join(repoRoot, CI_GREEN_WORKFLOW_FILE);
+        const fromRepo = relative(repoRoot, target).split(sep).join("/");
+        const scan = workflowsHolding(green, readWorkflowSources(repoRoot, fromRepo));
+        const extra = ctx.args.ciWorkflows ?? [];
+        const workflows = [...new Set([...scan.workflows, ...extra])].sort();
+        for (const f of scan.unreadable)
+            console.error(`warning: ${f} is not valid YAML, so its jobs were not read`);
+        for (const u of scan.unmatched)
+            console.error(`warning: no job in .github/workflows/ reports a check run matching ${JSON.stringify(u.pattern)} (phase ${u.phase}); pass --workflow <name> for the workflow that does`);
+        if (workflows.length === 0) {
+            throw new Error("no workflow in .github/workflows/ holds a check run of a required phase, so nothing would trigger the tick but its schedule; name one with --workflow <name>");
+        }
+        const base = member ? member.memberRoot : root;
+        const parts = ["chant", "ci", "workflow", ...extra.flatMap((w) => ["--workflow", w])];
+        if (ctx.args.output)
+            parts.push("--output", relative(base, target).split(sep).join("/"));
+        if (ctx.args.ciChant)
+            parts.push("--chant", ctx.args.ciChant);
+        if (ctx.args.ciInstall)
+            parts.push("--install", ctx.args.ciInstall);
+        if (push && "secret" in push)
+            parts.push("--token-secret", push.secret);
+        if (push && "appIdVar" in push)
+            parts.push("--app-id-var", push.appIdVar, "--app-key-secret", push.appKeySecret);
+        const command = parts.map(shellArg).join(" ");
+        const workspaceRoot = relative(repoRoot, root).split(sep).join("/") || ".";
+        // The install runs in the workspace root, so its lockfile there keys setup-node's npm cache.
+        const npmLock = ctx.args.ciInstall && existsSync(join(root, "package-lock.json")) ? (workspaceRoot === "." ? "package-lock.json" : `${workspaceRoot}/package-lock.json`) : undefined;
+        const yaml = renderCiGreenWorkflow({ green, workflows, chantVersion: readerVersion(), workspaceRoot, chant: ctx.args.ciChant, install: ctx.args.ciInstall, npmLock, push });
+        const written = writeWorkflowFile(target, ciGreenHeader(command, member ? "member" : "root") + yaml);
+        if (member)
+            recordGeneratedFiles(member.memberRoot, [{ path: fromRepo, command }]);
+        console.log(`Wrote ${written}: ticks when ${workflows.join(", ")} complete${workflows.length === 1 ? "s" : ""} on ${green.branch}, and every 15 minutes.`);
+        return 0;
+    }
+    catch (err) {
+        console.error(formatError({ message: `chant ci workflow: ${describe(err)}`, hint: USAGE }));
+        return 1;
+    }
+}

package/dist/workspace/ci-green-forge.js

@@ -0,0 +1,83 @@
+/**
+ * What `chant ci tick` asks of a forge (#3573, ws-103): every check run on a
+ * commit, every attempt of each, so the tick can judge a phase by each run's
+ * latest attempt.
+ *
+ * The tags themselves are git's, pushed to the remote like any other ref, so
+ * the forge is asked for check runs and nothing else. GitHub is the one
+ * forge implemented. Forgejo reports commit statuses rather than check runs,
+ * and GitLab reports pipeline jobs; each can implement {@link CiForge} by
+ * mapping those to {@link CheckRun}s, and until one does `--forge` refuses
+ * them by name.
+ *
+ * The client takes a `fetch` like the pull-request loop's (`../pr-forge.ts`),
+ * so the tests drive it with a recording fake and no network.
+ */
+import { ForgeApiError, ForgeEnvironmentError } from "../pr-forge.js";
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const str = (v) => (typeof v === "string" ? v : null);
+/** A GitHub client (github.com or GitHub Enterprise Server) for check runs. The token needs `checks: read`. */
+export function githubCiForge(opts) {
+    const root = opts.apiBase.replace(/\/+$/, "");
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    const headers = { Authorization: `Bearer ${opts.token}`, Accept: "application/vnd.github+json" };
+    return {
+        kind: "github",
+        async checkRuns(sha) {
+            // filter=all: every attempt, not only the newest per suite, so a re-run's
+            // own run is judged against the run it replaced by id.
+            const out = [];
+            for (let page = 1; page <= 50; page++) {
+                const url = `${root}/repos/${opts.repo}/commits/${sha}/check-runs?filter=all&per_page=100&page=${page}`;
+                const res = await fetchImpl(url, { method: "GET", headers });
+                const text = await res.text();
+                if (!res.ok)
+                    throw new ForgeApiError("GET", url, res.status, text);
+                const body = text ? JSON.parse(text) : null;
+                const runs = isObject(body) && Array.isArray(body.check_runs) ? body.check_runs : [];
+                for (const r of runs) {
+                    if (!isObject(r) || typeof r.id !== "number" || typeof r.name !== "string")
+                        continue;
+                    out.push({
+                        id: r.id,
+                        name: r.name,
+                        status: str(r.status) ?? "queued",
+                        conclusion: str(r.conclusion),
+                        completedAt: str(r.completed_at),
+                        url: str(r.html_url),
+                    });
+                }
+                const total = isObject(body) && typeof body.total_count === "number" ? body.total_count : 0;
+                if (runs.length < 100 || out.length >= total)
+                    break;
+            }
+            return out;
+        },
+    };
+}
+/** Thrown for a forge `chant ci tick` has no check-run client for yet. */
+export class CiForgeUnsupportedError extends Error {
+    constructor(kind) {
+        super(`check runs are read from GitHub only so far, and --forge asked for ${kind}; see #3573`);
+        this.name = "CiForgeUnsupportedError";
+    }
+}
+/**
+ * A check-run client for `kind` from the CI job's environment: the token is
+ * `CHANT_FORGE_TOKEN` when set, else `GITHUB_TOKEN` or `GH_TOKEN`, and the
+ * repository is `GITHUB_REPOSITORY`.
+ */
+export function ciForgeFromEnv(kind = "github", env = process.env, fetchImpl) {
+    if (kind !== "github")
+        throw new CiForgeUnsupportedError(kind);
+    const token = env.CHANT_FORGE_TOKEN ?? env.GITHUB_TOKEN ?? env.GH_TOKEN;
+    const missing = [...(env.GITHUB_REPOSITORY ? [] : ["GITHUB_REPOSITORY"]), ...(token ? [] : ["GITHUB_TOKEN or CHANT_FORGE_TOKEN"])];
+    if (missing.length > 0)
+        throw new ForgeEnvironmentError("github", missing);
+    return githubCiForge({
+        apiBase: env.GITHUB_API_URL ?? "https://api.github.com",
+        repo: env.GITHUB_REPOSITORY,
+        token: token,
+        ...(fetchImpl ? { fetch: fetchImpl } : {}),
+    });
+}