@intentius/chant 0.19.0 → 0.20.0

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;
 }
 
 /**

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

@@ -0,0 +1,135 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdir, writeFile, rm, symlink, 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 #1045 Phase 2 (post-merge finding) — regression test for a real
+ * bypass: `resolveProjectLexicons` (`./plugins.ts`) used to fall back to a
+ * full, unsandboxed `discover()` call whenever a project's `chant.config.ts`
+ * didn't list `lexicons` explicitly — importing and RUNNING every source
+ * file in the CLI's own process, with no `--fold`/`--sandbox` involved at
+ * all, before the caller's own (possibly folded, possibly sandboxed)
+ * discovery ever ran. `resolveProjectLexicons` sits underneath nearly every
+ * CLI command (`build`, `lint`, `doctor`, `import`, `graph`, the MCP server),
+ * so this reached far past `chant build --fold`.
+ *
+ * This is 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 `build()`/`buildCommand()` directly: calling
+ * either of those skips the exact code path the bug lived in
+ * (`main.ts`'s `loadPluginsOrExit` → `resolveProjectLexicons`), which is
+ * precisely how the corpus differential and Phase 2's other tests — all of
+ * which call `build()` — passed while this stayed open.
+ *
+ * Fixture lives in a fresh tmpdir per test, never in the source tree.
+ */
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const mainTsPath = resolve(thisDir, "main.ts");
+const repoRoot = resolve(thisDir, "../../../..");
+
+describe("CLI end-to-end — resolveProjectLexicons must not execute project source", () => {
+  let testDir: string;
+  let exfilMarkerPath: string;
+
+  beforeEach(async () => {
+    testDir = await realpath(
+      await (async () => {
+        const dir = join(tmpdir(), `chant-security-boundary-test-${Date.now()}-${Math.random()}`);
+        await mkdir(join(dir, "src"), { recursive: true });
+        return dir;
+      })(),
+    );
+    exfilMarkerPath = join(testDir, "exfil-happened.txt");
+
+    // A real `node_modules/@intentius/chant-lexicon-k8s` symlink — same shape
+    // this monorepo's own workspace linking produces — so the fixture's bare
+    // `from "@intentius/chant-lexicon-k8s"` import resolves exactly the way a
+    // real installed project's would, and `detectLexicons`'s text scan (which
+    // matches that literal specifier) has something genuine to find.
+    await mkdir(join(testDir, "node_modules", "@intentius"), { recursive: true });
+    await symlink(
+      join(repoRoot, "lexicons", "k8s"),
+      join(testDir, "node_modules", "@intentius", "chant-lexicon-k8s"),
+      "dir",
+    );
+
+    // No `lexicons` field — the exact condition that sends
+    // `resolveProjectLexicons` down the detection fallback.
+    await writeFile(join(testDir, "chant.config.ts"), "export default {};\n");
+
+    // A hostile source file: reads a file outside the project and the
+    // ambient environment at module top level (before its one Declarable
+    // export), and — if it got to run — writes a marker file so the test can
+    // tell "executed" apart from "folded" without depending on stdout
+    // capture alone.
+    await writeFile(
+      join(testDir, "src", "infra.ts"),
+      [
+        'import { readFileSync, writeFileSync } from "node:fs";',
+        'import { Namespace } from "@intentius/chant-lexicon-k8s";',
+        "",
+        "const stolen = readFileSync(\"/etc/hosts\", \"utf-8\");",
+        `writeFileSync(${JSON.stringify(exfilMarkerPath)}, "exfil: " + stolen.slice(0, 20) + " env=" + Object.keys(process.env).length);`,
+        'console.error(">>> EXFIL " + stolen.slice(0, 20) + " env=" + Object.keys(process.env).length);',
+        "",
+        'export const ns = new Namespace({ metadata: { name: "x" } });',
+        "",
+      ].join("\n"),
+    );
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, 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 ?? "" };
+  }
+
+  test("`chant build --fold` on a project with no `lexicons` config does not execute the hostile file", () => {
+    const { status, stdout, stderr } = runCli(["build", testDir, "--fold"]);
+
+    expect(stderr).not.toMatch(/EXFIL/);
+    expect(stdout).not.toMatch(/EXFIL/);
+    expect(existsSync(exfilMarkerPath), "hostile file wrote its marker — it executed").toBe(false);
+
+    // The build still has to actually work — this isn't proving safety by
+    // making the build fail outright.
+    expect(status).toBe(0);
+    expect(stdout).toContain("kind: Namespace");
+
+    // The fold decision for the hostile file should say what's now true:
+    // this file really did fold with zero module execution.
+    expect(stderr).toMatch(/\[fold:fold\] src\/infra\.ts/);
+  });
+
+  test("`chant build --fold --sandbox` also does not execute the hostile file (both layers closed)", () => {
+    const { status, stdout, stderr } = runCli(["build", testDir, "--fold", "--sandbox"]);
+
+    expect(stderr).not.toMatch(/EXFIL/);
+    expect(stdout).not.toMatch(/EXFIL/);
+    expect(existsSync(exfilMarkerPath)).toBe(false);
+    expect(status).toBe(0);
+    expect(stdout).toContain("kind: Namespace");
+  });
+
+  test("`chant lint` (which also resolves lexicons this way) does not execute the hostile file", () => {
+    const { stdout, stderr } = runCli(["lint", testDir]);
+
+    expect(stderr).not.toMatch(/EXFIL/);
+    expect(stdout).not.toMatch(/EXFIL/);
+    expect(existsSync(exfilMarkerPath), "hostile file wrote its marker — it executed").toBe(false);
+  });
+});

package/src/codegen/docs-sections.test.ts

@@ -0,0 +1,61 @@
+import { describe, test, expect } from "vitest";
+import { generateIntrinsics } from "./docs-sections";
+import { intrinsicFolds } from "../lexicon";
+import type { DocsConfig, ManifestJSON } from "./docs-types";
+
+/**
+ * chant #1062 (epic #1019) — the per-lexicon intrinsic foldability matrix.
+ * `generateIntrinsics`'s "Folds?" column must come from {@link intrinsicFolds}
+ * (`../lexicon.ts`), the SAME predicate `fold()` uses to decide whether a
+ * registered tag actually folds — not a second `isTag`-shaped guess that
+ * could silently disagree with it. This test locks in that the column
+ * exists, has the right value per intrinsic, and tracks `intrinsicFolds`
+ * rather than restating its logic.
+ */
+
+const config: DocsConfig = {
+  name: "test",
+  displayName: "Test",
+  description: "A test lexicon",
+  distDir: "/tmp/does-not-matter",
+  outDir: "/tmp/does-not-matter",
+};
+
+function manifestWith(intrinsics: ManifestJSON["intrinsics"]): ManifestJSON {
+  return { name: "test", version: "0.0.0", intrinsics };
+}
+
+describe("generateIntrinsics — Folds? column", () => {
+  test("a registered tagged-template intrinsic folds", () => {
+    const page = generateIntrinsics(config, manifestWith([{ name: "Sub", isTag: true }]));
+    expect(page).toContain("| Function | Description | Output Key | Tag? | Folds? |");
+    expect(page).toContain("| `Sub` | — | `Sub` | Yes | Yes |");
+  });
+
+  test("a plain-call intrinsic does not fold today", () => {
+    const page = generateIntrinsics(config, manifestWith([{ name: "Ref", isTag: false }]));
+    expect(page).toContain("| `Ref` | — | `Ref` | No | No |");
+  });
+
+  test("an intrinsic with isTag omitted does not fold (same as isTag: false)", () => {
+    const page = generateIntrinsics(config, manifestWith([{ name: "reference", outputKey: "!reference" }]));
+    expect(page).toContain("| `reference` | — | `!reference` | No | No |");
+  });
+
+  test("Folds? always matches intrinsicFolds() for every row, never a restated copy", () => {
+    const intrinsics: NonNullable<ManifestJSON["intrinsics"]> = [
+      { name: "Sub", isTag: true },
+      { name: "Ref" },
+      { name: "GetAtt", isTag: false },
+    ];
+    const page = generateIntrinsics(config, manifestWith(intrinsics));
+    for (const fn of intrinsics) {
+      const expected = intrinsicFolds(fn) ? "Yes" : "No";
+      const row = page.split("\n").find((line) => line.startsWith(`| \`${fn.name}\` |`));
+      expect(row, `no row rendered for ${fn.name}`).toBeDefined();
+      const cells = (row as string).split("|").map((c) => c.trim());
+      // | `name` | description | outputKey | Tag? | Folds? |  →  ["", "`name`", desc, key, tag, folds, ""]
+      expect(cells[5]).toBe(expected);
+    }
+  });
+});

package/src/codegen/docs-sections.ts

@@ -5,6 +5,7 @@
  */
 
 import { escapeMdx } from "./docs-file-markers";
+import { intrinsicFolds } from "../lexicon";
 import type { DocsConfig, ManifestJSON, MetaEntry, RuleMeta } from "./docs-types";
 
 export function generateOverview(
@@ -94,14 +95,17 @@ export function generateIntrinsics(
     "",
     `The ${config.displayName} lexicon provides **${intrinsics.length}** intrinsic functions.`,
     "",
-    "| Function | Description | Output Key | Tag? |",
-    "|----------|-------------|------------|------|",
+    `**Tag?** shows how an intrinsic is authored: a genuine tagged template (\`Sub\\\`...\\\`\`) or a plain function call (\`Ref(...)\`). **Folds?** shows whether [\`chant build --fold\`](/chant/concepts/typescript-as-data/#folded-vs-run) can reduce a call to this intrinsic today, without running the file — generated directly from this lexicon's registration, not restated by hand. Right now folding only reaches tagged templates, so most rows read \`No\`; that reflects the current state of the folder, not something specific to these intrinsics, and it changes as folding gains coverage.`,
+    "",
+    "| Function | Description | Output Key | Tag? | Folds? |",
+    "|----------|-------------|------------|------|--------|",
   ];
 
   for (const fn of intrinsics) {
     const tag = fn.isTag ? "Yes" : "No";
+    const folds = intrinsicFolds(fn) ? "Yes" : "No";
     lines.push(
-      `| \`${fn.name}\` | ${escapeMdx(fn.description ?? "—")} | \`${fn.outputKey ?? fn.name}\` | ${tag} |`,
+      `| \`${fn.name}\` | ${escapeMdx(fn.description ?? "—")} | \`${fn.outputKey ?? fn.name}\` | ${tag} | ${folds} |`,
     );
   }
 

package/src/components/cli-support.ts

@@ -61,8 +61,8 @@ export interface ListComponentsResult {
 }
 
 /** Discover components under `path` and shape them for `chant list --components`. */
-export async function listComponents(path: string): Promise<ListComponentsResult> {
-  const result = await discoverComponents(path);
+export async function listComponents(path: string, sandbox?: boolean): Promise<ListComponentsResult> {
+  const result = await discoverComponents(path, { sandbox });
   if (result.errors.length > 0) {
     return { success: false, components: [], errors: result.errors.map((e) => e.message) };
   }
@@ -100,8 +100,8 @@ export interface DescribeComponentResult {
 }
 
 /** Find and project one named component, for `chant describe <name> --components`. */
-export async function describeComponent(path: string, name: string): Promise<DescribeComponentResult> {
-  const result = await discoverComponents(path);
+export async function describeComponent(path: string, name: string, sandbox?: boolean): Promise<DescribeComponentResult> {
+  const result = await discoverComponents(path, { sandbox });
   if (result.errors.length > 0) {
     return { success: false, component: name, output: result.errors.map((e) => e.message).join("\n") };
   }
@@ -139,8 +139,8 @@ export interface ComponentGraphResult {
 }
 
 /** Compute the components' dependency graph under `path`, for `chant graph --components`. */
-export async function computeComponentGraph(path: string): Promise<ComponentGraphResult> {
-  const result = await discoverComponents(path);
+export async function computeComponentGraph(path: string, sandbox?: boolean): Promise<ComponentGraphResult> {
+  const result = await discoverComponents(path, { sandbox });
   if (result.errors.length > 0) {
     return { success: false, order: [], waves: [], edges: [], error: result.errors.map((e) => e.message).join("\n") };
   }
@@ -220,6 +220,7 @@ export async function generateComponentsPipeline(
   path: string,
   lexicon: GenerateLexicon,
   options?: ComponentPipelineOptions,
+  sandbox?: boolean,
 ): Promise<GenerateComponentsResult> {
   const plugin = await loadLexiconPlugin(lexicon);
   if (!plugin?.generateComponentPipeline) {
@@ -229,7 +230,7 @@ export async function generateComponentsPipeline(
     };
   }
 
-  const result = await discoverComponents(path);
+  const result = await discoverComponents(path, { sandbox });
   if (result.errors.length > 0) {
     return { success: false, error: result.errors.map((e) => e.message).join("\n") };
   }
@@ -295,6 +296,13 @@ export function findComponentGate(component: DriverComponent): { signalName: str
 export interface RunComponentsOptions {
   /** Target environment name, threaded into every capability's `DeployContext.env` (default: "local"). */
   env?: string;
+  /**
+   * chant #1051 — opt-in: discover `*.component.ts` files in a sandboxed
+   * child process (`chant run --components <name|all> --sandbox`) instead of
+   * in the CLI's own process. See `discoverComponents`'s `sandbox` option
+   * (../discover.ts).
+   */
+  sandbox?: boolean;
   /** Additional capability plugin package names to load on top of the built-in starter set (see `buildCapabilityRegistry`). */
   capabilityPlugins?: string[];
   /**
@@ -392,8 +400,12 @@ export interface ResolvedComponentTargets {
  * without also inheriting the local executor's pre-flight gate rejection
  * (gates are exactly what the durable path exists to support).
  */
-export async function resolveComponentTargets(path: string, selector: string): Promise<ResolvedComponentTargets> {
-  const result = await discoverComponents(path);
+export async function resolveComponentTargets(
+  path: string,
+  selector: string,
+  sandbox?: boolean,
+): Promise<ResolvedComponentTargets> {
+  const result = await discoverComponents(path, { sandbox });
   if (result.errors.length > 0) {
     return { success: false, targets: [], error: result.errors.map((e) => e.message).join("\n") };
   }
@@ -421,7 +433,7 @@ export async function runComponents(
   selector: string,
   options: RunComponentsOptions = {},
 ): Promise<RunComponentsResult> {
-  const resolved = await resolveComponentTargets(path, selector);
+  const resolved = await resolveComponentTargets(path, selector, options.sandbox);
   if (!resolved.success) {
     return { success: false, selected: [], error: resolved.error };
   }