@intentius/chant 0.19.1 → 0.20.0

package/src/cli/commands/check-lexicon.ts

@@ -1,5 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "fs";
 import { join, basename } from "path";
+import { auditIntrinsics } from "./check-lexicon-intrinsics";
+import { checkExamplesBuild } from "./check-lexicon-examples";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -65,7 +67,7 @@ function countSubdirs(dir: string): number {
 /**
  * Run all completeness checks against a lexicon directory.
  */
-export function checkLexicon(dir: string): CheckResult {
+export async function checkLexicon(dir: string): Promise<CheckResult> {
   const items: CheckItem[] = [];
 
   // ── Tier 1: Required ───────────────────────────────────────────
@@ -117,6 +119,70 @@ export function checkLexicon(dir: string): CheckResult {
     pass: existsSync(join(dir, "dist/manifest.json")),
   });
 
+  // chant #1067 — chantVersion was "optional, unchecked": a lexicon could
+  // declare (or omit) a core-version constraint and nothing failed. This
+  // does not validate compatibility against the running core version — that
+  // needs a live check at plugin-load time (a different tool: candidates are
+  // `loadPlugin`/`loadPlugins` in ../plugins.ts), which is a deliberate
+  // non-goal here (see PR description). It closes the narrower gap that the
+  // field can be silently absent or malformed in the shipped manifest.
+  const manifestJson = readOr(join(dir, "dist/manifest.json"));
+  let chantVersionOk = false;
+  let chantVersionDetail: string | undefined;
+  if (manifestJson) {
+    try {
+      const parsed = JSON.parse(manifestJson) as { chantVersion?: unknown };
+      const cv = parsed.chantVersion;
+      chantVersionOk = typeof cv === "string" && /\d/.test(cv);
+      chantVersionDetail = chantVersionOk ? `chantVersion: ${cv as string}` : `chantVersion: ${JSON.stringify(cv)}`;
+    } catch {
+      chantVersionDetail = "dist/manifest.json is not valid JSON";
+    }
+  } else {
+    chantVersionDetail = "dist/manifest.json missing or unreadable";
+  }
+  items.push({
+    name: "dist/manifest.json declares a chantVersion",
+    tier: 1,
+    pass: chantVersionOk,
+    detail: chantVersionDetail,
+  });
+
+  // chant #1067 — packaging shape ("all 11 lexicons route exports['.'].default
+  // at ./src/index.ts and delete emitted JS in build") was real but
+  // unenforced; a lexicon shipping differently would break consumers
+  // silently. Cheap structural check on package.json, not a build execution.
+  const packageJsonRaw = readOr(join(dir, "package.json"));
+  let packagingOk = false;
+  let packagingDetail: string | undefined;
+  if (packageJsonRaw) {
+    try {
+      const pkg = JSON.parse(packageJsonRaw) as {
+        exports?: { "."?: { default?: string } };
+        scripts?: { build?: string };
+      };
+      const defaultExport = pkg.exports?.["."]?.default;
+      const buildScript = pkg.scripts?.build ?? "";
+      const exportOk = defaultExport === "./src/index.ts";
+      const deletesEmittedJs = /-delete/.test(buildScript) && /\.js/.test(buildScript);
+      packagingOk = exportOk && deletesEmittedJs;
+      const problems: string[] = [];
+      if (!exportOk) problems.push(`exports["."].default is ${JSON.stringify(defaultExport)}, expected "./src/index.ts"`);
+      if (!deletesEmittedJs) problems.push(`build script doesn't delete emitted .js from dist/: ${JSON.stringify(buildScript)}`);
+      packagingDetail = problems.length > 0 ? problems.join("; ") : undefined;
+    } catch {
+      packagingDetail = "package.json is not valid JSON";
+    }
+  } else {
+    packagingDetail = "package.json missing or unreadable";
+  }
+  items.push({
+    name: 'package.json routes exports["."].default at ./src/index.ts and deletes emitted JS in build',
+    tier: 1,
+    pass: packagingOk,
+    detail: packagingDetail,
+  });
+
   const exampleCount = countSubdirs(join(dir, "examples"));
   items.push({
     name: "At least 1 example in examples/",
@@ -125,6 +191,58 @@ export function checkLexicon(dir: string): CheckResult {
     detail: exampleCount > 0 ? `${exampleCount} example(s)` : undefined,
   });
 
+  // chant #1067 — every shipped example must actually build. The prior
+  // checks only ever counted example directories; none tried to build one,
+  // so `lexicons/aws/examples/core-concepts` shipped with a discovery-time
+  // "Duplicate export name" error while this tool reported "All tier-1
+  // checks passed." See ./check-lexicon-examples.ts for exactly what
+  // "builds" means here (discovery + serialization, not post-synth/lint).
+  const exampleBuilds = await checkExamplesBuild(dir);
+  const brokenExamples = exampleBuilds.filter((e) => !e.ok);
+  items.push({
+    name: "Every shipped example builds",
+    tier: 1,
+    pass: brokenExamples.length === 0,
+    detail:
+      brokenExamples.length > 0
+        ? brokenExamples.map((e) => `${e.example}: ${e.detail}`).join(" | ")
+        : exampleBuilds.length > 0
+          ? `${exampleBuilds.length} example(s) built`
+          : undefined,
+  });
+
+  // chant #1067 — foldability (isTag) is required and validated, not an
+  // optional flag nobody checks. #1039 shipped with it wrong in both
+  // directions (aws's Sub missing isTag; gitlab's reference() claiming
+  // isTag: true for a plain call) and nothing caught either half. See
+  // ./check-lexicon-intrinsics.ts for what "exported"/"matches" mean.
+  const intrinsicAudit = auditIntrinsics(dir);
+  const unexportedIntrinsics = intrinsicAudit.filter((i) => !i.exported);
+  items.push({
+    name: "Registered intrinsics are exported by the package",
+    tier: 1,
+    pass: unexportedIntrinsics.length === 0,
+    detail:
+      unexportedIntrinsics.length > 0
+        ? unexportedIntrinsics.map((i) => i.detail).join(" | ")
+        : intrinsicAudit.length > 0
+          ? `${intrinsicAudit.length} intrinsic(s) checked`
+          : undefined,
+  });
+
+  const mismatchedIntrinsics = intrinsicAudit.filter((i) => !i.ok);
+  items.push({
+    name: "Registered intrinsics' isTag matches how they're authored",
+    tier: 1,
+    pass: mismatchedIntrinsics.length === 0,
+    detail:
+      mismatchedIntrinsics.length > 0
+        ? mismatchedIntrinsics.map((i) => i.detail).join(" | ")
+        : intrinsicAudit.length > 0
+          ? `${intrinsicAudit.length} intrinsic(s) checked`
+          : undefined,
+  });
+
   const hasPluginTest = findFiles(join(dir, "src"), (n) => n === "plugin.test.ts").length > 0;
   items.push({
     name: "plugin.test.ts exists",

package/src/cli/commands/lint.ts

@@ -39,6 +39,26 @@ export function isLintRule(value: unknown): value is LintRule {
 /**
  * Load custom lint rules from plugin files.
  * Each plugin file is dynamically imported and all exports conforming to LintRule are collected.
+ *
+ * chant #1051 — this (and `loadLocalRules`, `../../lint/rule-loader.ts`, for
+ * `.chant/rules/*.ts`) is unconditional project-source `import()` with no
+ * `--sandbox` equivalent, the same class of gap #1051 closes for
+ * `discoverComponents`. Deliberately NOT sandboxed here, and not a "decide by
+ * omission": a `LintRule` is not a one-shot data producer like `Component`/
+ * `Declarable` — its `check(context)` is a function the rule engine invokes
+ * inline, once per linted file, for the whole `chant lint` run. There is no
+ * cheap "collect once, JSON-serialize the result, hand it back" shape the way
+ * there is for a `Component` (plain JSON) or an entity (a wire codec) —
+ * `check` has to keep running as live JS in whichever process calls it. A
+ * shallow fix that sandboxed only the *import* step (mirroring
+ * `discoverComponents`) would give a false sense of safety: it would close
+ * off "malicious top-level module code" but leave `check()`'s own executable
+ * body — the dominant part of a rule's attack surface, since it runs for
+ * every file, every lint invocation — entirely unsandboxed regardless. A real
+ * fix needs either the AST/`ts.SourceFile` itself to cross the sandbox
+ * boundary or the whole custom-rule evaluation to run inside the child; both
+ * are materially harder, separate design problems from this issue's `Component`
+ * fix and are tracked separately (chant #1052).
  */
 export async function loadPluginRules(
   plugins: string[],
@@ -122,6 +142,13 @@ export interface LintOptions {
   format: "stylish" | "json" | "sarif";
   /** Rules to use (defaults to all) */
   rules?: LintRule[];
+  /**
+   * chant #1051 — opt-in: discover `*.component.ts` files (for the COMP*
+   * composition checks) in a sandboxed child process instead of the CLI's
+   * own process (`chant lint --sandbox`). See `discoverComponents`'s
+   * `sandbox` option (../../components/discover.ts).
+   */
+  sandbox?: boolean;
 }
 
 /**
@@ -296,6 +323,7 @@ async function resolveRegistryContext(
 
 async function runComponentCheckDiagnostics(
   infraPath: string,
+  sandbox?: boolean,
 ): Promise<{ diagnostics: LintDiagnostic[]; suppressed: Array<LintDiagnostic & { reason?: string }> }> {
   // Discovery stays scoped to the lint arg; COMP* severity overrides come from
   // the project-root config, same as the AST-rule pass.
@@ -304,7 +332,7 @@ async function runComponentCheckDiagnostics(
   const allCheckIds = new Set(checks.map((c) => c.id));
 
   const registryContext = await resolveRegistryContext(infraPath);
-  const raw = await runComponentChecks(infraPath, checks, registryContext);
+  const raw = await runComponentChecks(infraPath, checks, registryContext, sandbox);
 
   const fileDirectivesCache = new Map<string, ReturnType<typeof parseDisableComments>>();
   const fileLevelDisable = (
@@ -439,7 +467,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   // structurally distinct check family (whole-project, post-discovery,
   // see ../../lint/component-checks.ts) but the same `chant lint` output and
   // the same error-severity gating as every COR/EVL diagnostic.
-  const componentResult = await runComponentCheckDiagnostics(infraPath);
+  const componentResult = await runComponentCheckDiagnostics(infraPath, options.sandbox);
   diagnostics.push(...componentResult.diagnostics);
   suppressed.push(...componentResult.suppressed);
 
@@ -487,7 +515,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
     // `*.component.ts` file on their behalf), but a fix applied to another
     // rule could still be in the same file a component was discovered from —
     // re-run for consistency with the AST re-lint above.
-    const postComponentResult = await runComponentCheckDiagnostics(infraPath);
+    const postComponentResult = await runComponentCheckDiagnostics(infraPath, options.sandbox);
     diagnostics.push(...postComponentResult.diagnostics);
     suppressed.push(...postComponentResult.suppressed);
   }

package/src/cli/commands/onboard.ts

@@ -307,7 +307,7 @@ export async function printOnboardResult(result: OnboardResult, name: string): P
     console.log("");
     console.log("Lexicon completeness:");
     const { checkLexicon, printCheckResult } = await import("./check-lexicon");
-    const checkResult = checkLexicon(lexiconDir);
+    const checkResult = await checkLexicon(lexiconDir);
     printCheckResult(checkResult, false);
   }
 }

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