@intentius/chant 0.41.20 → 0.42.1

package/src/__snapshots__/okf.test.ts.snap

@@ -0,0 +1,381 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`buildOkfBundle over shipped examples > aws lambda-s3 emits a conformant, snapshot-stable bundle 1`] = `
+[
+  {
+    "content": "---
+type: AWS::S3::Bucket
+title: appBucket
+description: aws resource of type AWS::S3::Bucket
+name: appBucket
+lexicon: aws
+kind: resource
+source: main.ts
+composite: LambdaS3
+composite_instance: app
+---
+Declared in \`main.ts\`.
+
+## Referenced by
+
+- [appFunc](/aws/appFunc.md)
+- [appRole](/aws/appRole.md)
+",
+    "path": "aws/appBucket.md",
+  },
+  {
+    "content": "---
+type: AWS::Lambda::Function
+title: appFunc
+description: aws resource of type AWS::Lambda::Function
+name: appFunc
+lexicon: aws
+kind: resource
+source: main.ts
+composite: LambdaS3
+composite_instance: app
+---
+Declared in \`main.ts\`.
+
+## Depends on
+
+- [appBucket](/aws/appBucket.md)
+- [appRole](/aws/appRole.md)
+",
+    "path": "aws/appFunc.md",
+  },
+  {
+    "content": "---
+type: AWS::IAM::Role
+title: appRole
+description: aws resource of type AWS::IAM::Role
+name: appRole
+lexicon: aws
+kind: resource
+source: main.ts
+composite: LambdaS3
+composite_instance: app
+---
+Declared in \`main.ts\`.
+
+## Depends on
+
+- [appBucket](/aws/appBucket.md)
+
+## Referenced by
+
+- [appFunc](/aws/appFunc.md)
+",
+    "path": "aws/appRole.md",
+  },
+  {
+    "content": "---
+type: Output
+title: bucketArn
+description: aws output of type Output
+name: bucketArn
+lexicon: aws
+kind: output
+source: outputs.ts
+---
+Declared in \`outputs.ts\`.
+",
+    "path": "aws/bucketArn.md",
+  },
+  {
+    "content": "---
+type: AWS::CloudFormation::Parameter
+title: environment
+description: aws resource of type AWS::CloudFormation::Parameter
+name: environment
+lexicon: aws
+kind: resource
+source: params.ts
+---
+Declared in \`params.ts\`.
+",
+    "path": "aws/environment.md",
+  },
+  {
+    "content": "---
+type: chant:aws:defaultTags
+title: tags
+description: aws resource of type chant:aws:defaultTags
+name: tags
+lexicon: aws
+kind: resource
+source: tags.ts
+---
+Declared in \`tags.ts\`.
+",
+    "path": "aws/tags.md",
+  },
+  {
+    "content": "---
+okf_version: '0.2'
+---
+
+# Lexicon: aws
+
+* [appBucket](/aws/appBucket.md) - aws resource of type AWS::S3::Bucket
+* [appFunc](/aws/appFunc.md) - aws resource of type AWS::Lambda::Function
+* [appRole](/aws/appRole.md) - aws resource of type AWS::IAM::Role
+* [bucketArn](/aws/bucketArn.md) - aws output of type Output
+* [environment](/aws/environment.md) - aws resource of type AWS::CloudFormation::Parameter
+* [tags](/aws/tags.md) - aws resource of type chant:aws:defaultTags
+",
+    "path": "index.md",
+  },
+]
+`;
+
+exports[`buildOkfBundle over shipped examples > gitlab node-pipeline emits a conformant, snapshot-stable bundle 1`] = `
+[
+  {
+    "content": "---
+type: GitLab::CI::Job
+title: appBuild
+description: gitlab resource of type GitLab::CI::Job
+name: appBuild
+lexicon: gitlab
+kind: resource
+source: pipeline.ts
+composite: NodePipeline
+composite_instance: app
+---
+Declared in \`pipeline.ts\`.
+",
+    "path": "gitlab/appBuild.md",
+  },
+  {
+    "content": "---
+type: GitLab::CI::Default
+title: appDefaults
+description: gitlab resource of type GitLab::CI::Default
+name: appDefaults
+lexicon: gitlab
+kind: resource
+source: pipeline.ts
+composite: NodePipeline
+composite_instance: app
+---
+Declared in \`pipeline.ts\`.
+",
+    "path": "gitlab/appDefaults.md",
+  },
+  {
+    "content": "---
+type: GitLab::CI::Job
+title: appTest
+description: gitlab resource of type GitLab::CI::Job
+name: appTest
+lexicon: gitlab
+kind: resource
+source: pipeline.ts
+composite: NodePipeline
+composite_instance: app
+---
+Declared in \`pipeline.ts\`.
+",
+    "path": "gitlab/appTest.md",
+  },
+  {
+    "content": "---
+okf_version: '0.2'
+---
+
+# Lexicon: gitlab
+
+* [appBuild](/gitlab/appBuild.md) - gitlab resource of type GitLab::CI::Job
+* [appDefaults](/gitlab/appDefaults.md) - gitlab resource of type GitLab::CI::Default
+* [appTest](/gitlab/appTest.md) - gitlab resource of type GitLab::CI::Job
+",
+    "path": "index.md",
+  },
+]
+`;
+
+exports[`buildOkfBundle over shipped examples > k8s layered-config emits a conformant, snapshot-stable bundle 1`] = `
+[
+  {
+    "content": "---
+okf_version: '0.2'
+---
+
+# Lexicon: k8s
+
+* [devAppDeployment](/k8s/devAppDeployment.md) - k8s resource of type K8s::Apps::Deployment
+* [devAppService](/k8s/devAppService.md) - k8s resource of type K8s::Core::Service
+* [prodAppDeployment](/k8s/prodAppDeployment.md) - k8s resource of type K8s::Apps::Deployment
+* [prodAppIngress](/k8s/prodAppIngress.md) - k8s resource of type K8s::Networking::Ingress
+* [prodAppPdb](/k8s/prodAppPdb.md) - k8s resource of type K8s::Policy::PodDisruptionBudget
+* [prodAppService](/k8s/prodAppService.md) - k8s resource of type K8s::Core::Service
+* [stagingAppDeployment](/k8s/stagingAppDeployment.md) - k8s resource of type K8s::Apps::Deployment
+* [stagingAppIngress](/k8s/stagingAppIngress.md) - k8s resource of type K8s::Networking::Ingress
+* [stagingAppPdb](/k8s/stagingAppPdb.md) - k8s resource of type K8s::Policy::PodDisruptionBudget
+* [stagingAppService](/k8s/stagingAppService.md) - k8s resource of type K8s::Core::Service
+",
+    "path": "index.md",
+  },
+  {
+    "content": "---
+type: K8s::Apps::Deployment
+title: devAppDeployment
+description: k8s resource of type K8s::Apps::Deployment
+name: devAppDeployment
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: devApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/devAppDeployment.md",
+  },
+  {
+    "content": "---
+type: K8s::Core::Service
+title: devAppService
+description: k8s resource of type K8s::Core::Service
+name: devAppService
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: devApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/devAppService.md",
+  },
+  {
+    "content": "---
+type: K8s::Apps::Deployment
+title: prodAppDeployment
+description: k8s resource of type K8s::Apps::Deployment
+name: prodAppDeployment
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: prodApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/prodAppDeployment.md",
+  },
+  {
+    "content": "---
+type: K8s::Networking::Ingress
+title: prodAppIngress
+description: k8s resource of type K8s::Networking::Ingress
+name: prodAppIngress
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: prodApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/prodAppIngress.md",
+  },
+  {
+    "content": "---
+type: K8s::Policy::PodDisruptionBudget
+title: prodAppPdb
+description: k8s resource of type K8s::Policy::PodDisruptionBudget
+name: prodAppPdb
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: prodApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/prodAppPdb.md",
+  },
+  {
+    "content": "---
+type: K8s::Core::Service
+title: prodAppService
+description: k8s resource of type K8s::Core::Service
+name: prodAppService
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: prodApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/prodAppService.md",
+  },
+  {
+    "content": "---
+type: K8s::Apps::Deployment
+title: stagingAppDeployment
+description: k8s resource of type K8s::Apps::Deployment
+name: stagingAppDeployment
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: stagingApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/stagingAppDeployment.md",
+  },
+  {
+    "content": "---
+type: K8s::Networking::Ingress
+title: stagingAppIngress
+description: k8s resource of type K8s::Networking::Ingress
+name: stagingAppIngress
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: stagingApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/stagingAppIngress.md",
+  },
+  {
+    "content": "---
+type: K8s::Policy::PodDisruptionBudget
+title: stagingAppPdb
+description: k8s resource of type K8s::Policy::PodDisruptionBudget
+name: stagingAppPdb
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: stagingApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/stagingAppPdb.md",
+  },
+  {
+    "content": "---
+type: K8s::Core::Service
+title: stagingAppService
+description: k8s resource of type K8s::Core::Service
+name: stagingAppService
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: stagingApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/stagingAppService.md",
+  },
+]
+`;

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

@@ -4,6 +4,7 @@ import { tmpdir } from "os";
 import { join } from "path";
 import { carveApply, formatCarveApply } from "./carve-apply";
 import { loadHcl2json } from "../../terraform/parse";
+import { readCarveManifest, writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
 
 let parserAvailable = false;
 try {
@@ -30,10 +31,101 @@ 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("carveApply", () => {
-  test("requires --from and --select", async () => {
+  test("requires --from; without --select it needs a carve manifest", async () => {
     expect((await carveApply({})).error).toContain("--from");
-    expect((await carveApply({ from: "/x" })).error).toContain("--select");
+    await withEstate(async (dir) => {
+      const res = await carveApply({ from: dir });
+      expect(res.ok).toBe(false);
+      expect(res.error).toContain("--select");
+    });
+  });
+
+  test("composes with the carve manifest: target resolved without --select, graduation 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 carveApply({ from: dir, output: out, env: "prod", stack: "assets" });
+      expect(res.ok).toBe(true);
+      expect(res.selectFromManifest).toBe(true);
+      expect(formatCarveApply(res)).toContain("target from the carve manifest");
+
+      const m = readCarveManifest(res.manifestPath!)!;
+      expect(m.apply!.marker).toEqual({ stack: "assets", env: "prod" });
+      expect(m.apply!.ownershipTags["chant:managed-by"]).toBe("chant");
+    });
+  });
+
+  test("--write-source stamps the ownership marker into the emitted source and records it", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      const emitted = join(out, "assets.ts");
+      const manifest = manifestFor("aws_s3_bucket.assets", dir);
+      manifest.emit = { source: "tfstate", files: [emitted], at: "t" };
+      writeCarveManifest(out, manifest);
+      writeFileSync(emitted, 'export const assets = new Bucket({\n  BucketName: "myapp-assets-prod",\n});\n');
+
+      const res = await carveApply({ from: dir, output: out, env: "prod", stack: "assets", writeSource: true });
+      expect(res.ok).toBe(true);
+      expect(res.stamped).toEqual([emitted]);
+
+      const stamped = readFileSync(emitted, "utf-8");
+      expect(stamped).toContain('{"Key":"chant:managed-by","Value":"chant"}');
+      expect(stamped).toContain('{"Key":"chant:stack","Value":"assets"}');
+      expect(stamped).toContain('{"Key":"chant:env","Value":"prod"}');
+
+      const m = readCarveManifest(res.manifestPath!)!;
+      expect(m.apply!.stampedFiles).toEqual([emitted]);
+      expect(formatCarveApply(res)).toContain("Stamped the ownership marker into");
+
+      // Idempotent: a second graduation leaves the source stable.
+      const again = await carveApply({ from: dir, output: out, env: "prod", stack: "assets", writeSource: true });
+      expect(again.ok).toBe(true);
+      expect(readFileSync(emitted, "utf-8")).toBe(stamped);
+    });
+  });
+
+  test("--write-source without an emit record in the manifest is a clear error", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      writeCarveManifest(out, manifestFor("aws_s3_bucket.assets", dir));
+      const res = await carveApply({ from: dir, output: out, env: "prod", writeSource: true });
+      expect(res.ok).toBe(false);
+      expect(res.error).toContain("carve emit");
+    });
+  });
+
+  test("falls back to the manifest's persisted boundary when the block is already excised", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      writeCarveManifest(out, manifestFor("aws_s3_bucket.gone", dir));
+
+      const res = await carveApply({ from: dir, output: out, env: "prod" });
+      expect(res.ok).toBe(true);
+      expect(res.plan!.target).toBe("aws_s3_bucket.gone");
+    });
   });
 
   test("plans graduation with ownership marker; writes nothing by default", async () => {

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

@@ -9,14 +9,16 @@
  * lifecycle you brought.
  */
 
-import { existsSync, statSync, mkdirSync, writeFileSync } from "fs";
+import { existsSync, statSync, mkdirSync, readFileSync, 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";
+import { graduationPlan, stampOwnershipIntoSource, type GraduationPlan } from "../../terraform/graduate";
+import { resolveCarveManifest, updateCarveManifest } from "../../terraform/manifest";
 
 export interface CarveApplyOptions {
   from?: string;
+  /** Optional when the output dir holds a single carve manifest from `carve emit`. */
   select?: string;
   env?: string;
   stack?: string;
@@ -24,6 +26,8 @@ export interface CarveApplyOptions {
   output?: string;
   /** Write the graduation doc to the output dir. */
   write?: boolean;
+  /** Stamp the ownership marker into the emitted chant source. */
+  writeSource?: boolean;
 }
 
 export interface CarveApplyResult {
@@ -31,36 +35,77 @@ export interface CarveApplyResult {
   error?: string;
   plan?: GraduationPlan;
   written?: string;
+  /** Emitted source files the ownership marker was stamped into. */
+  stamped?: string[];
+  /** The carve state manifest this graduation was recorded into. */
+  manifestPath?: string;
+  /** True when the target came from the manifest, not --select. */
+  selectFromManifest?: boolean;
 }
 
 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}` };
   }
 
+  // Compose with the manifest emit/bridge persisted: it supplies the target
+  // (and tfstate) when --select is absent, and its persisted boundary stands in
+  // when the carved block is already excised from the estate.
+  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: 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}` };
+    const graph = await parseTerraformDir(opts.from, { statePath });
+    const report = boundaryReport(graph, select) ?? resolved.manifest?.boundary ?? null;
+    if (!report) return { ok: false, error: `${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)}` };
   }
 
+  // Stamp the marker into the emitted source (`--write-source`) — the emitted
+  // files are known from the manifest, so the tags the plan promises are the
+  // tags the source actually carries into the apply.
+  let stamped: string[] | undefined;
+  if (opts.writeSource) {
+    const files = resolved.manifest?.emit?.files ?? [];
+    if (files.length === 0) {
+      return {
+        ok: false,
+        error: "--write-source needs the emitted source recorded in the carve manifest — run `chant carve emit` first.",
+      };
+    }
+    stamped = [];
+    for (const file of files) {
+      if (!existsSync(file)) return { ok: false, error: `Emitted source not found: ${file}` };
+      const result = stampOwnershipIntoSource(readFileSync(file, "utf-8"), plan.ownershipTags);
+      if (!result) return { ok: false, error: `No constructor to stamp in ${file}.` };
+      if (result.changed) writeFileSync(file, result.content);
+      stamped.push(file);
+    }
+  }
+
   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, "-");
+    const slug = select.replace(/[^A-Za-z0-9_]+/g, "-");
     written = join(outDir, `${slug}-graduation.md`);
     writeFileSync(written, renderGraduationDoc(plan) + "\n");
   }
 
-  return { ok: true, plan, written };
+  // Record the graduation into an existing manifest; never create one here —
+  // plan-only stays plan-only unless a carve flow is already in progress.
+  const manifestPath = updateCarveManifest(outDir, select, {
+    apply: { marker: plan.marker, ownershipTags: plan.ownershipTags, stampedFiles: stamped, at: new Date().toISOString() },
+  });
+
+  return { ok: true, plan, written, stamped, manifestPath, selectFromManifest: !opts.select };
 }
 
 function renderGraduationDoc(plan: GraduationPlan): string {
@@ -86,7 +131,7 @@ 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(`Apply graduation for ${p.target} (dial-turn: observe → apply)${result.selectFromManifest ? " — target from the carve manifest" : ""}.`);
   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}`);
@@ -97,10 +142,16 @@ export function formatCarveApply(result: CarveApplyResult): string {
     for (const w of p.warnings) L.push(`  ! ${w}`);
   }
   L.push("");
+  if (result.stamped?.length) {
+    L.push(`Stamped the ownership marker into: ${result.stamped.join(", ")}`);
+  }
   if (result.written) {
     L.push(`Wrote graduation doc: ${result.written}`);
-  } else {
+  } else if (!result.stamped?.length) {
     L.push("Plan only — no cloud call, nothing written. The apply is your lifecycle (BYOL). Add --write to save this as a doc.");
   }
+  if (result.manifestPath) {
+    L.push(`Recorded in the carve manifest: ${result.manifestPath}`);
+  }
   return L.join("\n");
 }