@intentius/chant 0.124.33 → 0.124.34

package/src/workspace/ci-report-url.test.ts

@@ -44,6 +44,8 @@ const repoTemplate = repoFixture(() => {
   git(root, "symbolic-ref", "HEAD", "refs/heads/main");
   git(root, "config", "user.name", "t");
   git(root, "config", "user.email", "t@example.com");
+  git(root, "config", "gc.auto", "0");
+  git(root, "config", "maintenance.auto", "false");
   writeFiles(root, { "chant.workspace.json": declaration(MEMBERS), ".gitignore": ".chant/pr/\n", "app/a.txt": "a\n" });
   const commit = (msg: string) => {
     execFileSync("git", ["-c", "commit.gpgsign=false", "add", "-A"], { cwd: root, stdio: "ignore" });
@@ -77,10 +79,13 @@ async function cli(cwd: string, argv: string[], run: (ctx: CommandContext) => Pr
   return { code, out: out.join("\n"), err: err.join("\n") };
 }
 
+// A job image of its own, so the job gets no setup lines: the default image's
+// OpenTofu install downloads from the network on a runner without tofu, as
+// in ci-run.test.ts.
 const runPlan = (w: ReturnType<typeof workspace>, extra: string[] = []) =>
   cli(
     w.app,
-    ["ci", "run", "plan", "--env", "prod", "--base", w.base, "--pr", "7", "--forge", "forgejo", "--no-status", "--chant", w.chant, "-o", join(scratchDir("chant-report-url-out-"), "pr"), ...extra],
+    ["ci", "run", "plan", "--image", "chant-ci-report-url-test:local", "--env", "prod", "--base", w.base, "--pr", "7", "--forge", "forgejo", "--no-status", "--chant", w.chant, "-o", join(scratchDir("chant-report-url-out-"), "pr"), ...extra],
     runCiRun,
   );
 

package/src/workspace/ci-workflow.ts

@@ -0,0 +1,71 @@
+/**
+ * The prescribed delivery workflows (#4168 section 7): `ci.workflow` in the
+ * declaration, at the top level or on a member, which wins.
+ *
+ * `trunk-curated`: a merge records the plan and deploys nothing (#4168 4.1),
+ * the quick checks run before the branch moves (4.4), and a release is cut
+ * from a green commit and promoted through the member's environments, gated
+ * in the last (4.2). `trunk-curated+apply-on-merge` is the same with the apply
+ * on merge turned back on (section 5).
+ *
+ * A workflow requires no security group: those are opt-in on their own
+ * (./security.ts). `chant workspace check` reports what a member under a
+ * workflow still lacks (./checks/ci-workflow.ts, WSP151), and `chant ci
+ * init` writes what it can. {@link CI_WORKFLOW_REQUIREMENTS} is the table the
+ * reference page prints.
+ */
+import type { CiWorkflow, Declaration, Member } from "./declaration";
+
+/** The marker a component stub `chant ci init` writes carries until someone fills it in. WSP151 reports a member whose only components carry it. */
+export const STUB_MARKER = "TODO(chant ci init)";
+
+export const CI_WORKFLOWS = ["trunk-curated", "trunk-curated+apply-on-merge"] as const satisfies readonly CiWorkflow[];
+
+/** Whether `workflow` turns the apply on merge back on. */
+export function appliesOnMerge(workflow: CiWorkflow): boolean {
+  return workflow === "trunk-curated+apply-on-merge";
+}
+
+/** The workflow `member` follows: its own `ci.workflow`, else the top level's, else null. */
+export function workflowOf(declaration: Pick<Declaration, "ci">, member: Pick<Member, "ciWorkflow"> | null): CiWorkflow | null {
+  return member?.ciWorkflow ?? declaration.ci?.workflow ?? null;
+}
+
+/** One requirement of the workflows, with the `workspace check` code that reports it missing. */
+export interface CiWorkflowRequirement {
+  /** The reason code WSP151 reports. */
+  code: string;
+  /** What the workflow needs. */
+  requirement: string;
+  /** What adds it. */
+  fix: string;
+  /** Whether it applies per member (true) or once for the workspace. */
+  perMember: boolean;
+}
+
+/**
+ * Every requirement, in the order `workspace check` reports them. The
+ * reference page's table is printed from this list (`ciWorkflowTable`), and a
+ * test compares the two.
+ */
+export const CI_WORKFLOW_REQUIREMENTS = [
+  { code: "ci-workflow-green-undeclared", requirement: "`ci.green` is declared, so commits get a verdict and a release is cut only from a green one", fix: "`chant ci init`, or a hand-written `ci.green` block", perMember: false },
+  { code: "ci-workflow-no-pre-merge", requirement: "`ci.green.preMerge` names at least one phase, the quick checks that run before the branch moves", fix: "`preMerge` in `ci.green`", perMember: false },
+  { code: "ci-workflow-apply-in-green", requirement: "no phase in `ci.green.require` matches an apply job, which would wait on its own verdict", fix: "drop the apply job's pattern from the required phases", perMember: false },
+  { code: "ci-workflow-no-components", requirement: "the member declares a component (`*.component.ts`)", fix: "`chant ci init` writes a stub", perMember: true },
+  { code: "ci-workflow-no-environments", requirement: "the member's `chant.config.ts` declares `environments`, the promotion order", fix: "`environments` in `chant.config.ts`", perMember: true },
+  { code: "ci-workflow-ungated-env", requirement: "each component has a gate, so a promote to the last environment waits on an approval", fix: "a `gate()` step in the component", perMember: true },
+  { code: "ci-workflow-pipeline-missing", requirement: "a pipeline file runs the plan job, the merge job (`ci run record`, or `ci run apply` under apply on merge) and `chant ci tick`", fix: "`chant build --components --generate <forge> --pr-loop` and `chant ci workflow`", perMember: false },
+  { code: "ci-workflow-pipeline-differs", requirement: "the merge job matches the workflow: it records under `trunk-curated` and applies under `trunk-curated+apply-on-merge`", fix: "regenerate the pull-request pipeline, with `--apply-on-merge` only under apply on merge", perMember: false },
+  { code: "ci-workflow-publish-missing", requirement: "a pipeline file runs `chant release publish`", fix: "`chant release workflow`", perMember: false },
+] as const satisfies readonly CiWorkflowRequirement[];
+
+export type CiWorkflowCode = (typeof CI_WORKFLOW_REQUIREMENTS)[number]["code"];
+
+export const CI_WORKFLOW_FINDING_CODES = CI_WORKFLOW_REQUIREMENTS.map((r) => r.code) as readonly CiWorkflowCode[];
+
+/** The requirements table the reference page carries, row for row. */
+export function ciWorkflowTable(): string {
+  const rows = CI_WORKFLOW_REQUIREMENTS.map((r) => `| \`${r.code}\` | ${r.requirement} | ${r.perMember ? "each member" : "the workspace"} | ${r.fix} |`);
+  return ["| Code | Requirement | Checked for | Added by |", "|---|---|---|---|", ...rows].join("\n");
+}

package/src/workspace/declaration.schema.json

@@ -178,6 +178,9 @@
         "green": {
           "$ref": "#/$defs/ciGreen"
         },
+        "workflow": {
+          "$ref": "#/$defs/ciWorkflow"
+        },
         "reportUrl": {
           "type": "string",
           "minLength": 1,
@@ -491,6 +494,19 @@
           "minLength": 1,
           "description": "Where an embedded member's files come from. Versions live in the lock."
         },
+        "ci": {
+          "type": "object",
+          "additionalProperties": false,
+          "patternProperties": {
+            "^x-": true
+          },
+          "description": "This member's own CI settings (#4168 step 6). Added in schema 1 by chant 0.124.34, so a declaration that uses it sets minReader to 0.124.34 or newer.",
+          "properties": {
+            "workflow": {
+              "$ref": "#/$defs/ciWorkflow"
+            }
+          }
+        },
         "travel": {
           "type": "boolean",
           "description": "Whether the member goes with an export (#2524 D10, #2552). chant workspace export writes only members that set travel to true into the export member, and refuses to name one that does not. Added in schema 1 by chant 0.101.0, so a declaration that uses it sets minReader to 0.101.0 or newer."
@@ -1536,6 +1552,14 @@
             "$ref": "#/$defs/ciPhaseName"
           }
         },
+        "preMerge": {
+          "type": "array",
+          "uniqueItems": true,
+          "description": "The phases that must pass before the branch moves (#4168 4.4), by name: the quick checks a pull request's checks, a merge queue, chant ci serve landing a branch, or chant ci run --local give before a change lands. Each must be a declared phase. The trunk-curated workflow needs at least one. Added in schema 1 by chant 0.124.34, so a declaration that uses it sets minReader to 0.124.34 or newer.",
+          "items": {
+            "$ref": "#/$defs/ciPhaseName"
+          }
+        },
         "signedSince": {
           "type": "string",
           "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$",
@@ -1554,6 +1578,10 @@
       },
       "additionalProperties": false
     },
+    "ciWorkflow": {
+      "enum": ["trunk-curated", "trunk-curated+apply-on-merge"],
+      "description": "A prescribed delivery workflow (#4168). trunk-curated: a merge records the plan and deploys nothing; releases are cut from green commits and promoted through each member's environments, gated in the last. trunk-curated+apply-on-merge: the same, with the apply on merge turned back on. chant workspace check reports what a member under one still lacks (WSP151), and chant ci init writes it. At the top level for every member, or on a member, which wins. Added in schema 1 by chant 0.124.34, so a declaration that uses it sets minReader to 0.124.34 or newer."
+    },
     "ciPhaseName": {
       "type": "string",
       "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$"

package/src/workspace/declaration.ts

@@ -221,6 +221,12 @@ export interface CiGreen {
   phases: CiPhase[];
   /** The phases a commit must pass, by name, in file order. */
   require: string[];
+  /**
+   * The phases that must pass before the branch moves (#4168 4.4), by name,
+   * in file order: the quick checks a pull request, a merge queue or a local
+   * run gives before a change lands. Absent or empty when the declaration names none.
+   */
+  preMerge?: string[];
   /**
    * The full sha of the first commit on the branch whose ci tags need a
    * statement signed by a runner key (#4031). A tag on a strict
@@ -244,9 +250,20 @@ export interface CiGreen {
 /** Where `ci tick` reads phase results (#4044): forge check runs, or chant Op runs. */
 export type CiSource = "checks" | "runs";
 
+/**
+ * A prescribed delivery workflow (#4168 section 7). `trunk-curated`: a merge
+ * records the plan and deploys nothing, and releases are cut from green
+ * commits and promoted through the environments. `trunk-curated+apply-on-merge`
+ * adds the apply on merge as an opt-in. `chant workspace check` reports what a
+ * member under one still lacks (./checks/ci-workflow.ts, WSP151).
+ */
+export type CiWorkflow = "trunk-curated" | "trunk-curated+apply-on-merge";
+
 /** The declaration's `ci` block (#3573). */
 export interface CiDeclaration {
   green: CiGreen | null;
+  /** `ci.workflow` (#4168 step 6): the workflow every member follows unless it names its own; absent when the declaration sets none. */
+  workflow?: CiWorkflow;
   /**
    * `ci.reportUrl` (#4160): where the pull-request jobs copy their reports
    * and `chant ci run` keeps the run index, `<reportUrl>/runs/index.json`.
@@ -573,6 +590,8 @@ export interface Member {
   travel: boolean;
   /** The security groups this member adds to the declaration's top-level `security` (#4168 step 7), in file order; empty when it names none. */
   security: SecurityGroup[];
+  /** The member's own `ci.workflow` (#4168 step 6), which wins over the top level's; null when it names none. */
+  ciWorkflow: CiWorkflow | null;
   suppress: Suppression[];
   /** The entry's JSON Pointer in the file, for messages. */
   pointer: string;
@@ -869,6 +888,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       because: (e.because as string | undefined) ?? null,
       travel: e.travel === true,
       security: [...((e.security as SecurityGroup[] | undefined) ?? [])],
+      ciWorkflow: ((e.ci as { workflow?: CiWorkflow } | undefined)?.workflow) ?? null,
       suppress,
       pointer,
     };
@@ -1116,7 +1136,8 @@ function retentionOf(raw: unknown): RetentionOverride | null {
 
 function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
   if (raw === undefined) return null;
-  const block = raw as { reportUrl?: string; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; signedSince?: string; source?: CiSource } };
+  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
+  const workflow = block.workflow !== undefined ? { workflow: block.workflow } : {};
   let reportUrl: string | null = null;
   if (block.reportUrl !== undefined) {
     // #4160: refused here as pr-plan and ci run refuse the flag, so a reader never gets a URL no job can write to.
@@ -1124,7 +1145,7 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
     if ("error" in target) throw new WorkspaceReadError("declaration-invalid", target.error, at("/ci/reportUrl"));
     reportUrl = target.url;
   }
-  if (block.green === undefined) return { green: null, reportUrl };
+  if (block.green === undefined) return { green: null, ...workflow, reportUrl };
   const g = block.green;
   const phases: CiPhase[] = Object.entries(g.phases).map(([name, p]) => ({
     name,
@@ -1141,7 +1162,15 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
       at(`/ci/green/require/${i}`),
     );
   }
-  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, reportUrl };
+  for (const [i, name] of (g.preMerge ?? []).entries()) {
+    if (phases.some((p) => p.name === name)) continue;
+    throw new WorkspaceReadError(
+      "declaration-invalid",
+      `ci.green.preMerge names the phase ${JSON.stringify(name)}, which ci.green.phases does not declare; declared phases: ${phases.map((p) => p.name).join(", ")}`,
+      at(`/ci/green/preMerge/${i}`),
+    );
+  }
+  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], ...(g.preMerge !== undefined ? { preMerge: [...g.preMerge] } : {}), signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, ...workflow, reportUrl };
 }
 
 function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {

package/src/workspace/init.ts

@@ -559,7 +559,7 @@ export async function runWorkspaceInit(ctx: CommandContext): Promise<number> {
     console.error(
       formatError({
         message: `${join(root, existing[0])} already exists`,
-        hint: "Edit it by hand, or run chant workspace ls to see what it declares.",
+        hint: "Edit it by hand, or run chant workspace ls to see what it declares. To set it up for a delivery workflow, run chant ci init --workflow trunk-curated.",
       }),
     );
     return 1;
@@ -612,7 +612,7 @@ export async function runWorkspaceInit(ctx: CommandContext): Promise<number> {
     return 0;
   }
   writeFileSync(target, text, { flag: "wx" });
-  console.log(formatSuccess(`Wrote ${target}. chant workspace ls lists what it declares.`));
+  console.log(formatSuccess(`Wrote ${target}. chant workspace ls lists what it declares, and chant ci init --workflow trunk-curated sets up merging and releases.`));
   return 0;
 }
 

package/src/workspace/reason-codes.test.ts

@@ -29,6 +29,7 @@ import { WORK_WARNING_CODES } from "./work";
 import { BOX_FINDING_CODES } from "./checks/boxes";
 import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
 import { SECURITY_FINDING_CODES } from "./checks/security";
+import { CI_WORKFLOW_FINDING_CODES } from "./ci-workflow";
 import { WORK_ERROR_CODES, WORK_HISTORY_ERROR_CODES, WORK_LEASE_REFUSALS } from "./work-cli";
 import { RUN_STATEMENT_ERROR_CODES, RUNS_ERROR_CODES, RUNS_REASON_CODES, RUNS_WRITE_ERROR_CODES } from "./runs-cli";
 import { RUN_STATEMENT_FAILURE_CODES } from "./trust/run-statement";
@@ -68,6 +69,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   BOX_FINDING_CODES,
   DIAGRAM_FINDING_CODES,
   SECURITY_FINDING_CODES,
+  CI_WORKFLOW_FINDING_CODES,
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
   STATUS_GATE_REASON_CODES,

package/src/workspace/reason-codes.ts

@@ -247,6 +247,16 @@ export const REASONS = {
   "security-runner-start-no-key": "Under isolated-runners, .chant/trust.json lists no key under runners for a provisioner to sign runner-start statements with.",
   "security-runner-start-no-role": "Under isolated-runners, no principal under runners in .chant/trust.json holds the runner role.",
   "security-trust-unreadable": "Under isolated-runners, .chant/trust.json can't be read, so no runner-start statement can be checked.",
+  // The ci.workflow requirements (check, #4168 step 6). Each is also a WSP151 finding.
+  "ci-workflow-green-undeclared": "Under ci.workflow, the declaration has no ci.green block, so no commit gets a verdict and no release can be cut.",
+  "ci-workflow-no-pre-merge": "Under ci.workflow, ci.green.preMerge names no phase, so nothing says which checks run before the branch moves.",
+  "ci-workflow-apply-in-green": "Under ci.workflow, a phase in ci.green.require matches an apply job, which would wait on its own verdict.",
+  "ci-workflow-no-components": "Under ci.workflow, a member declares no component, so nothing of it can be cut or promoted.",
+  "ci-workflow-no-environments": "Under ci.workflow, a member's chant.config.ts declares no environments, so a release has nowhere to be promoted to.",
+  "ci-workflow-ungated-env": "Under ci.workflow, a component has no gate, so a promote to the last environment waits on no approval.",
+  "ci-workflow-pipeline-missing": "Under ci.workflow, no pipeline file runs the plan job, the merge job or chant ci tick.",
+  "ci-workflow-pipeline-differs": "Under ci.workflow, the merge job does not match the workflow: it applies under trunk-curated, or records under trunk-curated+apply-on-merge.",
+  "ci-workflow-publish-missing": "Under ci.workflow, no pipeline file runs chant release publish.",
   // A box that holds a credential (check, #2726). Each is also a WSP finding.
   "box-credential-declared": "A file in a box member's directory carries a literal secret: a credential's shape, or a literal where a credential goes. A variable or secret-manager reference is not one.",
   "box-capability-unbrokered": "A capability in a member's box block names no broker, so the box would hold its credential.",

package/src/workspace/release-workflow.ts

@@ -0,0 +1,167 @@
+/**
+ * `chant release workflow` (#4168 step 6): the publish workflow, generated
+ * the way `chant ci workflow` writes the tick, where the guides used to have
+ * one pasted (guide/release-from-workstation.mdx).
+ *
+ * The job runs on a `release/**` tag, checks the tag out, fetches the ci tags
+ * and `chant/lifecycle`, builds what the targets upload, and runs `chant
+ * release publish` for the label the tag names. The security groups decide
+ * the rest, and nothing is on without one (#4168 section 8):
+ *
+ * - `supply-chain` adds `--require-provenance`, so a run with no OIDC token
+ *   fails rather than publishing without provenance.
+ * - `verified-releases` adds a `chant release verify` step before the publish.
+ *
+ * The OIDC permission (`id-token: write`, or GitLab's `id_tokens`) is always
+ * there: it costs nothing, and with it what the job uploads carries
+ * provenance whether or not the group requires it.
+ */
+import { GENERATED_MARKER } from "../discovery/files";
+import type { SecurityGroup } from "./security";
+
+export const RELEASE_WORKFLOW_FORGES = ["github", "forgejo", "gitlab"] as const;
+export type ReleaseWorkflowForge = (typeof RELEASE_WORKFLOW_FORGES)[number];
+
+/** Where each forge's publish workflow is written, relative to the repository root. */
+export const RELEASE_WORKFLOW_FILES: Record<ReleaseWorkflowForge, string> = {
+  github: ".github/workflows/chant-release.yml",
+  forgejo: ".forgejo/workflows/chant-release.yml",
+  // GitLab reads one .gitlab-ci.yml, which includes this file: `include: { local: .gitlab/chant-release.yml }`.
+  gitlab: ".gitlab/chant-release.yml",
+};
+
+export interface ReleaseWorkflowInput {
+  forge: ReleaseWorkflowForge;
+  /** The security groups the workspace opts into at its root. */
+  groups: ReadonlySet<SecurityGroup>;
+  /** The command that installs what the build needs. Default `npm ci`. */
+  install?: string;
+  /** The command that builds what the targets upload, or none. Default `npm run build`. */
+  build?: string | null;
+  /** What runs chant. Default `npx chant`. */
+  chant?: string;
+  /** The workspace root relative to the repository root, `.` at the top. */
+  workspaceRoot?: string;
+}
+
+/** The flags `chant release publish` gets under the groups. */
+export function publishFlags(groups: ReadonlySet<SecurityGroup>): string[] {
+  return [...(groups.has("supply-chain") ? ["--require-provenance"] : []), "--yes"];
+}
+
+/** The workflow file's text, without the generated-by header. */
+export function renderReleaseWorkflow(input: ReleaseWorkflowInput): string {
+  const chant = input.chant ?? "npx chant";
+  const install = input.install ?? "npm ci";
+  const build = input.build === undefined ? "npm run build" : input.build;
+  const root = input.workspaceRoot && input.workspaceRoot !== "." ? input.workspaceRoot : null;
+  const verify = input.groups.has("verified-releases");
+  const flags = publishFlags(input.groups).join(" ");
+  if (input.forge === "gitlab") {
+    const label = '"${CI_COMMIT_TAG#release/}"';
+    const lines = [
+      "chant-release-publish:",
+      "  rules:",
+      "    - if: $CI_COMMIT_TAG =~ /^release\\//",
+      "  id_tokens:",
+      "    SIGSTORE_ID_TOKEN:",
+      "      aud: sigstore",
+      "  script:",
+      ...(root ? [`    - cd ${root}`] : []),
+      `    - ${install}`,
+      ...(build ? [`    - ${build}`] : []),
+      "    - git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'",
+      "    - git fetch origin chant/lifecycle:chant/lifecycle",
+      ...(verify ? [`    - ${chant} release verify ${label}`] : []),
+      `    - ${chant} release publish ${label} ${flags}`,
+    ];
+    return `${lines.join("\n")}\n`;
+  }
+  const label = '"${GITHUB_REF_NAME#release/}"';
+  const lines = [
+    "name: chant release publish",
+    "on:",
+    "  push:",
+    '    tags: ["release/**"]',
+    "permissions:",
+    "  contents: write",
+    "  id-token: write",
+    "jobs:",
+    "  publish:",
+    "    runs-on: ubuntu-latest",
+    ...(root ? ["    defaults:", "      run:", `        working-directory: ${root}`] : []),
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    "        with:",
+    "          fetch-depth: 0",
+    "      - uses: actions/setup-node@v4",
+    "        with:",
+    "          node-version: 24",
+    "          registry-url: https://registry.npmjs.org",
+    `      - run: ${install}`,
+    ...(build ? [`      - run: ${build}`] : []),
+    "      - run: git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'",
+    "      - run: git fetch origin chant/lifecycle:chant/lifecycle",
+    ...(verify ? [`      - run: ${chant} release verify ${label}`] : []),
+    `      - run: ${chant} release publish ${label} ${flags}`,
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+/** The header that marks the file generated, naming the command that regenerates it. */
+export function releaseWorkflowHeader(command: string): string {
+  return `# ${GENERATED_MARKER}. Regenerate with: ${command} (in the workspace root)\n`;
+}
+
+/**
+ * `chant release workflow [--forge github|gitlab|forgejo] [--install <command>]
+ * [--build <command>|--no-build] [--chant <command>] [--output <file>]`: write
+ * the publish workflow for the workspace's forge, under its security groups.
+ */
+export async function runReleaseWorkflow(ctx: import("../cli/registry").CommandContext): Promise<number> {
+  const { existsSync, mkdirSync, realpathSync, writeFileSync } = await import("node:fs");
+  const { dirname, join, relative, resolve, sep } = await import("node:path");
+  const { formatError, formatSuccess } = await import("../cli/format");
+  const { findWorkspaceRoot } = await import("../project-root");
+  const { gitTop } = await import("./tree");
+  const { securityGroupsAt } = await import("./security");
+  const { shellArg } = await import("./member-pipeline");
+  const usage = "chant release workflow [--forge github|gitlab|forgejo] [--install <command>] [--build <command>] [--chant <command>] [--output <file>]";
+  const { args } = ctx;
+  const found = findWorkspaceRoot(process.cwd());
+  if (!found) {
+    console.error(formatError({ message: "no chant.workspace.json between this directory and the git root", hint: usage }));
+    return 1;
+  }
+  const root = realpathSync(found.dir);
+  const repoRoot = gitTop(root) ?? root;
+  const forge = (args.forge ??
+    (existsSync(join(repoRoot, ".github", "workflows")) ? "github" : existsSync(join(repoRoot, ".forgejo", "workflows")) ? "forgejo" : existsSync(join(repoRoot, ".gitlab-ci.yml")) ? "gitlab" : "github")) as ReleaseWorkflowForge;
+  if (!(RELEASE_WORKFLOW_FORGES as readonly string[]).includes(forge)) {
+    console.error(formatError({ message: `--forge ${JSON.stringify(forge)} is not one of ${RELEASE_WORKFLOW_FORGES.join(", ")}`, hint: usage }));
+    return 1;
+  }
+  const groups = securityGroupsAt(root);
+  const workspaceRoot = relative(repoRoot, root).split(sep).join("/") || ".";
+  const text = renderReleaseWorkflow({
+    forge,
+    groups,
+    workspaceRoot,
+    ...(args.ciInstall ? { install: args.ciInstall } : {}),
+    ...(args.buildCommand ? { build: args.buildCommand } : {}),
+    ...(args.ciChant ? { chant: args.ciChant } : {}),
+  });
+  const target = args.output ? resolve(process.cwd(), args.output) : join(repoRoot, RELEASE_WORKFLOW_FILES[forge]);
+  const parts = ["chant", "release", "workflow", "--forge", forge];
+  if (args.ciInstall) parts.push("--install", args.ciInstall);
+  if (args.buildCommand) parts.push("--build", args.buildCommand);
+  if (args.ciChant) parts.push("--chant", args.ciChant);
+  if (args.output) parts.push("--output", relative(root, target).split(sep).join("/"));
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, releaseWorkflowHeader(parts.map(shellArg).join(" ")) + text);
+  const shown = relative(process.cwd(), target).split(sep).join("/") || target;
+  const extras = [groups.has("supply-chain") ? "requires OIDC provenance (supply-chain)" : null, groups.has("verified-releases") ? "verifies the release first (verified-releases)" : null].filter(Boolean);
+  console.log(formatSuccess(`Wrote ${shown}: publishes the release a release/** tag names${extras.length > 0 ? `, and ${extras.join(" and ")}` : ""}.`));
+  if (forge === "gitlab") console.log(`Include it from .gitlab-ci.yml: include: [{ local: ${RELEASE_WORKFLOW_FILES.gitlab} }]`);
+  return 0;
+}