@intentius/chant 0.41.20 → 0.42.1

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

@@ -1,9 +1,11 @@
 import { describe, test, expect } from "vitest";
+import { execFileSync } from "child_process";
 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";
+import { readCarveManifest, writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
 
 let parserAvailable = false;
 try {
@@ -39,10 +41,52 @@ async function withEstate<T>(fn: (dir: string) => Promise<T>): Promise<T> {
   }
 }
 
+function manifestFor(target: string, dir: string): CarveManifest {
+  return {
+    version: 1,
+    target,
+    from: dir,
+    boundary: {
+      target,
+      carveSet: [{ address: target, type: target.split(".")[0] }],
+      peelability: 90,
+      inbound: [],
+      outbound: [],
+      reversible: true,
+      diagnostics: [],
+    },
+  };
+}
+
 describe("carveBridge", () => {
-  test("requires --from and --select", async () => {
+  test("requires --from; without --select it needs a carve manifest", async () => {
     expect((await carveBridge({})).error).toContain("--from");
-    expect((await carveBridge({ from: "/x" })).error).toContain("--select");
+    await withEstate(async (dir) => {
+      const res = await carveBridge({ from: dir });
+      expect(res.ok).toBe(false);
+      expect(res.error).toContain("--select");
+      expect(res.error).toContain("carve emit");
+    });
+  });
+
+  test("composes with the carve manifest: target resolved without --select, bridge recorded", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      writeCarveManifest(out, manifestFor("aws_s3_bucket.assets", dir));
+
+      const res = await carveBridge({ from: dir, output: out });
+      expect(res.ok).toBe(true);
+      expect(res.selectFromManifest).toBe(true);
+      expect(res.plan!.target).toBe("aws_s3_bucket.assets");
+      expect(formatCarveBridge(res)).toContain("target from the carve manifest");
+
+      const m = readCarveManifest(res.manifestPath!)!;
+      expect(m.bridge!.written.length).toBeGreaterThan(0);
+      expect(m.bridge!.appliedInPlace).toBe(false);
+      // The boundary is refreshed from the estate, not left as the stub.
+      expect(m.boundary.inbound.map((e) => e.survivor)).toEqual(["aws_lambda_function.api"]);
+    });
   });
 
   test("dry-run: writes runbook + data sources + proposed survivor, touches no .tf in place", async () => {
@@ -65,6 +109,39 @@ describe("carveBridge", () => {
     });
   });
 
+  test("emits one git-applyable patch carrying the whole survivor edit", 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.patchPath).toBe(join(out, "aws_s3_bucket-assets-bridge.patch"));
+      expect(res.written).toContain(res.patchPath);
+
+      const patch = readFileSync(res.patchPath!, "utf-8");
+      expect(patch).toContain("diff --git a/aws_s3_bucket-assets-datasources.tf b/aws_s3_bucket-assets-datasources.tf");
+      expect(patch).toContain("new file mode 100644");
+      expect(patch).toContain("diff --git a/api.tf b/api.tf");
+      expect(patch).toContain("-      ASSETS_BUCKET = aws_s3_bucket.assets.bucket");
+      expect(patch).toContain("+      ASSETS_BUCKET = data.aws_s3_bucket.assets.bucket");
+
+      const m = readCarveManifest(res.manifestPath!)!;
+      expect(m.bridge!.patch).toBe(res.patchPath);
+      expect(formatCarveBridge(res)).toContain("git apply");
+
+      // The patch really applies: `git apply` from the estate reproduces the
+      // rewired survivor and the new data-source file.
+      try {
+        execFileSync("git", ["apply", res.patchPath!], { cwd: dir });
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") return; // no git on this machine
+        throw err;
+      }
+      expect(readFileSync(join(dir, "api.tf"), "utf-8")).toContain("data.aws_s3_bucket.assets.bucket");
+      expect(readFileSync(join(dir, "aws_s3_bucket-assets-datasources.tf"), "utf-8")).toContain('data "aws_s3_bucket" "assets"');
+    });
+  });
+
   test("--apply-rewrites edits the survivor .tf in place", async () => {
     if (!parserAvailable) return;
     await withEstate(async (dir) => {
@@ -77,10 +154,11 @@ describe("carveBridge", () => {
       expect(res.ok).toBe(true);
       expect(res.appliedInPlace).toBe(true);
 
-      // api.tf rewritten in place; bucket.tf (the carved declaration) untouched.
+      // api.tf rewritten in place; bucket.tf's carved declaration excised
+      // (#998 — after `terraform state rm`, the block would re-create it).
       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);
+      expect(readFileSync(join(dir, "bucket.tf"), "utf-8")).not.toContain('resource "aws_s3_bucket" "assets"');
     });
   });
 

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

@@ -10,14 +10,17 @@
  */
 
 import { existsSync, statSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
-import { join, basename } from "path";
+import { join, basename, relative, resolve } from "path";
 import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
-import { boundaryReport } from "../../terraform/carve";
+import { boundaryReport, type CarveReport } from "../../terraform/carve";
 import { generateBridge, type BridgePlan, type CarvedIdentity } from "../../terraform/bridge";
 import { IDENTITY_ATTR } from "../../terraform/tier-map";
+import { resolveCarveManifest, writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
+import { newFileDiff, unifiedDiff } from "../../terraform/unified-diff";
 
 export interface CarveBridgeOptions {
   from?: string;
+  /** Optional when the output dir holds a single carve manifest from `carve emit`. */
   select?: string;
   statePath?: string;
   /** Output directory for proposed files (default `<from>/carveout`). */
@@ -34,6 +37,12 @@ export interface CarveBridgeResult {
   written?: string[];
   /** True if survivor files were edited in place. */
   appliedInPlace?: boolean;
+  /** The git-applyable `.patch` carrying the whole survivor edit. */
+  patchPath?: string;
+  /** The carve state manifest this bridge composed with / recorded into. */
+  manifestPath?: string;
+  /** True when the target came from the manifest, not --select. */
+  selectFromManifest?: boolean;
 }
 
 function listTfFiles(dir: string): string[] {
@@ -45,16 +54,25 @@ function listTfFiles(dir: string): string[] {
 
 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}` };
   }
 
+  // Compose with the carve state manifest `carve emit` persisted: without
+  // --select it supplies the target (and tfstate), with it it is updated below.
+  const outDir = opts.output ?? join(opts.from, "carveout");
+  const resolved = resolveCarveManifest(outDir, opts.select);
+  if (!opts.select && resolved.error) return { ok: false, error: resolved.error };
+  const select = opts.select ?? resolved.manifest!.target;
+  const statePath = opts.statePath ?? resolved.manifest?.statePath;
+
   let plan: BridgePlan;
+  let report: CarveReport;
   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}` };
+    const graph = await parseTerraformDir(opts.from, { statePath });
+    const found = boundaryReport(graph, select);
+    if (!found) return { ok: false, error: `${select} not found in ${opts.from}` };
+    report = found;
 
     // Physical identities for the carved resources, for the data sources.
     const identities = new Map<string, CarvedIdentity>();
@@ -71,8 +89,7 @@ export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridge
     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");
+  const slug = select.replace(/[^A-Za-z0-9_]+/g, "-");
   mkdirSync(outDir, { recursive: true });
   const written: string[] = [];
 
@@ -101,19 +118,66 @@ export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridge
     }
   }
 
-  return { ok: true, plan, written, appliedInPlace: opts.applyRewrites && changed.length > 0 };
+  // The whole survivor edit as one git-applyable patch: the data-source file as
+  // a new file, plus the rewired references — `cd <from> && git apply <patch>`.
+  let patchPath: string | undefined;
+  if (plan.dataSources.length || changed.length) {
+    const chunks: string[] = [];
+    if (plan.dataSources.length) {
+      chunks.push(newFileDiff(`${slug}-datasources.tf`, plan.dataSources.map((d) => d.hcl).join("\n\n") + "\n"));
+    }
+    for (const r of changed) {
+      chunks.push(unifiedDiff(relative(opts.from, r.path), r.original, r.rewritten));
+    }
+    patchPath = join(outDir, `${slug}-bridge.patch`);
+    writeFileSync(patchPath, chunks.join(""));
+    written.push(patchPath);
+  }
+
+  // Record the bridge into the manifest (create one on a standalone bridge),
+  // so `carve apply` composes with this step too.
+  const applied = Boolean(opts.applyRewrites) && changed.length > 0;
+  const manifest: CarveManifest = resolved.manifest ?? {
+    version: 1,
+    target: select,
+    from: resolve(opts.from),
+    statePath: statePath ? resolve(statePath) : undefined,
+    boundary: report,
+  };
+  manifest.boundary = report;
+  manifest.bridge = {
+    written: written.map((w) => resolve(w)),
+    appliedInPlace: applied,
+    patch: patchPath ? resolve(patchPath) : undefined,
+    excised: plan.excised.length ? plan.excised : undefined,
+    at: new Date().toISOString(),
+  };
+  const manifestPath = writeCarveManifest(outDir, manifest);
+
+  return {
+    ok: true,
+    plan,
+    written,
+    appliedInPlace: applied,
+    patchPath,
+    manifestPath,
+    selectFromManifest: !opts.select,
+  };
 }
 
 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}:`);
+  L.push(`Boundary bridge for ${p.target}${result.selectFromManifest ? " (target from the carve manifest)" : ""}:`);
   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.");
+    L.push("  no inbound edges — nothing reads the carved resource, no data source needed.");
+  }
+  if (p.excised.length) {
+    L.push(`  carved block(s) excised from the survivor source: ${p.excised.join(", ")}`);
   }
   const changed = p.rewrites.filter((r) => r.changed);
   if (changed.length) {
@@ -124,6 +188,10 @@ export function formatCarveBridge(result: CarveBridgeResult): string {
     for (const d of p.deferredInputs) L.push(`    - ${d.note}`);
   }
   L.push("");
+  if (result.patchPath && !result.appliedInPlace) {
+    L.push(`One git-applyable patch carries the whole edit: git apply --directory=<terraform-dir> ${resolve(result.patchPath)}`);
+    L.push("  (--directory is the Terraform dir relative to your repo root; plain `git apply` from the dir works outside a repo.)");
+  }
   if (result.appliedInPlace) {
     L.push("Rewritten survivor Terraform in place. Review with `git diff`, then `terraform plan`.");
   } else {

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

@@ -4,6 +4,7 @@ import { tmpdir } from "os";
 import { join } from "path";
 import { carveEmit, formatCarveEmit } from "./carve-emit";
 import { loadHcl2json } from "../../terraform/parse";
+import { readCarveManifest } from "../../terraform/manifest";
 import type { ImportResult, LiveImportOptions } from "./import";
 import type { LexiconPlugin } from "../../lexicon";
 
@@ -89,7 +90,7 @@ describe("carve emit --state (real adoption from tfstate)", () => {
       expect(liveImport).not.toHaveBeenCalled(); // offline — no cloud
 
       // A real .ts file with the native constructor + props from real state.
-      expect(res.emittedFiles).toEqual([join(out, "assets.ts")]);
+      expect(res.emittedFiles).toEqual([join(out, "src", "assets.ts")]);
       const emitted = readFileSync(res.emittedFiles![0], "utf-8");
       expect(emitted).toContain("new Bucket({");
       expect(emitted).toContain('BucketName: "myapp-assets-prod"');
@@ -98,11 +99,119 @@ describe("carve emit --state (real adoption from tfstate)", () => {
       // Boundary still classified (the Lambda inbound).
       expect(res.report!.inbound.map((e) => e.survivor)).toEqual(["aws_lambda_function.api"]);
 
+      // The carve state manifest persists boundary + selector for bridge/apply.
+      expect(res.manifestPath).toBe(join(out, "aws_s3_bucket-assets.carve.json"));
+      const manifest = readCarveManifest(res.manifestPath!)!;
+      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")]);
+      expect(manifest.boundary.inbound.map((e) => e.survivor)).toEqual(["aws_lambda_function.api"]);
+
       const text = formatCarveEmit(res);
       expect(text).toContain("Adopted from Terraform state (offline)");
+      expect(text).toContain("State manifest");
+      expect(text).toContain("Scaffolded a buildable chant project");
     });
   });
 
+  test("scaffolds a buildable chant project around the emitted source, never overwriting", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      const res = await carveEmit(
+        { from: dir, select: "aws_s3_bucket.assets", statePath: join(dir, "terraform.tfstate"), output: out },
+        { plugins: [], liveImport },
+      );
+      expect(res.ok).toBe(true);
+      expect(res.scaffolded!.map((f) => f.slice(out.length + 1)).sort()).toEqual([
+        "chant.config.ts",
+        "package.json",
+        "tsconfig.json",
+      ]);
+
+      const pkg = JSON.parse(readFileSync(join(out, "package.json"), "utf-8"));
+      expect(pkg.scripts.build).toBe("chant build src --lexicon aws");
+      expect(Object.keys(pkg.dependencies)).toEqual(["@intentius/chant", "@intentius/chant-lexicon-aws"]);
+      expect(readFileSync(join(out, "chant.config.ts"), "utf-8")).toContain('lexicons: ["aws"]');
+
+      // A second emit into the same dir leaves the scaffold (and edits) alone.
+      writeFileSync(join(out, "package.json"), '{"name":"edited"}');
+      const again = await carveEmit(
+        { from: dir, select: "aws_s3_bucket.assets", statePath: join(dir, "terraform.tfstate"), output: out },
+        { plugins: [], liveImport },
+      );
+      expect(again.ok).toBe(true);
+      expect(again.scaffolded).toEqual([]);
+      expect(readFileSync(join(out, "package.json"), "utf-8")).toBe('{"name":"edited"}');
+    });
+  });
+
+  test("deferred outbound inputs become declared build params (#998)", async () => {
+    if (!parserAvailable) return;
+    const dir = mkdtempSync(join(tmpdir(), "chant-emit-params-"));
+    try {
+      writeFileSync(
+        join(dir, "main.tf"),
+        `
+resource "aws_vpc" "main" { cidr_block = "10.0.0.0/16" }
+resource "aws_subnet" "a" {
+  vpc_id     = aws_vpc.main.id
+  cidr_block = "10.0.1.0/24"
+}
+`,
+      );
+      writeFileSync(
+        join(dir, "terraform.tfstate"),
+        JSON.stringify({
+          version: 4,
+          resources: [
+            {
+              mode: "managed",
+              type: "aws_subnet",
+              name: "a",
+              instances: [{ attributes: { id: "subnet-0aa", vpc_id: "vpc-0abc", cidr_block: "10.0.1.0/24" } }],
+            },
+            {
+              mode: "managed",
+              type: "aws_vpc",
+              name: "main",
+              instances: [{ attributes: { id: "vpc-0abc", cidr_block: "10.0.0.0/16" } }],
+            },
+          ],
+        }),
+      );
+      const out = join(dir, "carveout");
+      const res = await carveEmit(
+        { from: dir, select: "aws_subnet.a", statePath: join(dir, "terraform.tfstate"), output: out },
+        { plugins: [], liveImport },
+      );
+      expect(res.ok).toBe(true);
+
+      // The survivor-fed prop is a params reference; the rest stay literal.
+      const emitted = readFileSync(join(out, "src", "a.ts"), "utf-8");
+      expect(emitted).toContain('import { params } from "@intentius/chant/params";');
+      expect(emitted).toContain("VpcId: params.vpc_id as string,");
+      expect(emitted).toContain('CidrBlock: "10.0.1.0/24"');
+
+      // The scaffolded config declares the param, defaulted from state.
+      const config = readFileSync(join(out, "chant.config.ts"), "utf-8");
+      expect(config).toContain("buildParams: {");
+      expect(config).toContain("vpc_id: {");
+      expect(config).toContain('default: "vpc-0abc",');
+      expect(config).toContain("was aws_vpc.main.id in Terraform");
+
+      // Recorded in the manifest, reported in the summary.
+      const manifest = readCarveManifest(res.manifestPath!)!;
+      expect(manifest.emit!.params).toEqual({
+        vpc_id: { tfAttr: "vpc_id", survivor: "aws_vpc.main", attrs: ["id"], default: "vpc-0abc" },
+      });
+      expect(formatCarveEmit(res)).toContain("vpc_id — was aws_vpc.main.id");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   test("without --state or --env it explains both adoption sources", async () => {
     if (!parserAvailable) return;
     await withEstate(async (dir) => {

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

@@ -13,12 +13,14 @@
  */
 
 import { existsSync, statSync, writeFileSync, mkdirSync } from "fs";
-import { join } from "path";
+import { basename, join, resolve } from "path";
 import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
-import { boundaryReport, type CarveReport } from "../../terraform/carve";
+import { boundaryReport, deferredParamName, type CarveReport } from "../../terraform/carve";
 import { resolveTier } from "../../terraform/tier-map";
 import { readStateResource } from "../../terraform/state";
-import { adoptFromState, canAdoptFromState, supportedStateAdoptionTypes } from "../../terraform/adopt-state";
+import { writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
+import { adoptFromState, canAdoptFromState, supportedStateAdoptionTypes, type DeferredParam } from "../../terraform/adopt-state";
+import { getChantVersion } from "./init";
 import type { LexiconPlugin, ResourceSelector } from "../../lexicon";
 import type { ImportResult, LiveImportOptions } from "./import";
 
@@ -61,6 +63,12 @@ export interface CarveEmitResult {
   source?: "tfstate" | "live";
   /** Emitted file path(s). */
   emittedFiles?: string[];
+  /** Project files scaffolded around the emitted source (config, package.json). */
+  scaffolded?: string[];
+  /** Deferred outbound inputs declared as build parameters in the emitted project (#998). */
+  params?: DeferredParam[];
+  /** The persisted carve state manifest bridge/apply compose with. */
+  manifestPath?: string;
 }
 
 export async function carveEmit(opts: CarveEmitOptions, deps: CarveEmitDeps): Promise<CarveEmitResult> {
@@ -113,15 +121,25 @@ export async function carveEmit(opts: CarveEmitOptions, deps: CarveEmitDeps): Pr
     if (!stateResource) {
       return { ok: false, error: `${opts.select} not found in state ${opts.statePath} (or is a data source / module-nested).` };
     }
-    const adopted = adoptFromState(stateResource);
+    // Deferred outbound inputs → real build parameters (#998): each survivor
+    // value the carved block read enters the emitted project as a declared
+    // param, defaulted to the value the state resolved.
+    const params = deferredParams(report, stateResource.attributes);
+    const adopted = adoptFromState(stateResource, params);
     if (!adopted) return { ok: false, error: `Could not adopt ${opts.select} from state.` };
 
+    // The output dir is a buildable chant project: source in src/, plus the
+    // config + package.json scaffold (written once, never overwritten).
     const outDir = opts.output ?? join(opts.from, "carveout");
-    mkdirSync(outDir, { recursive: true });
-    const outPath = join(outDir, adopted.fileName);
+    const srcDir = join(outDir, "src");
+    mkdirSync(srcDir, { recursive: true });
+    const outPath = join(srcDir, adopted.fileName);
     writeFileSync(outPath, adopted.content);
+    const lexicon = tier.mapsTo.split("::")[0]?.toLowerCase() ?? "aws";
+    const scaffolded = scaffoldProject(outDir, lexicon, params);
 
-    return { ok: true, report, source: "tfstate", emittedFiles: [outPath] };
+    const manifestPath = persistManifest(outDir, opts, report, tfType, "tfstate", [outPath], params);
+    return { ok: true, report, source: "tfstate", emittedFiles: [outPath], scaffolded, manifestPath, params };
   }
 
   // ── Adoption path 2: live import (cloud→code) ──
@@ -140,7 +158,152 @@ export async function carveEmit(opts: CarveEmitOptions, deps: CarveEmitDeps): Pr
     lexicon: tier.mapsTo.split("::")[0]?.toLowerCase() === "aws" ? "aws" : undefined,
   });
 
-  return { ok: true, report, emit, selector, source: "live", emittedFiles: emit.generatedFiles };
+  const outDir = opts.output ?? join(opts.from, "carveout");
+  const manifestPath = persistManifest(outDir, opts, report, tfType, "live", emit.generatedFiles ?? []);
+  return { ok: true, report, emit, selector, source: "live", emittedFiles: emit.generatedFiles, manifestPath };
+}
+
+/**
+ * Turn the boundary report's outbound edges into build parameters (#998): one
+ * per carved-block attribute that read a survivor (`via`), named after that
+ * attribute, defaulted to the value the state resolved for it. A non-scalar
+ * value (a nested block) is declared without a default (`required: false`) —
+ * it documents the deferred input without blocking an out-of-the-box build.
+ */
+function deferredParams(report: CarveReport, attributes: Record<string, unknown>): DeferredParam[] {
+  const byName = new Map<string, DeferredParam>();
+  for (const edge of report.outbound) {
+    for (const tfAttr of edge.via ?? []) {
+      const name = deferredParamName(tfAttr);
+      const raw = attributes[tfAttr];
+      const scalar = typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean" ? raw : undefined;
+      const prev = byName.get(name);
+      byName.set(name, {
+        name,
+        tfAttr,
+        survivor: prev && prev.survivor !== edge.survivor ? `${prev.survivor}, ${edge.survivor}` : edge.survivor,
+        attrs: [...new Set([...(prev?.attrs ?? []), ...edge.attrs])].sort(),
+        default: scalar,
+      });
+    }
+  }
+  return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/**
+ * Scaffold the emitted source into a buildable chant project: chant.config.ts,
+ * package.json, tsconfig.json — same shape `chant init` produces, so
+ * `npm install && npm run build` works in the output dir as-is. Existing files
+ * are never overwritten (re-emits and user edits survive). Deferred inputs are
+ * declared as `buildParams` (#998), defaults taken from the state's resolved
+ * values, so the first build reproduces what is live while every survivor-fed
+ * value stays overridable (`--param <name>=<value>`).
+ */
+function scaffoldProject(outDir: string, lexicon: string, params: DeferredParam[] = []): string[] {
+  const ver = getChantVersion();
+  const packageJson = {
+    name: "chant-carveout",
+    version: "0.1.0",
+    type: "module" as const,
+    scripts: {
+      build: `chant build src --lexicon ${lexicon}`,
+      lint: "chant lint src",
+    },
+    dependencies: {
+      "@intentius/chant": `^${ver}`,
+      [`@intentius/chant-lexicon-${lexicon}`]: `^${ver}`,
+    },
+    devDependencies: {
+      typescript: "^5.0.0",
+    },
+  };
+  const tsconfig = {
+    compilerOptions: {
+      target: "ES2022",
+      module: "NodeNext",
+      moduleResolution: "NodeNext",
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+    },
+    include: ["src"],
+    exclude: ["node_modules"],
+  };
+  const files: Array<[string, string]> = [
+    ["package.json", JSON.stringify(packageJson, null, 2) + "\n"],
+    ["chant.config.ts", renderConfig(lexicon, params)],
+    ["tsconfig.json", JSON.stringify(tsconfig, null, 2) + "\n"],
+  ];
+
+  const written: string[] = [];
+  for (const [name, content] of files) {
+    const path = join(outDir, name);
+    if (existsSync(path)) continue;
+    writeFileSync(path, content);
+    written.push(path);
+  }
+  return written;
+}
+
+/** Render the scaffolded `chant.config.ts`, declaring deferred inputs as `buildParams` (#998). */
+function renderConfig(lexicon: string, params: DeferredParam[]): string {
+  const L: string[] = [];
+  L.push(`import type { ChantConfig } from "@intentius/chant";`);
+  L.push("");
+  L.push("export default {");
+  L.push(`  lexicons: ["${lexicon}"],`);
+  if (params.length) {
+    L.push("  // Deferred deploy-time inputs — values the Terraform source read from");
+    L.push("  // surviving resources. Defaults are the values the tfstate resolved;");
+    L.push("  // override per build with --param <name>=<value>.");
+    L.push("  buildParams: {");
+    for (const p of params) {
+      const type = typeof p.default === "number" ? "number" : typeof p.default === "boolean" ? "boolean" : "string";
+      L.push(`    ${p.name}: {`);
+      L.push(`      type: ${JSON.stringify(type)},`);
+      if (p.default !== undefined) {
+        L.push(`      default: ${JSON.stringify(p.default)},`);
+      } else {
+        L.push(`      required: false,`);
+      }
+      L.push(`      description: ${JSON.stringify(`was ${p.survivor}.${p.attrs.join("/")} in Terraform (deferred deploy-time input)`)},`);
+      L.push("    },");
+    }
+    L.push("  },");
+  }
+  L.push("} satisfies ChantConfig;");
+  return L.join("\n") + "\n";
+}
+
+/** Persist the carve state manifest so bridge/apply compose with this emit. */
+function persistManifest(
+  outDir: string,
+  opts: CarveEmitOptions,
+  report: CarveReport,
+  tfType: string | undefined,
+  source: "tfstate" | "live",
+  files: string[],
+  params: DeferredParam[] = [],
+): string {
+  const manifest: CarveManifest = {
+    version: 1,
+    target: report.target,
+    tfType,
+    from: resolve(opts.from!),
+    statePath: opts.statePath ? resolve(opts.statePath) : undefined,
+    boundary: report,
+    emit: {
+      source,
+      files: files.map((f) => resolve(f)),
+      params: params.length
+        ? Object.fromEntries(
+            params.map((p) => [p.name, { tfAttr: p.tfAttr, survivor: p.survivor, attrs: p.attrs, default: p.default }]),
+          )
+        : undefined,
+      at: new Date().toISOString(),
+    },
+  };
+  return writeCarveManifest(outDir, manifest);
 }
 
 /** Human-readable emit summary: what was adopted and what boundary work remains. */
@@ -158,6 +321,19 @@ export function formatCarveEmit(result: CarveEmitResult): string {
   if (result.emittedFiles?.length) {
     lines.push(`  Emitted: ${result.emittedFiles.join(", ")}`);
   }
+  if (result.scaffolded?.length) {
+    lines.push(`  Scaffolded a buildable chant project: ${result.scaffolded.map((f) => basename(f)).join(", ")} (npm install && npm run build).`);
+  }
+  if (result.params?.length) {
+    lines.push(`  Deferred input(s) declared as build params (override with --param <name>=<value>):`);
+    for (const p of result.params) {
+      const def = p.default !== undefined ? `default ${JSON.stringify(p.default)} from state` : "no default (required: false)";
+      lines.push(`    ${p.name} — was ${p.survivor}.${p.attrs.join("/")}; ${def}`);
+    }
+  }
+  if (result.manifestPath) {
+    lines.push(`  State manifest: ${result.manifestPath} — carve bridge/apply pick the target up from here.`);
+  }
   if (r.carveSet.length > 1) {
     const folded = r.carveSet.filter((m) => m.foldedInto).map((m) => m.address);
     lines.push(`  Folded in: ${folded.join(", ")}`);

package/src/cli/commands/init.ts

@@ -7,7 +7,7 @@ import { formatSuccess, formatWarning } from "../format";
 import { loadPlugin } from "../plugins";
 
 /** Read the current chant package version from our own package.json. */
-function getChantVersion(): string {
+export function getChantVersion(): string {
   try {
     const pkgDir = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))));
     const pkg = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf-8"));

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

@@ -19,6 +19,7 @@ export async function runCarveApply(ctx: CommandContext): Promise<number> {
     statePath: args.statePath,
     output: args.output,
     write: args.write,
+    writeSource: args.writeSource,
   });
 
   if (!result.ok) {