@intentius/chant 0.19.1 → 0.21.0

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,67 @@
+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 its lexicon never opted in does not fold", () => {
+    const page = generateIntrinsics(config, manifestWith([{ name: "Ref", isTag: false }]));
+    expect(page).toContain("| `Ref` | — | `Ref` | No | No |");
+  });
+
+  test("a plain-call intrinsic opted into call-form folding does fold (chant #1044)", () => {
+    const page = generateIntrinsics(config, manifestWith([{ name: "Ref", isTag: false, foldsAsCall: true }]));
+    expect(page).toContain("| `Ref` | — | `Ref` | No | Yes |");
+  });
+
+  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 },
+      { name: "Join", isTag: false, foldsAsCall: true },
+    ];
+    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 use of this intrinsic today, without running the file — generated directly from this lexicon's registration, not restated by hand. A tagged template folds once it is registered. A plain call folds only where this lexicon has opted that intrinsic in one at a time (\`foldsAsCall\`), so a \`No\` in this column means this intrinsic has not been opted in, not that calls in general cannot fold.`,
+    "",
+    "| 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/codegen/docs-types.ts

@@ -55,6 +55,8 @@ export interface ManifestJSON {
     description?: string;
     outputKey?: string;
     isTag?: boolean;
+    /** chant #1044 — the call-form fold opt-in, as published in the lexicon's manifest. Absent in any manifest built before #1044, which reads the same as "not opted in". */
+    foldsAsCall?: boolean;
   }>;
   pseudoParameters?: Record<string, string>;
 }

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

package/src/components/discover.ts

@@ -27,6 +27,17 @@
  * components the same way it can for `*.op.ts` files, and so discovery does
  * not have to import (and risk side-effecting) every `.ts` file in the
  * project looking for stray `Component`-shaped objects.
+ *
+ * chant #1051 — `discoverComponents` unconditionally `await import()`s every
+ * discovered file in the CLI's own process, the same exposure #1045 Phase 2
+ * closed for lexicon-resource discovery (`../discovery/index.ts`'s
+ * `discover({ sandbox: true })`). `{ sandbox: true }` here runs that import
+ * (and the duplicate-name collection below) together, isolated, in one
+ * sandboxed child process instead — see `./sandbox/driver.ts`/`./sandbox/
+ * run.ts`. Materially simpler than the entity path: a `Component` is plain
+ * JSON (no `AttrRef` cross-references), so the child can hand back its result
+ * with a bare `JSON.stringify` — no entity-wire codec needed (`projectToJson`,
+ * `./component.ts`, already proves the plain-JSON round-trip).
  */
 
 import { readdir } from "node:fs/promises";
@@ -52,6 +63,26 @@ export interface ComponentDiscoveryResult {
   errors: DiscoveryError[];
 }
 
+/** Options for {@link discoverComponents}. */
+export interface ComponentDiscoveryOptions {
+  /**
+   * chant #1051 — opt-in: import every discovered `*.component.ts` file
+   * together, isolated, in one sandboxed child process (`./sandbox/run.ts`)
+   * instead of in this (the CLI's own) process. Mirrors `discover({ sandbox:
+   * true })` (`../discovery/index.ts`, chant #1045 Phase 2) for the parallel
+   * `*.component.ts` convention. Default `false` — behavior, including
+   * performance (no bundling, no child process, no IPC), is unchanged unless
+   * requested.
+   */
+  sandbox?: boolean;
+}
+
+/** One already-imported `*.component.ts` module — the input to {@link collectComponents}. */
+export interface ImportedComponentModule {
+  file: string;
+  exports: Record<string, unknown>;
+}
+
 /**
  * Recursively find every `*.component.ts` file under `path`, the same
  * child-project boundary rule `findInfraFiles` (`../discovery/files.ts`)
@@ -106,36 +137,35 @@ async function findComponentFiles(path: string): Promise<string[]> {
 }
 
 /**
- * Discover every `Component` declared under `path`: scan for `*.component.ts`
- * files, import each, and collect every export whose value satisfies
- * `isComponent` (any export name — not just `default` — so a file may
- * declare several related components, matching how a resource file can
- * export several `Declarable`s). Duplicate `component.name` across files (or
- * within one file) is a discovery error, matching `collectEntities`'s
- * duplicate-export handling and `discoverOps`'s duplicate-Op-name handling —
- * except the identity compared is the schema-level `name` field, since two
- * different export bindings could otherwise declare the same component name
- * and silently collide at deploy time.
+ * Collect every `Component`-shaped export from already-imported `modules`,
+ * enforcing the duplicate-`component.name` rule (across files, or within one
+ * file): a discovery error, matching `collectEntities`'s duplicate-export
+ * handling and `discoverOps`'s duplicate-Op-name handling — except the
+ * identity compared is the schema-level `name` field, since two different
+ * export bindings could otherwise declare the same component name and
+ * silently collide at deploy time. `existing.component !== value` — object
+ * identity, not deep equality — is what lets the SAME component re-exported
+ * under several bindings pass through without tripping the duplicate check.
+ *
+ * Split out from {@link discoverComponents} (#1051) precisely because that
+ * identity check has to run on the LIVE, still-in-memory export values —
+ * identity does not survive a process boundary. That means this function
+ * must run wherever `modules` were actually imported: in this process for
+ * the default (unsandboxed) path below, or inside the sandboxed child for
+ * `{ sandbox: true }` (`./sandbox/driver.ts`, which bundles and calls this
+ * same function), mirroring how `collectEntities` runs inside `../discovery/
+ * sandbox/driver.ts` for the lexicon-resource run-fallback set (chant #1045
+ * Phase 2).
  */
-export async function discoverComponents(path: string): Promise<ComponentDiscoveryResult> {
+export function collectComponents(modules: readonly ImportedComponentModule[]): {
+  components: Map<string, DiscoveredComponent>;
+  errors: DiscoveryError[];
+} {
   const errors: DiscoveryError[] = [];
-  const sourceFiles = await findComponentFiles(path);
   const components = new Map<string, DiscoveredComponent>();
   const nameToFile = new Map<string, string>();
 
-  for (const filePath of sourceFiles) {
-    let exports: Record<string, unknown>;
-    try {
-      // Resolve to an absolute file:// URL before importing. A relative
-      // `filePath` (e.g. from `chant build --components --generate`, which passes
-      // a bare "." path) would otherwise be treated by `import()` as a bare
-      // package specifier and fail with "Cannot find package 'x.component.ts'".
-      exports = await import(pathToFileURL(resolve(filePath)).href);
-    } catch (err) {
-      errors.push(new DiscoveryError(filePath, err instanceof Error ? err.message : String(err), "import"));
-      continue;
-    }
-
+  for (const { file: filePath, exports } of modules) {
     for (const [exportName, value] of Object.entries(exports)) {
       if (!isComponent(value)) continue;
 
@@ -163,5 +193,77 @@ export async function discoverComponents(path: string): Promise<ComponentDiscove
     }
   }
 
+  return { components, errors };
+}
+
+/**
+ * Import every already-discovered `*.component.ts` file in THIS process (the
+ * unsandboxed default) and collect their `Component`-shaped exports.
+ */
+async function importAndCollectComponents(
+  sourceFiles: readonly string[],
+): Promise<{ components: Map<string, DiscoveredComponent>; errors: DiscoveryError[] }> {
+  const modules: ImportedComponentModule[] = [];
+  const importErrors: DiscoveryError[] = [];
+
+  for (const filePath of sourceFiles) {
+    try {
+      // Resolve to an absolute file:// URL before importing. A relative
+      // `filePath` (e.g. from `chant build --components --generate`, which passes
+      // a bare "." path) would otherwise be treated by `import()` as a bare
+      // package specifier and fail with "Cannot find package 'x.component.ts'".
+      const exports = await import(pathToFileURL(resolve(filePath)).href);
+      modules.push({ file: filePath, exports });
+    } catch (err) {
+      importErrors.push(new DiscoveryError(filePath, err instanceof Error ? err.message : String(err), "import"));
+    }
+  }
+
+  const { components, errors: collectErrors } = collectComponents(modules);
+  return { components, errors: [...importErrors, ...collectErrors] };
+}
+
+/**
+ * Discover every `Component` declared under `path`: scan for `*.component.ts`
+ * files, import each, and collect every export whose value satisfies
+ * `isComponent` (any export name — not just `default` — so a file may
+ * declare several related components, matching how a resource file can
+ * export several `Declarable`s). See {@link collectComponents} for the
+ * duplicate-name rule.
+ *
+ * `{ sandbox: true }` (#1051) imports every file together, isolated, in one
+ * sandboxed child process instead (`./sandbox/run.ts`) — the same isolation
+ * `discover({ sandbox: true })` (`../discovery/index.ts`) gives lexicon
+ * resources, chant #1045 Phase 2.
+ */
+export async function discoverComponents(
+  path: string,
+  options?: ComponentDiscoveryOptions,
+): Promise<ComponentDiscoveryResult> {
+  const sourceFiles = await findComponentFiles(path);
+
+  if (options?.sandbox && sourceFiles.length > 0) {
+    // Dynamic, not static — for the same reason `../discovery/index.ts`
+    // dynamically imports its own `./sandbox/run`: that module (transitively)
+    // imports `esbuild`, a large package with its own module-scope filesystem
+    // access, and this module is reachable from `@intentius/chant`'s package
+    // root, which project source commonly imports. A static import here would
+    // make `esbuild` bundled and eagerly evaluated by any build of a project
+    // that itself imports chant. A dynamic import is only ever actually
+    // reached here, at runtime, when a caller opts into `sandbox: true`.
+    try {
+      const { discoverComponentsSandboxed } = await import("./sandbox/run");
+      const result = await discoverComponentsSandboxed(sourceFiles, path);
+      return { components: result.components, sourceFiles, errors: result.errors };
+    } catch (err) {
+      return {
+        components: new Map(),
+        sourceFiles,
+        errors: [new DiscoveryError(path, err instanceof Error ? err.message : String(err), "resolution")],
+      };
+    }
+  }
+
+  const { components, errors } = await importAndCollectComponents(sourceFiles);
   return { components, sourceFiles, errors };
 }

package/src/components/sandbox/driver.ts

@@ -0,0 +1,114 @@
+import { join, resolve } from "node:path";
+
+/**
+ * chant #1051 — generates the source of the "driver" module that runs INSIDE
+ * the sandboxed child for component discovery. Mirrors `../../discovery/
+ * sandbox/driver.ts`'s shape (chant #1045 Phase 2) but is materially simpler:
+ * a `Component` is plain JSON (no `AttrRef` cross-references to resolve), so
+ * there is no equivalent of `resolveAttrRefs`/`encodeEntitySet` here — the
+ * driver hands back its collected components with a bare, structural
+ * `JSON.stringify` over the IPC channel (see `./run.ts`'s `send`).
+ *
+ * Like the entity driver, every file is imported via a LITERAL string
+ * specifier dynamic `import()` — not a variable — so esbuild's bundler can
+ * trace and inline it into ONE self-contained module graph (see `../../
+ * discovery/sandbox/driver.ts`'s doc for why that's verified to lower to a
+ * lazily-invoked local module initializer, not a runtime resolution). That
+ * single module graph is what lets `collectComponents`'s duplicate-name check
+ * (`../discover.ts`) run over real, live object identity — "the same
+ * component re-exported under two bindings" only detects correctly when both
+ * bindings really do resolve to the same in-memory object, which requires
+ * every `*.component.ts` file for one discovery call to share one module
+ * cache inside a single child (see `../discover.ts`'s `collectComponents` doc
+ * for the full identity-correctness argument).
+ */
+
+const HERE = import.meta.dirname;
+const COMPONENTS_DIR = join(HERE, "..");
+
+/** Absolute paths to chant's OWN trusted modules the generated driver imports — resolved relative to THIS file's own location on disk, exactly like `../../discovery/sandbox/driver.ts` does for the entity path (works whether chant runs from the monorepo or a consumer's `node_modules`). */
+const DISCOVER_MODULE = join(COMPONENTS_DIR, "discover.ts");
+const CHILD_ERRORS_MODULE = join(COMPONENTS_DIR, "..", "discovery", "sandbox", "child-errors.ts");
+
+export interface GenerateComponentDriverOptions {
+  /** Absolute paths to every discovered `*.component.ts` file for this build. */
+  files: readonly string[];
+}
+
+/** Escape a value for embedding as a JS/TS source-level literal. */
+function lit(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+/**
+ * Generate the component driver module's full TypeScript source. Written to
+ * a tmp file and bundled (`../../discovery/sandbox/bundle.ts`'s `bundleDriver`
+ * — generic, reused as-is) before being handed to a sandboxed child — never
+ * executed directly by the parent process.
+ */
+export function generateComponentDriverSource(options: GenerateComponentDriverOptions): string {
+  const { files } = options;
+
+  const lines: string[] = [
+    `import { collectComponents } from ${lit(DISCOVER_MODULE)};`,
+    `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
+    ``,
+    `function send(payload) {`,
+    `  if (typeof process.send === "function") process.send(payload);`,
+    `  else console.log(JSON.stringify(payload));`,
+    `}`,
+    ``,
+    `async function main() {`,
+    `  const modules = [];`,
+    `  const errors = [];`,
+  ];
+
+  for (const file of files) {
+    // `file` (as discovered by `findComponentFiles`, `../discover.ts`) may be
+    // relative to whatever cwd-relative `path` `discoverComponents` was
+    // called with — `chant list --components examples/foo` never resolves
+    // its argument before discovery, matching the unsandboxed import loop's
+    // own tolerance for that (`pathToFileURL(resolve(filePath)).href`, see
+    // `../discover.ts`'s `importAndCollectComponents`). A bare relative
+    // string hits Node's *bare-specifier* (package) resolution instead of
+    // being treated as a path, so only the import target — never the `file`
+    // key `collectComponents` dedupes and reports by — is resolved to an
+    // absolute filesystem path here, in THIS (parent) process, before being
+    // embedded as a literal in the bundled child (mirrors `../../discovery/
+    // sandbox/driver.ts`'s own literal-specifier `import()`s, which are
+    // likewise plain absolute paths, not `file://` URLs — kept that way
+    // rather than converting to a URL since esbuild's bundler is only
+    // verified to trace/inline a literal filesystem-path specifier).
+    const absoluteFile = resolve(file);
+    lines.push(
+      `  try {`,
+      `    const mod = await import(${lit(absoluteFile)});`,
+      `    modules.push({ file: ${lit(file)}, exports: mod });`,
+      `  } catch (err) {`,
+      `    errors.push(classifyChildError(${lit(file)}, err).toJSON());`,
+      `  }`,
+    );
+  }
+
+  lines.push(
+    ``,
+    `  const collected = collectComponents(modules);`,
+    `  for (const err of collected.errors) errors.push(err.toJSON());`,
+    ``,
+    // Plain JSON: no entity-wire codec needed (see this module's doc + chant
+    // #1051's issue — `projectToJson`, ../component.ts, already proves the
+    // bare JSON.parse(JSON.stringify()) round-trip for a Component).
+    `  const components = [];`,
+    `  for (const [name, discovered] of collected.components) {`,
+    `    components.push({ name, component: discovered.component, exportName: discovered.exportName, filePath: discovered.filePath });`,
+    `  }`,
+    `  send({ components, errors });`,
+    `}`,
+    ``,
+    `main().catch((err) => {`,
+    `  send({ components: [], errors: [classifyChildError("", err).toJSON()], fatal: true });`,
+    `});`,
+  );
+
+  return lines.join("\n");
+}