@intentius/chant 0.79.0 → 0.81.0

package/src/cli/path-lexicon-messages.test.ts

@@ -0,0 +1,152 @@
+/**
+ * chant#2578 — init, onboard, audit and import-agents name a lexicon declared
+ * by path (#2520) by that path, and print no install line for it. A lexicon
+ * named by package keeps its package name and `npm i` line.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  lexiconPackagesToInstall,
+  lexiconSourceLabel,
+  registerLexiconDeclarations,
+  resetLexiconModules,
+} from "../lexicon-module";
+import { initCommand } from "./commands/init";
+import { onboardCommand } from "./commands/onboard";
+import { installLine } from "./commands/audit";
+import { importAgentsCommand } from "./commands/import-agents";
+import { auditFiles, MissingLexiconError, type AuditInput } from "../audit/core";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-2578-")));
+  resetLexiconModules();
+});
+
+afterEach(() => {
+  resetLexiconModules();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("the shared helpers", () => {
+  test("a path lexicon is labelled by its path and has no package to install", () => {
+    registerLexiconDeclarations(["aws", { name: "site", module: "./lexicon/index.ts" }], dir);
+    expect(lexiconSourceLabel("site", dir)).toBe("./lexicon/index.ts");
+    expect(lexiconSourceLabel("aws", dir)).toBe("@intentius/chant-lexicon-aws");
+    expect(lexiconPackagesToInstall(["aws", "site"])).toEqual(["@intentius/chant-lexicon-aws"]);
+  });
+
+  test("a path outside the directory is shown absolute", () => {
+    registerLexiconDeclarations([{ name: "site", module: "/elsewhere/site.ts" }], dir);
+    expect(lexiconSourceLabel("site", dir)).toBe("/elsewhere/site.ts");
+  });
+});
+
+describe("init", () => {
+  function writeConfig(entry: string): void {
+    writeFileSync(join(dir, "chant.config.ts"), `export default { lexicons: [${entry}] };\n`);
+  }
+
+  test("a lexicon the existing config declares by path gets no dependency and no type stub", async () => {
+    writeConfig(`{ name: "site", module: "./lexicon/index.ts" }`);
+    const result = await initCommand({ path: dir, lexicon: "site", force: true, skipMcp: true, skipInstall: true });
+
+    expect(result.success).toBe(true);
+    expect(result.lexiconModule).toBe("./lexicon/index.ts");
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+    expect(Object.keys(pkg.dependencies)).toEqual(["@intentius/chant"]);
+    expect(existsSync(join(dir, ".chant", "types", "lexicon-site"))).toBe(false);
+  });
+
+  test("a package lexicon is unchanged", async () => {
+    writeConfig(`"aws"`);
+    const result = await initCommand({ path: dir, lexicon: "aws", force: true, skipMcp: true, skipInstall: true });
+
+    expect(result.success).toBe(true);
+    expect(result.lexiconModule).toBeUndefined();
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+    expect(Object.keys(pkg.dependencies)).toEqual(["@intentius/chant", "@intentius/chant-lexicon-aws"]);
+    expect(existsSync(join(dir, ".chant", "types", "lexicon-aws", "package.json"))).toBe(true);
+  });
+});
+
+describe("onboard", () => {
+  test("a lexicon declared by path is named by its path, with nothing patched", () => {
+    registerLexiconDeclarations([{ name: "site", module: "./lexicon/index.ts" }], process.cwd());
+    const result = onboardCommand({ name: "site", root: dir });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("./lexicon/index.ts");
+    expect(result.error).not.toMatch(/npm (i|install)\b/);
+    expect(result.patched).toEqual([]);
+  });
+
+  test("a package lexicon still patches", () => {
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "root", dependencies: {} }));
+    const result = onboardCommand({ name: "site", root: dir });
+
+    expect(result.success).toBe(true);
+    expect(result.patched.some((p) => p.startsWith("package.json"))).toBe(true);
+  });
+});
+
+describe("audit", () => {
+  test("the npx line leaves out a lexicon declared by path", () => {
+    registerLexiconDeclarations([{ name: "github", module: "./gh/index.ts" }], dir);
+    expect(installLine(["github", "gitlab"], ".")).toBe(
+      "npx -p @intentius/chant -p @intentius/chant-lexicon-gitlab chant audit .",
+    );
+  });
+
+  test("a path lexicon that fails to load is named by its path, with no npm line", async () => {
+    registerLexiconDeclarations([{ name: "helm", module: join(dir, "missing.ts") }], dir);
+    const input = { lexicon: "helm", path: "Chart.yaml", content: "" } as AuditInput;
+
+    const error = await auditFiles([input]).then(
+      () => undefined,
+      (err: unknown) => err,
+    );
+    expect(error).toBeInstanceOf(MissingLexiconError);
+    expect((error as Error).message).toContain(join(dir, "missing.ts"));
+    expect((error as Error).message).not.toContain("npm i");
+  });
+});
+
+describe("import-agents", () => {
+  function seedAgentConfig(home: string): void {
+    mkdirSync(join(home, ".claude"), { recursive: true });
+    writeFileSync(join(home, ".claude", "mcp.json"), JSON.stringify({ mcpServers: { a: { command: "x" } } }));
+  }
+
+  test("a path lexicon that fails to load is named by its path, with no npm line", async () => {
+    const home = join(dir, "home");
+    seedAgentConfig(home);
+    registerLexiconDeclarations([{ name: "fountain", module: "./agents/missing.ts" }], dir);
+
+    const result = await importAgentsCommand({ home, platform: "linux", projectRoots: [], output: join(dir, "out") });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("declared by path");
+    expect(result.error).toContain("missing.ts");
+    expect(result.error).not.toContain("npm i");
+  });
+
+  test("a package lexicon still gets its npm line", async () => {
+    const home = join(dir, "home");
+    seedAgentConfig(home);
+
+    const result = await importAgentsCommand({
+      home,
+      platform: "linux",
+      projectRoots: [],
+      output: join(dir, "out"),
+      lexicon: "no-such-lexicon",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("npm i @intentius/chant-lexicon-no-such-lexicon");
+  });
+});

package/src/cli/plugins.ts

@@ -1,10 +1,30 @@
+import { importLexiconModule, lexiconModulePath, lexiconNames, registerLexiconDeclarations } from "../lexicon-module";
+import { readLexiconDeclarationsStatically, type StaticLexiconRead } from "../config-static";
+export { unknownPathLexiconsNotice } from "../config-static";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { isLexiconPlugin, type LexiconPlugin } from "../lexicon";
 import { loadChantConfigUpward } from "../config";
 import { findInfraFiles, detectLexicons } from "../index";
-import { checkConflicts } from "./conflict-check";
+import { checkConflicts, describeConflict } from "./conflict-check";
+
+/**
+ * chant#2591 — record the lexicons the chant.config nearest `dir` declares by
+ * path (../lexicon-module.ts), for a command that does not otherwise read the
+ * config: `init --force`, `dev onboard` and `import --agents`.
+ *
+ * The config is read statically (../config-static.ts) and never evaluated,
+ * so these commands run no project code to learn it. When the `lexicons`
+ * value cannot be read that way, nothing is recorded, every lexicon keeps its
+ * package behaviour, and the returned read carries the reason; the caller
+ * prints {@link unknownPathLexiconsNotice} for it.
+ */
+export function recordProjectLexicons(dir: string): StaticLexiconRead {
+  const read = readLexiconDeclarationsStatically(dir);
+  if (read.status === "read") registerLexiconDeclarations(read.entries, dirname(read.configPath));
+  return read;
+}
 
 /**
  * Load a single lexicon plugin by lexicon name.
@@ -13,6 +33,23 @@ import { checkConflicts } from "./conflict-check";
  * LexiconPlugin export. Falls back to wrapping a raw Serializer export.
  */
 export async function loadPlugin(lexiconName: string): Promise<LexiconPlugin> {
+  // chant #2520 — a lexicon declared by module path loads from that module.
+  const modulePath = lexiconModulePath(lexiconName);
+  if (modulePath !== undefined) {
+    const mod = (await importLexiconModule(lexiconName))!;
+    for (const value of Object.values(mod)) {
+      if (isLexiconPlugin(value)) {
+        if (value.name !== lexiconName) {
+          throw new Error(
+            `lexicon "${lexiconName}" is declared with module ${modulePath}, but the plugin it exports is named "${value.name}"`,
+          );
+        }
+        return value;
+      }
+    }
+    throw new Error(`Module ${modulePath} (lexicon "${lexiconName}") does not export a LexiconPlugin`);
+  }
+
   const packageName = `@intentius/chant-lexicon-${lexiconName}`;
   const mod = await import(packageName);
 
@@ -67,6 +104,9 @@ export function resolveLexiconVersions(lexiconNames: readonly string[]): Record<
   const versions: Record<string, string> = {};
 
   for (const name of lexiconNames) {
+    // chant #2520 — a lexicon declared by module path is not an installed
+    // package, so it has no package version to report.
+    if (lexiconModulePath(name) !== undefined) continue;
     const packageName = `@intentius/chant-lexicon-${name}`;
     try {
       let dir = dirname(require_.resolve(packageName));
@@ -177,9 +217,7 @@ export async function loadPlugins(lexiconNames: string[]): Promise<LexiconPlugin
   }
 
   if (report.conflicts.length > 0) {
-    const details = report.conflicts
-      .map((c) => `  ${c.type} "${c.key}" from: ${c.plugins.join(", ")}`)
-      .join("\n");
+    const details = report.conflicts.map(describeConflict).join("\n");
     throw new Error(
       `Cross-lexicon conflicts detected:\n${details}`,
     );
@@ -222,7 +260,7 @@ export async function resolveProjectLexicons(projectPath: string): Promise<strin
   const { config } = await loadChantConfigUpward(projectPath);
 
   if (config.lexicons && config.lexicons.length > 0) {
-    return config.lexicons;
+    return lexiconNames(config.lexicons);
   }
 
   // Fallback: detect from source imports — a pure text scan, no execution.

package/src/cli/registry.ts

@@ -129,6 +129,8 @@ export interface ParsedArgs {
    * ignore it.
    */
   namespace?: string;
+  /** `chant workspace upgrade --allow-code` (#2550) — run migrations whose body is the template's own code. */
+  allowCode?: boolean;
   /** `chant lifecycle rollback --dry-run` — compute the rollback delta and print it; open no PR, push nothing, leave no branch. */
   dryRun?: boolean;
   /** `chant lifecycle teardown <env> --yes` — execute the planned deletion
@@ -145,6 +147,8 @@ export interface ParsedArgs {
   /** `--env <name>` — active environment: sets CHANT_ENV so env-aware source
    * re-evaluates for that environment (`build` + `graph`), and drives policy. */
   env?: string;
+  /** `chant build --components --generate <lexicon> --promote-to <env>` (#2575) — add a promote job to the generated pipeline. */
+  promoteTo?: string;
   /** `chant graph --stacks` — render the cross-stack apply-ordering graph */
   stacks?: boolean;
   /** `chant graph --live --overlay` — classify the provisioned graph against
@@ -175,8 +179,13 @@ export interface ParsedArgs {
   components?: boolean;
   /** `chant build --components --generate <lexicon>` — generate mode (#563):
    * synthesize CI YAML from discovered components instead of running a normal
-   * lexicon build. Only "gitlab" is implemented for v1. */
+   * lexicon build. Also `chant run --generate <provider>` (#2533): one CI
+   * pipeline file per scheduled Op, through `generateOpsPipeline`. */
   generate?: string;
+  /** `chant run --generate <provider> --spec <file>` (#2533): a JSON file of
+   * `ScheduledOpSpec`s (or `{ ops, options }`) to generate instead of every
+   * discovered Op that declares a `schedule`. */
+  opsSpec?: string;
   /** `chant graph --format ir --detail <0..3>` — graph IR detail tier */
   detail?: number;
   /** `chant graph --lens <kind>:<target>` — focus the graph IR on a slice */
@@ -242,6 +251,8 @@ export interface ParsedArgs {
   allProjects?: boolean;
   /** `chant audit --fail-on merge-worthy|warning|error|none` */
   failOn?: string;
+  /** `chant audit --max-files <n>` (#2528) — files the local walk takes before it stops (default 1000). */
+  maxFiles?: number;
   /** `chant audit --theme <file>` — JSON theme knobs for the HTML report */
   theme?: string;
   /** `chant dev surface-diff --update-snapshot` — write the fresh snapshot as the new baseline */
@@ -270,6 +281,29 @@ export interface ParsedArgs {
    * should win.
    */
   at?: string;
+  /** `chant workspace records --kind <path>` (#2546): the record kind file to read records through. */
+  kind?: string;
+  /** `chant workspace records --current` (#2546): leave out records a closed record supersedes. */
+  current?: boolean;
+  /** `chant workspace records|verify --require attested` (#2547): the provenance level a gate requires. */
+  require?: string;
+  /**
+   * `chant build --root-only` and `chant lint --root-only` (#2537): run on the
+   * root project of a declared workspace, members left out, instead of
+   * refusing with `WSP000`.
+   */
+  rootOnly?: boolean;
+  /**
+   * `chant workspace check --generated` (#2641): run each declared generator
+   * and compare its output with the file in the tree. Off by default, since
+   * generators run member code.
+   */
+  generated?: boolean;
+  /**
+   * `chant workspace build|lint|audit|graph --member <name>` (#2537): run only
+   * the named members or example groups. Repeatable, and a comma list works too.
+   */
+  members?: string[];
   /**
    * `chant search "<q>" --ambient --live --env <name>` (#1278) — also report
    * resources of a kind this estate manages that exist in the account without
@@ -312,6 +346,8 @@ export interface ParsedArgs {
   component?: string;
   /** `chant components release record --digest <sha256:...>` (#568) — artifact digest to record, joining this release to the build archive/ledger. Also `chant components export --digest <manifestDigest>` (#929) — a build archive manifest digest to export directly, bypassing env/component resolution. */
   digest?: string;
+  /** Every `--digest` value, in order (#2602). `chant components promote --digest <component>=<sha256:...>` is repeatable, one per component; the other commands read the single {@link digest}. */
+  digests?: string[];
   /** `chant components release record --git-sha <sha>` (#568) — git commit the deploy was built from. */
   gitSha?: string;
   /** `chant components release record --run-id <id>` (#568) — orchestrator/CI run identifier. */
@@ -328,6 +364,8 @@ export interface ParsedArgs {
   noReleaseRecord?: boolean;
   /** `chant run --components <name> --dump-outputs <file>` — after the run, write the accumulated cross-component/cross-stack outputs (JSON, keyed by component name) to `<file>`, for a downstream job to `--seed-outputs`. */
   dumpOutputs?: string;
+  /** `chant run --components <name> --digest-file <file>` (#2602) — after a successful run, write one `<component>=<digest>` line per release the run recorded to `<file>`, the form `chant components promote --digest` takes, so a generated promote job promotes exactly the release its pipeline run built. Written empty when nothing was recorded. */
+  digestFile?: string;
   /** `chant run --components <name> --seed-outputs <file>` (repeatable) — before the run, load each JSON outputs file (as written by `--dump-outputs`) and seed cross-component/cross-stack resolution with it, so a `stackOutput()`/`@<dep>.publish.*` reference to a component that ran in an earlier job resolves. */
   seedOutputs?: string[];
   /** `chant build --fold` (#1022/#1023, epic #1019) — opt-in: fold source modules statically instead of importing/running them; folds resource constructors and composite factory calls, falling back to run per-file for anything the folder can't represent (a cross-file-only reference, a re-export, `export default`, …). Also settable project-wide via `chant.config.ts`'s `build.fold: true`; the flag always wins when set. Default (flag omitted): the existing run path, unchanged. */
@@ -388,6 +426,13 @@ export interface CommandDef {
   name: string;
   /** If true, load lexicon plugins before calling handler */
   requiresPlugins?: boolean;
+  /**
+   * chant#2591, chant#2589 — the command never evaluates the project's
+   * `chant.config.ts`, so `main` does not load it before dispatch either. Such
+   * a command reads what it needs from the config statically
+   * (../config-static.ts). A function decides per invocation.
+   */
+  runsNoConfig?: boolean | ((args: ParsedArgs) => boolean);
   /** Command handler — returns exit code */
   handler: (ctx: CommandContext) => Promise<number>;
 }

package/src/cli/static-config-read.test.ts

@@ -0,0 +1,208 @@
+/**
+ * chant#2591, chant#2589 — `init --force`, `dev onboard`, `import --agents`
+ * and `audit` learn the lexicons a project declares by path without running
+ * its `chant.config.ts`.
+ *
+ * The CLI is spawned the way `bin/chant` runs it, because `main.ts` loads the
+ * config before dispatch for most commands, and a test calling the command
+ * functions would miss that load. Each fixture's config writes a marker file
+ * when it runs. The marker must never appear, and each command's output must
+ * still name the lexicon's path.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { auditCommand } from "./commands/audit";
+import { runCommandInProcess } from "./main";
+import { resetLexiconModules } from "../lexicon-module";
+import { captureRun } from "../workspace/member-run";
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const mainTs = resolve(thisDir, "main.ts");
+const repoRoot = resolve(thisDir, "../../../..");
+const tsxLoader = join(repoRoot, "node_modules", "tsx", "dist", "loader.mjs");
+
+let root: string;
+let project: string;
+let marker: string;
+let home: string;
+let moduleMarker: string;
+
+function writeConfig(lexicons: string): void {
+  writeFileSync(
+    join(project, "chant.config.ts"),
+    `import { writeFileSync } from "node:fs";\n` +
+      `writeFileSync(${JSON.stringify(marker)}, "ran");\n` +
+      `export default { lexicons: ${lexicons} };\n`,
+  );
+}
+
+beforeEach(() => {
+  resetLexiconModules();
+  root = realpathSync(mkdtempSync(join(tmpdir(), "chant-2591-cli-")));
+  project = join(root, "project");
+  marker = join(root, "config-ran");
+  home = join(root, "home");
+  moduleMarker = join(root, "module-ran");
+  mkdirSync(join(project, ".github", "workflows"), { recursive: true });
+  mkdirSync(join(project, "gh"), { recursive: true });
+  mkdirSync(join(project, ".git"));
+  // The path lexicon's module is project code too. Audit must never import it.
+  writeFileSync(
+    join(project, "gh", "index.ts"),
+    `import { writeFileSync } from "node:fs";\nwriteFileSync(${JSON.stringify(moduleMarker)}, "ran");\nexport {};\n`,
+  );
+  writeFileSync(
+    join(project, ".github", "workflows", "ci.yml"),
+    "on: push\njobs:\n  a:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n",
+  );
+  mkdirSync(join(home, ".claude"), { recursive: true });
+  writeFileSync(join(home, ".claude", "mcp.json"), JSON.stringify({ mcpServers: { a: { command: "x" } } }));
+  writeConfig(`[{ name: "github", module: "./gh/index.ts" }]`);
+});
+
+afterEach(() => {
+  resetLexiconModules();
+  rmSync(root, { recursive: true, force: true });
+});
+
+function chant(args: string[], cwd: string): string {
+  const result = spawnSync(process.execPath, ["--import", tsxLoader, mainTs, ...args], {
+    cwd,
+    env: { PATH: process.env.PATH ?? "", HOME: home },
+    encoding: "utf-8",
+    input: "n\n",
+    timeout: 60_000,
+  });
+  return `${result.stdout}\n${result.stderr}`;
+}
+
+const COMMANDS: Array<{ name: string; args: () => string[]; cwd: () => string }> = [
+  { name: "init --force", args: () => ["init", project, "--lexicon", "github", "--force", "--skip-mcp"], cwd: () => root },
+  { name: "dev onboard", args: () => ["dev", "onboard", "github"], cwd: () => project },
+  { name: "import --agents", args: () => ["import", "--agents", "--lexicon", "github", "--output", join(root, "out")], cwd: () => project },
+];
+
+describe("commands that read path lexicons statically run no project code", () => {
+  for (const command of COMMANDS) {
+    for (const sandbox of [false, true]) {
+      test(`${command.name}${sandbox ? " --sandbox" : ""} names the path and never runs chant.config.ts`, () => {
+        const output = chant([...command.args(), ...(sandbox ? ["--sandbox"] : [])], command.cwd());
+        expect(output).toContain("./gh/index.ts");
+        expect(existsSync(marker)).toBe(false);
+      }, 90_000);
+    }
+  }
+
+  test("audit never runs chant.config.ts or the path lexicon's module", () => {
+    chant(["audit", project], root);
+    expect(existsSync(marker)).toBe(false);
+    expect(existsSync(moduleMarker)).toBe(false);
+  }, 90_000);
+
+  test("a config it cannot read is reported, and still not run", () => {
+    writeConfig(`process.env.CI ? ["github"] : [{ name: "github", module: "./gh/index.ts" }]`);
+    const output = chant(["dev", "onboard", "github"], project);
+    expect(output).toContain("could not read the lexicons in");
+    expect(output).toContain("treated as a package");
+    expect(existsSync(marker)).toBe(false);
+
+    const audit = chant(["audit", project], root);
+    expect(audit).toContain("could not read the lexicons in");
+    expect(existsSync(marker)).toBe(false);
+  }, 180_000);
+
+  test("control: build does run chant.config.ts", () => {
+    chant(["build", "."], project);
+    expect(existsSync(marker)).toBe(true);
+  }, 90_000);
+});
+
+describe("audit names a path lexicon by its path and leaves it out of the install line (chant#2589)", () => {
+  test("text output", async () => {
+    const result = await auditCommand({ path: project, plugins: [] });
+    expect(result.status).toBe("no-lexicons");
+    expect(result.output).toContain("github is declared by path: ");
+    expect(result.output).toContain("gh/index.ts");
+    const install = result.output.split("\n").find((line) => line.includes("npx "));
+    expect(install).toBeDefined();
+    expect(install).not.toContain("@intentius/chant-lexicon-github");
+    expect(existsSync(marker)).toBe(false);
+  });
+
+  test("json output", async () => {
+    const result = await auditCommand({ path: project, plugins: [], format: "json" });
+    const report = JSON.parse(result.output) as { install: string };
+    expect(report.install).toMatch(/^npx -p @intentius\/chant( |$)/);
+    expect(report.install).not.toContain("@intentius/chant-lexicon-github");
+    expect(existsSync(marker)).toBe(false);
+  });
+
+  test("a partial run names the path in its coverage note", async () => {
+    // Some other audit lexicon loaded, github not: the workflow is skipped and the note names the path.
+    const { loadPlugin } = await import("./plugins");
+    const docker = await loadPlugin("docker");
+    const result = await auditCommand({ path: project, plugins: [docker] });
+    expect(result.output).toContain("github is declared by path: ");
+    expect(result.output).not.toContain("npm i @intentius/chant-lexicon-github");
+    expect(existsSync(marker)).toBe(false);
+    expect(existsSync(moduleMarker)).toBe(false);
+  });
+});
+
+/**
+ * chant#2618 — the other ways into `audit`: main's dispatch run in-process
+ * (what `workspace member-run` calls once per member), and `workspace audit`
+ * through the CLI, which reaches it through that member-run process.
+ */
+describe("chant audit never evaluates the audited repository's config (chant#2618)", () => {
+  test("main's in-process dispatch runs neither the config nor the path lexicon's module", async () => {
+    const run = await captureRun(() => runCommandInProcess(["audit", project]));
+    expect(run.exitCode).toBe(0);
+    expect(existsSync(marker)).toBe(false);
+    expect(existsSync(moduleMarker)).toBe(false);
+  }, 90_000);
+
+  test("workspace audit runs no member's config and no path lexicon's module", () => {
+    // The project becomes the root member of a workspace, with a second
+    // member whose config and path lexicon leave markers of their own.
+    const apiMarker = join(root, "api-config-ran");
+    const apiModuleMarker = join(root, "api-module-ran");
+    const api = join(project, "api");
+    mkdirSync(join(api, ".github", "workflows"), { recursive: true });
+    mkdirSync(join(api, "gh"), { recursive: true });
+    writeFileSync(
+      join(api, "chant.config.ts"),
+      `import { writeFileSync } from "node:fs";\nwriteFileSync(${JSON.stringify(apiMarker)}, "ran");\n` +
+        `export default { lexicons: [{ name: "github", module: "./gh/index.ts" }] };\n`,
+    );
+    writeFileSync(
+      join(api, "gh", "index.ts"),
+      `import { writeFileSync } from "node:fs";\nwriteFileSync(${JSON.stringify(apiModuleMarker)}, "ran");\nexport {};\n`,
+    );
+    writeFileSync(
+      join(api, ".github", "workflows", "ci.yml"),
+      "on: push\njobs:\n  a:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n",
+    );
+    writeFileSync(
+      join(project, "chant.workspace.json"),
+      JSON.stringify({
+        name: "acme",
+        schema: 1,
+        members: [
+          { name: "root", dir: ".", kind: "chant" },
+          { name: "api", dir: "api", kind: "chant" },
+        ],
+      }),
+    );
+    const output = chant(["workspace", "audit", "--json"], project);
+    expect(output).toContain('"api"');
+    expect(existsSync(marker)).toBe(false);
+    expect(existsSync(moduleMarker)).toBe(false);
+    expect(existsSync(apiMarker)).toBe(false);
+    expect(existsSync(apiModuleMarker)).toBe(false);
+  }, 180_000);
+});

package/src/codegen/fetch.test.ts

@@ -1,5 +1,8 @@
 import { describe, test, expect, vi, afterEach } from "vitest";
-import { extractFromTar, fetchWithRetry, TransientFetchError } from "./fetch";
+import { extractFromTar, fetchWithCache, fetchWithRetry, TransientFetchError } from "./fetch";
+import { mkdtempSync, utimesSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
 
 /**
  * Build a minimal valid tar buffer with a single file entry.
@@ -318,3 +321,62 @@ describe("fetchWithRetry", () => {
     expect((err as TransientFetchError).message).toContain("1 attempt");
   });
 });
+
+describe("fetchWithCache", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  function cacheAt(ageMs: number, content = "stale bytes"): string {
+    const file = join(mkdtempSync(join(tmpdir(), "chant-fetch-cache-")), "spec.bin");
+    writeFileSync(file, content);
+    const then = (Date.now() - ageMs) / 1000;
+    utimesSync(file, then, then);
+    return file;
+  }
+
+  test("returns the stale cached copy when every download attempt fails transiently", async () => {
+    const cacheFile = cacheAt(2 * 24 * 60 * 60 * 1000);
+    const fetchMock = vi.fn().mockRejectedValue(new Error("ECONNRESET"));
+    vi.stubGlobal("fetch", fetchMock);
+    const errors: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((m: unknown) => { errors.push(String(m)); });
+
+    const data = await fetchWithCache({ url: "https://example.test/spec", cacheFile, retries: 1, backoffMs: 1 });
+
+    expect(data.toString()).toBe("stale bytes");
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(errors.join("\n")).toContain("Using the cached copy");
+  });
+
+  test("force ignores the stale copy and throws", async () => {
+    const cacheFile = cacheAt(2 * 24 * 60 * 60 * 1000);
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("ECONNRESET")));
+
+    await expect(
+      fetchWithCache({ url: "https://example.test/spec", cacheFile, retries: 1, backoffMs: 1 }, true),
+    ).rejects.toBeInstanceOf(TransientFetchError);
+  });
+
+  test("a permanent failure with a stale copy still throws", async () => {
+    const cacheFile = cacheAt(2 * 24 * 60 * 60 * 1000);
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("gone", { status: 404 })));
+
+    await expect(
+      fetchWithCache({ url: "https://example.test/spec", cacheFile, retries: 1, backoffMs: 1 }),
+    ).rejects.toThrow();
+  });
+
+  test("passes attemptTimeoutMs through as the attempt signal", async () => {
+    const cacheFile = cacheAt(2 * 24 * 60 * 60 * 1000);
+    const fetchMock = vi.fn().mockResolvedValue(new Response("fresh"));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const data = await fetchWithCache({ url: "https://example.test/spec", cacheFile, attemptTimeoutMs: 120_000 });
+
+    expect(data.toString()).toBe("fresh");
+    const init = fetchMock.mock.calls[0][1] as RequestInit;
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+  });
+});

package/src/codegen/fetch.ts

@@ -18,6 +18,16 @@ export interface FetchConfig {
   cacheFile: string;
   /** Cache TTL in milliseconds (default: 24 hours). */
   cacheTtlMs?: number;
+  /**
+   * Per-attempt timeout for the download in milliseconds (default: 15 seconds).
+   * A source archive of tens of megabytes needs more than the default, which
+   * is sized for a JSON schema.
+   */
+  attemptTimeoutMs?: number;
+  /** Retries after the first attempt (default: 4). */
+  retries?: number;
+  /** Base back-off between attempts in milliseconds (default: 1 second). */
+  backoffMs?: number;
 }
 
 // ── Transient-aware fetch ──────────────────────────────────────────
@@ -198,7 +208,26 @@ export async function fetchWithCache(config: FetchConfig, force = false): Promis
     }
   }
 
-  const response = await fetchWithRetry(config.url);
+  let response: Response;
+  try {
+    response = await fetchWithRetry(
+      config.url,
+      config.retries ?? DEFAULT_RETRIES,
+      config.backoffMs ?? DEFAULT_BACKOFF_MS,
+      undefined,
+      config.attemptTimeoutMs ?? DEFAULT_ATTEMPT_TIMEOUT_MS,
+    );
+  } catch (e) {
+    // A stale copy beats a failed build. The archives this caches are pinned
+    // by tag or by version in the URL, so a copy past its TTL is the same
+    // bytes; the TTL exists to notice an unpinned URL moving, not to expire
+    // good data. `force` means the caller needs fresh bytes, so it still throws.
+    if (!force && e instanceof TransientFetchError && existsSync(config.cacheFile)) {
+      console.error(`${e.message} Using the cached copy at ${config.cacheFile} from ${new Date(statSync(config.cacheFile).mtimeMs).toISOString()}.`);
+      return readFileSync(config.cacheFile) as unknown as Buffer;
+    }
+    throw e;
+  }
   const arrayBuffer = await response.arrayBuffer();
   const data = Buffer.from(arrayBuffer);