@intentius/chant 0.19.1 → 0.20.0

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");
+}

package/src/components/sandbox/run.test.ts

@@ -0,0 +1,185 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { discoverComponentsSandboxed } from "./run";
+
+/**
+ * chant #1051 — proves the actual isolation properties for sandboxed
+ * component discovery (not just that it returns the right components),
+ * mirroring `../../discovery/sandbox/run.test.ts`'s coverage for the
+ * lexicon-resource run-fallback path (chant #1045 Phase 2): a hostile
+ * `*.component.ts` file cannot read outside the project directory, write
+ * anywhere, spawn a process, or read the ambient environment, and a
+ * permission denial names the file and the operation rather than leaking a
+ * raw `ERR_ACCESS_DENIED`.
+ *
+ * Fixtures are written to a fresh tmpdir per test, never into the source
+ * tree.
+ */
+describe("discoverComponentsSandboxed — isolation", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = await realpath(
+      await (async () => {
+        const dir = join(tmpdir(), `chant-component-sandbox-run-test-${Date.now()}-${Math.random()}`);
+        await mkdir(dir, { recursive: true });
+        return dir;
+      })(),
+    );
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("denies filesystem reads outside the project directory, naming the file and the operation", async () => {
+    const file = join(testDir, "evil.component.ts");
+    await writeFile(
+      file,
+      `
+        import { readFileSync } from "node:fs";
+        readFileSync("/etc/hosts", "utf-8");
+        export const evil = { name: "evil", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }] };
+      `,
+    );
+
+    const result = await discoverComponentsSandboxed([file], testDir);
+
+    expect(result.components.size).toBe(0);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].file).toBe(file);
+    expect(result.errors[0].type).toBe("permission");
+    expect(result.errors[0].message).toMatch(/FileSystemRead/);
+    expect(result.errors[0].message).toContain(file);
+  });
+
+  test("denies filesystem writes anywhere", async () => {
+    const file = join(testDir, "evil.component.ts");
+    const targetPath = join(testDir, "..", "escaped.txt");
+    await writeFile(
+      file,
+      `
+        import { writeFileSync } from "node:fs";
+        writeFileSync(${JSON.stringify(targetPath)}, "pwned");
+        export const evil = { name: "evil", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }] };
+      `,
+    );
+
+    const result = await discoverComponentsSandboxed([file], testDir);
+
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].type).toBe("permission");
+    expect(result.errors[0].message).toMatch(/FileSystemWrite/);
+    expect(existsSync(targetPath)).toBe(false);
+  });
+
+  test("denies spawning a child process", async () => {
+    const file = join(testDir, "evil.component.ts");
+    const markerPath = join(testDir, "spawned.txt");
+    await writeFile(
+      file,
+      `
+        import { execSync } from "node:child_process";
+        execSync(${JSON.stringify(`touch ${markerPath}`)});
+        export const evil = { name: "evil", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }] };
+      `,
+    );
+
+    const result = await discoverComponentsSandboxed([file], testDir);
+
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].type).toBe("permission");
+    expect(result.errors[0].message).toMatch(/ChildProcess/);
+    expect(existsSync(markerPath)).toBe(false);
+  });
+
+  test("scrubs the ambient environment — a real secret set on the parent's process.env is invisible to project source", async () => {
+    const file = join(testDir, "evil.component.ts");
+    await writeFile(
+      file,
+      `
+        const seen = process.env.CHANT_SANDBOX_TEST_SECRET;
+        if (seen !== undefined) {
+          throw new Error("ambient env leaked: " + seen);
+        }
+        export const evil = {
+          name: "evil",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell", envKeyCount: Object.keys(process.env).length }] }],
+        };
+      `,
+    );
+
+    const previous = process.env.CHANT_SANDBOX_TEST_SECRET;
+    process.env.CHANT_SANDBOX_TEST_SECRET = "super-secret-should-not-cross-the-boundary";
+    try {
+      const result = await discoverComponentsSandboxed([file], testDir);
+      expect(result.errors).toEqual([]);
+      expect(result.components.has("evil")).toBe(true);
+    } finally {
+      if (previous === undefined) delete process.env.CHANT_SANDBOX_TEST_SECRET;
+      else process.env.CHANT_SANDBOX_TEST_SECRET = previous;
+    }
+  });
+
+  test("the same component object re-exported under two bindings in one file is NOT a duplicate — the identity check runs on live objects, before any serialization", async () => {
+    // `collectComponents`'s dedupe check (`../discover.ts`) compares
+    // candidates with `existing.component !== value` — real object identity,
+    // not deep equality. That distinction only matters if the check runs
+    // over the LIVE, still-in-memory export values: had this instead run
+    // over a JSON-round-tripped copy (e.g. serialize each file's exports in
+    // the child, decode in the parent, THEN dedupe), `JSON.parse` never
+    // returns the same reference twice, so even this legitimate case — one
+    // object, two export bindings — would wrongly report a duplicate. This
+    // proves the sandboxed path preserves the unsandboxed behavior: the
+    // dedupe collector (`collectComponents`) runs bundled INSIDE the child,
+    // over the driver's own live `modules` array, before the one
+    // `JSON.stringify` at the very end (`./driver.ts`).
+    const file = join(testDir, "aliased.component.ts");
+    await writeFile(
+      file,
+      `
+        const base = {
+          name: "search-service",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+        export const searchService = base;
+        export const searchServiceAlias = base;
+      `,
+    );
+
+    const result = await discoverComponentsSandboxed([file], testDir);
+
+    expect(result.errors).toEqual([]);
+    expect(result.components.size).toBe(1);
+    expect(result.components.has("search-service")).toBe(true);
+  });
+
+  test("a genuine duplicate — two DIFFERENT objects declaring the same component name — is still reported", async () => {
+    await writeFile(
+      join(testDir, "one.component.ts"),
+      `
+        export const svc = { name: "dup", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }] };
+      `,
+    );
+    await writeFile(
+      join(testDir, "two.component.ts"),
+      `
+        export const svcAgain = { name: "dup", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }] };
+      `,
+    );
+
+    const result = await discoverComponentsSandboxed(
+      [join(testDir, "one.component.ts"), join(testDir, "two.component.ts")],
+      testDir,
+    );
+
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(result.errors[0].type).toBe("resolution");
+    expect(result.errors[0].message).toMatch(/Duplicate component name "dup"/);
+  });
+});

package/src/components/sandbox/run.ts

@@ -0,0 +1,177 @@
+import { fork } from "node:child_process";
+import { realpathSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { bundleDriver } from "../../discovery/sandbox/bundle";
+import { classifyChildError } from "../../discovery/sandbox/child-errors";
+import { DiscoveryError, type DiscoveryErrorType } from "../../errors";
+import type { Component } from "../component";
+import type { DiscoveredComponent } from "../discover";
+import { generateComponentDriverSource } from "./driver";
+
+/**
+ * chant #1051 — imports every discovered `*.component.ts` file for a build
+ * TOGETHER, as one bundled module graph, inside one sandboxed child process,
+ * and returns the same shape `discoverComponents`'s own in-process import
+ * loop would have produced: named components plus any errors.
+ *
+ * Isolation mechanics are identical to `../../discovery/sandbox/run.ts`'s
+ * `runFallbackFilesSandboxed` (chant #1045 Phase 2 — see that module's doc
+ * for the full write-up, verified on Node v24.13.1): `--permission
+ * --allow-fs-read=<bundle dir>,<project dir>[,<trusted external package
+ * dirs>]`, a spawn-time-scrubbed `env`, and a bounded wait before the child
+ * is treated as hung. `bundleDriver` (`../../discovery/sandbox/bundle.ts`) is
+ * reused as-is — it is generic over what the driver does, so the same
+ * esbuild bundling (and the same `typescript`-stays-external carve-out) that
+ * serves the entity path serves this one too.
+ */
+
+export interface ComponentSandboxRunResult {
+  /** Discovered components from this sandboxed import, keyed by `component.name` — functionally indistinguishable from what `discoverComponents`'s in-process path would have produced for this same file set. */
+  components: Map<string, DiscoveredComponent>;
+  /** Import/collection/permission errors, already chant-shaped (`../../discovery/sandbox/child-errors.ts` — a permission denial names the file and the operation, never a raw `ERR_ACCESS_DENIED`). */
+  errors: DiscoveryError[];
+  /** esbuild bundling wall-clock time. */
+  bundleMs: number;
+  /** Bundle size in bytes. */
+  bundleBytes: number;
+}
+
+interface ChildComponentEntry {
+  name: string;
+  component: Component;
+  exportName: string;
+  filePath: string;
+}
+
+interface ChildResponse {
+  components: ChildComponentEntry[];
+  errors: Array<{ file: string; message: string; type: DiscoveryErrorType }>;
+  fatal?: boolean;
+}
+
+/** How long to wait for the sandboxed child to report back before treating it as hung and killing it. Generous, matching the entity path's own budget. */
+const CHILD_TIMEOUT_MS = 120_000;
+
+function isChildResponse(value: unknown): value is ChildResponse {
+  return typeof value === "object" && value !== null && "components" in value && "errors" in value;
+}
+
+/**
+ * Import `files` (every discovered `*.component.ts` file) together, isolated,
+ * in one sandboxed child process, and collect their `Component`-shaped
+ * exports — including the duplicate-name check, which runs INSIDE the child
+ * over live objects before anything is serialized (`../discover.ts`'s
+ * `collectComponents`, bundled into the driver).
+ *
+ * @param files - Absolute paths to every discovered `*.component.ts` file.
+ * @param buildRoot - The directory `discoverComponents` was pointed at — used
+ *   to compute the project-directory read allowance, mirroring `../../
+ *   discovery/sandbox/run.ts`.
+ */
+export async function discoverComponentsSandboxed(
+  files: readonly string[],
+  buildRoot: string,
+): Promise<ComponentSandboxRunResult> {
+  if (files.length === 0) {
+    return { components: new Map(), errors: [], bundleMs: 0, bundleBytes: 0 };
+  }
+
+  const driverSource = generateComponentDriverSource({ files });
+  const { bundlePath, bundleDir, externalReadPaths, durationMs, bytes } = await bundleDriver(driverSource);
+
+  try {
+    let projectRealpath: string;
+    try {
+      projectRealpath = realpathSync(resolve(buildRoot));
+    } catch {
+      projectRealpath = resolve(buildRoot);
+    }
+
+    const response = await runChildProcess(bundlePath, bundleDir, projectRealpath, externalReadPaths);
+
+    const errors = (response.errors ?? []).map((e) => new DiscoveryError(e.file, e.message, e.type));
+    if (response.fatal) {
+      return { components: new Map(), errors, bundleMs: durationMs, bundleBytes: bytes };
+    }
+
+    const components = new Map<string, DiscoveredComponent>();
+    for (const entry of response.components ?? []) {
+      components.set(entry.name, {
+        component: entry.component,
+        exportName: entry.exportName,
+        filePath: entry.filePath,
+      });
+    }
+    return { components, errors, bundleMs: durationMs, bundleBytes: bytes };
+  } catch (err) {
+    return {
+      components: new Map(),
+      errors: [classifyChildError("", err, "import")],
+      bundleMs: durationMs,
+      bundleBytes: bytes,
+    };
+  } finally {
+    rmSync(bundleDir, { recursive: true, force: true });
+  }
+}
+
+/** Fork the bundle under `--permission`, with a scrubbed environment, and resolve with its one IPC message (or reject on crash/timeout/fork error). Mirrors `../../discovery/sandbox/run.ts`'s `runChildProcess`. */
+function runChildProcess(
+  bundlePath: string,
+  bundleDir: string,
+  projectRealpath: string,
+  externalReadPaths: readonly string[],
+): Promise<ChildResponse> {
+  return new Promise((resolvePromise, reject) => {
+    const readAllowances = [bundleDir, projectRealpath, ...externalReadPaths].map(
+      (p) => `--allow-fs-read=${p}`,
+    );
+    const child = fork(bundlePath, [], {
+      execArgv: ["--permission", ...readAllowances],
+      // chant #1051 — Node's Permission Model does not gate `process.env`;
+      // scrubbing it here is the only way to keep the ambient environment out
+      // of untrusted project source's reach, exactly as the entity path does.
+      env: { PATH: process.env.PATH ?? "" },
+      stdio: ["ignore", "pipe", "pipe", "ipc"],
+    });
+
+    let settled = false;
+    let stderrBuf = "";
+
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill();
+      reject(new Error(`sandboxed component discovery timed out after ${CHILD_TIMEOUT_MS}ms`));
+    }, CHILD_TIMEOUT_MS);
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderrBuf += chunk.toString();
+    });
+
+    child.on("message", (msg: unknown) => {
+      if (settled || !isChildResponse(msg)) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolvePromise(msg);
+    });
+
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(err);
+    });
+
+    child.on("exit", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(
+        new Error(
+          `sandboxed component discovery child exited before reporting results (code ${code}, signal ${signal})${stderrBuf.trim() ? `: ${stderrBuf.trim()}` : ""}`,
+        ),
+      );
+    });
+  });
+}