@intentius/chant 0.41.19 → 0.42.1

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/import.ts

@@ -241,20 +241,68 @@ export async function importCommand(options: ImportOptions): Promise<ImportResul
 
   const lexicon = plugin.name;
 
+  return parseAndWrite(plugin, content, outputDir, options.force, warnings, generatedFiles, lexicon);
+}
+
+/**
+ * Import from an in-memory template string through a KNOWN plugin — no
+ * detection, no JSON assumption (#1548). This is the seam
+ * `chant import --kustomize <dir>` drives with `kustomize build` output
+ * through the k8s plugin's YAML parser; `importCommand` above is the same
+ * pipeline behind file reading + JSON detection.
+ */
+export interface ContentImportOptions {
+  /** The raw template content (YAML or JSON — the plugin's parser decides). */
+  content: string;
+  /** The lexicon whose parser/generator handle it, e.g. "k8s". */
+  lexicon: string;
+  output?: string;
+  force?: boolean;
+}
+
+export async function importFromContent(options: ContentImportOptions): Promise<ImportResult> {
+  const outputDir = resolve(options.output ?? "./infra/");
+  let plugins: LexiconPlugin[];
+  try {
+    plugins = await loadPlugins([options.lexicon]);
+  } catch (err) {
+    return {
+      success: false,
+      generatedFiles: [],
+      warnings: [],
+      error: `Could not load lexicon "${options.lexicon}": ${err}`,
+    };
+  }
+  const plugin = plugins[0];
+  if (!plugin) {
+    return { success: false, generatedFiles: [], warnings: [], error: `Lexicon "${options.lexicon}" not available.` };
+  }
   if (!plugin.templateParser || !plugin.templateGenerator) {
     return {
       success: false,
       generatedFiles: [],
       warnings: [],
       error: `Lexicon "${plugin.name}" does not support template import.`,
-      lexicon,
+      lexicon: plugin.name,
     };
   }
+  return parseAndWrite(plugin, options.content, outputDir, options.force, [], [], plugin.name);
+}
 
+/** The shared tail of every template import: parse → generate → write. */
+function parseAndWrite(
+  plugin: LexiconPlugin,
+  content: string,
+  outputDir: string,
+  force: boolean | undefined,
+  warnings: string[],
+  generatedFiles: string[],
+  lexicon: string,
+): ImportResult {
   // Parse template
   let ir: TemplateIR;
   try {
-    const parser = plugin.templateParser();
+    const parser = plugin.templateParser!();
     ir = parser.parse(content);
   } catch (err) {
     return {
@@ -265,10 +313,10 @@ export async function importCommand(options: ImportOptions): Promise<ImportResul
     };
   }
 
-  const generator = plugin.templateGenerator();
+  const generator = plugin.templateGenerator!();
 
   // Check output directory
-  if (existsSync(outputDir) && !options.force) {
+  if (existsSync(outputDir) && !force) {
     const files = readdirSync(outputDir);
     if (files.length > 0) {
       warnings.push(`Output directory ${outputDir} is not empty. Use --force to overwrite.`);
@@ -293,7 +341,7 @@ export async function importCommand(options: ImportOptions): Promise<ImportResul
     }
 
     // Check for existing file
-    if (existsSync(filePath) && !options.force) {
+    if (existsSync(filePath) && !force) {
       warnings.push(`File ${file.path} already exists, skipping`);
       continue;
     }

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/build.test.ts

@@ -88,7 +88,9 @@ describe("runBuild --components --generate (chant #1108 build-time parameters)",
       undefined,
       [{ name: "tier", value: "light", source: "default" }],
     );
-    expect(stderr.join("\n")).toContain("[param] tier");
+    // A parameter at its default collapses into the count line now; the
+    // provenance forwarded above is where its value is asserted.
+    expect(stderr.join("\n")).toContain("at their defaults");
     vi.restoreAllMocks();
   });
 

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) {

package/src/cli/handlers/components.ts

@@ -42,6 +42,7 @@ import { findBuildManifestByArtifactDigest } from "../../lifecycle/build-ledger-
 import type { ComponentBomSummary } from "../../lifecycle/build-ledger";
 import { loadChantConfig } from "../../config";
 import { applyLiveEndpoint } from "../../live-endpoint";
+import { isResourceDeclarable } from "../../declarable";
 import { build } from "../../build";
 import { discoverComponents } from "../../components/discover";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
@@ -397,11 +398,12 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
           const declared = new Set<string>();
           const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
           for (const [name, entity] of buildResult.entities) {
-            if (entity.lexicon === plugin.name) {
+            // Resource declarables only (see lifecycle/observe.ts).
+            if (entity.lexicon === plugin.name && isResourceDeclarable(entity)) {
               declared.add(name);
               entities.set(name, {
                 entityType: entity.entityType,
-                props: ("props" in entity && entity.props != null ? entity.props : {}) as Record<string, unknown>,
+                props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
               });
             }
           }

package/src/cli/handlers/explain.test.ts

@@ -0,0 +1,93 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
+import type { ParsedArgs } from "../registry";
+
+const discoverMock = vi.fn();
+vi.mock("../../discovery/index", () => ({
+  discover: (...a: unknown[]) => discoverMock(...a),
+}));
+
+import { runExplain } from "./explain";
+
+function decl<T extends object>(base: T): Declarable & T {
+  return { [DECLARABLE_MARKER]: true, ...base } as Declarable & T;
+}
+
+function ctx(overrides: Partial<ParsedArgs>): Parameters<typeof runExplain>[0] {
+  return {
+    args: { command: "explain", path: ".", format: "", fix: false, watch: false, verbose: false, help: false, live: false, ...overrides } as ParsedArgs,
+    plugins: [],
+    serializers: [],
+  };
+}
+
+function discoveryResult() {
+  const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+  const subnet = decl({ lexicon: "gcp", entityType: "Subnet" });
+  return {
+    entities: new Map<string, Declarable>([
+      ["vpc", vpc],
+      ["subnet", subnet],
+    ]),
+    dependencies: new Map([["subnet", new Set(["vpc"])]]),
+    sourceFiles: ["net.ts"],
+    errors: [],
+    foldDecisions: [],
+  };
+}
+
+describe("runExplain", () => {
+  let outDir: string;
+  let logSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(async () => {
+    outDir = await mkdtemp(join(tmpdir(), "chant-explain-okf-"));
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    discoverMock.mockResolvedValue(discoveryResult());
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await rm(outDir, { recursive: true, force: true });
+  });
+
+  test("--format okf -o <dir> writes the bundle as a directory tree", async () => {
+    const code = await runExplain(ctx({ format: "okf", output: outDir }));
+    expect(code).toBe(0);
+
+    expect((await stat(join(outDir, "index.md"))).isFile()).toBe(true);
+    const subnet = await readFile(join(outDir, "gcp", "subnet.md"), "utf-8");
+    expect(subnet).toContain("type: Subnet");
+    expect(subnet).toContain("- [vpc](/gcp/vpc.md)");
+  });
+
+  test("--format okf without -o prints the bundle as JSON path -> content", async () => {
+    const code = await runExplain(ctx({ format: "okf" }));
+    expect(code).toBe(0);
+
+    const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(parsed.okf_version).toBe("0.2");
+    expect(Object.keys(parsed.files).sort()).toEqual(["gcp/subnet.md", "gcp/vpc.md", "index.md"]);
+  });
+
+  test("default format renders the markdown summary", async () => {
+    const code = await runExplain(ctx({}));
+    expect(code).toBe(0);
+    expect(logSpy.mock.calls[0][0]).toContain("# Project Summary");
+  });
+
+  test("an unknown format is rejected", async () => {
+    const code = await runExplain(ctx({ format: "xml" }));
+    expect(code).toBe(1);
+  });
+
+  test("discovery errors surface as a non-zero exit for okf", async () => {
+    discoverMock.mockResolvedValue({ ...discoveryResult(), errors: [new Error("boom")] });
+    const code = await runExplain(ctx({ format: "okf" }));
+    expect(code).toBe(1);
+  });
+});

package/src/cli/handlers/explain.ts

@@ -0,0 +1,60 @@
+import { resolve, join, dirname } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import { discover } from "../../discovery/index";
+import { buildOkfBundle, OKF_VERSION, type OkfFile } from "../../okf";
+import { handleExplain } from "../mcp/tools/explain";
+import { formatError, formatSuccess } from "../format";
+import type { CommandContext } from "../registry";
+
+const EXPLAIN_FORMATS = ["markdown", "json", "okf"] as const;
+type ExplainFormat = (typeof EXPLAIN_FORMATS)[number];
+
+/**
+ * `chant explain [path] [--format markdown|json|okf] [-o <dir>]` — the CLI
+ * path of the MCP `explain` tool (#1058): a structured summary of every
+ * discovered entity. `--format okf` emits an OKF v0.2 knowledge bundle
+ * instead — one markdown concept per entity plus an `index.md` — written as a
+ * directory tree under `-o <dir>`, or printed as JSON (path → content) when
+ * no output directory is given.
+ */
+export async function runExplain(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const format = (args.format || "markdown") as ExplainFormat;
+  if (!EXPLAIN_FORMATS.includes(format)) {
+    console.error(formatError({
+      message: `Invalid --format: ${format}. Expected one of ${EXPLAIN_FORMATS.join(", ")}.`,
+    }));
+    return 1;
+  }
+
+  const projectPath = resolve(args.path === "." ? "." : args.path);
+
+  if (format === "okf") {
+    const result = await discover(projectPath);
+    for (const err of result.errors) console.error(formatError({ message: err.message }));
+    const bundle = buildOkfBundle(result, projectPath);
+    if (args.output) {
+      await writeBundle(bundle, resolve(args.output));
+      console.log(formatSuccess(`Wrote OKF v${OKF_VERSION} bundle: ${bundle.length} file(s) under ${args.output}`));
+    } else {
+      console.log(JSON.stringify({
+        okf_version: OKF_VERSION,
+        files: Object.fromEntries(bundle.map((f) => [f.path, f.content])),
+      }, null, 2));
+    }
+    return result.errors.length > 0 ? 1 : 0;
+  }
+
+  const summary = await handleExplain({ path: projectPath, format });
+  console.log(typeof summary === "string" ? summary : JSON.stringify(summary, null, 2));
+  return 0;
+}
+
+/** Write the bundle's files under `outDir`, creating subdirectories as needed. */
+async function writeBundle(bundle: OkfFile[], outDir: string): Promise<void> {
+  for (const file of bundle) {
+    const target = join(outDir, file.path);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, file.content, "utf-8");
+  }
+}