@intentius/chant 0.19.1 → 0.21.0

package/src/cli/component-security-boundary.test.ts

@@ -0,0 +1,170 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+/**
+ * chant #1051 — regression test for `discoverComponents`'s exposure:
+ * `packages/core/src/components/discover.ts` used to `await import()` every
+ * `*.component.ts` file unconditionally, in the CLI's own process, with no
+ * `--fold`/`--sandbox` equivalent at all — the same class of bug #1045 fixed
+ * for lexicon-resource discovery, but for the parallel `*.component.ts`
+ * convention (`chant list --components`, `chant describe --components`,
+ * `chant graph --components`, `chant build --components --generate`, `chant
+ * run --components`, `chant lint`'s COMP* checks, `chant lifecycle
+ * diff/plan --live`).
+ *
+ * Deliberately an end-to-end test of the real CLI entry point (`main.ts`,
+ * spawned as a genuine child process — the same way `bin/chant` invokes it),
+ * NOT a call to `discoverComponents()`/`listComponents()` directly: calling
+ * either of those skips the exact thing this test exists to prove — that the
+ * `--sandbox` flag is actually wired from `chant`'s argv, through `main.ts`,
+ * into the CLI handler, into `discoverComponents`'s `sandbox` option. This
+ * mirrors `./security-boundary.test.ts`'s rationale (the #1045 Phase 2 bypass
+ * was caught precisely because a differential calling `build()` directly
+ * couldn't see a hole in the CLI layer above it).
+ *
+ * Evidence is routed through `chant list --components`'s own JSON stdout (a
+ * component NAME), never stderr and never a bare "did it print EXFIL" check —
+ * a suppressed/swallowed console message from the sandboxed child can't fake
+ * this: the hostile fixture always exports a syntactically valid `Component`
+ * (wrapping every privileged attempt in try/catch, so discovery never simply
+ * errors out) whose `name` field encodes exactly what it managed to do:
+ * "OK" for each of read/write/spawn that succeeded, or the Permission
+ * Model's real `err.code` when denied, plus the ambient env var count —
+ * mirroring how the #1045 PR itself was verified ("unsandboxed produced
+ * read-u-env77, sandboxed produced blocked-erraccessdenied-env2").
+ */
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const mainTsPath = resolve(thisDir, "main.ts");
+const repoRoot = resolve(thisDir, "../../../..");
+
+describe("CLI end-to-end — discoverComponents must not execute *.component.ts unsandboxed when --sandbox is passed", () => {
+  let testDir: string;
+  let escapedMarkerPath: string;
+
+  beforeEach(async () => {
+    testDir = await realpath(
+      await (async () => {
+        const dir = join(tmpdir(), `chant-component-security-boundary-test-${Date.now()}-${Math.random()}`);
+        await mkdir(dir, { recursive: true });
+        return dir;
+      })(),
+    );
+    // Outside the project directory chant scans — the sandbox's
+    // `--allow-fs-write` allowance (there isn't one) and `--allow-fs-read`
+    // scope (project dir + bundle dir only) must both reject this.
+    escapedMarkerPath = join(testDir, "..", `chant-component-escaped-${Date.now()}.txt`);
+
+    await writeFile(join(testDir, "chant.config.ts"), "export default {};\n");
+
+    // A hostile component file: attempts a filesystem read outside the
+    // project, a filesystem write outside the project, and a child-process
+    // spawn, all at module top level (before its one real Component export),
+    // wrapping each attempt so a permission denial never throws discovery
+    // into "import error" — every signal is folded into the component's own
+    // `name`, which is what `chant list --components --format json` prints
+    // to STDOUT, so suppressed child stderr/console output cannot fake a
+    // pass here.
+    await writeFile(
+      join(testDir, "evil.component.ts"),
+      [
+        'import { readFileSync, writeFileSync } from "node:fs";',
+        'import { execSync } from "node:child_process";',
+        "",
+        "function attempt(label, fn) {",
+        "  try {",
+        "    fn();",
+        '    return label + "OK";',
+        "  } catch (err) {",
+        '    const code = err && err.code ? String(err.code).replace(/[^A-Za-z0-9]/g, "") : "ERR";',
+        "    return label + code;",
+        "  }",
+        "}",
+        "",
+        `const readTag = attempt("read", () => { readFileSync("/etc/hosts", "utf-8"); });`,
+        `const writeTag = attempt("write", () => { writeFileSync(${JSON.stringify(escapedMarkerPath)}, "pwned"); });`,
+        `const spawnTag = attempt("spawn", () => { execSync("true"); });`,
+        "const envCount = Object.keys(process.env).length;",
+        "",
+        "export const probe = {",
+        "  name: `probe-${readTag}-${writeTag}-${spawnTag}-env${envCount}`,",
+        "  dependsOn: [],",
+        '  deploy: [{ phase: "Apply", steps: [{ kind: "shell", command: "echo ok" }] }],',
+        "};",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+    await rm(escapedMarkerPath, { force: true });
+  });
+
+  /** Spawn the real CLI (`main.ts`, exactly as `bin/chant` invokes it via `npx tsx`) and capture its output. */
+  function runCli(args: string[]): { status: number | null; stdout: string; stderr: string } {
+    const result = spawnSync("npx", ["tsx", mainTsPath, ...args], {
+      cwd: repoRoot,
+      encoding: "utf-8",
+      timeout: 30_000,
+      env: { ...process.env, CHANT_SECRET_FOR_TEST: "should-never-leak" },
+    });
+    return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+  }
+
+  /** Pull the discovered component's `name` field out of `chant list --components --format json`'s stdout. */
+  function probeNameFrom(stdout: string): string {
+    const parsed = JSON.parse(stdout) as Array<{ name: string }>;
+    const found = parsed.find((c) => c.name.startsWith("probe-"));
+    expect(found, `expected a "probe-*" component in stdout: ${stdout}`).toBeDefined();
+    return found!.name;
+  }
+
+  test("without --sandbox, the hostile *.component.ts file executes fully (establishes the fixture is genuinely hostile)", () => {
+    const { status, stdout } = runCli(["list", testDir, "--components", "--format", "json"]);
+    expect(status).toBe(0);
+
+    const name = probeNameFrom(stdout);
+    expect(name).toMatch(/^probe-readOK-writeOK-spawnOK-env\d+$/);
+
+    // A real env var count, not the sandbox's scrubbed-to-just-PATH count.
+    const envCount = Number(name.match(/env(\d+)$/)![1]);
+    expect(envCount).toBeGreaterThan(2);
+
+    expect(existsSync(escapedMarkerPath), "hostile file's write should have landed unsandboxed").toBe(true);
+  });
+
+  test("with --sandbox, the hostile *.component.ts file is denied filesystem read/write, process spawn, and sees a scrubbed environment", () => {
+    const { status, stdout } = runCli(["list", testDir, "--components", "--format", "json", "--sandbox"]);
+    expect(status).toBe(0);
+
+    const name = probeNameFrom(stdout);
+    expect(name).toMatch(/^probe-readERRACCESSDENIED-writeERRACCESSDENIED-spawnERRACCESSDENIED-env\d+$/);
+
+    // Only PATH (deliberately kept, see `./sandbox/run.ts`) plus whatever the
+    // OS itself injects into every child regardless of the `env` passed to
+    // `fork()` (macOS adds `__CF_USER_TEXT_ENCODING`) survive the spawn-time
+    // env scrub — a small constant, nowhere near the ambient environment's
+    // real size. Mirrors the #1045 PR's own reported number for this exact
+    // shape of check ("blocked-erraccessdenied-env2").
+    const envCount = Number(name.match(/env(\d+)$/)![1]);
+    expect(envCount).toBeLessThanOrEqual(2);
+
+    expect(existsSync(escapedMarkerPath), "sandboxed write must not have landed").toBe(false);
+  });
+
+  test("`chant lint --sandbox` (COMP* checks) also does not let the hostile file's write land", () => {
+    const { status } = runCli(["lint", testDir, "--sandbox", "--format", "json"]);
+    // Not asserting on exit code (COMP* rules may or may not flag this
+    // fixture) — the write escaping the sandbox is the actual property
+    // under test, matching how `./security-boundary.test.ts` treats `chant
+    // lint`'s coverage of the same discovery path.
+    expect(status === 0 || status === 1).toBe(true);
+    expect(existsSync(escapedMarkerPath)).toBe(false);
+  });
+});

package/src/cli/handlers/build.ts

@@ -21,9 +21,12 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
   // plugins (those implementing `generateComponentPipeline`, #688), not a
   // hard-coded core list — `generateComponentsPipeline` returns a descriptive
   // error when the target lexicon has no generator.
-  const result = await generateComponentsPipeline(args.path, lexicon, {
-    env: args.env,
-  });
+  const result = await generateComponentsPipeline(
+    args.path,
+    lexicon,
+    { env: args.env },
+    args.sandbox,
+  );
 
   if (!result.success) {
     console.error(formatError({ message: result.error ?? "Failed to generate CI pipeline from components" }));
@@ -83,6 +86,16 @@ export async function runBuild(ctx: CommandContext): Promise<number> {
     console.error(formatInfo(formatWarningMsg));
   }
 
+  // #1064 — `--param name=value`, repeated, into a flat { name: value } record.
+  const params = args.param?.length
+    ? Object.fromEntries(
+        args.param.map((entry) => {
+          const eq = entry.indexOf("=");
+          return eq === -1 ? [entry, ""] : [entry.slice(0, eq), entry.slice(eq + 1)];
+        }),
+      )
+    : undefined;
+
   if (args.watch) {
     const cleanup = buildCommandWatch({
       path: args.path,
@@ -90,6 +103,10 @@ export async function runBuild(ctx: CommandContext): Promise<number> {
       format: buildFormat,
       serializers,
       plugins,
+      fold: args.fold,
+      sandbox: args.sandbox,
+      params,
+      paramsFile: args.paramsFile,
     });
     process.on("SIGINT", () => {
       cleanup();
@@ -107,6 +124,10 @@ export async function runBuild(ctx: CommandContext): Promise<number> {
     plugins,
     verbose: args.verbose,
     env: args.env,
+    fold: args.fold,
+    sandbox: args.sandbox,
+    params,
+    paramsFile: args.paramsFile,
   });
 
   // When --lexicon filters to a subset, suppress "No serializer" warnings for excluded lexicons

package/src/cli/handlers/components.ts

@@ -79,7 +79,7 @@ export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<n
   if (!component || !digest) {
     console.error(formatError({
       message: "--component and --digest are required",
-      hint: "chant components release <env> --component <name> --digest <sha256:...> [--git-sha <sha>] [--run-id <id>] [--actor <name>]",
+      hint: "chant components release <env> --component <name> --digest <sha256:...> [--git-sha <sha>] [--run-id <id>] [--actor <name>] [--approver <name>]",
     }));
     return 1;
   }
@@ -87,6 +87,10 @@ export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<n
   const gitSha = args.gitSha ?? (await getHeadCommit().catch(() => undefined));
   const runId = args.runId ?? process.env.GITHUB_RUN_ID ?? process.env.CI_PIPELINE_ID ?? `local-${Date.now()}`;
   const actor = args.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER;
+  // Who approved a gated change (#1035). Optional — omitted for an ungated
+  // change, and never defaulted to `actor`, since recording the approver as the
+  // triggerer would defeat the separation-of-duties the field exists to attest.
+  const approver = args.approver;
 
   if (!gitSha) {
     console.error(formatError({ message: "Could not resolve --git-sha (not in a git repo?) — pass it explicitly." }));
@@ -111,6 +115,7 @@ export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<n
       runId,
       timestamp,
       actor,
+      ...(approver ? { approver } : {}),
     });
     await pushLifecycle();
     if (args.json) {
@@ -277,7 +282,9 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
   // Discover components (best-effort) so a live/owned-but-never-recorded
   // component still gets a row, not just those that appear in the ledger.
   const { config } = await loadChantConfig(resolve("."));
-  const discovery = await discoverComponents(resolve(args.src ?? config.sourceDir ?? "."));
+  const discovery = await discoverComponents(resolve(args.src ?? config.sourceDir ?? "."), {
+    sandbox: args.sandbox,
+  });
   const allComponents = [...discovery.components.keys()];
 
   // Component -> live entity/resource name(s) it owns (#598), when declared

package/src/cli/handlers/dev.ts

@@ -41,7 +41,7 @@ export async function runDevOnboard(ctx: CommandContext): Promise<number> {
 export async function runDevCheckLexicon(ctx: CommandContext): Promise<number> {
   const dir = ctx.args.extraPositional ?? ".";
   const { checkLexicon, printCheckResult } = await import("../commands/check-lexicon");
-  const result = checkLexicon(resolve(dir));
+  const result = await checkLexicon(resolve(dir));
   printCheckResult(result, ctx.args.format === "json");
   return result.tier1Pass ? 0 : 1;
 }

package/src/cli/handlers/graph.ts

@@ -109,7 +109,9 @@ async function runGraphLive(
   // and unions the results. A project with no components (or whose discovery
   // errors) yields no stacks, so `observeResources` falls back to its
   // original single-stack call — unchanged.
-  const componentsDiscovery = await discoverComponents(resolve(args.src ?? config.sourceDir ?? "."));
+  const componentsDiscovery = await discoverComponents(resolve(args.src ?? config.sourceDir ?? "."), {
+    sandbox: args.sandbox,
+  });
   const stacks = new Set<string>();
   if (componentsDiscovery.errors.length === 0) {
     for (const { component } of componentsDiscovery.components.values()) {
@@ -207,7 +209,7 @@ async function runGraphLive(
  */
 async function runComponentGraph(ctx: CommandContext): Promise<number> {
   const projectPath = resolve(ctx.args.path === "." ? "." : ctx.args.path);
-  const graph = await computeComponentGraph(projectPath);
+  const graph = await computeComponentGraph(projectPath, ctx.args.sandbox);
 
   if (!graph.success) {
     console.error(formatError({ message: graph.error ?? "Failed to compute component graph" }));
@@ -254,7 +256,7 @@ async function runComponentGraphView(
 ): Promise<number> {
   const projectPath = resolve(ctx.args.path === "." ? "." : ctx.args.path);
 
-  const lint = await lintCommand({ path: ctx.args.path, format: "stylish" });
+  const lint = await lintCommand({ path: ctx.args.path, format: "stylish", sandbox: ctx.args.sandbox });
   if (!lint.success) {
     console.error(
       formatError({
@@ -264,7 +266,7 @@ async function runComponentGraphView(
     return 1;
   }
 
-  const graph = await computeComponentGraph(projectPath);
+  const graph = await computeComponentGraph(projectPath, ctx.args.sandbox);
   if (!graph.success) {
     console.error(formatError({ message: graph.error ?? "Failed to compute component graph" }));
     return 1;
@@ -316,7 +318,7 @@ async function runGraphView(
   }
 
   // Gate: only emit for lint-clean source.
-  const lint = await lintCommand({ path: ctx.args.path, format: "stylish" });
+  const lint = await lintCommand({ path: ctx.args.path, format: "stylish", sandbox: ctx.args.sandbox });
   if (!lint.success) {
     console.error(
       formatError({

package/src/cli/handlers/lifecycle.ts

@@ -286,7 +286,7 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
       let componentStacks: string[] = [];
       if (!target.stack) {
         try {
-          const disc = await discoverComponents(target.root);
+          const disc = await discoverComponents(target.root, { sandbox: args.sandbox });
           const set = new Set<string>();
           for (const { component } of disc.components.values()) for (const s of cfnDeployStacks(component.deploy)) set.add(s);
           componentStacks = [...set];
@@ -698,7 +698,7 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
   // single-stack project → the original single-call path is kept.
   let componentStacks: string[] = [];
   try {
-    const disc = await discoverComponents(resolveBuildRoot(args, config));
+    const disc = await discoverComponents(resolveBuildRoot(args, config), { sandbox: args.sandbox });
     const set = new Set<string>();
     for (const { component } of disc.components.values()) for (const s of cfnDeployStacks(component.deploy)) set.add(s);
     componentStacks = [...set];

package/src/cli/handlers/lint.ts

@@ -16,6 +16,7 @@ export async function runLint(ctx: CommandContext): Promise<number> {
       path: args.path,
       fix: args.fix,
       format: lintFormat,
+      sandbox: args.sandbox,
     });
     process.on("SIGINT", () => {
       cleanup();
@@ -29,6 +30,7 @@ export async function runLint(ctx: CommandContext): Promise<number> {
     path: args.path,
     fix: args.fix,
     format: lintFormat,
+    sandbox: args.sandbox,
   });
 
   printLintResult(result);

package/src/cli/handlers/misc.ts

@@ -92,7 +92,7 @@ export async function runList(ctx: CommandContext): Promise<number> {
   // `lexicon`/`entityType`), so it is a separate branch rather than folded
   // into `listCommand`'s Declarable-shaped `ListEntity` rows.
   if (args.components) {
-    const result = await listComponents(args.path);
+    const result = await listComponents(args.path, args.sandbox);
     if (!result.success) {
       for (const e of result.errors) console.error(formatError({ message: e }));
       return 1;
@@ -143,7 +143,7 @@ export async function runDescribe(ctx: CommandContext): Promise<number> {
   // `Component` (its full JSON contract projection) rather than a lexicon
   // resource's resolved props bag.
   if (args.components) {
-    const result = await describeComponent(args.extraPositional ?? ".", component);
+    const result = await describeComponent(args.extraPositional ?? ".", component, args.sandbox);
     if (!result.success || !result.described) {
       console.log(result.output);
       return 1;

package/src/cli/handlers/run-client.ts

@@ -29,7 +29,7 @@ export interface WorkflowHandleRaw {
   result(): Promise<unknown>;
   describe(): Promise<WorkflowExecutionDescription>;
   fetchHistory(): Promise<WorkflowHistoryRaw>;
-  signal(signalName: string): Promise<void>;
+  signal(signalName: string, ...args: unknown[]): Promise<void>;
   cancel(): Promise<void>;
 }
 

package/src/cli/handlers/run.ts

@@ -176,7 +176,7 @@ async function runComponentsList(ctx: CommandContext): Promise<number> {
   if (!requireTemporalMode(ctx, "chant run list --components")) return 1;
 
   const projectPath = resolve(".");
-  const result = await listComponents(projectPath);
+  const result = await listComponents(projectPath, ctx.args.sandbox);
 
   if (!result.success) {
     for (const err of result.errors) console.error(formatError({ message: err }));
@@ -442,17 +442,27 @@ export async function runOpSignal(ctx: CommandContext): Promise<number> {
 
   const projectPath = resolve(".");
   const workflowId = ctx.args.components ? componentWorkflowId(name) : resolveWorkflowId(name);
+  // Approver identity for an approval gate (#1035): supplied via --approver, or
+  // resolved from the CI/user environment the same way `chant components
+  // release` resolves --actor. Rides the gate signal payload so Temporal
+  // persists "who approved" in the workflow history. Optional — a signal that
+  // is not an approval gate (or an approver who declines to identify) sends no
+  // payload and the gate still clears.
+  const approver = ctx.args.approver ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER;
   let handle: WorkflowHandleRaw;
   try {
     const { client } = await makeTemporalClient(ctx.args.profile, projectPath);
     handle = client.workflow.getHandle(workflowId);
-    await handle.signal(signalName);
+    await handle.signal(signalName, ...(approver ? [{ approver }] : []));
   } catch (err) {
     console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
     return 1;
   }
 
-  console.error(formatSuccess(`Signal "${signalName}" sent to ${ctx.args.components ? "component" : "Op"} "${name}"`));
+  console.error(formatSuccess(
+    `Signal "${signalName}" sent to ${ctx.args.components ? "component" : "Op"} "${name}"` +
+      (approver ? ` (approver: ${approver})` : ""),
+  ));
   return 0;
 }
 
@@ -694,7 +704,12 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
   // `undefined` and every `onProgress?.(...)` call in the driver is a no-op —
   // behavior is byte-for-byte unchanged from before this flag existed.
   const onProgress = ctx.args.progressJson ? ndjsonProgressSink() : undefined;
-  const result = await runComponents(resolve("."), selector, { env: ctx.args.env, componentOutputs: seededOutputs, onProgress });
+  const result = await runComponents(resolve("."), selector, {
+    env: ctx.args.env,
+    componentOutputs: seededOutputs,
+    onProgress,
+    sandbox: ctx.args.sandbox,
+  });
 
   // Dump the accumulated outputs for a downstream job to seed from. Written
   // even on failure (partial outputs) so a resumed run still has what completed.
@@ -767,7 +782,7 @@ async function runComponentTemporal(ctx: CommandContext, selector: string): Prom
   }
 
   const projectPath = resolve(".");
-  const resolved = await resolveComponentTargets(projectPath, selector);
+  const resolved = await resolveComponentTargets(projectPath, selector, ctx.args.sandbox);
   if (!resolved.success || resolved.targets.length === 0) {
     console.error(formatError({ message: resolved.error ?? `Component "${selector}" not found` }));
     return 1;

package/src/cli/main.test.ts

@@ -248,6 +248,28 @@ describe("parseArgs", () => {
     const result = parseArgs(["run", "--components", "search-service"]);
     expect(result.progressJson).toBeUndefined();
   });
+
+  // ── --param / --params-file (chant #1064) ────────────────────────────────
+
+  test("parses a single --param as a one-element array", () => {
+    const result = parseArgs(["build", "src", "--param", "tier=production"]);
+    expect(result.param).toEqual(["tier=production"]);
+  });
+
+  test("repeated --param accumulates in order", () => {
+    const result = parseArgs(["build", "src", "--param", "tier=production", "--param", "env=staging"]);
+    expect(result.param).toEqual(["tier=production", "env=staging"]);
+  });
+
+  test("--param is undefined when omitted", () => {
+    const result = parseArgs(["build", "src"]);
+    expect(result.param).toBeUndefined();
+  });
+
+  test("parses --params-file with a path", () => {
+    const result = parseArgs(["build", "src", "--params-file", "./params.json"]);
+    expect(result.paramsFile).toBe("./params.json");
+  });
 });
 
 // ── resolveCommand tests ──────────────────────────────────────────

package/src/cli/main.ts

@@ -45,6 +45,8 @@ export function parseArgs(args: string[]): ParsedArgs {
     verbose: false,
     help: false,
     profile: undefined,
+    param: undefined,
+    paramsFile: undefined,
     report: undefined,
     local: undefined,
     temporal: undefined,
@@ -210,10 +212,20 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.runId = args[++i];
     } else if (arg === "--actor") {
       result.actor = args[++i];
+    } else if (arg === "--approver") {
+      result.approver = args[++i];
     } else if (arg === "--compare-to") {
       result.compareTo = args[++i];
     } else if (arg === "--no-release-record") {
       result.noReleaseRecord = true;
+    } else if (arg === "--fold") {
+      result.fold = true;
+    } else if (arg === "--sandbox") {
+      result.sandbox = true;
+    } else if (arg === "--param") {
+      (result.param ??= []).push(args[++i]);
+    } else if (arg === "--params-file") {
+      result.paramsFile = args[++i];
     } else if (!arg.startsWith("-")) {
       if (!result.command) {
         result.command = arg;
@@ -403,12 +415,39 @@ Options:
                         successful \`run --components\` deploy (default: on;
                         also settable via chant.config.ts's
                         release.autoRecord: false; #597)
+  --fold                (build) Fold source modules statically instead of
+                        running them; folds resource constructors and
+                        composite factory calls (#1022/#1023), falling back
+                        to run per-file for anything else outside the fold
+                        subset (a cross-file-only reference, a re-export,
+                        \`export default\`, ...). Logs which path each file
+                        took. Default: off (also settable via
+                        chant.config.ts's build.fold: true; #1022)
+  --sandbox             (build) Run run-fallback source files (or every
+                        file, without --fold) together, isolated, in one
+                        sandboxed child process instead of in-process
+                        (#1045). No filesystem write, no child process, no
+                        worker threads, no ambient environment visible to
+                        project source; network egress is NOT blocked (see
+                        docs). Default: off (also settable via
+                        chant.config.ts's build.sandbox: true; #1045)
+  --param <name=value>  (build) Bind a declared build-time parameter
+                        (chant.config.ts's buildParams) to a value, for
+                        source to read as params.<name> (#1064) instead of
+                        process.env — repeatable. Distinct from the AWS
+                        lexicon's deploy-time Parameter(): this resolves
+                        before synthesis, so it can change which resources
+                        are produced at all. Highest precedence.
+  --params-file <path>  (build) JSON file of { "name": value } build-time
+                        parameter values (#1064). Second precedence, after
+                        --param.
 
 Examples:
   chant build ./infra/
   chant build ./infra/ --output stack.json
   chant build ./infra/ --format yaml
   chant build ./infra/ --watch
+  chant build ./infra/ --fold
   chant build ./infra/ --components --generate gitlab
   chant build ./infra/ --components --generate gitlab --output .gitlab-ci.yml
   chant run --components search-service --env staging

package/src/cli/plugins.ts

@@ -1,6 +1,6 @@
 import { isLexiconPlugin, type LexiconPlugin } from "../lexicon";
 import { loadChantConfig } from "../config";
-import { discover, detectLexicons } from "../index";
+import { findInfraFiles, detectLexicons } from "../index";
 import { checkConflicts } from "./conflict-check";
 
 /**
@@ -80,6 +80,22 @@ export async function loadPlugins(lexiconNames: string[]): Promise<LexiconPlugin
  *
  * Reads `lexicons` from `chant.config.ts` / `chant.config.json` if present.
  * Falls back to source-file detection via `detectLexicons()`.
+ *
+ * chant #1045 Phase 2 — this used to fall back to a full `discover()` call
+ * just to read its `sourceFiles` list, which imports and RUNS every project
+ * source file to collect entities that are then discarded here. That ran
+ * unconditionally, on every command that reaches this function without an
+ * explicit `chant.config.ts` `lexicons` list (`build`, `lint`, `doctor`,
+ * `import`, `graph`, the MCP server — effectively the whole CLI), with no
+ * `--fold`/`--sandbox` involved at all: a project could omit `lexicons` and
+ * every file would execute here, in the CLI's own process, before the
+ * caller's OWN (possibly folded, possibly sandboxed) build ever ran. Fixed
+ * by using `findInfraFiles()` alone — the pure directory walk `discover()`
+ * itself starts from, no import, no execution — since `detectLexicons()` is
+ * already a plain text/regex scan over file contents (`../detectLexicon.ts`)
+ * that never needed live module exports to begin with. This is strictly
+ * better than routing the detection through the sandbox: it removes the
+ * execution entirely rather than containing it, at no bundling/spawn cost.
  */
 export async function resolveProjectLexicons(projectPath: string): Promise<string[]> {
   const { config } = await loadChantConfig(projectPath);
@@ -88,7 +104,7 @@ export async function resolveProjectLexicons(projectPath: string): Promise<strin
     return config.lexicons;
   }
 
-  // Fallback: detect from source imports
-  const discoveryResult = await discover(projectPath);
-  return detectLexicons(discoveryResult.sourceFiles);
+  // Fallback: detect from source imports — a pure text scan, no execution.
+  const files = await findInfraFiles(projectPath);
+  return detectLexicons(files);
 }

package/src/cli/registry.ts

@@ -136,6 +136,8 @@ export interface ParsedArgs {
   runId?: string;
   /** `chant components release record --actor <name>` (#568) — who/what triggered the deploy. */
   actor?: string;
+  /** `--approver <name>` (#1035) — who approved a gated change. Supplied to `chant run signal` (rides the gate signal payload into workflow history) and to `chant components release` (recorded on the release ledger). Optional; absent for ungated changes. */
+  approver?: string;
   /** `chant components status <env> --compare-to <env>` (#568) — a second environment to cross-check the same component's recorded digest against. */
   compareTo?: string;
   /** `chant run --components <name> --env <env> --no-release-record` (#597) — opt out of auto-emitting a release-ledger record after a successful component deploy. Default (flag omitted): recording is ON. Also settable project-wide via `chant.config.ts`'s `release.autoRecord: false`. */
@@ -144,6 +146,14 @@ export interface ParsedArgs {
   dumpOutputs?: 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. */
+  fold?: boolean;
+  /** `chant build --sandbox` (#1045 Phase 2) — opt-in: run-fallback source files (or every file, without `--fold`) execute together, isolated, in one sandboxed child process instead of in-process. Also settable project-wide via `chant.config.ts`'s `build.sandbox: true`; the flag always wins when set. Default (flag omitted): in-process execution, unchanged. */
+  sandbox?: boolean;
+  /** `chant build --param name=value` (#1064) — repeatable. Bound to `params.<name>` (`@intentius/chant/params`) for source to reference, after validation against `chant.config.ts`'s declared `buildParams`. Highest precedence over `--params-file`/a declared `env` mapping/the declared `default`. */
+  param?: string[];
+  /** `chant build --params-file <path>` (#1064) — a JSON file of `{ "name": value }` build-time parameter values. Second precedence, after `--param`. */
+  paramsFile?: string;
 }
 
 /**