@intentius/chant 0.18.36 → 0.19.0

package/dist/terraform/score.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Peelability scoring for the carve-out advisor (#214 T3).
+ *
+ * The model, verbatim from #197:
+ *
+ *   score = 100
+ *     - 12 * inbound          # survivors that depend on this → each a TF data-source patch
+ *     -  4 * outbound         # this depends on survivors → a deferred deploy-time input
+ *     - 15 * (tier - 1)       # native-spec map: tier1=0, tier2=-15, tier3=-30
+ *     - 10 * has_dynamic      # count / for_each / data present
+ *     -  3 * (instances - 1)  # state-expanded instance count
+ *   clamp 0..100   (unsupported provider/type → 0)
+ *
+ * Sub-resources that inline into a parent (see `FOLDS_INTO`) are folded into the
+ * parent's carve set: they are removed from the ranking and their edge to the
+ * parent is not counted as inbound — inlining them is free, not boundary work.
+ */
+import type { TfGraph } from "./types.js";
+export type PeelabilityBand = "clean leaf" | "carvable w/ edits" | "leave in Terraform";
+export interface PeelabilityBreakdown {
+    inbound: number;
+    outbound: number;
+    tier: 1 | 2 | 3 | null;
+    hasDynamic: boolean;
+    instances: number;
+    /** Signed penalty contributions, for report transparency. */
+    penalties: {
+        inbound: number;
+        outbound: number;
+        tier: number;
+        dynamic: number;
+        instances: number;
+    };
+}
+export interface Peelability {
+    address: string;
+    kind: "resource" | "module";
+    score: number;
+    band: PeelabilityBand;
+    /** Native spec type a carve would target; undefined for modules/unsupported. */
+    mapsTo?: string;
+    breakdown: PeelabilityBreakdown;
+}
+export declare function bandFor(score: number): PeelabilityBand;
+/**
+ * Score every carvable node in the estate, ranked most-peelable first. Folded
+ * sub-resources are omitted (they carve with their parent, not on their own).
+ */
+export declare function scoreEstate(graph: TfGraph): Peelability[];
+//# sourceMappingURL=score.d.ts.map

package/dist/terraform/score.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.d.ts","sourceRoot":"","sources":["../../src/terraform/score.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAU,MAAM,SAAS,CAAC;AAE/C,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,mBAAmB,GAAG,oBAAoB,CAAC;AAExF,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,SAAS,EAAE;QACT,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,eAAe,CAAC;IACtB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,oBAAoB,CAAC;CACjC;AAID,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAItD;AAiFD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,EAAE,CAMzD"}

package/dist/terraform/state.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Opt-in `.tfstate` reader for the carve-out advisor (#214 T2).
+ *
+ * A `.tf`-only parse cannot know how many instances a `count`/`for_each` block
+ * expands to — it reports 1 and flags the node dynamic. State is where those
+ * are unrolled: each managed resource carries an `instances` array with one
+ * entry per expansion. Feeding state in makes the `-3*(instances-1)` penalty
+ * accurate, so a 200-instance fan-out ranks as the boundary work it really is.
+ *
+ * This is deliberately separate and opt-in (`--state <path>`): a pure-`.tf`
+ * parse is a plain file read, while reading state pulls in a state backend's
+ * output. JSON only — no HCL, no wasm.
+ */
+import type { TfGraph } from "./types.js";
+/** A resource's resolved attributes, read from state for adoption. */
+export interface StateResource {
+    type: string;
+    name: string;
+    /** The first instance's resolved attributes (id, arn, tags, ...). */
+    attributes: Record<string, unknown>;
+}
+/**
+ * Read one root-module managed resource's resolved attributes from state, by
+ * Terraform address (`aws_s3_bucket.assets`). This is the true source of a
+ * Terraform-managed resource's live shape — unlike a CloudFormation export, it
+ * exists whether or not the resource was ever in a CFN stack. Returns null if
+ * the address is absent, is a data source, or is module-nested.
+ */
+export declare function readStateResource(statePath: string, address: string): StateResource | null;
+/**
+ * Map each root-module managed resource address to its state-expanded instance
+ * count. Resources nested in a `module` are skipped: the `.tf` graph models a
+ * module as a single node, so there is no per-resource node to attach the count
+ * to (a documented v1 limitation — module internals are not descended into).
+ */
+export declare function readStateInstanceCounts(statePath: string): Map<string, number>;
+/**
+ * Overlay state instance counts onto a graph in place. Nodes absent from state
+ * keep their `.tf`-derived count of 1. Returns the same graph for chaining.
+ */
+export declare function applyStateCounts(graph: TfGraph, counts: Map<string, number>): TfGraph;
+//# sourceMappingURL=state.d.ts.map

package/dist/terraform/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/terraform/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAevC,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAU1F;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAW9E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAMrF"}

package/dist/terraform/tier-map.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Terraform-type → native-spec tier map for the carve-out advisor (#214 T3).
+ *
+ * The AWS entries are derived from the single AWS carve-out table
+ * (`aws-resources.ts`), so the advisor ranks exactly the AWS types `carve emit`
+ * can produce — no advise↔emit cliff. Non-AWS entries (e.g. `kubernetes_manifest`)
+ * are listed here directly; emit for those is a separate target.
+ *
+ *   tier 1 — a clean 1:1 native resource
+ *   tier 2 — maps, but with reshaping
+ *   tier 3 — a hard/partial map
+ *   null   — no known native mapping (unsupported provider/type) → score 0
+ */
+export interface TierInfo {
+    tier: 1 | 2 | 3;
+    /** The native spec type a carve would target, for the report. */
+    mapsTo: string;
+}
+/** TF resource type → native tier. Absent = unsupported (score 0). */
+export declare const TIER_MAP: Record<string, TierInfo>;
+/**
+ * TF "sub-resource" types that inline into a parent resource rather than
+ * standing alone (TF splits config the native spec keeps in one resource).
+ * A sub-resource that shares its parent's name is folded into the parent's
+ * carve set: it is not ranked on its own, and its edge to the parent does not
+ * count as inbound boundary work — inlining it is free.
+ *
+ * Maps sub-resource TF type → parent TF type.
+ */
+export declare const FOLDS_INTO: Record<string, string>;
+/**
+ * The HCL attribute carrying a resource's physical name, per type — derived
+ * from the AWS carve-out table. Used for the graph's identity and the
+ * live-import hint. Absent → fall back to the TF logical name.
+ */
+export declare const IDENTITY_ATTR: Record<string, string>;
+export declare function resolveTier(tfType: string): TierInfo | null;
+//# sourceMappingURL=tier-map.d.ts.map

package/dist/terraform/tier-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier-map.d.ts","sourceRoot":"","sources":["../../src/terraform/tier-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAK7C,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAO7C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEhD,CAAC;AAEF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAE3D"}

package/dist/terraform/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Types for the read-only Terraform carve-out advisor (#214).
+ *
+ * The advisor never emits, patches, or mutates state. It parses a Terraform
+ * estate into a dependency graph and scores each resource/module by
+ * "peelability" — how cleanly it could later be carved into native chant
+ * source (the emit/boundary/apply phases stay in #197, gated on demand).
+ *
+ * The graph layer here is intentionally pure: it consumes the JSON shape
+ * `@cdktf/hcl2json` produces (see `parse.ts`), so the graph and scoring can
+ * be tested without loading the wasm parser.
+ */
+/** A node in the Terraform dependency graph — one resource or module block. */
+export interface TfNode {
+    /** Terraform address, e.g. `aws_s3_bucket.assets` or `module.cdn`. */
+    address: string;
+    kind: "resource" | "module";
+    /** Resource type (`aws_s3_bucket`); undefined for modules. */
+    type?: string;
+    /** Local name (`assets`) or module name (`cdn`). */
+    name: string;
+    /**
+     * State-expanded instance count. 1 unless `count`/`for_each` is present and
+     * a `.tfstate` was read (see `state.ts`, #214 T2). Without state, a block
+     * with `count`/`for_each` reports 1 and sets `hasDynamic`.
+     */
+    instances: number;
+    /** `count`, `for_each`, a `data` source, or an unresolved interpolation is present. */
+    hasDynamic: boolean;
+    /**
+     * The resource's physical name, when it is a plain literal in the HCL (e.g.
+     * `bucket = "myapp-assets-prod"`). Used to build the live-import selector on
+     * emit. Undefined when the identity attribute is absent or interpolated.
+     */
+    identity?: string;
+}
+/**
+ * A directed dependency edge: `from` references `to`.
+ *
+ * For a candidate carve target T:
+ *  - inbound  = edges where `to === T`  (surviving resources depend on T → each is a data-source patch)
+ *  - outbound = edges where `from === T` (T depends on survivors → a deferred deploy-time input)
+ */
+export interface TfEdge {
+    from: string;
+    to: string;
+    /** The attribute path(s) referenced, e.g. `["id", "arn"]`. */
+    attrs: string[];
+}
+export interface TfGraph {
+    nodes: TfNode[];
+    edges: TfEdge[];
+}
+/**
+ * The subset of `@cdktf/hcl2json`'s `parse()` output the advisor reads. A
+ * merged tree across every `.tf` file in the estate. Values are left as the
+ * raw hcl2json encoding (interpolations survive as `"${...}"` strings), which
+ * is what edge extraction scans.
+ */
+export interface Hcl2JsonTree {
+    resource?: Record<string, Record<string, unknown[]>>;
+    module?: Record<string, unknown[]>;
+    data?: Record<string, Record<string, unknown[]>>;
+    [k: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/terraform/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/terraform/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,MAAM;IACrB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC5B,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,UAAU,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.18.36",
+  "version": "0.19.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -83,6 +83,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@cdktf/hcl2json": "^0.21.0",
     "ajv": "^8.20.0"
   }
 }

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

@@ -0,0 +1,82 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync, readFileSync, existsSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { carveApply, formatCarveApply } from "./carve-apply";
+import { loadHcl2json } from "../../terraform/parse";
+
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = `
+resource "aws_s3_bucket" "assets" { bucket = "myapp-assets-prod" }
+resource "aws_lambda_function" "api" {
+  environment { variables = { B = aws_s3_bucket.assets.bucket } }
+}
+`;
+
+async function withEstate<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-apply-"));
+  try {
+    writeFileSync(join(dir, "main.tf"), ESTATE);
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe("carveApply", () => {
+  test("requires --from and --select", async () => {
+    expect((await carveApply({})).error).toContain("--from");
+    expect((await carveApply({ from: "/x" })).error).toContain("--select");
+  });
+
+  test("plans graduation with ownership marker; writes nothing by default", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const res = await carveApply({ from: dir, select: "aws_s3_bucket.assets", env: "prod", stack: "assets" });
+      expect(res.ok).toBe(true);
+      expect(res.written).toBeUndefined();
+      expect(res.plan!.ownershipTags["chant:managed-by"]).toBe("chant");
+      expect(res.plan!.marker).toEqual({ stack: "assets", env: "prod" });
+
+      const text = formatCarveApply(res);
+      expect(text).toContain("observe → apply");
+      expect(text).toContain("no cloud call");
+    });
+  });
+
+  test("--write emits the graduation doc", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      const res = await carveApply({
+        from: dir,
+        select: "aws_s3_bucket.assets",
+        env: "prod",
+        output: out,
+        write: true,
+      });
+      expect(res.ok).toBe(true);
+      expect(res.written).toBe(join(out, "aws_s3_bucket-assets-graduation.md"));
+      expect(existsSync(res.written!)).toBe(true);
+      const doc = readFileSync(res.written!, "utf-8");
+      expect(doc).toContain("# Apply graduation: aws_s3_bucket.assets");
+      expect(doc).toContain("chant:managed-by = chant");
+    });
+  });
+
+  test("errors on an unknown target", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const res = await carveApply({ from: dir, select: "aws_s3_bucket.nope", env: "prod" });
+      expect(res.ok).toBe(false);
+      expect(res.error).toContain("not found");
+    });
+  });
+});

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

@@ -0,0 +1,106 @@
+/**
+ * `chant carve apply` — apply graduation for the strangler-fig carve (#197).
+ *
+ * The dial-turn from observe to apply: resolve the ownership marker that makes
+ * the carved resource chant-owned and finalize the ordered apply runbook.
+ *
+ * BYOL-honest: it does not call the cloud. It computes the marker + graduation
+ * plan and (with `--write`) emits a graduation doc. The apply is whatever
+ * lifecycle you brought.
+ */
+
+import { existsSync, statSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
+import { boundaryReport } from "../../terraform/carve";
+import { graduationPlan, type GraduationPlan } from "../../terraform/graduate";
+
+export interface CarveApplyOptions {
+  from?: string;
+  select?: string;
+  env?: string;
+  stack?: string;
+  statePath?: string;
+  output?: string;
+  /** Write the graduation doc to the output dir. */
+  write?: boolean;
+}
+
+export interface CarveApplyResult {
+  ok: boolean;
+  error?: string;
+  plan?: GraduationPlan;
+  written?: string;
+}
+
+export async function carveApply(opts: CarveApplyOptions): Promise<CarveApplyResult> {
+  if (!opts.from) return { ok: false, error: "chant carve apply requires --from <terraform-dir>" };
+  if (!opts.select) return { ok: false, error: "chant carve apply requires --select <tf-address>" };
+  if (!existsSync(opts.from) || !statSync(opts.from).isDirectory()) {
+    return { ok: false, error: `Not a directory: ${opts.from}` };
+  }
+
+  let plan: GraduationPlan;
+  try {
+    const graph = await parseTerraformDir(opts.from, { statePath: opts.statePath });
+    const report = boundaryReport(graph, opts.select);
+    if (!report) return { ok: false, error: `${opts.select} not found in ${opts.from}` };
+    plan = graduationPlan(report, { stack: opts.stack, env: opts.env });
+  } catch (err) {
+    if (err instanceof Hcl2JsonNotInstalled) return { ok: false, error: err.message };
+    return { ok: false, error: `Failed to plan graduation: ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  let written: string | undefined;
+  if (opts.write) {
+    const outDir = opts.output ?? join(opts.from, "carveout");
+    mkdirSync(outDir, { recursive: true });
+    const slug = opts.select.replace(/[^A-Za-z0-9_]+/g, "-");
+    written = join(outDir, `${slug}-graduation.md`);
+    writeFileSync(written, renderGraduationDoc(plan) + "\n");
+  }
+
+  return { ok: true, plan, written };
+}
+
+function renderGraduationDoc(plan: GraduationPlan): string {
+  const L: string[] = [];
+  L.push(`# Apply graduation: ${plan.target}`);
+  L.push("");
+  L.push(`Ownership marker: stack=${plan.marker.stack}${plan.marker.env ? `, env=${plan.marker.env}` : ""}`);
+  L.push("");
+  L.push("## Ownership tags (stamped on apply so chant owns the resource)");
+  for (const [k, v] of Object.entries(plan.ownershipTags)) L.push(`- ${k} = ${v}`);
+  L.push("");
+  L.push("## Steps");
+  for (const s of plan.steps) L.push(s);
+  if (plan.warnings.length) {
+    L.push("");
+    L.push("## Before you apply");
+    for (const w of plan.warnings) L.push(`- ${w}`);
+  }
+  return L.join("\n");
+}
+
+export function formatCarveApply(result: CarveApplyResult): string {
+  if (!result.ok || !result.plan) return result.error ?? "carve apply failed";
+  const p = result.plan;
+  const L: string[] = [];
+  L.push(`Apply graduation for ${p.target} (dial-turn: observe → apply).`);
+  L.push(`  Ownership marker: stack=${p.marker.stack}${p.marker.env ? `, env=${p.marker.env}` : ""}`);
+  L.push("  Ownership tags (stamped on apply):");
+  for (const [k, v] of Object.entries(p.ownershipTags)) L.push(`    ${k} = ${v}`);
+  L.push("");
+  for (const s of p.steps) L.push(`  ${s}`);
+  if (p.warnings.length) {
+    L.push("");
+    for (const w of p.warnings) L.push(`  ! ${w}`);
+  }
+  L.push("");
+  if (result.written) {
+    L.push(`Wrote graduation doc: ${result.written}`);
+  } else {
+    L.push("Plan only — no cloud call, nothing written. The apply is your lifecycle (BYOL). Add --write to save this as a doc.");
+  }
+  return L.join("\n");
+}

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

@@ -0,0 +1,97 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync, readFileSync, existsSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { carveBridge, formatCarveBridge } from "./carve-bridge";
+import { loadHcl2json } from "../../terraform/parse";
+
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const BUCKET_TF = `resource "aws_s3_bucket" "assets" {
+  bucket = "myapp-assets-prod"
+}
+`;
+const API_TF = `resource "aws_lambda_function" "api" {
+  function_name = "myapp-api"
+  environment {
+    variables = {
+      ASSETS_BUCKET = aws_s3_bucket.assets.bucket
+      ASSETS_ARN    = aws_s3_bucket.assets.arn
+    }
+  }
+}
+`;
+
+async function withEstate<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-bridge-"));
+  try {
+    writeFileSync(join(dir, "bucket.tf"), BUCKET_TF);
+    writeFileSync(join(dir, "api.tf"), API_TF);
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe("carveBridge", () => {
+  test("requires --from and --select", async () => {
+    expect((await carveBridge({})).error).toContain("--from");
+    expect((await carveBridge({ from: "/x" })).error).toContain("--select");
+  });
+
+  test("dry-run: writes runbook + data sources + proposed survivor, touches no .tf in place", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      const res = await carveBridge({ from: dir, select: "aws_s3_bucket.assets", output: out });
+      expect(res.ok).toBe(true);
+      expect(res.appliedInPlace).toBeFalsy();
+
+      // Runbook + data sources + proposed api.tf were written to the output dir.
+      expect(existsSync(join(out, "aws_s3_bucket-assets-runbook.md"))).toBe(true);
+      const ds = readFileSync(join(out, "aws_s3_bucket-assets-datasources.tf"), "utf-8");
+      expect(ds).toContain('data "aws_s3_bucket" "assets"');
+      const proposed = readFileSync(join(out, "api.tf"), "utf-8");
+      expect(proposed).toContain("data.aws_s3_bucket.assets.bucket");
+
+      // The ORIGINAL api.tf in the estate is untouched.
+      expect(readFileSync(join(dir, "api.tf"), "utf-8")).toBe(API_TF);
+    });
+  });
+
+  test("--apply-rewrites edits the survivor .tf in place", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const res = await carveBridge({
+        from: dir,
+        select: "aws_s3_bucket.assets",
+        output: join(dir, "carveout"),
+        applyRewrites: true,
+      });
+      expect(res.ok).toBe(true);
+      expect(res.appliedInPlace).toBe(true);
+
+      // api.tf rewritten in place; bucket.tf (the carved declaration) untouched.
+      const api = readFileSync(join(dir, "api.tf"), "utf-8");
+      expect(api).toContain("data.aws_s3_bucket.assets.bucket");
+      expect(readFileSync(join(dir, "bucket.tf"), "utf-8")).toBe(BUCKET_TF);
+    });
+  });
+
+  test("formatCarveBridge summarizes data sources, rewires, and safety", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const res = await carveBridge({ from: dir, select: "aws_s3_bucket.assets", output: join(dir, "carveout") });
+      const text = formatCarveBridge(res);
+      expect(text).toContain("data.aws_s3_bucket.assets");
+      expect(text).toContain("Nothing in your Terraform changed");
+      expect(text).toContain("runbook");
+    });
+  });
+});

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

@@ -0,0 +1,134 @@
+/**
+ * `chant carve bridge` — the boundary-bridging step of the strangler-fig carve
+ * (#197). Generates the edits to the surviving Terraform (data sources +
+ * rewired references), records the deferred deploy-time inputs, and writes a
+ * reversible handoff runbook.
+ *
+ * Safe by default: writes proposed files to an output directory for review.
+ * `--apply-rewrites` writes the rewritten survivor `.tf` back in place — an
+ * opt-in mutation of your Terraform, never the default.
+ */
+
+import { existsSync, statSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
+import { join, basename } from "path";
+import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
+import { boundaryReport } from "../../terraform/carve";
+import { generateBridge, type BridgePlan, type CarvedIdentity } from "../../terraform/bridge";
+import { IDENTITY_ATTR } from "../../terraform/tier-map";
+
+export interface CarveBridgeOptions {
+  from?: string;
+  select?: string;
+  statePath?: string;
+  /** Output directory for proposed files (default `<from>/carveout`). */
+  output?: string;
+  /** Write rewritten survivor `.tf` back in place instead of to the output dir. */
+  applyRewrites?: boolean;
+}
+
+export interface CarveBridgeResult {
+  ok: boolean;
+  error?: string;
+  plan?: BridgePlan;
+  /** Absolute paths written. */
+  written?: string[];
+  /** True if survivor files were edited in place. */
+  appliedInPlace?: boolean;
+}
+
+function listTfFiles(dir: string): string[] {
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".tf"))
+    .map((f) => join(dir, f))
+    .sort();
+}
+
+export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridgeResult> {
+  if (!opts.from) return { ok: false, error: "chant carve bridge requires --from <terraform-dir>" };
+  if (!opts.select) return { ok: false, error: "chant carve bridge requires --select <tf-address>" };
+  if (!existsSync(opts.from) || !statSync(opts.from).isDirectory()) {
+    return { ok: false, error: `Not a directory: ${opts.from}` };
+  }
+
+  let plan: BridgePlan;
+  try {
+    const graph = await parseTerraformDir(opts.from, { statePath: opts.statePath });
+    const report = boundaryReport(graph, opts.select);
+    if (!report) return { ok: false, error: `${opts.select} not found in ${opts.from}` };
+
+    // Physical identities for the carved resources, for the data sources.
+    const identities = new Map<string, CarvedIdentity>();
+    for (const node of graph.nodes) {
+      if (node.type && node.identity) {
+        identities.set(node.address, { attr: IDENTITY_ATTR[node.type], value: node.identity });
+      }
+    }
+
+    const files = listTfFiles(opts.from).map((path) => ({ path, content: readFileSync(path, "utf-8") }));
+    plan = generateBridge(report, files, identities);
+  } catch (err) {
+    if (err instanceof Hcl2JsonNotInstalled) return { ok: false, error: err.message };
+    return { ok: false, error: `Failed to build the bridge: ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  const slug = opts.select.replace(/[^A-Za-z0-9_]+/g, "-");
+  const outDir = opts.output ?? join(opts.from, "carveout");
+  mkdirSync(outDir, { recursive: true });
+  const written: string[] = [];
+
+  // Runbook.
+  const runbookPath = join(outDir, `${slug}-runbook.md`);
+  writeFileSync(runbookPath, plan.runbook + "\n");
+  written.push(runbookPath);
+
+  // Data sources for the survivors to read.
+  if (plan.dataSources.length) {
+    const dsPath = join(outDir, `${slug}-datasources.tf`);
+    writeFileSync(dsPath, plan.dataSources.map((d) => d.hcl).join("\n\n") + "\n");
+    written.push(dsPath);
+  }
+
+  // Rewritten survivors: in place (opt-in) or proposed into the output dir.
+  const changed = plan.rewrites.filter((r) => r.changed);
+  for (const r of changed) {
+    if (opts.applyRewrites) {
+      writeFileSync(r.path, r.rewritten);
+      written.push(r.path);
+    } else {
+      const proposed = join(outDir, basename(r.path));
+      writeFileSync(proposed, r.rewritten);
+      written.push(proposed);
+    }
+  }
+
+  return { ok: true, plan, written, appliedInPlace: opts.applyRewrites && changed.length > 0 };
+}
+
+export function formatCarveBridge(result: CarveBridgeResult): string {
+  if (!result.ok || !result.plan) return result.error ?? "carve bridge failed";
+  const p = result.plan;
+  const L: string[] = [];
+  L.push(`Boundary bridge for ${p.target}:`);
+  if (p.dataSources.length) {
+    L.push(`  ${p.dataSources.length} data source(s) for survivors to read:`);
+    for (const d of p.dataSources) L.push(`    data.${d.type}.${d.name}  (was ${d.address})`);
+  } else {
+    L.push("  no inbound edges — no survivor patch needed.");
+  }
+  const changed = p.rewrites.filter((r) => r.changed);
+  if (changed.length) {
+    L.push(`  ${changed.length} survivor file(s) rewired: ${changed.map((r) => basename(r.path)).join(", ")}`);
+  }
+  if (p.deferredInputs.length) {
+    L.push(`  ${p.deferredInputs.length} deferred deploy-time input(s) (wired at apply):`);
+    for (const d of p.deferredInputs) L.push(`    - ${d.note}`);
+  }
+  L.push("");
+  if (result.appliedInPlace) {
+    L.push("Rewritten survivor Terraform in place. Review with `git diff`, then `terraform plan`.");
+  } else {
+    L.push(`Wrote proposals to ${result.written?.[0] ? result.written[0].replace(/[^/]+$/, "") : "the output dir"} — review, then apply. Nothing in your Terraform changed.`);
+  }
+  L.push("See the runbook for the reversible, observe-first handoff steps.");
+  return L.join("\n");
+}