@intentius/chant 0.124.32 → 0.124.34

package/dist/workspace/ci-green.js

@@ -56,7 +56,10 @@ import { judgeCommits, mergeCommits, readWorkIndex } from "./commit-links.js";
 import { execFileSync } from "node:child_process";
 import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError } from "./declaration.js";
 import { readRunLedger } from "../lifecycle/run-ledger.js";
-import { fetchLifecycleStatus, listFilesInDir, listLedgerTrees } from "../lifecycle/git.js";
+import { fetchLifecycleStatus, listFilesInDir, listLedgerTrees, pushLifecycleStatus, writeLedgerFiles } from "../lifecycle/git.js";
+import { ledgerRecordingOff } from "../lifecycle/no-record.js";
+import { agedOut, buildRequestAnnotation, CI_BUILD_TAG_PREFIX, planBuilds, readBuildRequests, readCiRecords, recordOf, recordPath, requestedBuild, sameRecord } from "./ci-builds.js";
+import { dispatchableWorkflows, readWorkflowSources } from "./ci-green-workflow.js";
 import { signOpRunRecord, verifyOpRunStatement } from "./trust/op-run-statement.js";
 import { gitTop } from "./tree.js";
 import { locateWorkspace } from "./which-chant.js";
@@ -79,6 +82,8 @@ export class CiGreenError extends Error {
         this.name = "CiGreenError";
     }
 }
+/** Conclusions that say a run was stopped, or never started, rather than that it failed (#4169). */
+const UNBUILT_CONCLUSIONS = new Set(["cancelled", "stale"]);
 /** Whether a check run's name matches a pattern: the whole name, `*` standing for any run of characters. */
 export function matchesCheckRun(pattern, name) {
     const re = new RegExp(`^${pattern.split("*").map((p) => p.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`, "s");
@@ -101,6 +106,8 @@ function runVerdict(phase, r) {
         return "pass";
     if (r.conclusion === "skipped")
         return phase.skipped === "pass" ? "pass" : "fail";
+    if (r.conclusion !== null && UNBUILT_CONCLUSIONS.has(r.conclusion))
+        return "unbuilt";
     return "fail";
 }
 /** Judge one phase against a commit's latest attempts. */
@@ -117,21 +124,34 @@ export function evaluatePhase(phase, latest) {
             runs.push({ name: r.name, id: r.id, status: r.status, conclusion: r.conclusion, url: r.url, verdict: runVerdict(phase, r), ...(r.opRun ? { opRun: r.opRun } : {}), ...(r.failureCode ? { failureCode: r.failureCode } : {}) });
         }
     }
-    const verdict = runs.some((r) => r.verdict === "fail")
-        ? "fail"
-        : runs.some((r) => r.verdict === "pending") || unmatched.length > 0
-            ? "pending"
-            : "pass";
-    return { phase: phase.name, verdict, runs, unmatched };
+    return { phase: phase.name, ...phaseVerdictOf(runs, unmatched), runs, unmatched };
+}
+/** A phase's verdict from its runs: a failure wins, then a run still going or a pattern no run matches, then a cancelled run. */
+export function phaseVerdictOf(runs, unmatched) {
+    if (runs.some((r) => r.verdict === "fail"))
+        return { verdict: "fail" };
+    if (runs.some((r) => r.verdict === "pending") || unmatched.length > 0)
+        return { verdict: "pending" };
+    if (runs.some((r) => r.verdict === "unbuilt"))
+        return { verdict: "unbuilt", reason: "cancelled" };
+    return { verdict: "pass" };
 }
 /** Judge a commit: it fails when a required phase fails, and passes when every one passes. */
 export function evaluateCommit(green, runs) {
     const latest = latestAttempts(runs);
-    const phases = green.require.map((name) => evaluatePhase(green.phases.find((p) => p.name === name), latest));
+    return commitVerdictOf(green.require.map((name) => evaluatePhase(green.phases.find((p) => p.name === name), latest)));
+}
+/**
+ * A commit's verdict from its required phases: it fails when one fails, is
+ * pending while one is, is unbuilt when one is unbuilt (#4169), and passes
+ * when every one passes.
+ */
+export function commitVerdictOf(phases) {
     const failed = phases.find((p) => p.verdict === "fail");
     if (failed)
         return { verdict: "fail", phases, failure: { phase: failed.phase, run: failed.runs.find((r) => r.verdict === "fail") } };
-    return { verdict: phases.some((p) => p.verdict === "pending") ? "pending" : "pass", phases, failure: null };
+    const verdict = phases.some((p) => p.verdict === "pending") ? "pending" : phases.some((p) => p.verdict === "unbuilt") ? "unbuilt" : "pass";
+    return { verdict, phases, failure: null };
 }
 /** A time as an annotation and a tick report write it: UTC, to the second. */
 const iso = (d) => d.toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -398,22 +418,31 @@ export async function ciTick(req) {
     const signer = req.runnerKey !== undefined ? ciTagSigner(top, base, req.runnerKey) : undefined;
     const links = await commitLinks(req.cwd, top, tracking, commits.map((c) => c.sha));
     const tags = readCiTags(top, green, base);
+    const warnings = [];
     let runs;
-    if (green.source === "runs") {
-        // The runs live on chant/lifecycle, which a CI checkout may not have yet.
-        const fetched = await fetchLifecycleStatus({ cwd: top });
-        if (fetched.status === "diverged" || fetched.status === "unreachable") {
-            throw new Error(`could not fetch chant/lifecycle, where the Op runs are recorded, from ${fetched.remote}: ${fetched.status === "diverged" ? "the local branch and the remote's have diverged" : fetched.stderr}`);
-        }
-        runs = await readOpRunSource(req.cwd, top, base, green.signedSince);
+    // The runs and the records (#4169) live on chant/lifecycle, which a CI checkout may not have yet.
+    const fetched = await fetchLifecycleStatus({ cwd: top });
+    const ledgerOk = fetched.status !== "diverged" && fetched.status !== "unreachable";
+    if (!ledgerOk) {
+        const why = `could not fetch chant/lifecycle from ${fetched.remote}: ${fetched.status === "diverged" ? "the local branch and the remote's have diverged" : fetched.stderr}`;
+        if (green.source === "runs")
+            throw new Error(why.replace("chant/lifecycle", "chant/lifecycle, where the Op runs are recorded,"));
+        warnings.push(`${why}; no _ci records were read or written`);
     }
+    if (green.source === "runs")
+        runs = await readOpRunSource(req.cwd, top, base, green.signedSince);
+    const runsBy = new Map();
     const planned = await planTick({
         green,
         commits,
         greenTags: new Set(tags.green.keys()),
         revokedTags: new Set(tags.revoked.keys()),
         ignored: tags.ignored,
-        checkRuns: async (sha) => (runs ? runs.checkRuns(sha) : forge.checkRuns(sha)),
+        checkRuns: async (sha) => {
+            const got = runs ? runs.checkRuns(sha) : await forge.checkRuns(sha);
+            runsBy.set(sha, got);
+            return got;
+        },
         now,
         signer,
     });
@@ -427,6 +456,10 @@ export async function ciTick(req) {
                 c.ignoredRuns = ignored;
         }
     }
+    const records = ledgerOk ? readCiRecords(top) : new Map();
+    const requests = readBuildRequests(top);
+    const retryVia = green.source === "runs" ? "request" : forge?.rerun ? "forge" : null;
+    const builds = planBuilds({ green, commits: planned, runs: runsBy, requests, records, now, retryVia });
     const due = planned.filter((c) => c.made !== null);
     if (!req.dryRun && due.length > 0) {
         const ident = taggerConfig(top);
@@ -442,7 +475,217 @@ export async function ciTick(req) {
             throw new Error(`could not push ${due.map((c) => c.made.tag).join(", ")} to ${remote}: ${cause ? `${cause}\n` : ""}${stderr}`);
         }
     }
-    return { branch: green.branch, window: green.window, ref: tracking, commits: planned, made: due.map((c) => c.made.tag), signer: signer?.principal ?? null, source: green.source };
+    const retried = builds.retries.map((r) => ({ sha: r.sha, run: r.run.name }));
+    let recorded = [];
+    if (!req.dryRun) {
+        const asked = await askForBuilds({ top, remote, green, forge, builds, requests, records, planned, warnings });
+        recorded = ledgerOk && !ledgerRecordingOff() ? await writeRecords({ top, green, planned, records, builds, requests: asked.live, dispatched: asked.dispatched, now, warnings }) : [];
+    }
+    return {
+        branch: green.branch,
+        window: green.window,
+        ref: tracking,
+        commits: planned,
+        made: due.map((c) => c.made.tag),
+        requested: builds.requests,
+        retried,
+        recorded,
+        warnings,
+        signer: signer?.principal ?? null,
+        source: green.source,
+    };
+}
+/**
+ * Make what the plan asks for (#4169): push each new request tag and start
+ * the workflows holding its phases at it on GitHub, start any older request
+ * no tick has started yet, run the failed jobs again, and delete the tags of
+ * requests that are done. Each step that fails is a warning, never the
+ * tick's failure: the green tags are already pushed.
+ */
+async function askForBuilds(input) {
+    const { top, remote, green, forge, builds, warnings } = input;
+    const live = new Map(input.requests);
+    for (const tag of builds.resolved)
+        live.delete(tag.slice(CI_BUILD_TAG_PREFIX.length));
+    if (builds.requests.length > 0) {
+        const ident = taggerConfig(top);
+        const made = [];
+        for (const r of builds.requests) {
+            if (tryGit(top, [...ident, "tag", "-a", "-m", buildRequestAnnotation(r), r.tag, r.commit]) === null)
+                warnings.push(`could not make ${r.tag}`);
+            else
+                made.push(r);
+        }
+        if (made.length > 0) {
+            try {
+                git(top, ["push", "--quiet", remote, ...made.map((r) => `refs/tags/${r.tag}`)]);
+                for (const r of made)
+                    live.set(r.commit, r);
+            }
+            catch (err) {
+                for (const r of made)
+                    tryGit(top, ["tag", "-d", r.tag]);
+                const stderr = stderrOf(err);
+                warnings.push(`could not push ${made.map((r) => r.tag).join(", ")} to ${remote}: ${pushRefusalCause(stderr) ?? stderr}`);
+            }
+        }
+    }
+    const dispatched = new Set();
+    if (green.source === "checks" && forge?.dispatch) {
+        const sources = readWorkflowSources(top, "");
+        for (const r of live.values()) {
+            if (input.records.get(r.commit)?.request?.dispatched && input.records.get(r.commit)?.request?.tag === r.tag)
+                continue;
+            // A run already going at the commit was started for it, by the tick before or by `ci run --at`.
+            const c = input.planned.find((x) => x.sha === r.commit);
+            if (c?.verdict?.phases.some((p) => r.phases.includes(p.phase) && p.runs.some((x) => x.status !== "completed"))) {
+                dispatched.add(r.commit);
+                continue;
+            }
+            const { dispatchable, without } = dispatchableWorkflows(green, r.phases, sources);
+            for (const w of without)
+                warnings.push(`${w} holds a run of ${r.phases.join(", ")} and has no workflow_dispatch trigger, so ${r.tag} can't start it; regenerate it with chant ci workflow`);
+            let ok = dispatchable.length > 0;
+            for (const w of dispatchable) {
+                try {
+                    await forge.dispatch(w, r.tag);
+                }
+                catch (err) {
+                    ok = false;
+                    warnings.push(`could not start ${w} at ${r.tag}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            if (ok)
+                dispatched.add(r.commit);
+        }
+    }
+    if (forge?.rerun) {
+        for (const r of builds.retries) {
+            try {
+                await forge.rerun(r.run);
+            }
+            catch (err) {
+                warnings.push(`could not run ${r.run.name} at ${r.sha.slice(0, 12)} again, so its failure counts once the retry's hour is up: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    if (builds.resolved.length > 0) {
+        for (const tag of builds.resolved)
+            tryGit(top, ["tag", "-d", tag]);
+        if (tryGit(top, ["push", "--quiet", remote, ...builds.resolved.map((t) => `:refs/tags/${t}`)]) === null) {
+            warnings.push(`could not delete ${builds.resolved.join(", ")} on ${remote}; a done request asks for nothing, so they can stay`);
+        }
+    }
+    return { live, dispatched };
+}
+/**
+ * Write each judged commit's record, and rewrite a record whose commit left
+ * the window still pending as unbuilt (#4169), in one commit on
+ * `chant/lifecycle`, and push it. Only records whose content changed are
+ * written. A push another writer beat is tried once more on the new tip.
+ */
+async function writeRecords(input) {
+    const { top, green, planned, records, builds, requests, now, warnings } = input;
+    const writes = [];
+    const inWindow = new Set(planned.map((c) => c.sha));
+    for (const c of planned) {
+        const previous = records.get(c.sha);
+        let record = recordOf({ green, commit: c, previous, retries: builds.retries, requests, now });
+        if (record.request) {
+            const started = input.dispatched.has(c.sha) || (previous?.request?.tag === record.request.tag && previous.request.dispatched === true);
+            if (started)
+                record = { ...record, request: { ...record.request, dispatched: true } };
+        }
+        if (!sameRecord(previous, record))
+            writes.push({ path: recordPath(c.sha), content: `${JSON.stringify(record, null, 2)}\n` });
+    }
+    for (const [sha, r] of records) {
+        if (inWindow.has(sha) || r.state !== "pending")
+            continue;
+        writes.push({ path: recordPath(sha), content: `${JSON.stringify(agedOut(r, now), null, 2)}\n` });
+    }
+    if (writes.length === 0)
+        return [];
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await writeLedgerFiles(writes, `ci: ${writes.length} commit record${writes.length === 1 ? "" : "s"}`, { cwd: top });
+        }
+        catch (err) {
+            warnings.push(`could not write the _ci records: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+        const pushed = await pushLifecycleStatus({ cwd: top });
+        if (pushed.status === "pushed" || pushed.status === "no-remote" || pushed.status === "not-recorded")
+            return writes.map((w) => w.path);
+        if (pushed.status !== "stale" || attempt === 1) {
+            warnings.push(`could not push the _ci records: ${pushed.stderr}`);
+            return [];
+        }
+        // Another writer pushed first: drop this commit, follow the remote, and write again on its tip.
+        tryGit(top, ["update-ref", "refs/heads/chant/lifecycle", "refs/heads/chant/lifecycle^"]);
+        const again = await fetchLifecycleStatus({ cwd: top });
+        if (again.status === "diverged" || again.status === "unreachable") {
+            warnings.push(`could not push the _ci records: chant/lifecycle moved on the remote and could not be fetched again`);
+            return [];
+        }
+    }
+    return [];
+}
+/**
+ * `chant ci run --at <sha>`: ask for every required phase to be built at a
+ * commit of the branch, by pushing `ci/build/<sha>`. Given a forge that can
+ * start workflows, and with the source check runs, it starts the workflows
+ * holding the phases at the tag now; otherwise the next tick does, or `ci
+ * serve --build-command` for chant runs. Once the phases pass, the tick tags
+ * the commit green like any other, so it can be cut.
+ */
+export async function requestBuild(req) {
+    const read = readGreen(req.cwd);
+    const { green, top } = read;
+    const remote = req.remote ?? "origin";
+    const tracking = `refs/remotes/${remote}/${green.branch}`;
+    try {
+        git(top, ["fetch", "--quiet", "--no-tags", remote, `+refs/heads/${green.branch}:${tracking}`, `+refs/tags/${CI_BUILD_TAG_PREFIX}*:refs/tags/${CI_BUILD_TAG_PREFIX}*`]);
+    }
+    catch (err) {
+        throw new Error(`could not fetch ${green.branch} and the build requests from ${remote}: ${stderrOf(err)}`);
+    }
+    if (req.at.startsWith("-") || tryGit(top, ["rev-parse", "--verify", "--quiet", `${req.at}^{commit}`]) === null)
+        throw new WorkspaceReadError("revision-unknown", `--at ${req.at} names no commit in this repository`);
+    const sha = git(top, ["rev-parse", `${req.at}^{commit}`]);
+    const onBranch = git(top, ["rev-list", "--first-parent", tracking]).split("\n").includes(sha);
+    if (!onBranch)
+        throw new Error(`${sha.slice(0, 12)} is not a first-parent commit of ${remote}/${green.branch}, and only those are judged green`);
+    const existing = readBuildRequests(top).get(sha);
+    const request = existing ?? requestedBuild(green, sha, green.require, req.now ?? new Date());
+    const warnings = [];
+    if (!existing) {
+        git(top, [...taggerConfig(top), "tag", "-a", "-m", buildRequestAnnotation(request), request.tag, sha]);
+        try {
+            git(top, ["push", "--quiet", remote, `refs/tags/${request.tag}`]);
+        }
+        catch (err) {
+            tryGit(top, ["tag", "-d", request.tag]);
+            const stderr = stderrOf(err);
+            throw new Error(`could not push ${request.tag} to ${remote}: ${pushRefusalCause(stderr) ?? stderr}`);
+        }
+    }
+    const dispatched = [];
+    if (green.source === "checks" && req.forge?.dispatch) {
+        const { dispatchable, without } = dispatchableWorkflows(green, request.phases, readWorkflowSources(top, ""));
+        for (const w of without)
+            warnings.push(`${w} holds a run of a required phase and has no workflow_dispatch trigger, so it can't be started at ${request.tag}`);
+        for (const w of dispatchable) {
+            try {
+                await req.forge.dispatch(w, request.tag);
+                dispatched.push(w);
+            }
+            catch (err) {
+                warnings.push(`could not start ${w} at ${request.tag}: ${err instanceof Error ? err.message : String(err)}; the next tick tries again`);
+            }
+        }
+    }
+    return { request, existed: existing !== undefined, dispatched, warnings };
 }
 const RUN_LEDGER_FILE = /^runs__(.+)\.jsonl$/;
 /**
@@ -589,8 +832,17 @@ export function formatTick(r, dryRun = false) {
         }
         else {
             const v = c.verdict;
-            const waiting = v.phases.filter((p) => p.verdict === "pending").map((p) => p.phase);
-            const what = c.before === "green" ? "green" : v.verdict === "fail" ? `failed: phase ${v.failure.phase}, ${v.failure.run.name} ${v.failure.run.conclusion}` : `undecided: ${waiting.join(", ")}`;
+            const why = (p) => `${p.phase}${p.reason ? ` (${p.reason}${p.coveredBy ? `, covered by ${p.coveredBy.slice(0, 12)}` : ""})` : ""}`;
+            const waiting = v.phases.filter((p) => p.verdict === "pending").map(why);
+            const unbuilt = v.phases.filter((p) => p.verdict === "unbuilt").map(why);
+            const culprit = v.phases.find((p) => p.culprit)?.culprit;
+            const what = c.before === "green"
+                ? "green"
+                : v.verdict === "fail"
+                    ? `failed: phase ${v.failure.phase}, ${v.failure.run.name} ${v.failure.run.conclusion}${culprit ? `; culprit ${culprit.slice(0, 12)}` : ""}`
+                    : v.verdict === "unbuilt"
+                        ? `unbuilt: ${unbuilt.join(", ")}`
+                        : `undecided: ${waiting.join(", ")}`;
             lines.push(`  ${short}  ${what}`);
         }
         const why = whyWorkUnknown(c.work);
@@ -605,6 +857,14 @@ export function formatTick(r, dryRun = false) {
     }
     if (r.signer && r.made.length > 0)
         lines.push(`signed as ${r.signer}`);
+    for (const q of r.requested)
+        lines.push(`${dryRun ? "would ask" : "asked"} for ${q.phases.join(", ")} at ${q.commit.slice(0, 12)} (${q.reason}): ${q.tag}`);
+    for (const x of r.retried)
+        lines.push(`${dryRun ? "would run" : "ran"} ${x.run} at ${x.sha.slice(0, 12)} again`);
+    if (r.recorded.length > 0)
+        lines.push(`recorded ${r.recorded.length} commit${r.recorded.length === 1 ? "" : "s"} on chant/lifecycle`);
+    for (const w of r.warnings)
+        lines.push(`warning: ${w}`);
     return lines.join("\n");
 }
 // ── last-green ───────────────────────────────────────────────────────────────
@@ -616,6 +876,8 @@ function branchRefOf(top, green, remote = "origin") {
         throw new CiGreenError("ci-branch-unknown", `this repository has neither ${candidates.join(" nor ")}`);
     return ref;
 }
+/** How many commits above the green one `ci last-green` reports with their records. */
+export const LAST_GREEN_NEWER = 50;
 /**
  * `chant ci last-green`: the newest first-parent commit of the branch with a
  * green tag and no revoked tag. It reads local refs and tags and never
@@ -637,16 +899,21 @@ export function lastGreen(req) {
         const tags = readCiTags(top, green, git(top, ["rev-parse", `${branchRef}^{commit}`]));
         let commit = null;
         const ignored = [];
-        if (tags.green.size > 0 || tags.ignored.size > 0) {
+        const newer = [];
+        const records = readCiRecords(top);
+        if (tags.green.size > 0 || tags.ignored.size > 0 || records.size > 0) {
             for (const sha of git(top, ["rev-list", "--first-parent", ref]).split("\n")) {
                 ignored.push(...(tags.ignored.get(sha) ?? []));
-                if (!tags.green.has(sha) || tags.revoked.has(sha))
+                if (!tags.green.has(sha) || tags.revoked.has(sha)) {
+                    if (newer.length < LAST_GREEN_NEWER)
+                        newer.push({ sha, record: recordSummary(green, records.get(sha)) });
                     continue;
+                }
                 commit = { sha, tag: `${CI_GREEN_TAG_PREFIX}${sha}`, tagged: tags.green.get(sha).tagged, committed: git(top, ["show", "-s", "--format=%cI", sha]) };
                 break;
             }
         }
-        return { ...head, workspace, branch: green.branch, ref, commit, ignored };
+        return { ...head, workspace, branch: green.branch, ref, commit, ignored, newer: commit ? newer : [] };
     }
     catch (err) {
         if (err instanceof CiGreenError || err instanceof WorkspaceReadError)
@@ -657,6 +924,17 @@ export function lastGreen(req) {
 // ── list ─────────────────────────────────────────────────────────────────────
 export const CI_LIST_CONTRACT_VERSION = 1;
 export const CI_LIST_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/ci-list/v1/ci-list.schema.json";
+/** The summary of a record, from its required phases in `require` order. */
+export function recordSummary(green, r) {
+    if (!r)
+        return null;
+    const phases = green.require.map((name) => r.phases[name]).filter((p) => p !== undefined);
+    const first = (k) => phases.find((p) => p[k] !== undefined)?.[k];
+    const reason = first("reason");
+    const coveredBy = first("coveredBy");
+    const culprit = first("culprit");
+    return { state: r.state, ...(reason ? { reason } : {}), ...(coveredBy ? { coveredBy } : {}), ...(culprit ? { culprit } : {}) };
+}
 const asRun = (r) => {
     if (!r || typeof r !== "object")
         return null;
@@ -722,6 +1000,7 @@ export async function ciList(req) {
         if (source === "runs" && req.forge)
             throw new Error("--forge reads check runs, and the source is chant runs (ci.green.source or --source runs); drop one");
         const runs = source === "runs" ? await readOpRunSource(req.cwd, top, base, green.signedSince) : undefined;
+        const records = readCiRecords(top);
         const out = [];
         for (const c of commits) {
             const g = tags.green.get(c.sha);
@@ -747,6 +1026,7 @@ export async function ciList(req) {
                 work: links?.get(c.sha) ?? null,
                 ignored: tags.ignored.get(c.sha) ?? [],
                 ...(runs ? { ignoredRuns: runs.ignored.get(c.sha) ?? [] } : {}),
+                record: recordSummary(green, records.get(c.sha)),
             });
         }
         return { ...head, workspace, branch: green.branch, ref, window: req.since === undefined ? green.window : null, since: req.since ?? null, require: [...green.require], commits: out };
@@ -757,6 +1037,11 @@ export async function ciList(req) {
         throw err;
     }
 }
+/** A record summary in words, for `ci list` and the tick. */
+export function describeRecord(r) {
+    const parts = [r.state, ...(r.reason ? [r.reason] : []), ...(r.coveredBy ? [`covered by ${r.coveredBy.slice(0, 12)}`] : []), ...(r.culprit ? [`culprit ${r.culprit.slice(0, 12)}`] : [])];
+    return parts.join(", ");
+}
 /** The text `chant ci list` prints: one line per commit. */
 export function formatList(doc) {
     const lines = [`${doc.branch}, ${doc.since ? `commits after ${doc.since}` : `commits within ${doc.window}`}: ${doc.commits.length}`];
@@ -764,6 +1049,8 @@ export function formatList(doc) {
         const phases = c.phases.map((p) => `${p.phase}=${p.result}`).join(" ");
         const why = whyWorkUnknown(c.work);
         lines.push(`  ${c.sha.slice(0, 12)}  ${c.state.padEnd(9)}  ${phases}${why ? `; why unknown: ${why}` : ""}`);
+        if (c.record && c.state === "undecided")
+            lines.push(`      recorded ${describeRecord(c.record)}`);
         for (const t of c.ignored)
             lines.push(`      ignored ${t.tag} (${t.status}): ${t.reason}`);
         for (const r of c.ignoredRuns ?? [])

package/dist/workspace/ci-init.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `chant ci init --workflow <name> [--forge <forge>] [--security <group>]...
+ * [--yes]` (#4168 step 6, section 9): set a workspace up for a prescribed
+ * delivery workflow (../ci-workflow.ts).
+ *
+ * It proposes, prints the proposal as a diff, and writes only on `--yes` or a
+ * yes at the prompt. What it proposes comes from what `workspace check`'s
+ * WSP151 reports for the workspace as it would be with `ci.workflow` set, so
+ * a second run proposes only what is still missing, and nothing once the
+ * workspace has it all.
+ *
+ * - The declaration gains `ci.workflow`, a `ci.green` block when it has none
+ *   (one phase per GitHub workflow, its jobs as the check runs, and the
+ *   workflows a pull request runs as `preMerge`), and `preMerge` when the
+ *   block has none. `--security` adds groups to the top-level `security`;
+ *   without it no group is turned on, and the groups are listed.
+ * - A member that builds with chant and declares no component gets a
+ *   `<member>.component.ts` stub with a gate and a TODO line, which WSP151
+ *   keeps reporting until someone fills the stub in. A `chant.config.ts`
+ *   that declares no environments gains `environments: ["staging", "prod"]`
+ *   when its default export is a plain object literal.
+ * - The generated files are written by the generators that own them, run
+ *   after the edits: `chant build --components --generate <forge> --pr-loop`
+ *   in each member, `chant ci workflow` for the tick, and `chant release
+ *   workflow` for the publish job. Each is named in the proposal before it
+ *   runs.
+ *
+ * It never edits a file the diff did not show, and never overwrites a file
+ * it proposed to create that appeared in the meantime.
+ */
+import type { CommandContext } from "../cli/registry.js";
+import type { WorkspaceDiagnostic } from "./checks.js";
+import { STUB_MARKER } from "./ci-workflow.js";
+export { STUB_MARKER };
+import { type CiWorkflow } from "./declaration.js";
+import { type SecurityGroup } from "./security.js";
+import { type ReleaseWorkflowForge } from "./release-workflow.js";
+/** The environments a config with none is given. */
+export declare const DEFAULT_ENVIRONMENTS: readonly ["staging", "prod"];
+/** One file the proposal writes: created when `before` is null. */
+export interface ProposedFile {
+    path: string;
+    before: string | null;
+    after: string;
+}
+/** A generator the proposal runs after the edits, in `cwd` (relative to the workspace root). */
+export interface ProposedCommand {
+    cwd: string;
+    args: string[];
+    why: string;
+}
+export interface CiInitProposal {
+    files: ProposedFile[];
+    commands: ProposedCommand[];
+    /** What the proposal leaves to a person, such as a component with no gate. */
+    notes: string[];
+    /** The WSP151 findings the proposal answers. */
+    findings: WorkspaceDiagnostic[];
+}
+export interface CiInitOptions {
+    workflow: CiWorkflow;
+    forge?: ReleaseWorkflowForge;
+    security?: readonly SecurityGroup[];
+}
+/** The forge whose pipeline files the repository has, or null. */
+export declare function inferForge(repoRoot: string): ReleaseWorkflowForge | null;
+/** The branch `origin/HEAD` names, else `main`. */
+export declare function inferTrunk(repoRoot: string): string;
+/**
+ * A `ci.green` block from the repository's GitHub workflows: a phase per
+ * workflow holding its jobs' check runs, all required, and those a pull
+ * request runs as `preMerge`. chant's own generated workflows are left out.
+ */
+export declare function inferGreen(repoRoot: string): {
+    branch: string;
+    phases: Record<string, string[]>;
+    require: string[];
+    preMerge: string[];
+};
+/**
+ * The declaration's text with `next`'s top-level keys. A key the file lacks
+ * is added as text before the closing brace, so the rest keeps its layout; a
+ * key it has whose value changes rewrites the file, two-space indented.
+ */
+export declare function editDeclarationText(text: string, raw: Record<string, unknown>, next: Record<string, unknown>): string;
+/** The component stub for a member that declares none: a gate and a TODO, so WSP151 keeps asking until it is filled in. */
+export declare function componentStub(member: string, lastEnvironment: string): string;
+/** The config with `environments` added after `export default {`, or null when its default export is not a plain object literal. */
+export declare function withEnvironments(config: string, environments?: readonly string[]): string | null;
+/**
+ * What `chant ci init` would write for the workspace at `root`, and the
+ * generators it would run. Reads only; {@link applyCiInit} writes.
+ */
+export declare function proposeCiInit(root: string, options: CiInitOptions): CiInitProposal;
+/** A unified-style diff of two texts, for the proposal. Line-based, from their longest common subsequence. */
+export declare function lineDiff(path: string, before: string | null, after: string): string;
+/** Write the proposal's files. A file it would create that now exists is refused, and nothing is written. */
+export declare function applyCiInit(root: string, proposal: CiInitProposal): string[];
+export declare function runCiInit(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=ci-init.d.ts.map

package/dist/workspace/ci-init.d.ts.map

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