@intentius/chant 0.124.27 → 0.124.29

package/dist/cli/commands/build.js

@@ -4,7 +4,7 @@ import { resolveBuildModes, resolveProjectBuildOptions } from "../build-options.
 import { resolveTelemetryAttribution } from "../../telemetry-attribution.js";
 import { loadOkfBundle } from "../../okf-read.js";
 import { unknownEnvError } from "../../env.js";
-import { resolveCliBuildParams } from "../build-params-cli.js";
+import { resolveFlaggedBuildParams } from "../../flag-params.js";
 import { runPostSynthChecks } from "../../lint/post-synth.js";
 import { loadActivityContracts } from "../../op/activity-contract-registry.js";
 import { isOpEntity } from "../../op/resource.js";
@@ -25,6 +25,10 @@ import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } fro
 import { writeFileSync, mkdirSync } from "fs";
 import { resolve, dirname, join, relative } from "path";
 import { watchDirectory, formatTimestamp, formatChangedFiles } from "../watch.js";
+function writeFileCreatingDir(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+}
 /**
  * Resolve the output format for `chant build`.
  *
@@ -148,11 +152,14 @@ export async function buildCommand(options) {
     // project's own `params.ts` does before migrating to this mechanism). Also
     // logs a one-line count on success, or every resolved value (`[param] name =
     // value (source)`) under --verbose (#1424).
-    const paramsResolution = resolveCliBuildParams(config.buildParams, {
+    // #4024: in a workspace member, a build for an environment also reads the
+    // flag records that back its parameters, and refuses an override of one
+    // where the environment has a gate (../../flag-params.ts).
+    const paramsResolution = await resolveFlaggedBuildParams(configDir, config.buildParams, {
         cli: options.params,
         paramsFile: options.paramsFile,
         verbose: options.verbose,
-    });
+    }, options.env);
     if (!paramsResolution.success) {
         errors.push(...paramsResolution.errors);
         return { success: false, resourceCount: 0, fileCount: 0, errors, warnings };
@@ -552,6 +559,7 @@ export async function buildCommand(options) {
         }));
     }
     // Handle output
+    const writeOutput = options.writeFile ?? writeFileCreatingDir;
     if (result.errors.length === 0 && errors.length === 0) {
         // Extract primary content and collect additional files from SerializerResult.
         // Each entry remembers which lexicon produced it, so a same-basename
@@ -680,8 +688,7 @@ export async function buildCommand(options) {
             additionalFiles.delete(filename);
             try {
                 const targetPath = join(projectDist, filename);
-                mkdirSync(dirname(targetPath), { recursive: true });
-                writeFileSync(targetPath, entry.content);
+                writeOutput(targetPath, entry.content);
                 opsWritten += 1;
             }
             catch (err) {
@@ -706,8 +713,7 @@ export async function buildCommand(options) {
                 continue;
             try {
                 const targetPath = join(projectDist, "ops", config.name, "op.json");
-                mkdirSync(dirname(targetPath), { recursive: true });
-                writeFileSync(targetPath, serializeOpIR(config));
+                writeOutput(targetPath, serializeOpIR(config));
                 irWritten += 1;
             }
             catch (err) {
@@ -724,8 +730,7 @@ export async function buildCommand(options) {
             // output path and any nested additional-file paths (e.g. ops/<name>/...).
             try {
                 const outputPath = resolve(options.output);
-                mkdirSync(dirname(outputPath), { recursive: true });
-                writeFileSync(outputPath, output);
+                writeOutput(outputPath, output);
                 // Write additional files (e.g. nested stack templates) alongside the primary output
                 if (additionalFiles.size > 0) {
                     const outputDir = dirname(outputPath);
@@ -746,8 +751,7 @@ export async function buildCommand(options) {
                             }
                         }
                         const targetPath = join(outputDir, filename);
-                        mkdirSync(dirname(targetPath), { recursive: true });
-                        writeFileSync(targetPath, fileContent);
+                        writeOutput(targetPath, fileContent);
                     }
                 }
             }

package/dist/cli/commands/check-lexicon-docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-lexicon-docs.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check-lexicon-docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAM9D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAkB1E;AAED,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAClB,gFAAgF;IAChF,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAID;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAa9E"}
+{"version":3,"file":"check-lexicon-docs.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check-lexicon-docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAM9D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAkB1E;AAED,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAClB,gFAAgF;IAChF,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAID;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAa9E"}

package/dist/cli/commands/check-lexicon-docs.js

@@ -14,7 +14,9 @@
  * membership is the whole of reachability for a lexicon site.
  */
 import { existsSync, readdirSync, readFileSync } from "fs";
-import { join } from "path";
+import { basename, join, resolve } from "path";
+import { collectSidebarSlugs } from "../../codegen/docs.js";
+import { findChantDocsSite, sectionContentDir } from "../../codegen/docs-in-site.js";
 /**
  * Slugs the sidebar reaches, including nested group `items`.
  *
@@ -42,7 +44,7 @@ export function auditDocsReachability(lexiconDir) {
     const contentDir = join(lexiconDir, "docs", "src", "content", "docs");
     const configPath = join(lexiconDir, "docs", "astro.config.mjs");
     if (!existsSync(contentDir) || !existsSync(configPath)) {
-        return { hasSite: false, pages: [], unreachable: [] };
+        return auditSectionReachability(lexiconDir);
     }
     const slugs = sidebarSlugs(readFileSync(configPath, "utf-8"));
     const pages = readdirSync(contentDir)
@@ -77,3 +79,29 @@ export function auditDocsClassification(lexiconDir) {
     }
     return { hasPages: true, unclassified };
 }
+/**
+ * Reachability for a lexicon whose docs are a section of the chant main site
+ * (chant #3993): its generated pages under
+ * `docs/src/content/docs/lexicons/<name>/` against the `_sidebar.json` the
+ * pipeline wrote beside them. A page the fragment lists as hidden is
+ * deliberately URL-only and does not count. Before the section has been
+ * generated there is nothing to audit, which reads as no site, like a
+ * lexicon with no docs.
+ */
+function auditSectionReachability(lexiconDir) {
+    const site = findChantDocsSite(lexiconDir);
+    const name = basename(resolve(lexiconDir));
+    const dir = site ? sectionContentDir(site, name) : undefined;
+    const fragmentPath = dir ? join(dir, "_sidebar.json") : undefined;
+    if (!dir || !fragmentPath || !existsSync(fragmentPath))
+        return { hasSite: false, pages: [], unreachable: [] };
+    const fragment = JSON.parse(readFileSync(fragmentPath, "utf-8"));
+    const prefix = `lexicons/${name}/`;
+    const reached = new Set([...collectSidebarSlugs([fragment.group]), ...(fragment.hidden ?? [])].map((slug) => slug.startsWith(prefix) ? slug.slice(prefix.length) : slug));
+    const pages = readdirSync(dir)
+        .filter((f) => f.endsWith(".mdx") || f.endsWith(".md"))
+        .map((f) => f.replace(/\.mdx?$/, ""))
+        .sort();
+    const unreachable = pages.filter((slug) => slug !== "index" && !reached.has(slug));
+    return { hasSite: true, pages, unreachable };
+}

package/dist/cli/commands/check-lexicon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-lexicon.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check-lexicon.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAyBD,gEAAgE;AAChE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAIlE;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAyB/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAanC;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAazE;AAID;;GAEG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAgmBpE;AAqBD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAmDzE"}
+{"version":3,"file":"check-lexicon.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check-lexicon.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAyBD,gEAAgE;AAChE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAIlE;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAyB/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAanC;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAazE;AAID;;GAEG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA4mBpE;AAqBD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAmDzE"}

package/dist/cli/commands/check-lexicon.js

@@ -406,12 +406,23 @@ export async function checkLexicon(dir) {
         tier: 1,
         pass: hasSerializerTest,
     });
+    // A lexicon whose src/codegen/docs.ts runs docsPipeline always has a page:
+    // the pipeline writes the overview (index.mdx) from the manifest. Inside the
+    // chant repository that page is generated into the main docs site rather
+    // than committed under docs/ (chant #3993), so k3d, whose docs are all
+    // generated, has no .mdx of its own to count.
     const mdxFiles = findFiles(join(dir, "docs"), (n) => n.endsWith(".mdx"));
+    const docsTs = join(dir, "src", "codegen", "docs.ts");
+    const pipelineOverview = existsSync(docsTs) && readFileSync(docsTs, "utf-8").includes("docsPipeline(");
     items.push({
         name: "At least 1 .mdx doc page",
         tier: 1,
-        pass: mdxFiles.length > 0,
-        detail: mdxFiles.length > 0 ? `${mdxFiles.length} page(s)` : undefined,
+        pass: mdxFiles.length > 0 || pipelineOverview,
+        detail: mdxFiles.length > 0
+            ? `${mdxFiles.length} page(s)`
+            : pipelineOverview
+                ? "the docs pipeline's generated overview"
+                : undefined,
     });
     // Counting pages says nothing about whether a reader can find them.
     // Starlight has no auto-discovery, so a page missing from the sidebar is

package/dist/cli/commands/init-lexicon/templates/docs.d.ts

@@ -1,5 +1,8 @@
 /**
- * Docs site template generators for init-lexicon scaffold.
+ * Docs site template generators for init-lexicon scaffold. The app files
+ * (package.json, tsconfig, Astro config, content config) are written only for a
+ * lexicon outside the chant repository; inside it, the lexicon's docs are a
+ * section of the main site (chant #3993).
  */
 export declare function generateDocsPackageJson(name: string): string;
 export declare function generateDocsTsConfig(): string;

package/dist/cli/commands/init-lexicon/templates/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/init-lexicon/templates/docs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqB5D;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAU7C;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiB5D;AAED,wBAAgB,yBAAyB,IAAI,MAAM,CAiBlD;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmBlE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWzD"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/init-lexicon/templates/docs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiB5D;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAU7C;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiB5D;AAED,wBAAgB,yBAAyB,IAAI,MAAM,CAiBlD;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmBlE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWzD"}

package/dist/cli/commands/init-lexicon/templates/docs.js

@@ -1,6 +1,10 @@
 /**
- * Docs site template generators for init-lexicon scaffold.
+ * Docs site template generators for init-lexicon scaffold. The app files
+ * (package.json, tsconfig, Astro config, content config) are written only for a
+ * lexicon outside the chant repository; inside it, the lexicon's docs are a
+ * section of the main site (chant #3993).
  */
+import { DOCS_SITE_DEPENDENCIES } from "../../../../codegen/docs-in-site.js";
 export function generateDocsPackageJson(name) {
     return JSON.stringify({
         name: `@intentius/chant-lexicon-${name}-docs`,
@@ -12,11 +16,7 @@ export function generateDocsPackageJson(name) {
             build: "astro build",
             preview: "astro preview",
         },
-        dependencies: {
-            "@astrojs/starlight": "^0.37.6",
-            astro: "^5.6.1",
-            sharp: "^0.34.2",
-        },
+        dependencies: { ...DOCS_SITE_DEPENDENCIES },
     }, null, 2) + "\n";
 }
 export function generateDocsTsConfig() {

package/dist/cli/commands/init-lexicon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-lexicon.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init-lexicon.ts"],"names":[],"mappings":"AAeA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0BAA0B;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAQD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM;IAGpC,aAAa;IACb,iBAAiB;IACjB,UAAU;IACV,WAAW;EAEd;AAqBD;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAyHhG;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBrF"}
+{"version":3,"file":"init-lexicon.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init-lexicon.ts"],"names":[],"mappings":"AAgBA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0BAA0B;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAQD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM;IAGpC,aAAa;IACb,iBAAiB;IACjB,UAAU;IACV,WAAW;EAEd;AAqBD;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAkIhG;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBrF"}

package/dist/cli/commands/init-lexicon.js

@@ -11,6 +11,7 @@ import { generatePackageJson, generateTsConfig, generateTsConfigBuild, generateJ
 import { generatePluginTestTs, generateSerializerTestTs, generateCompletionsTestTs, generateHoverTestTs } from "./init-lexicon/templates/tests.js";
 import { generateDocsPackageJson, generateDocsTsConfig, generateDocsAstroConfig, generateDocsContentConfig, generateDocsIndexMdx, generateDocsGettingStartedMdx } from "./init-lexicon/templates/docs.js";
 import { generateExamplePackageJson, generateExampleInfraTs } from "./init-lexicon/templates/examples.js";
+import { findChantDocsSite } from "../../codegen/docs-in-site.js";
 // ── Name derivation helpers ──────────────────────────────────────────
 function toCamelCase(name) {
     return name.replace(/[-_]+(.)/g, (_, c) => c.toUpperCase());
@@ -60,6 +61,12 @@ export async function initLexiconCommand(options) {
             warnings.push("Initializing in non-empty directory");
         }
     }
+    // Inside the chant repository a lexicon's docs are a section of the main
+    // site (chant #3993): the pipeline writes its pages into docs/, so the
+    // lexicon gets only docs/pages/. Anywhere else it gets a standalone
+    // Starlight app of its own, as before.
+    const standaloneDocs = findChantDocsSite(targetDir) === undefined;
+    const standaloneDocsDirs = ["docs/src", "docs/src/content", "docs/src/content/docs"];
     // Create directory structure
     const dirs = [
         "",
@@ -71,9 +78,7 @@ export async function initLexiconCommand(options) {
         "src/lsp",
         "src/generated",
         "docs",
-        "docs/src",
-        "docs/src/content",
-        "docs/src/content/docs",
+        ...(standaloneDocs ? standaloneDocsDirs : []),
         "docs/pages",
         "examples/getting-started",
         "examples/getting-started/src",
@@ -114,11 +119,15 @@ export async function initLexiconCommand(options) {
         "justfile": generateJustfile(name),
         ".gitignore": generateGitignore(),
         "README.md": generateReadme(name, names),
-        "docs/package.json": generateDocsPackageJson(name),
-        "docs/tsconfig.json": generateDocsTsConfig(),
-        "docs/astro.config.mjs": generateDocsAstroConfig(name),
-        "docs/src/content.config.ts": generateDocsContentConfig(),
-        "docs/src/content/docs/index.mdx": generateDocsIndexMdx(name),
+        ...(standaloneDocs
+            ? {
+                "docs/package.json": generateDocsPackageJson(name),
+                "docs/tsconfig.json": generateDocsTsConfig(),
+                "docs/astro.config.mjs": generateDocsAstroConfig(name),
+                "docs/src/content.config.ts": generateDocsContentConfig(),
+                "docs/src/content/docs/index.mdx": generateDocsIndexMdx(name),
+            }
+            : {}),
         "docs/pages/getting-started.mdx": generateDocsGettingStartedMdx(name),
         "examples/getting-started/package.json": generateExamplePackageJson(name),
         "examples/getting-started/src/infra.ts": generateExampleInfraTs(name, names),

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

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

package/dist/cli/handlers/approve.js

@@ -11,7 +11,7 @@ import { appendGateResolution, appendPendingGate, readGateLedger, latestPendingG
 import { isPlanDigest, samePlanDigest } from "../../lifecycle/plan-digest.js";
 import { gateContextDigest, gatePolicyRequest, loadGatePolicyEvaluator, } from "../../op/gate-approval.js";
 import { approverOf, humanQuorumSince, tallyGateApprovals } from "../../op/gate.js";
-import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name.js";
+import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, RELEASE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name.js";
 import { PR_GATE_OP } from "../../pr-loop.js";
 import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git.js";
 import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note.js";
@@ -99,6 +99,8 @@ export async function runApprove(ctx) {
             timestamp: now,
             expiresAt: now,
             ...(standing.description ? { description: standing.description } : {}),
+            ...(standing.runId ? { runId: standing.runId } : {}),
+            ...(standing.gitSha ? { gitSha: standing.gitSha } : {}),
         });
         const push = await reportedPush(`The expiry is recorded locally on ${LIFECYCLE_BRANCH}. Until it reaches the remote, ` +
             `a run in another checkout still sees the old pending fact.`);
@@ -109,7 +111,9 @@ export async function runApprove(ctx) {
                 ? `The next \`chant components pr-apply\` decides this gate from scratch and records a fresh pending fact.`
                 : opName === WORKSPACE_UPGRADE_GATE_OP
                     ? `The next \`chant workspace upgrade ${gate}\` decides this gate from scratch and records a fresh pending fact.`
-                    : `The next \`chant run ${opName}\` decides this gate from scratch and records a fresh pending fact.`));
+                    : opName === RELEASE_GATE_OP
+                        ? `The next \`chant components promote --release\` decides this gate from scratch and records a fresh pending fact.`
+                        : `The next \`chant run ${opName}\` decides this gate from scratch and records a fresh pending fact.`));
         return 0;
     }
     // #3760: an override of a denied plan names its rules and gives a reason.
@@ -154,9 +158,48 @@ export async function runApprove(ctx) {
                 ? `The pull request's apply (\`chant components pr-apply\`) walks through gate "${gate}" when it plans this same digest.`
                 : opName === WORKSPACE_UPGRADE_GATE_OP
                     ? `Repeat \`chant workspace upgrade ${gate}\` with the same target, and it applies the patch this approval names.`
-                    : `Run \`chant run ${opName}\` and it walks through gate "${gate}".`)));
+                    : opName === RELEASE_GATE_OP
+                        ? `Repeat the same \`chant components promote --release\`, and it walks through gate "${gate}" when it plans this same change set for this release.`
+                        : `Run \`chant run ${opName}\` and it walks through gate "${gate}".`)));
     return 0;
 }
+/**
+ * Refuse the approval of a release gate whose release is revoked (#4033,
+ * ws-105): its commit carries a `ci/revoked/<sha>` tag that counts, read from
+ * local tags as `release cut` reads them. Prints the refusal and returns true
+ * when it refuses. A release file that can't be read, or tags that can't be
+ * judged, refuse too, since whether the release is revoked is then unknown.
+ */
+async function refuseRevokedRelease(opName, gate, releaseDigest, cwd) {
+    const { readRelease, readCuts, labelsByDigest } = await import("../../lifecycle/release-store.js");
+    const { readRevokedCommits, revocationOf, revokedRefusal } = await import("../../lifecycle/release-revocation.js");
+    const release = await readRelease(releaseDigest, { cwd }).catch(() => null);
+    if (!release) {
+        console.error(formatError({
+            message: `Gate "${gate}" on "${opName}" binds release ${releaseDigest}, which can't be read from ${LIFECYCLE_BRANCH}, so whether it is revoked is unknown [release-unreadable]`,
+            hint: `Fetch the ledger branch (git fetch origin ${LIFECYCLE_BRANCH}:${LIFECYCLE_BRANCH}) and approve again from the member's directory.`,
+        }));
+        return true;
+    }
+    let revoked;
+    try {
+        revoked = await readRevokedCommits(cwd);
+    }
+    catch (err) {
+        console.error(formatError({
+            message: `Gate "${gate}" on "${opName}" binds release ${releaseDigest}, and the ci tags can't be judged: ${err instanceof Error ? err.message : String(err)} [declaration-invalid]`,
+            hint: "Fix ci.green in chant.workspace.json at base; chant workspace check names the problem.",
+        }));
+        return true;
+    }
+    const r = revocationOf(release, revoked);
+    if (!r)
+        return false;
+    const label = labelsByDigest((await readCuts({ cwd }).catch(() => ({ cuts: [] }))).cuts).get(releaseDigest) ?? null;
+    console.error(formatError(revokedRefusal({ releaseDigest, label }, r, `Clear the pending gate with \`chant approve ${opName} ${gate} --expire\`, then promote a release cut from a green commit: ` +
+        "`chant ci last-green` names the newest, and `chant release list` marks the revoked releases.")));
+    return true;
+}
 /**
  * The ledger write behind `chant approve` — extracted so `chant run approve`
  * (#2121) records the identical fact before waking the runtime that hosts the
@@ -187,7 +230,7 @@ export async function recordGateApproval(opName, gate, opts) {
     // so there is no `*.op.ts` to find and nothing is wrong when none is there.
     // #3949: a gate that lists this one as an alias, after an Op was restructured.
     const successor = aliasingGate([...ops.values()].map((o) => o.config), opName, gate);
-    if (!successor && !ops.has(opName) && opName !== FAN_OUT_GATE_OP && opName !== WORKSPACE_UPGRADE_GATE_OP && opName !== OVERRIDE_GATE_OP) {
+    if (!successor && !ops.has(opName) && opName !== FAN_OUT_GATE_OP && opName !== WORKSPACE_UPGRADE_GATE_OP && opName !== OVERRIDE_GATE_OP && opName !== RELEASE_GATE_OP) {
         console.error(formatWarning({
             message: `Op "${opName}" was not found among discovered *.op.ts declarations — recording the resolution anyway`,
         }));
@@ -284,6 +327,18 @@ export async function recordGateApproval(opName, gate, opts) {
     const checkpointDigest = standing?.checkpointDigest !== undefined && samePlanDigest(planDigest, standing.planDigest)
         ? standing.checkpointDigest
         : undefined;
+    // #4045: a release gate's fact names the release its change set was
+    // planned for. An approval of that fact's plan is for that release too; an
+    // approval of another plan names none, and no release gate counts it.
+    const releaseDigest = standing?.releaseDigest !== undefined && samePlanDigest(planDigest, standing.planDigest) ? standing.releaseDigest : undefined;
+    // #4033 (ws-105): a release gate whose release was cut from a revoked
+    // commit is superseded. Its promote refuses the release, so an approval of
+    // it would count for nothing; refuse it here, whatever plan is named.
+    if (standing?.releaseDigest !== undefined) {
+        const refused = await refuseRevokedRelease(opName, gate, standing.releaseDigest, opts.cwd ?? process.cwd());
+        if (refused)
+            return { ok: false };
+    }
     // chant#2384 — the gate's whole value is that its two halves have different
     // authors. At a shell they do: a person runs, reads the plan, and approves.
     // On MCP and ACP the person's only act was launching the server, and every
@@ -476,6 +531,10 @@ export async function recordGateApproval(opName, gate, opts) {
         ...(planDigest !== undefined ? { planDigest } : {}),
         ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
         ...(environment !== undefined ? { environment } : {}),
+        ...(releaseDigest !== undefined ? { releaseDigest } : {}),
+        // #4020: the commit and run the gate waited on, off the fact this approves.
+        ...(standing?.gitSha ? { gitSha: standing.gitSha } : {}),
+        ...(standing?.runId ? { runId: standing.runId } : {}),
         origin,
         ...(refusal && opts.allowSameOrigin ? { sameOriginOverride: true } : {}),
     });
@@ -490,6 +549,7 @@ export async function recordGateApproval(opName, gate, opts) {
     if (record.planDigest) {
         console.error(formatInfo(`This approves the plan ${record.planDigest}` +
             (record.environment !== undefined ? ` in environment "${record.environment}"` : "") +
+            (record.releaseDigest !== undefined ? ` for release ${record.releaseDigest}` : "") +
             ", and only that plan. A run whose fresh plan differs refuses rather than applying it."));
     }
     if (record.checkpointDigest) {

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

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/build.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA+IlD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAkJnE"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/build.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAyLlD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAkJnE"}

package/dist/cli/handlers/build.js

@@ -6,6 +6,20 @@ import { generateComponentsPipeline } from "../../components/cli-support.js";
 import { loadChantConfigUpward } from "../../config.js";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli.js";
 import { findWorkspaceRoot } from "../../project-root.js";
+import { resolvePromotionSource } from "../../components/promote-order.js";
+/**
+ * The `prLoop` generator option from `--pr-loop`'s flags (#3183): the gate
+ * and the branch, and with `--events-json` and `--report-url` (#4007) the
+ * flags the generated jobs pass to pr-plan and pr-apply.
+ */
+function prLoopOption(args) {
+    return {
+        ...(args.gate ? { gate: args.gate } : {}),
+        ...(args.branch ? { branch: args.branch } : {}),
+        ...(args.eventsJson ? { events: true } : {}),
+        ...(args.reportUrl ? { reportUrl: args.reportUrl } : {}),
+    };
+}
 /**
  * `chant build --components --generate <lexicon>` — generate mode (#563,
  * epic #551 Phase 3). Discovers `Component` declarations under `args.path`
@@ -42,6 +56,23 @@ async function runGenerateComponents(ctx) {
             console.error(message);
         return 1;
     }
+    // #4030: the generated promote job runs `promote --from <env> --to <promote-to>`,
+    // which the member's declared promotion order refuses when it skips a step.
+    // Refuse here, with the same code, rather than write a job that fails.
+    if (args.promoteTo) {
+        // Loaded here, not at the top: a build without --promote-to loads no workspace module (#2526).
+        const { promotionOrder } = await import("../../workspace/promotion-order.js");
+        const resolved = resolvePromotionSource({
+            order: promotionOrder(config.environments),
+            to: args.promoteTo,
+            from: args.env ?? "production",
+            ...(args.allowSkip ? { allowSkip: true } : {}),
+        });
+        if ("error" in resolved) {
+            console.error(formatError({ message: `${resolved.error.message} [${resolved.error.code}]`, hint: resolved.error.fix }));
+            return 1;
+        }
+    }
     // A project inside a workspace member gets that member's pipeline (#2542):
     // path-filtered, run in the member's directory, written to a file named
     // after the member and recorded as the member's generated file. The
@@ -59,11 +90,14 @@ async function runGenerateComponents(ctx) {
                 lexicon,
                 env: args.env,
                 promoteTo: args.promoteTo,
+                ...(args.allowSkip ? { allowSkip: true } : {}),
                 output: args.output,
                 params: args.param,
                 paramsFile: args.paramsFile,
                 ...(args.waveGate ? { waveGate: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } } : {}),
-                ...(args.prLoop ? { prLoop: { ...(args.gate ? { gate: args.gate } : {}), ...(args.branch ? { branch: args.branch } : {}) } } : {}),
+                ...(args.prLoop ? { prLoop: prLoopOption(args) } : {}),
+                ...(args.image ? { image: args.image } : {}),
+                ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
             });
         }
         catch (err) {
@@ -78,15 +112,20 @@ async function runGenerateComponents(ctx) {
     const result = await generateComponentsPipeline(args.path, lexicon, {
         env: args.env,
         ...(args.promoteTo ? { promoteTo: args.promoteTo } : {}),
+        // #4030: the job passes --allow-skip through, so it is not refused again at deploy time.
+        ...(args.promoteTo && args.allowSkip
+            ? { promoteCommand: ["chant", "components", "promote", "--from", args.env ?? "production", "--to", args.promoteTo, "--allow-skip"] }
+            : {}),
         ...(plan ? { member: plan.member } : {}),
         // #3049: one job per wave of a gated-wave fan-out instead of one per component.
         ...(args.waveGate
             ? { gatedWaves: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } }
             : {}),
         // #3183: a plan job per pull request and an apply job per merge.
-        ...(args.prLoop
-            ? { prLoop: { ...(args.gate ? { gate: args.gate } : {}), ...(args.branch ? { branch: args.branch } : {}) } }
-            : {}),
+        ...(args.prLoop ? { prLoop: prLoopOption(args) } : {}),
+        // #4002: the job image and the lines that install what it lacks, chant itself included.
+        ...(args.image ? { image: args.image } : {}),
+        ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
     }, args.sandbox, paramsResolution.provenance);
     if (!result.success) {
         console.error(formatError({ message: result.error ?? "Failed to generate CI pipeline from components" }));

package/dist/cli/handlers/change-set.d.ts

@@ -8,4 +8,14 @@ import type { CommandContext } from "../registry.js";
  * file; no project, no plugins, no network.
  */
 export declare function runChangeSetSummary(ctx: CommandContext): Promise<number>;
+/**
+ * `chant change-set show <digest>` (#4022): the change-set document a gate
+ * bound, stored on `chant/lifecycle` under its digest, with each entry's
+ * graph node. `--json` prints the read contract's `change-set-show`
+ * document (`../../workspace/change-set-show.ts`); without it, the grouped
+ * summary and each entry with its node. `--member` reads a workspace
+ * member's ledger from anywhere in the checkout. Exit 1 when nothing is
+ * stored under the digest.
+ */
+export declare function runChangeSetShow(ctx: CommandContext): Promise<number>;
 //# sourceMappingURL=change-set.d.ts.map

package/dist/cli/handlers/change-set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/change-set.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2B9E"}
+{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/change-set.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKlD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2B9E;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAmC3E"}

package/dist/cli/handlers/change-set.js

@@ -1,8 +1,10 @@
 import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { CHANGE_SET_CONTRACT, CHANGE_SET_SCHEMA_ID } from "../../change-set.js";
 import { GITHUB_COMMENT_LIMIT, groupChangeSet, renderPlanSummaryMarkdown, renderPlanSummaryText } from "../../plan-summary.js";
-import { formatError } from "../format.js";
+import { formatError, formatWarning } from "../format.js";
 const USAGE = "chant change-set summary <change-set.json> [--format text|json|markdown] [--limit <chars>]";
+const SHOW_USAGE = "chant change-set show <digest> [--member <name>] [--json]";
 /**
  * `chant change-set summary <file>` (#3188): the grouped plan summary of a
  * change-set document (`../../change-set.ts`), such as the `document` a
@@ -44,3 +46,51 @@ export async function runChangeSetSummary(ctx) {
         process.stdout.write(renderPlanSummaryText(summary));
     return 0;
 }
+/**
+ * `chant change-set show <digest>` (#4022): the change-set document a gate
+ * bound, stored on `chant/lifecycle` under its digest, with each entry's
+ * graph node. `--json` prints the read contract's `change-set-show`
+ * document (`../../workspace/change-set-show.ts`); without it, the grouped
+ * summary and each entry with its node. `--member` reads a workspace
+ * member's ledger from anywhere in the checkout. Exit 1 when nothing is
+ * stored under the digest.
+ */
+export async function runChangeSetShow(ctx) {
+    const { args } = ctx;
+    const digest = args.extraPositional;
+    const { changeSetShowDocument, CHANGE_SET_DIGEST_PATTERN } = await import("../../workspace/change-set-show.js");
+    if (!digest || !CHANGE_SET_DIGEST_PATTERN.test(digest)) {
+        console.error(formatError({ message: digest ? `${digest} is not a change-set digest` : "change-set show needs the digest a gate binds", hint: SHOW_USAGE }));
+        return 1;
+    }
+    if ((args.members?.length ?? 0) > 1) {
+        console.error(formatError({ message: `change-set show reads one member, not ${args.members.join(", ")}`, hint: SHOW_USAGE }));
+        return 1;
+    }
+    const member = args.members?.[0]?.split("/").filter(Boolean);
+    const doc = await changeSetShowDocument({ cwd: resolve("."), digest, ...(member ? { member } : {}) });
+    if (args.json) {
+        console.log(JSON.stringify(doc, null, 2));
+        return "error" in doc || doc.changeSet === null ? 1 : 0;
+    }
+    if ("error" in doc) {
+        console.error(formatError({ message: doc.error.message, hint: SHOW_USAGE }));
+        return 1;
+    }
+    if (doc.reason)
+        console.error(formatWarning({ message: doc.reason.message }));
+    if (doc.changeSet === null) {
+        if (!doc.reason)
+            console.error(formatError({ message: `no change set is stored under ${digest}${doc.member ? ` for member ${doc.member}` : ""}`, hint: "A pull-request or release gate stores the change set it binds; a component gate binds a lifecycle plan and stores none." }));
+        return 1;
+    }
+    process.stdout.write(renderPlanSummaryText(groupChangeSet(doc.changeSet)));
+    const graph = doc.changeSet.graph;
+    console.log(graph ? `\nNodes from the graph of ${graph.member ?? "this project"}${graph.at ? ` at ${graph.at.slice(0, 12)}` : ""}:` : "\nNo graph was read, so no entry has a node.");
+    for (const e of doc.changeSet.entries) {
+        if (e.action === "no-op" || e.action === "read")
+            continue;
+        console.log(`  ${e.action.padEnd(8)} ${e.member}  ${e.address}${e.deposed ? ` (deposed ${e.deposed})` : ""}  ${e.node ?? "(no node)"}`);
+    }
+    return 0;
+}

package/dist/cli/handlers/fan-out.d.ts

@@ -34,6 +34,15 @@
  * the plan before the gate is decided, and the digest is carried rather than
  * recomputed, so the approval still stands.
  *
+ * The approval and the progress are bound to different things (#4081). The
+ * approval is bound to the plan digest, the derivation: who runs, in what
+ * order, off which edges. The progress is bound to each component's input
+ * digest (../../components/fan-out-inputs.ts): a component the earlier
+ * attempt applied stays `already-applied` only while what it would apply is
+ * the same, and one whose template, step inputs or upstream moved runs again
+ * with a line saying so. The fix after a failure keeps the approval, and a
+ * different change of the same shape does not inherit the progress.
+ *
  * `--wave-gate <name>` (#3049) swaps the one gate for one per wave: the same
  * repeated command stops at each wave's gate in turn, each planned after the
  * wave before it applied, and `chant approve fan-out <name>-wave-<n>` answers
@@ -72,7 +81,7 @@ export declare function resolveChangedUnits(ctx: CommandContext, config: ChantCo
  * chant components fan-out --base <ref> | --from-affected <file>
  *   [--head <ref>] [--include-dependents] [--env <env>] [--gate <name>]
  *   [--dry-run] [--json] [--resume <file>] [--seed-outputs <file>]
- *   [--dump-outputs <file>] [--progress-json]
+ *   [--dump-outputs <file>] [--progress-json | --events-json]
  */
 export declare function runComponentsFanOut(ctx: CommandContext): Promise<number>;
 //# sourceMappingURL=fan-out.d.ts.map

package/dist/cli/handlers/fan-out.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fan-out.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/fan-out.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,EAA+C,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAa7F,OAAO,EAAmB,KAAK,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AAMnG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE;IACJ,yFAAyF;IACzF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,UAAU,CAAC,EAAE,OAAO,CAAC;CACjB,GACL,OAAO,CAAC;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA+ErE;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAoR9E"}
+{"version":3,"file":"fan-out.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/fan-out.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,OAAO,EAA+C,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAe7F,OAAO,EAAmB,KAAK,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AAMnG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE;IACJ,yFAAyF;IACzF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,UAAU,CAAC,EAAE,OAAO,CAAC;CACjB,GACL,OAAO,CAAC;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA+ErE;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAwT9E"}