@intentius/chant 0.52.1 → 0.53.0

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

@@ -14,18 +14,14 @@
 
 import { existsSync, statSync, writeFileSync, mkdirSync } from "fs";
 import { basename, join, resolve } from "path";
+import { cdkNotSupported, isCloudAssembly } from "../../cdk/assembly";
 import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
 import { boundaryReport, deferredParamName, type CarveReport } from "../../terraform/carve";
-import { resolveTier } from "../../terraform/tier-map";
+import { carveEmitTypes, resolveTier } from "../../terraform/tier-map";
+import { resolveEmitProvider } from "../../terraform/carve-provider";
 import { readStateResource, type StateResource } from "../../terraform/state";
 import { writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
-import {
-  adoptFromState,
-  canAdoptFromState,
-  supportedStateAdoptionTypes,
-  type DeferredParam,
-  type FoldedContribution,
-} from "../../terraform/adopt-state";
+import { adoptFromState, type DeferredParam, type FoldedContribution } from "../../terraform/adopt-state";
 import { getChantVersion } from "./init";
 import type { LexiconPlugin, ResourceSelector } from "../../lexicon";
 import type { ImportResult, LiveImportOptions } from "./import";
@@ -90,6 +86,7 @@ export async function carveEmit(opts: CarveEmitOptions, deps: CarveEmitDeps): Pr
   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, "emit") };
 
   let report: CarveReport | null;
   let tfType: string | undefined;
@@ -104,27 +101,32 @@ export async function carveEmit(opts: CarveEmitOptions, deps: CarveEmitDeps): Pr
 
   if (!report) return { ok: false, error: `${opts.select} not found in ${opts.from}` };
 
-  const tier = tfType ? resolveTier(tfType) : null;
-  if (!tier) {
+  if (!tfType || !resolveTier(tfType)) {
     return {
       ok: false,
       error: `${opts.select} (${tfType ?? "unknown type"}) has no known native mapping, so it cannot be emitted. Advisor bands it "leave in Terraform".`,
     };
   }
 
+  // `carve advise` ranks every type a provider declares; emit produces source
+  // only for the ones that provider can adopt. Both adoption paths refuse the
+  // rest here — before any file is written or any cloud call is made — so
+  // neither path can proceed on a type the other rejects.
+  const provider = resolveEmitProvider(tfType);
+  if (!provider) {
+    return {
+      ok: false,
+      error:
+        `${tfType} cannot be emitted yet (no carve provider adopts it).\n` +
+        `Supported types: ${carveEmitTypes().join(", ")}. ` +
+        `Coverage is expanding — see chant issue #1001.`,
+    };
+  }
+
   if (opts.reportFile) writeFileSync(opts.reportFile, JSON.stringify(report, null, 2));
 
   // ── Adoption path 1: from .tfstate (offline, correct for TF-managed) ──
   if (opts.statePath) {
-    if (!canAdoptFromState(tfType!)) {
-      return {
-        ok: false,
-        error:
-          `${tfType} cannot be adopted from state yet (no native constructor mapping).\n` +
-          `Supported types: ${supportedStateAdoptionTypes().join(", ")}. ` +
-          `Coverage is expanding — see chant issue #1001.`,
-      };
-    }
     const stateResource = readStateResource(opts.statePath, opts.select);
     if (!stateResource) {
       return { ok: false, error: `${opts.select} not found in state ${opts.statePath} (or is a data source / module-nested).` };
@@ -149,8 +151,7 @@ export async function carveEmit(opts: CarveEmitOptions, deps: CarveEmitDeps): Pr
     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);
+    const scaffolded = scaffoldProject(outDir, provider.lexicon, params);
 
     const manifestPath = persistManifest(outDir, opts, report, tfType, "tfstate", [outPath], params);
     return {
@@ -166,21 +167,47 @@ export async function carveEmit(opts: CarveEmitOptions, deps: CarveEmitDeps): Pr
   }
 
   // ── Adoption path 2: live import (cloud→code) ──
-  // The live import filters a CloudFormation stack's template by logical ID, not
-  // the Terraform physical name — so select by native type, narrowing to a
-  // logical ID only when the caller passes --live-name (a stack with several of
-  // that type). `identity` (the TF physical name) is not a valid CFN selector.
+  // The provider names the selector type its live export filters on — for aws a
+  // CloudFormation type, filtered by logical ID rather than the Terraform
+  // physical name, so `--live-name` (not `identity`) is what narrows a stack
+  // holding several of that type.
+  const selectorType = provider.liveSelectorType?.(tfType);
+  if (!selectorType) {
+    return {
+      ok: false,
+      error:
+        `${tfType} has no live adoption path — the ${provider.name} carve provider adopts it from state only.\n` +
+        `Re-run with --state <tfstate>.`,
+    };
+  }
   const selector: ResourceSelector = opts.liveName
-    ? { type: tier.mapsTo, name: opts.liveName }
-    : { type: tier.mapsTo };
+    ? { type: selectorType, name: opts.liveName }
+    : { type: selectorType };
 
   const emit = await deps.liveImport(deps.plugins, {
     environment: opts.env!,
     selector,
     output: opts.output,
-    lexicon: tier.mapsTo.split("::")[0]?.toLowerCase() === "aws" ? "aws" : undefined,
+    lexicon: provider.lexicon,
   });
 
+  // A failed import emitted no source. Reporting success here would write a
+  // carve manifest that `carve bridge` composes from, and bridge excises the
+  // survivor's `.tf` block for the resource — so the estate would lose a
+  // declaration that was never adopted. Fail, and persist nothing.
+  if (!emit.success) {
+    return {
+      ok: false,
+      error:
+        `Live import of ${selector.type} from ${opts.env} failed: ${emit.error ?? "no error reported"}\n` +
+        `Nothing was emitted and no carve manifest was written.`,
+      report,
+      emit,
+      selector,
+      source: "live",
+    };
+  }
+
   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 };

package/src/cli/commands/carve.ts

@@ -1,20 +1,29 @@
 /**
- * `chant carve advise` — the read-only Terraform peelability advisor (#214).
+ * `chant carve advise` — the read-only peelability advisor (#214, #1056).
  *
- * Points at a Terraform estate and reports which resources/modules are cheap to
- * carve into native chant later and which should stay in Terraform. It emits
+ * Points at foreign infrastructure and reports which pieces are cheap to carve
+ * into native chant later and which should stay where they are. It emits
  * nothing, patches nothing, and touches no live resource — pure analysis. The
- * emit/boundary/apply phases stay in #197, gated on demand.
+ * emit/boundary/apply phases (`carve emit|bridge|apply`, #197) read Terraform
+ * only, and refuse a cloud assembly by name.
+ *
+ * Two sources, one report. A Terraform estate is parsed from `.tf`; a CDK cloud
+ * assembly is read from `cdk.out` (#1056). Which one is in `--from` is decided
+ * by looking, not by a second flag: a directory holding `manifest.json` plus a
+ * synthesized `*.template.json` is an assembly. Both produce the same bands,
+ * the same score arithmetic, and the same JSON shape.
  */
 
 import { existsSync, statSync, writeFileSync } from "fs";
+import { adviseCloudAssembly, CDK_DIALECT } from "../../cdk/advise";
+import { isCloudAssembly } from "../../cdk/assembly";
 import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
-import { scoreEstate, type Peelability, type PeelabilityBand } from "../../terraform/score";
-import { boundaryReport, type BoundaryEdge } from "../../terraform/carve";
+import { scoreEstate, type Peelability, type PeelabilityBand, type ScoreOptions } from "../../terraform/score";
+import { boundaryReport, type BoundaryEdge, type CarveDialect } from "../../terraform/carve";
 import type { TfGraph } from "../../terraform/types";
 
 export interface CarveAdviseOptions {
-  /** Terraform estate directory (from `--from`). */
+  /** Terraform estate directory or CDK cloud assembly (from `--from`). */
   from?: string;
   /** Opt-in `.tfstate` path (from `--state`): accurate fan-out instance counts. */
   statePath?: string;
@@ -22,10 +31,19 @@ export interface CarveAdviseOptions {
   reportFile?: string;
 }
 
+/**
+ * Which source the ranking came from. Terraform addresses and CDK construct
+ * paths are different namespaces, and the bridge patches have different names,
+ * so a report says which it is rather than leaving a reader to guess from the
+ * shape of an address.
+ */
+export type CarveSource = "terraform" | "cdk";
+
 export interface CarveAdviseResult {
   ok: boolean;
   error?: string;
   from?: string;
+  source?: CarveSource;
   results?: Peelability[];
   /**
    * The parsed dependency graph the scores came from. Kept so the JSON report
@@ -33,37 +51,69 @@ export interface CarveAdviseResult {
    * Not part of the JSON payload — `carveJson` derives from it.
    */
   graph?: TfGraph;
+  /** The hooks the scores were produced with, so the boundary pass agrees. */
+  scoreOptions?: ScoreOptions;
+  /** Anything about the read itself worth saying out loud. */
+  diagnostics?: string[];
 }
 
 const BAND_ORDER: PeelabilityBand[] = ["clean leaf", "carvable w/ edits", "leave in Terraform"];
 
 export async function carveAdvise(opts: CarveAdviseOptions): Promise<CarveAdviseResult> {
   if (!opts.from) {
-    return { ok: false, error: "chant carve advise requires --from <terraform-dir>" };
+    return { ok: false, error: "chant carve advise requires --from <terraform-dir | cdk.out>" };
   }
   if (!existsSync(opts.from) || !statSync(opts.from).isDirectory()) {
     return { ok: false, error: `Not a directory: ${opts.from}` };
   }
+
+  const result = isCloudAssembly(opts.from) ? adviseCdk(opts) : await adviseTerraform(opts);
+  if (result.ok && opts.reportFile) {
+    writeFileSync(opts.reportFile, JSON.stringify(carveJson(result), null, 2));
+  }
+  return result;
+}
+
+/** Rank a CDK cloud assembly. No parser to install, no state file to read. */
+function adviseCdk(opts: CarveAdviseOptions): CarveAdviseResult {
+  if (opts.statePath) {
+    return {
+      ok: false,
+      error:
+        `${opts.from} is a CDK cloud assembly, and --state is a Terraform option. ` +
+        "A synthesized template already carries its own instance counts.",
+    };
+  }
+  try {
+    const advice = adviseCloudAssembly(opts.from!);
+    return {
+      ok: true,
+      from: opts.from,
+      source: "cdk",
+      results: advice.results,
+      graph: advice.graph,
+      scoreOptions: advice.scoreOptions,
+      diagnostics: advice.diagnostics,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `Failed to read the CDK cloud assembly in ${opts.from}: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+async function adviseTerraform(opts: CarveAdviseOptions): Promise<CarveAdviseResult> {
   if (opts.statePath && !existsSync(opts.statePath)) {
     return { ok: false, error: `State file not found: ${opts.statePath}` };
   }
-
-  let graph: TfGraph;
-  let results: Peelability[];
   try {
-    graph = await parseTerraformDir(opts.from, { statePath: opts.statePath });
-    results = scoreEstate(graph);
+    const graph = await parseTerraformDir(opts.from!, { statePath: opts.statePath });
+    return { ok: true, from: opts.from, source: "terraform", results: scoreEstate(graph), graph };
   } catch (err) {
     if (err instanceof Hcl2JsonNotInstalled) return { ok: false, error: err.message };
     return { ok: false, error: `Failed to parse Terraform in ${opts.from}: ${err instanceof Error ? err.message : String(err)}` };
   }
-
-  const result: CarveAdviseResult = { ok: true, from: opts.from, results, graph };
-  if (opts.reportFile) {
-    writeFileSync(opts.reportFile, JSON.stringify(carveJson(result), null, 2));
-  }
-
-  return result;
 }
 
 /**
@@ -81,6 +131,16 @@ export async function carveAdvise(opts: CarveAdviseOptions): Promise<CarveAdvise
  *    not).
  *  - A reader that does not know the version it is handed should refuse the
  *    report rather than half-read it.
+ *
+ * The CDK source (#1056) stays inside that promise and does not bump the
+ * version. Every field an existing reader keys on keeps its type and meaning:
+ * `address` is still an opaque string identifier (a construct path instead of a
+ * Terraform address), `kind` is still `"resource"` or `"module"` (an L3
+ * construct subtree is a Composite candidate, which is what `module` already
+ * means), `score`/`band`/`breakdown` are the same arithmetic. What is new is
+ * additive and ignorable: the top-level `source` discriminator, per-resource
+ * `notes` and `members`, and two more `bridge` values in a list that was
+ * already declared open-ended.
  */
 export const CARVE_REPORT_VERSION = 1;
 
@@ -113,10 +173,23 @@ export interface CarveJsonResource extends Peelability {
 export interface CarveJsonReport {
   version: number;
   from?: string;
+  /**
+   * Which source was read (#1056). `terraform` — addresses are Terraform
+   * addresses, bridges are `data` sources. `cdk` — addresses are construct
+   * paths and bridges are reimports. Absent on a chant that predates the CDK
+   * advisor, which a reader should take as `terraform`.
+   */
+  source: CarveSource;
   advisory: string;
   count: number;
   /** Band name -> how many resources landed in it. */
   bands: Record<string, number>;
+  /**
+   * Anything about the read the scores alone do not say — a missing `tree.json`,
+   * an assembly synthesized from unresolved context lookups. Present only when
+   * there is something to report.
+   */
+  diagnostics?: string[];
   resources: CarveJsonResource[];
 }
 
@@ -126,20 +199,29 @@ export function carveJson(result: CarveAdviseResult): CarveJsonReport {
   const counts = Object.fromEntries(
     BAND_ORDER.map((b) => [b, results.filter((r) => r.band === b).length]),
   );
+  const source = result.source ?? "terraform";
+  const dialect: CarveDialect = source === "cdk" ? CDK_DIALECT : "terraform";
   return {
     version: CARVE_REPORT_VERSION,
     from: result.from,
+    source,
     advisory: "read-only — emits nothing, patches nothing, touches no live resource",
     count: results.length,
     bands: counts,
-    resources: results.map((r) => withBoundary(r, result.graph)),
+    ...(result.diagnostics?.length ? { diagnostics: result.diagnostics } : {}),
+    resources: results.map((r) => withBoundary(r, result.graph, dialect, result.scoreOptions)),
   };
 }
 
 /** A scored resource plus its carve boundary, when the graph is at hand (#1636). */
-function withBoundary(r: Peelability, graph?: TfGraph): CarveJsonResource {
+function withBoundary(
+  r: Peelability,
+  graph: TfGraph | undefined,
+  dialect: CarveDialect,
+  score: ScoreOptions | undefined,
+): CarveJsonResource {
   if (!graph) return r;
-  const report = boundaryReport(graph, r.address);
+  const report = boundaryReport(graph, r.address, { dialect, score });
   if (!report) return r;
   return { ...r, boundary: { inbound: report.inbound, outbound: report.outbound } };
 }
@@ -147,52 +229,73 @@ function withBoundary(r: Peelability, graph?: TfGraph): CarveJsonResource {
 /** Human-readable banded, ranked summary. */
 export function formatCarveReport(result: CarveAdviseResult): string {
   const results = result.results ?? [];
+  const source = result.source ?? "terraform";
+  const cdk = source === "cdk";
+
   if (results.length === 0) {
-    return `No carvable resources found in ${result.from}\n(only data sources, providers, or unsupported types were present).`;
+    return cdk
+      ? `No carvable constructs found in ${result.from}\n(the assembly synthesized no infrastructure beyond CDK's own scaffolding).`
+      : `No carvable resources found in ${result.from}\n(only data sources, providers, or unsupported types were present).`;
   }
 
   const lines: string[] = [];
-  lines.push(`Terraform carve-out advisory for ${result.from}`);
-  lines.push(`  ${results.length} resource(s)/module(s) scored. Advises only — nothing is emitted or changed.`);
+  lines.push(`${cdk ? "CDK cloud-assembly" : "Terraform"} carve-out advisory for ${result.from}`);
+  lines.push(
+    `  ${results.length} ${cdk ? "construct(s)" : "resource(s)/module(s)"} scored. ` +
+      "Advises only — nothing is emitted or changed.",
+  );
+  for (const note of result.diagnostics ?? []) lines.push(`  ! ${note}`);
   lines.push("");
 
   for (const band of BAND_ORDER) {
     const inBand = results.filter((r) => r.band === band);
     if (inBand.length === 0) continue;
-    lines.push(`${bandLabel(band)}  (${inBand.length})`);
+    lines.push(`${bandLabel(band, cdk)}  (${inBand.length})`);
     for (const r of inBand) {
       const target = r.mapsTo ? ` -> ${r.mapsTo}` : "";
       lines.push(`  ${String(r.score).padStart(3)}  ${r.address}${target}`);
-      lines.push(`       ${reasons(r)}`);
+      lines.push(`       ${reasons(r, cdk)}`);
+      for (const note of r.notes ?? []) lines.push(`       ${note}`);
     }
     lines.push("");
   }
 
-  lines.push("Bands: 80-100 carve now | 50-79 carve with boundary edits | 0-49 leave in Terraform");
+  lines.push(
+    `Bands: 80-100 carve now | 50-79 carve with boundary edits | 0-49 leave in ${cdk ? "CDK" : "Terraform"}`,
+  );
   return lines.join("\n").trimEnd();
 }
 
-function bandLabel(band: PeelabilityBand): string {
+function bandLabel(band: PeelabilityBand, cdk: boolean): string {
   switch (band) {
     case "clean leaf":
       return "CLEAN LEAF — carve now";
     case "carvable w/ edits":
       return "CARVABLE — has boundary work";
     case "leave in Terraform":
-      return "LEAVE IN TERRAFORM";
+      // The band's name is part of the JSON contract and does not change per
+      // source; only the heading a person reads does.
+      return cdk ? "LEAVE IN CDK" : "LEAVE IN TERRAFORM";
   }
 }
 
 /** One-line explanation of what drove a score, from its breakdown. */
-function reasons(r: Peelability): string {
+function reasons(r: Peelability, cdk = false): string {
   const b = r.breakdown;
-  if (b.tier === null) return "no known native mapping (unsupported provider/type)";
+  if (b.tier === null) {
+    return cdk ? "no chant AWS lexicon target for this type" : "no known native mapping (unsupported provider/type)";
+  }
+  // A node that scored 0 with every penalty at 0 was disqualified outright, not
+  // scored down. Reciting the arithmetic would credit terms that never applied;
+  // the stated reason follows on the next line.
+  if (r.score === 0 && Object.values(b.penalties).every((p) => p === 0)) return "not carvable as it stands";
   const parts: string[] = [];
-  if (b.inbound) parts.push(`${b.inbound} inbound (data-source patch each)`);
-  if (b.outputs) parts.push(`${b.outputs} output block(s) reading it (one-line rewrite each)`);
+  if (b.inbound) parts.push(`${b.inbound} inbound (${cdk ? "a reimport each" : "data-source patch each"})`);
+  if (b.outputs) parts.push(`${b.outputs} ${cdk ? "stack output(s)" : "output block(s)"} reading it (one-line rewrite each)`);
   if (b.outbound) parts.push(`${b.outbound} outbound (deferred input each)`);
   if (b.tier > 1) parts.push(`tier ${b.tier} map`);
-  if (b.hasDynamic) parts.push("count/for_each/data present");
+  if (b.hasDynamic) parts.push(cdk ? "condition/parameter present" : "count/for_each/data present");
   if (b.instances > 1) parts.push(`${b.instances} instances`);
+  if (b.penalties.asset) parts.push("asset-backed");
   return parts.length ? parts.join(", ") : "clean 1:1 native map, no boundary edges";
 }

package/src/cli/commands/import-agents.test.ts

@@ -0,0 +1,208 @@
+/**
+ * The import command's own contract, separate from the mapping it delegates to
+ * (covered by the fountain lexicon's `local-agents.test.ts`).
+ *
+ * What matters here is the parts a user hits when something is off: a lexicon
+ * that can't be loaded or can't express agents, an output directory that
+ * already has files in it, and — above all — that every lossy step the mapper
+ * reports actually reaches the user. Re-expression silently dropping a config
+ * or defaulting a required field is the failure mode that would make the
+ * generated code untrustworthy.
+ *
+ * The plugin is injected rather than loaded, so these run without a built
+ * lexicon on disk.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, writeFileSync, rmSync, readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { importAgentsCommand, DEFAULT_AGENT_LEXICON, type PluginLoader } from "./import-agents";
+import type { LexiconPlugin } from "../../lexicon";
+import type { AgentImportOutcome } from "../../agents/importer";
+import type { TemplateIR } from "../../import/parser";
+
+let home: string;
+let out: string;
+
+function writeIn(root: string, rel: string, content: string): void {
+  const full = join(root, rel);
+  mkdirSync(join(full, ".."), { recursive: true });
+  writeFileSync(full, content, "utf-8");
+}
+
+beforeEach(() => {
+  home = join(tmpdir(), `chant-ia-home-${Math.random().toString(36).slice(2)}`);
+  out = join(tmpdir(), `chant-ia-out-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(home, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(home, { recursive: true, force: true });
+  rmSync(out, { recursive: true, force: true });
+});
+
+/** A config with one MCP server, so the scan finds something to import. */
+function seedConfig(): void {
+  writeIn(home, ".claude/mcp.json", JSON.stringify({ mcpServers: { a: { command: "x" } } }));
+}
+
+const EMPTY_OUTCOME: AgentImportOutcome = { ir: { resources: [], parameters: [] }, skipped: [], unmappedModel: [], redactedSecrets: [] };
+
+/** A plugin whose importer and generator are both stubbed. */
+function fakePlugin(outcome: Partial<AgentImportOutcome> = {}, overrides: Partial<LexiconPlugin> = {}): LexiconPlugin {
+  const resolved: AgentImportOutcome = { ...EMPTY_OUTCOME, ...outcome };
+  return {
+    name: "fountain",
+    agentConfigImporter: () => ({ toTemplateIR: () => resolved }),
+    templateGenerator: () => ({
+      generate: (ir: TemplateIR) => [{ path: "main.ts", content: ir.resources.map((r) => `export const ${r.logicalId} = {};`).join("\n") }],
+    }),
+    ...overrides,
+  } as unknown as LexiconPlugin;
+}
+
+/** An outcome with one resource, so the command reaches the write step. */
+const ONE_RESOURCE: Partial<AgentImportOutcome> = {
+  ir: { resources: [{ logicalId: "userClaude", type: "Fountain::V1::Agent", properties: {} }], parameters: [] },
+};
+
+const loaderFor = (plugin: LexiconPlugin): PluginLoader => async () => plugin;
+
+const run = (opts: Parameters<typeof importAgentsCommand>[0] = {}) =>
+  importAgentsCommand({ home, platform: "linux", projectRoots: [], output: out, pluginLoader: loaderFor(fakePlugin(ONE_RESOURCE)), ...opts });
+
+describe("nothing to import", () => {
+  test("fails with a clear message when no agent config exists", async () => {
+    const result = await run();
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("No agent configuration found");
+    expect(result.generatedFiles).toEqual([]);
+  });
+});
+
+describe("lexicon resolution", () => {
+  test("defaults to the fountain lexicon", async () => {
+    seedConfig();
+    let asked: string | undefined;
+    await run({ pluginLoader: async (name) => { asked = name; return fakePlugin(ONE_RESOURCE); } });
+    expect(asked).toBe(DEFAULT_AGENT_LEXICON);
+  });
+
+  test("reports an install hint when the lexicon package is missing", async () => {
+    seedConfig();
+    const result = await run({
+      lexicon: "nope",
+      pluginLoader: async () => { throw new Error("Cannot find module"); },
+    });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("npm i @intentius/chant-lexicon-nope");
+  });
+
+  test("names the fallback when the lexicon cannot express agent config", async () => {
+    seedConfig();
+    const result = await run({ lexicon: "k8s", pluginLoader: loaderFor(fakePlugin({}, { agentConfigImporter: undefined })) });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("cannot express agent configuration");
+    expect(result.error).toContain(`--lexicon ${DEFAULT_AGENT_LEXICON}`);
+  });
+
+  test("fails when the lexicon has no generator to emit TypeScript", async () => {
+    seedConfig();
+    const result = await run({ pluginLoader: loaderFor(fakePlugin(ONE_RESOURCE, { templateGenerator: undefined })) });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("no templateGenerator");
+  });
+});
+
+describe("reporting what was lost", () => {
+  test("surfaces a skipped site with the mapper's reason", async () => {
+    seedConfig();
+    const result = await run({
+      pluginLoader: loaderFor(fakePlugin({ ...ONE_RESOURCE, skipped: [{ siteId: "user-cursor", reason: 'fountain has no "cursor" runtime' }] })),
+    });
+    expect(result.warnings.some((w) => w.includes("user-cursor") && w.includes("cursor"))).toBe(true);
+  });
+
+  test("warns that a defaulted model needs editing before it is applied", async () => {
+    seedConfig();
+    const result = await run({ pluginLoader: loaderFor(fakePlugin({ ...ONE_RESOURCE, unmappedModel: ["user-claude"] })) });
+    expect(result.warnings.some((w) => w.includes("user-claude") && w.includes("Edit it before applying"))).toBe(true);
+  });
+
+  test("states that redacted credentials were not copied into the generated code", async () => {
+    // The user has to know a secret was *removed*, not carried over — otherwise
+    // they'd assume the generated config works as-is.
+    seedConfig();
+    const result = await run({ pluginLoader: loaderFor(fakePlugin({ ...ONE_RESOURCE, redactedSecrets: ["user-claude"] })) });
+    const warning = result.warnings.find((w) => w.includes("Literal credentials"));
+    expect(warning).toContain("were NOT copied");
+  });
+
+  test("fails, rather than writing an empty file, when nothing could be mapped", async () => {
+    seedConfig();
+    const result = await run({ pluginLoader: loaderFor(fakePlugin({ skipped: [{ siteId: "user-cursor", reason: "no runtime" }] })) });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("none could be expressed");
+    expect(existsSync(join(out, "main.ts"))).toBe(false);
+  });
+});
+
+describe("writing output", () => {
+  test("writes the generated files and reports what it counted", async () => {
+    seedConfig();
+    const result = await run();
+    expect(result.success).toBe(true);
+    expect(result.generatedFiles).toEqual([join(out, "main.ts")]);
+    expect(readFileSync(join(out, "main.ts"), "utf-8")).toContain("export const userClaude");
+    expect(result.summary).toEqual({ discovered: 1, mapped: 1 });
+  });
+
+  test("refuses to overwrite an existing file without --force", async () => {
+    // Generated agent code gets hand-edited after the first run; silently
+    // reverting those edits would be the worst outcome for this command.
+    seedConfig();
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, "main.ts"), "// hand-edited", "utf-8");
+
+    const result = await run();
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("--force");
+    expect(readFileSync(join(out, "main.ts"), "utf-8")).toBe("// hand-edited");
+  });
+
+  test("overwrites with --force", async () => {
+    seedConfig();
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, "main.ts"), "// hand-edited", "utf-8");
+
+    const result = await run({ force: true });
+    expect(result.success).toBe(true);
+    expect(readFileSync(join(out, "main.ts"), "utf-8")).toContain("export const userClaude");
+  });
+
+  test("creates the output directory when it does not exist", async () => {
+    seedConfig();
+    const nested = join(out, "deep", "nested");
+    const result = await run({ output: nested });
+    expect(result.success).toBe(true);
+    expect(existsSync(join(nested, "main.ts"))).toBe(true);
+  });
+});
+
+describe("scope and runtime filtering", () => {
+  test("passes the scope filter through to the scan", async () => {
+    seedConfig();
+    // user scope holds the config; restricting to project finds nothing.
+    const result = await run({ scopes: ["project"] });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("No agent configuration found");
+  });
+
+  test("passes the runtime filter through to the scan", async () => {
+    seedConfig();
+    const result = await run({ runtimes: ["codex"] });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("No agent configuration found");
+  });
+});