@intentius/chant 0.124.13 → 0.124.14

package/dist/cli/commands/carve-apply.js

@@ -0,0 +1,153 @@
+/**
+ * `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, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { cdkNotSupported, isCloudAssembly } from "../../cdk/assembly.js";
+import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse.js";
+import { boundaryReport } from "../../terraform/carve.js";
+import { graduationPlan, stampOwnershipIntoSource } from "../../terraform/graduate.js";
+import { resolveCarveManifest, resolveManifestFilePath, updateCarveManifest } from "../../terraform/manifest.js";
+import { resolveEmitProvider } from "../../terraform/carve-provider.js";
+export async function carveApply(opts) {
+    if (!opts.from)
+        return { ok: false, error: "chant carve apply requires --from <terraform-dir>" };
+    if (!existsSync(opts.from) || !statSync(opts.from).isDirectory()) {
+        return { ok: false, error: `Not a directory: ${opts.from}` };
+    }
+    if (isCloudAssembly(opts.from))
+        return { ok: false, error: cdkNotSupported(opts.from, "apply") };
+    // 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;
+    try {
+        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}` };
+        // The carved type decides what the apply step even looks like: a
+        // CloudFormation deploy for aws, a cluster apply for k8s (#999). The
+        // manifest records the type; the graph has it when there is no manifest.
+        const tfType = resolved.manifest?.tfType ?? graph.nodes.find((n) => n.address === select)?.type;
+        const lexicon = tfType ? resolveEmitProvider(tfType)?.lexicon : undefined;
+        plan = graduationPlan(report, { stack: opts.stack, env: opts.env, lexicon });
+    }
+    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;
+    if (opts.writeSource) {
+        // 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,
+                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}. Tag-based ownership is a property of a native constructor call; ` +
+                        `on a Kubernetes object the marker is a label the k8s build merges in (defaultLabels), not a tag in the ` +
+                        `emitted source. Re-run without --write-source to get the marker and the graduation plan.`,
+                };
+            }
+            if (result.changed)
+                writeFileSync(file, result.content);
+            stamped.push(file);
+        }
+    }
+    let written;
+    if (opts.write) {
+        mkdirSync(outDir, { recursive: true });
+        const slug = select.replace(/[^A-Za-z0-9_]+/g, "-");
+        written = join(outDir, `${slug}-graduation.md`);
+        writeFileSync(written, renderGraduationDoc(plan) + "\n");
+    }
+    // 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) {
+    const L = [];
+    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 ${plan.markerKind} (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) {
+    if (!result.ok || !result.plan)
+        return result.error ?? "carve apply failed";
+    const p = result.plan;
+    const L = [];
+    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 ${p.markerKind} (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.stamped?.length) {
+        L.push(`Stamped the ownership marker into: ${result.stamped.join(", ")}`);
+    }
+    if (result.written) {
+        L.push(`Wrote graduation doc: ${result.written}`);
+    }
+    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");
+}

package/dist/cli/commands/carve-bridge.js

@@ -0,0 +1,201 @@
+/**
+ * `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, relative, resolve } from "path";
+import { cdkNotSupported, isCloudAssembly } from "../../cdk/assembly.js";
+import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse.js";
+import { boundaryReport } from "../../terraform/carve.js";
+import { generateBridge } from "../../terraform/bridge.js";
+import { identityAttrOf, canBridge, dataSourceShapeOf } from "../../terraform/tier-map.js";
+import { resolveCarveManifest, writeCarveManifest } from "../../terraform/manifest.js";
+import { newFileDiff, unifiedDiff } from "../../terraform/unified-diff.js";
+function listTfFiles(dir) {
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".tf"))
+        .map((f) => join(dir, f))
+        .sort();
+}
+export async function carveBridge(opts) {
+    if (!opts.from)
+        return { ok: false, error: "chant carve bridge requires --from <terraform-dir>" };
+    if (!existsSync(opts.from) || !statSync(opts.from).isDirectory()) {
+        return { ok: false, error: `Not a directory: ${opts.from}` };
+    }
+    if (isCloudAssembly(opts.from))
+        return { ok: false, error: cdkNotSupported(opts.from, "bridge") };
+    // 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;
+    let report;
+    try {
+        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;
+        // Refuse a carve set no provider says how to read back. A dotted identity
+        // attribute is a path into nested values and a data body is flat
+        // `attr = value`, so such a type bridges only once its provider declares a
+        // data-source shape — the data type, its arguments and where each comes
+        // from in the carved body (#2034). `kubernetes_manifest` declares one now:
+        // `data "kubernetes_resource"`, built from the manifest's apiVersion,
+        // kind and metadata.
+        const carvedTypes = report.carveSet.map((m) => m.type).filter((t) => t !== undefined);
+        const unbridgeable = [...new Set(carvedTypes.filter((t) => !canBridge(t)))];
+        if (unbridgeable.length) {
+            return {
+                ok: false,
+                error: `${select} cannot be bridged: ${unbridgeable
+                    .map((t) => `${t} identifies itself by \`${identityAttrOf(t)}\``)
+                    .join(", ")}, a path into nested values that a flat Terraform data source body cannot express, ` +
+                    `and no carve provider declares a data-source shape for it. A provider contributes one through ` +
+                    `\`dataSourceShapes\` (see \`kubernetes_manifest\` reading back as \`data "kubernetes_resource"\`, chant issue #2034).`,
+            };
+        }
+        // How each carved resource is read back, and the literals to render the
+        // data-source body from. The shape comes from the provider, the values from
+        // the parsed block (`dataSourceValues`, a superset of the old identity).
+        const readBacks = new Map();
+        for (const node of graph.nodes) {
+            if (!node.type)
+                continue;
+            const shape = dataSourceShapeOf(node.type);
+            if (!shape)
+                continue;
+            readBacks.set(node.address, { shape, values: node.dataSourceValues ?? {} });
+        }
+        const files = listTfFiles(opts.from).map((path) => ({ path, content: readFileSync(path, "utf-8") }));
+        plan = generateBridge(report, files, readBacks);
+    }
+    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 = select.replace(/[^A-Za-z0-9_]+/g, "-");
+    mkdirSync(outDir, { recursive: true });
+    const written = [];
+    // 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);
+        }
+    }
+    // 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;
+    if (plan.dataSources.length || changed.length) {
+        const chunks = [];
+        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 = 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) {
+    if (!result.ok || !result.plan)
+        return result.error ?? "carve bridge failed";
+    const p = result.plan;
+    const L = [];
+    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 — 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) {
+        L.push(`  ${changed.length} survivor file(s) rewired: ${changed.map((r) => basename(r.path)).join(", ")}`);
+    }
+    if (p.outputRewrites.length) {
+        L.push(`  ${p.outputRewrites.length} output block(s) repointed at the data source: ${p.outputRewrites.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.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 {
+        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");
+}