@intentius/chant 0.53.1 → 0.54.0

package/src/audit/nginx.ts

@@ -0,0 +1,379 @@
+/**
+ * nginx config audit (#1979, the #446 follow-up) — the second spike-gated
+ * format after Wrangler (PR #1978). nginx's native config is a directive/block
+ * DSL no structured-data parser reads, so before this the audit engine could
+ * fetch an estate's `nginx.conf` but not see inside it.
+ *
+ * Follows `wrangler.ts`'s shape exactly: no lexicon plugin, no
+ * `AuditInput`/`classifyFiles` involvement, no npm package. A principled,
+ * dependency-free recursive-descent parser (directives end with `;`, blocks
+ * nest with `{}`, `#` comments, single/double quotes) feeds a fixed check
+ * list; `auditNginxConfigs` is called alongside `auditWranglerConfigs` from
+ * the CLI. Disjoint id namespace (`NGX0xx`), `AuditFinding.lexicon = "nginx"`.
+ *
+ * Detection is two-stage on purpose: the *path* detector is broad (`.conf`
+ * under nginx-ish directories), because `conf.d/`-style names are shared with
+ * unrelated software (systemd drop-ins are `.conf` too) — so a candidate only
+ * produces findings when its parsed form also carries an nginx marker
+ * directive (`http`, `server`, `location`, `upstream`, …). A file that fails
+ * to parse, or parses to something that isn't nginx, contributes nothing:
+ * the audit contract is "runs against any repo," never a crash on odd config.
+ *
+ * Pure: no fs, no network, no Node-only global — Workers-safe (epic #350).
+ */
+
+import type { AuditFinding } from "./core";
+
+/** The minimal file shape the scanner needs (matches `discover.ts`'s `RepoFile`). */
+export interface ScannableFile {
+  path: string;
+  content: string;
+}
+
+/** nginx-ish directories whose `.conf` files are candidates. */
+const NGINX_DIR_RE = /(^|\/)(nginx|conf\.d|sites-available|sites-enabled|snippets)(\/|$)/;
+
+/** Detector: does this path look like nginx config? (Confirmed by content markers at parse time.) */
+export function isNginxConfigPath(path: string): boolean {
+  const base = path.split("/").pop() ?? path;
+  if (base === "nginx.conf") return true;
+  return base.endsWith(".conf") && NGINX_DIR_RE.test(path.slice(0, path.length - base.length));
+}
+
+// ── Parser ──────────────────────────────────────────────────────────────────
+
+/** One parsed directive. A block directive (`server { … }`) carries `block`. */
+export interface NginxDirective {
+  name: string;
+  args: string[];
+  block?: NginxDirective[];
+  /** 1-based line the directive's name starts on. */
+  line: number;
+}
+
+export class NginxParseError extends Error {
+  constructor(message: string, public readonly line: number) {
+    super(`${message} (line ${line})`);
+    this.name = "NginxParseError";
+  }
+}
+
+interface Token {
+  value: string;
+  line: number;
+  kind: "word" | "{" | "}" | ";";
+}
+
+function tokenize(content: string): Token[] {
+  const tokens: Token[] = [];
+  let i = 0;
+  let line = 1;
+  const n = content.length;
+  while (i < n) {
+    const c = content[i];
+    if (c === "\n") {
+      line++;
+      i++;
+    } else if (c === " " || c === "\t" || c === "\r") {
+      i++;
+    } else if (c === "#") {
+      while (i < n && content[i] !== "\n") i++;
+    } else if (c === "{" || c === "}" || c === ";") {
+      tokens.push({ value: c, line, kind: c });
+      i++;
+    } else if (c === '"' || c === "'") {
+      const quote = c;
+      const startLine = line;
+      let value = "";
+      i++;
+      while (i < n && content[i] !== quote) {
+        if (content[i] === "\\" && i + 1 < n) {
+          value += content[i + 1];
+          if (content[i + 1] === "\n") line++;
+          i += 2;
+        } else {
+          if (content[i] === "\n") line++;
+          value += content[i];
+          i++;
+        }
+      }
+      if (i >= n) throw new NginxParseError("Unterminated quoted string", startLine);
+      i++; // closing quote
+      tokens.push({ value, line: startLine, kind: "word" });
+    } else {
+      const start = i;
+      const startLine = line;
+      while (i < n && !' \t\r\n#{};"\''.includes(content[i])) i++;
+      tokens.push({ value: content.slice(start, i), line: startLine, kind: "word" });
+    }
+  }
+  return tokens;
+}
+
+/** Parse nginx config into a directive tree. Throws `NginxParseError` on malformed input. */
+export function parseNginx(content: string): NginxDirective[] {
+  const tokens = tokenize(content);
+  let pos = 0;
+
+  function parseDirectives(depth: number): NginxDirective[] {
+    const out: NginxDirective[] = [];
+    while (pos < tokens.length) {
+      const tok = tokens[pos];
+      if (tok.kind === "}") {
+        if (depth === 0) throw new NginxParseError("Unexpected '}'", tok.line);
+        pos++;
+        return out;
+      }
+      if (tok.kind !== "word") throw new NginxParseError(`Unexpected '${tok.value}'`, tok.line);
+      const name = tok.value;
+      const line = tok.line;
+      pos++;
+      const args: string[] = [];
+      for (;;) {
+        if (pos >= tokens.length) throw new NginxParseError(`Directive "${name}" is never terminated`, line);
+        const next = tokens[pos];
+        if (next.kind === "word") {
+          args.push(next.value);
+          pos++;
+        } else if (next.kind === ";") {
+          pos++;
+          out.push({ name, args, line });
+          break;
+        } else if (next.kind === "{") {
+          pos++;
+          out.push({ name, args, line, block: parseDirectives(depth + 1) });
+          break;
+        } else {
+          throw new NginxParseError(`Unexpected '}' inside directive "${name}"`, next.line);
+        }
+      }
+    }
+    if (depth > 0) throw new NginxParseError("Unclosed '{'", tokens[tokens.length - 1]?.line ?? 1);
+    return out;
+  }
+
+  return parseDirectives(0);
+}
+
+// ── Walk helpers ────────────────────────────────────────────────────────────
+
+/** Directive names that confirm a parsed `.conf` is actually nginx. */
+const NGINX_MARKERS = new Set(["http", "server", "location", "upstream", "events", "stream", "listen", "proxy_pass", "server_name"]);
+
+function hasNginxMarker(tree: NginxDirective[]): boolean {
+  return tree.some((d) => NGINX_MARKERS.has(d.name) || (d.block !== undefined && hasNginxMarker(d.block)));
+}
+
+/** Depth-first visit of every directive with its ancestor block-name chain. */
+function walk(tree: NginxDirective[], visit: (d: NginxDirective, ancestors: string[]) => void, ancestors: string[] = []): void {
+  for (const d of tree) {
+    visit(d, ancestors);
+    if (d.block) walk(d.block, visit, [...ancestors, d.name]);
+  }
+}
+
+// ── NGX001: deprecated TLS protocol enabled ─────────────────────────────────
+
+const DEPRECATED_TLS = new Set(["sslv2", "sslv3", "tlsv1", "tlsv1.1"]);
+
+function checkDeprecatedTls(file: ScannableFile, tree: NginxDirective[]): AuditFinding[] {
+  const out: AuditFinding[] = [];
+  walk(tree, (d) => {
+    if (d.name !== "ssl_protocols") return;
+    const bad = d.args.filter((a) => DEPRECATED_TLS.has(a.toLowerCase()));
+    if (bad.length === 0) return;
+    out.push({
+      checkId: "NGX001",
+      severity: "error",
+      message: `ssl_protocols enables ${bad.join(", ")} — protocols with known breaks (POODLE, BEAST) that every current client has moved past. Serve TLSv1.2 and TLSv1.3 only.`,
+      file: file.path,
+      lexicon: "nginx",
+      entity: "ssl_protocols",
+      line: d.line,
+    });
+  });
+  return out;
+}
+
+// ── NGX002: weak cipher suite enabled ───────────────────────────────────────
+
+const WEAK_CIPHER_RE = /(RC4|DES|MD5|NULL|EXPORT|LOW|aNULL|eNULL)/i;
+
+function checkWeakCiphers(file: ScannableFile, tree: NginxDirective[]): AuditFinding[] {
+  const out: AuditFinding[] = [];
+  walk(tree, (d) => {
+    if (d.name !== "ssl_ciphers") return;
+    // A cipher string is ':'-separated; an entry starting with '!' is an
+    // exclusion (good), so only positive entries can be findings.
+    const weak = d.args
+      .flatMap((a) => a.split(":"))
+      .filter((s) => s !== "" && !s.startsWith("!") && WEAK_CIPHER_RE.test(s));
+    if (weak.length === 0) return;
+    out.push({
+      checkId: "NGX002",
+      severity: "error",
+      message: `ssl_ciphers enables weak suite(s): ${[...new Set(weak)].join(", ")} — breakable ciphers (RC4/DES/MD5/NULL/EXPORT classes) undermine every connection that negotiates one. Use a modern cipher list.`,
+      file: file.path,
+      lexicon: "nginx",
+      entity: "ssl_ciphers",
+      line: d.line,
+    });
+  });
+  return out;
+}
+
+// ── NGX003: directory listing enabled ───────────────────────────────────────
+
+function checkAutoindex(file: ScannableFile, tree: NginxDirective[]): AuditFinding[] {
+  const out: AuditFinding[] = [];
+  walk(tree, (d, ancestors) => {
+    if (d.name !== "autoindex" || d.args[0]?.toLowerCase() !== "on") return;
+    out.push({
+      checkId: "NGX003",
+      severity: "warning",
+      message: `autoindex on (${ancestors.join(" > ") || "top level"}) — the directory's full file listing is served to anyone, including files never meant to be enumerated.`,
+      file: file.path,
+      lexicon: "nginx",
+      entity: "autoindex",
+      line: d.line,
+    });
+  });
+  return out;
+}
+
+// ── NGX004: alias path traversal (the gixy classic) ─────────────────────────
+
+/** Location args end with the prefix; earlier args are modifiers (`=`, `^~`, `~`, `~*`). */
+function locationPrefix(args: string[]): { prefix: string; isRegex: boolean } | undefined {
+  if (args.length === 0) return undefined;
+  const modifiers = args.slice(0, -1);
+  return { prefix: args[args.length - 1], isRegex: modifiers.includes("~") || modifiers.includes("~*") };
+}
+
+function checkAliasTraversal(file: ScannableFile, tree: NginxDirective[]): AuditFinding[] {
+  const out: AuditFinding[] = [];
+  walk(tree, (d) => {
+    if (d.name !== "location" || !d.block) return;
+    const loc = locationPrefix(d.args);
+    if (!loc || loc.isRegex || loc.prefix.endsWith("/")) return;
+    for (const inner of d.block) {
+      if (inner.name !== "alias") continue;
+      const target = inner.args[0] ?? "";
+      if (!target.endsWith("/")) continue;
+      out.push({
+        checkId: "NGX004",
+        severity: "error",
+        message: `location "${loc.prefix}" (no trailing slash) with alias "${target}" — a request for "${loc.prefix}../" resolves outside the aliased directory (path traversal). End the location prefix with "/" to match the alias.`,
+        file: file.path,
+        lexicon: "nginx",
+        entity: loc.prefix,
+        line: inner.line,
+      });
+    }
+  });
+  return out;
+}
+
+// ── NGX005: status endpoint with no access restriction ──────────────────────
+
+function checkOpenStatusEndpoint(file: ScannableFile, tree: NginxDirective[]): AuditFinding[] {
+  const out: AuditFinding[] = [];
+  walk(tree, (d) => {
+    if (d.name !== "location" || !d.block) return;
+    const hasStatus = d.block.some((inner) => inner.name === "stub_status");
+    if (!hasStatus) return;
+    const restricted = d.block.some(
+      (inner) => inner.name === "deny" || inner.name === "allow" || inner.name === "auth_basic" || inner.name === "auth_request",
+    );
+    if (restricted) return;
+    out.push({
+      checkId: "NGX005",
+      severity: "warning",
+      message: `stub_status in location "${d.args[d.args.length - 1] ?? ""}" with no allow/deny or auth — the server's connection metrics are readable by anyone, a reconnaissance gift.`,
+      file: file.path,
+      lexicon: "nginx",
+      entity: "stub_status",
+      line: d.line,
+    });
+  });
+  return out;
+}
+
+// ── NGX006: server version disclosure (server_tokens not disabled) ──────────
+
+function checkServerTokens(file: ScannableFile, tree: NginxDirective[]): AuditFinding[] {
+  const http = tree.find((d) => d.name === "http" && d.block);
+  if (!http) return []; // a partial include has no http{} — the main conf is where this belongs
+  let disabled = false;
+  walk(tree, (d) => {
+    if (d.name === "server_tokens" && d.args[0]?.toLowerCase() !== "on") disabled = true;
+  });
+  if (disabled) return [];
+  return [
+    {
+      checkId: "NGX006",
+      severity: "info",
+      message: `server_tokens is not disabled — nginx defaults to advertising its exact version in the Server header and error pages, handing scanners a version to match CVEs against. Add "server_tokens off;" in the http block.`,
+      file: file.path,
+      lexicon: "nginx",
+      entity: "http",
+      line: http.line,
+    },
+  ];
+}
+
+// ── NGX007: access logging disabled at server scope ─────────────────────────
+
+function checkAccessLogOff(file: ScannableFile, tree: NginxDirective[]): AuditFinding[] {
+  const out: AuditFinding[] = [];
+  walk(tree, (d, ancestors) => {
+    if (d.name !== "access_log" || d.args[0]?.toLowerCase() !== "off") return;
+    // Silencing a single noisy location (favicon, health checks) is normal
+    // practice; going dark at http/server scope is what blocks investigation.
+    const scope = ancestors[ancestors.length - 1] ?? "top level";
+    if (scope === "location") return;
+    out.push({
+      checkId: "NGX007",
+      severity: "info",
+      message: `access_log off at ${scope} scope — no requests are recorded for this ${scope === "server" ? "server" : "configuration"}, which will slow down or block incident investigation.`,
+      file: file.path,
+      lexicon: "nginx",
+      entity: scope,
+      line: d.line,
+    });
+  });
+  return out;
+}
+
+const CHECKS: Array<(file: ScannableFile, tree: NginxDirective[]) => AuditFinding[]> = [
+  checkDeprecatedTls,
+  checkWeakCiphers,
+  checkAutoindex,
+  checkAliasTraversal,
+  checkOpenStatusEndpoint,
+  checkServerTokens,
+  checkAccessLogOff,
+];
+
+/**
+ * Audit every nginx config in `files`. Pure with respect to the filesystem
+ * and network. A candidate that fails to parse, or parses to something with
+ * no nginx marker directive (a systemd-style `.conf` in a `conf.d/`),
+ * contributes no findings.
+ */
+export function auditNginxConfigs(files: ScannableFile[]): AuditFinding[] {
+  const findings: AuditFinding[] = [];
+  for (const file of files) {
+    if (!isNginxConfigPath(file.path)) continue;
+    let tree: NginxDirective[];
+    try {
+      tree = parseNginx(file.content);
+    } catch (err) {
+      if (err instanceof NginxParseError) continue;
+      throw err;
+    }
+    if (!hasNginxMarker(tree)) continue;
+    for (const check of CHECKS) findings.push(...check(file, tree));
+  }
+  return findings;
+}

package/src/audit/rules-doc.ts

@@ -23,6 +23,7 @@ const GROUPS: Array<{ heading: string; prefixes: string[]; blurb: string }> = [
   { heading: "fountain (FTN)", prefixes: ["FTN"], blurb: "Run against fountain manifests (`apiVersion: fountain.dev/v1`) — standalone `fountain apply` YAML is parsed back into the entity graph, so the same rules fire on `chant build` and `chant audit`." },
   { heading: "Secrets & credentials (SEC)", prefixes: ["SEC"], blurb: "Lexicon-independent — scans the raw text of every scanned file for likely credentials, regardless of which audit lexicons are installed. Matched values are always redacted; see [suppressing false positives](/chant/cli/audit/#suppressing-a-secrets-finding)." },
   { heading: "Wrangler config (WRG)", prefixes: ["WRG"], blurb: "Lexicon-independent, audit-only (#446) — scans `wrangler.toml`, Cloudflare Workers' native deploy config, which the engine cannot otherwise parse (it is not YAML/JSON). No authoring surface: chant does not write Wrangler config, it only reads it for these checks." },
+  { heading: "nginx config (NGX)", prefixes: ["NGX"], blurb: "Lexicon-independent, audit-only (#1979) — parses nginx's native directive/block config (`nginx.conf` and `.conf` files under nginx-ish directories, confirmed by content). No authoring surface: chant does not write nginx config, it only reads it for these checks." },
   {
     heading: "Agent configuration (AGT)",
     prefixes: ["AGT"],

package/src/cli/commands/audit.ts

@@ -12,6 +12,7 @@ import { AUDIT_LEXICONS, classifyFiles, collectCandidates, loadAuditPlugins, unc
 import { RULE_CATALOG, resolveAuditCatalog, type RuleMeta } from "../../audit/catalog";
 import { scanForSecrets, parseSecretsConfig, type SecretsScanOptions } from "../../audit/secrets";
 import { auditWranglerConfigs } from "../../audit/wrangler";
+import { auditNginxConfigs } from "../../audit/nginx";
 import { renderMarkdown } from "../../audit/report";
 import { renderHtml, type ReportTheme } from "../../audit/report-html";
 import { buildReportJson, REPORT_SCHEMA_VERSION, type AuditSnapshot } from "../../audit/report-model";
@@ -390,15 +391,19 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
   // `classifyFiles`/an installed lexicon package (no such package exists —
   // this format ships only a detector and checks, per the issue's scope).
   const wranglerFindings = auditWranglerConfigs(candidates);
+  // nginx config audit (#1979) — same lexicon-independent shape as wrangler:
+  // its own path detector plus a parsed-content marker check (a `.conf` in a
+  // shared directory name like conf.d/ only counts once it parses as nginx).
+  const nginxFindings = auditNginxConfigs(candidates);
 
   if (plugins.length === 0) {
     const output = format === "json" ? renderNoLexiconsJson(options.path, unclaimed) : renderNoLexicons(options.path, unclaimed);
-    return { success: true, status: "no-lexicons", output, findings: [...secretsFindings, ...wranglerFindings], scanned: [], unclaimed, exitCode: NO_LEXICONS_EXIT_CODE, stream: format === "json" ? "stdout" : "stderr" };
+    return { success: true, status: "no-lexicons", output, findings: [...secretsFindings, ...wranglerFindings, ...nginxFindings], scanned: [], unclaimed, exitCode: NO_LEXICONS_EXIT_CODE, stream: format === "json" ? "stdout" : "stderr" };
   }
 
   const missingLexiconNote = missingLexiconHint(unclaimed);
 
-  if (inputs.length === 0 && secretsFindings.length === 0 && wranglerFindings.length === 0) {
+  if (inputs.length === 0 && secretsFindings.length === 0 && wranglerFindings.length === 0 && nginxFindings.length === 0) {
     const output = `No auditable files found under ${options.path}.${missingLexiconNote ? ` ${missingLexiconNote}` : ""}`;
     return { success: true, status: "ok", output, findings: [], scanned: [], unclaimed, exitCode: 0 };
   }
@@ -412,7 +417,7 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
       return { success: false, output: "", findings: [], scanned, exitCode: 1, error: msg };
     }
   }
-  findings = [...findings, ...secretsFindings, ...wranglerFindings];
+  findings = [...findings, ...secretsFindings, ...wranglerFindings, ...nginxFindings];
   // Resolve the audit catalog once, aggregating the audited lexicons' own
   // metadata over core's static catalog (#687). The lexicons are already loaded
   // by `auditFiles` above, so this is cheap. Core's static catalog (always

package/src/cli/commands/carve-apply.test.ts

@@ -95,7 +95,10 @@ describe("carveApply", () => {
       expect(stamped).toContain('{"Key":"chant:env","Value":"prod"}');
 
       const m = readCarveManifest(res.manifestPath!)!;
-      expect(m.apply!.stampedFiles).toEqual([emitted]);
+      // Recorded relative to the manifest's directory (#2039), not the
+      // run-time absolute path the stamping itself used.
+      expect(m.apply!.stampedFiles).toEqual(["assets.ts"]);
+      expect(m.emit!.files).toEqual(["assets.ts"]);
       expect(formatCarveApply(res)).toContain("Stamped the ownership marker into");
 
       // Idempotent: a second graduation leaves the source stable.

package/src/cli/commands/carve-apply.ts

@@ -15,7 +15,7 @@ import { cdkNotSupported, isCloudAssembly } from "../../cdk/assembly";
 import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
 import { boundaryReport } from "../../terraform/carve";
 import { graduationPlan, stampOwnershipIntoSource, type GraduationPlan } from "../../terraform/graduate";
-import { resolveCarveManifest, updateCarveManifest } from "../../terraform/manifest";
+import { resolveCarveManifest, resolveManifestFilePath, updateCarveManifest } from "../../terraform/manifest";
 import { resolveEmitProvider } from "../../terraform/carve-provider";
 
 export interface CarveApplyOptions {
@@ -82,7 +82,9 @@ export async function carveApply(opts: CarveApplyOptions): Promise<CarveApplyRes
   // tags the source actually carries into the apply.
   let stamped: string[] | undefined;
   if (opts.writeSource) {
-    const files = resolved.manifest?.emit?.files ?? [];
+    // Manifest paths are relative to the manifest's own directory (#2039);
+    // resolve them back to real files (absolute version-1 entries pass through).
+    const files = (resolved.manifest?.emit?.files ?? []).map((f) => resolveManifestFilePath(outDir, f));
     if (files.length === 0) {
       return {
         ok: false,

package/src/cli/commands/carve-bridge.test.ts

@@ -126,7 +126,8 @@ describe("carveBridge", () => {
       expect(patch).toContain("+      ASSETS_BUCKET = data.aws_s3_bucket.assets.bucket");
 
       const m = readCarveManifest(res.manifestPath!)!;
-      expect(m.bridge!.patch).toBe(res.patchPath);
+      // The manifest records the patch relative to its own directory (#2039).
+      expect(m.bridge!.patch).toBe("aws_s3_bucket-assets-bridge.patch");
       expect(formatCarveBridge(res)).toContain("git apply");
 
       // The patch really applies: `git apply` from the estate reproduces the

package/src/cli/commands/carve-emit-state.test.ts

@@ -106,7 +106,9 @@ describe("carve emit --state (real adoption from tfstate)", () => {
       expect(manifest.target).toBe("aws_s3_bucket.assets");
       expect(manifest.statePath).toBe(join(dir, "terraform.tfstate"));
       expect(manifest.emit!.source).toBe("tfstate");
-      expect(manifest.emit!.files).toEqual([join(out, "src", "assets.ts")]);
+      // Recorded relative to the manifest's own directory (#2039) — the same
+      // base the graph IR's sourceLoc uses, which is the #2040 join.
+      expect(manifest.emit!.files).toEqual([join("src", "assets.ts")]);
       expect(manifest.boundary.inbound.map((e) => e.survivor)).toEqual(["aws_lambda_function.api"]);
 
       const text = formatCarveEmit(res);

package/src/cli/commands/carve-status.test.ts

@@ -0,0 +1,116 @@
+import { describe, test, expect } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { carveStatus, carveStatusJson, formatCarveStatus } from "./carve-status";
+import { writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
+import type { CarveReport } from "../../terraform/carve";
+
+function report(target: string): CarveReport {
+  return {
+    target,
+    carveSet: [{ address: target, type: target.split(".")[0] }],
+    peelability: 90,
+    inbound: [],
+    outbound: [],
+    reversible: true,
+    diagnostics: [],
+  };
+}
+
+function manifest(target: string): CarveManifest {
+  return { version: 1, target, from: "/estate", boundary: report(target) };
+}
+
+function withDir<T>(fn: (dir: string) => T): T {
+  const dir = mkdtempSync(join(tmpdir(), "chant-carve-status-"));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe("carve status", () => {
+  test("walks the tree at any depth and reports target, stage, and root-relative path", () => {
+    withDir((dir) => {
+      // Flat under a named output dir…
+      writeCarveManifest(join(dir, "carveout"), manifest("aws_s3_bucket.assets"));
+      // …and nested deeper than the two levels a walker would guess at.
+      const deep = { ...manifest("aws_sqs_queue.jobs"), tfType: "aws_sqs_queue" };
+      deep.emit = { source: "tfstate" as const, files: ["src/jobs.ts"], at: "2026-08-30T00:00:00Z" };
+      writeCarveManifest(join(dir, "stacks", "queues", "carveout"), deep);
+
+      const res = carveStatus({ from: dir });
+      expect(res.ok).toBe(true);
+      expect(res.from).toBe(dir);
+      expect(res.carves).toHaveLength(2);
+
+      const [flat, nested] = res.carves!;
+      expect(flat.path).toBe(join("carveout", "aws_s3_bucket-assets.carve.json"));
+      expect(flat.target).toBe("aws_s3_bucket.assets");
+      expect(flat.stage).toBe("planned"); // boundary only, no recorded step
+      expect(flat.at).toEqual({});
+
+      expect(nested.path).toBe(join("stacks", "queues", "carveout", "aws_sqs_queue-jobs.carve.json"));
+      expect(nested.target).toBe("aws_sqs_queue.jobs");
+      expect(nested.tfType).toBe("aws_sqs_queue");
+      expect(nested.stage).toBe("emitted");
+      expect(nested.at).toEqual({ emit: "2026-08-30T00:00:00Z" });
+      expect(nested.emittedFiles).toEqual(["src/jobs.ts"]);
+    });
+  });
+
+  test("stage is the highest recorded step: emitted < bridged < applied", () => {
+    withDir((dir) => {
+      const m = manifest("aws_s3_bucket.assets");
+      m.emit = { source: "tfstate", files: ["src/assets.ts"], at: "t1" };
+      m.bridge = { written: ["runbook.md"], appliedInPlace: false, at: "t2" };
+      m.apply = { marker: { stack: "assets", env: "prod" }, ownershipTags: {}, at: "t3" };
+      writeCarveManifest(dir, m);
+
+      const res = carveStatus({ from: dir });
+      expect(res.carves![0].stage).toBe("applied");
+      expect(res.carves![0].at).toEqual({ emit: "t1", bridge: "t2", apply: "t3" });
+    });
+  });
+
+  test("reports unreadable manifest files instead of failing or silently dropping them", () => {
+    withDir((dir) => {
+      writeCarveManifest(dir, manifest("aws_s3_bucket.assets"));
+      writeFileSync(join(dir, "bad.carve.json"), "not json");
+
+      const res = carveStatus({ from: dir });
+      expect(res.ok).toBe(true);
+      expect(res.carves).toHaveLength(1);
+      expect(res.unreadable).toEqual(["bad.carve.json"]);
+      expect(formatCarveStatus(res)).toContain("bad.carve.json");
+    });
+  });
+
+  test("skips node_modules and .git", () => {
+    withDir((dir) => {
+      mkdirSync(join(dir, "node_modules", "dep"), { recursive: true });
+      writeCarveManifest(join(dir, "node_modules", "dep"), manifest("aws_s3_bucket.vendored"));
+      const res = carveStatus({ from: dir });
+      expect(res.carves).toHaveLength(0);
+      expect(formatCarveStatus(res)).toContain("No carve manifests");
+    });
+  });
+
+  test("errors on a non-directory root", () => {
+    const res = carveStatus({ from: "/definitely/not/a/dir" });
+    expect(res.ok).toBe(false);
+    expect(res.error).toContain("Not a directory");
+  });
+
+  test("--json payload carries from, carves, and unreadable only when present", () => {
+    withDir((dir) => {
+      writeCarveManifest(dir, manifest("aws_s3_bucket.assets"));
+      const res = carveStatus({ from: dir });
+      const json = carveStatusJson(res);
+      expect(Object.keys(json)).toEqual(["from", "carves"]);
+      expect((json.carves as unknown[]).length).toBe(1);
+    });
+  });
+});