@intentius/chant 0.52.1 → 0.52.2

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

@@ -14,7 +14,7 @@ import { join, basename, relative, resolve } from "path";
 import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
 import { boundaryReport, type CarveReport } from "../../terraform/carve";
 import { generateBridge, type BridgePlan, type CarvedIdentity } from "../../terraform/bridge";
-import { IDENTITY_ATTR } from "../../terraform/tier-map";
+import { IDENTITY_ATTR, canBridge } from "../../terraform/tier-map";
 import { resolveCarveManifest, writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
 import { newFileDiff, unifiedDiff } from "../../terraform/unified-diff";
 
@@ -74,6 +74,24 @@ export async function carveBridge(opts: CarveBridgeOptions): Promise<CarveBridge
     if (!found) return { ok: false, error: `${select} not found in ${opts.from}` };
     report = found;
 
+    // Refuse a carve set whose data source cannot be written as valid HCL: a
+    // dotted identity attribute is a path into nested blocks, and a data body
+    // is flat `attr = value`. `kubernetes_manifest` is the standing case — the
+    // provider has no `kubernetes_manifest` data source either; its generic
+    // read is `kubernetes_resource`, a different shape (#999).
+    const carvedTypes = report.carveSet.map((m) => m.type).filter((t): t is string => 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 \`${IDENTITY_ATTR[t]}\``)
+            .join(", ")}, a path into nested blocks that a Terraform data source body cannot express. ` +
+          `Bridging these types needs a data-source mapping — see chant issue #999.`,
+      };
+    }
+
     // Physical identities for the carved resources, for the data sources.
     const identities = new Map<string, CarvedIdentity>();
     for (const node of graph.nodes) {

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

@@ -1,9 +1,10 @@
 import { describe, test, expect, vi } from "vitest";
-import { mkdtempSync, writeFileSync, rmSync, readFileSync } from "fs";
+import { mkdtempSync, writeFileSync, rmSync, readFileSync, existsSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import { carveEmit, formatCarveEmit } from "./carve-emit";
 import { loadHcl2json } from "../../terraform/parse";
+import { listCarveManifests } from "../../terraform/manifest";
 import type { ImportResult, LiveImportOptions } from "./import";
 import type { LexiconPlugin } from "../../lexicon";
 
@@ -35,12 +36,30 @@ resource "aws_lambda_function" "api" {
 resource "random_pet" "suffix" {
   length = 2
 }
+resource "kubernetes_config_map" "demo" {
+  metadata { name = "demo-config" }
+}
 `;
 
+// A state file for the bucket, so the --state path reaches the same gate the
+// --env path does rather than stopping at "not found in state".
+const TFSTATE = JSON.stringify({
+  version: 4,
+  resources: [
+    {
+      mode: "managed",
+      type: "kubernetes_config_map",
+      name: "demo",
+      instances: [{ attributes: { id: "default/demo-config" } }],
+    },
+  ],
+});
+
 async function withEstate<T>(fn: (dir: string) => Promise<T>): Promise<T> {
   const dir = mkdtempSync(join(tmpdir(), "chant-carve-emit-"));
   try {
     writeFileSync(join(dir, "main.tf"), ESTATE);
+    writeFileSync(join(dir, "terraform.tfstate"), TFSTATE);
     return await fn(dir);
   } finally {
     rmSync(dir, { recursive: true, force: true });
@@ -142,6 +161,58 @@ describe("carveEmit — emit + boundary", () => {
     });
   });
 
+  test("a failed live import fails the emit and writes no carve manifest (#2015)", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      const li = vi.fn(
+        async (_p: LexiconPlugin[], _o: LiveImportOptions): Promise<ImportResult> => ({
+          success: false,
+          generatedFiles: [],
+          warnings: [],
+          error: "no stack in prod exports AWS::S3::Bucket",
+        }),
+      );
+      const res = await carveEmit(
+        { from: dir, select: "aws_s3_bucket.assets", env: "prod", output: out },
+        { plugins: noPlugins, liveImport: li },
+      );
+
+      expect(res.ok).toBe(false);
+      expect(res.error).toContain("no stack in prod exports AWS::S3::Bucket");
+      expect(res.manifestPath).toBeUndefined();
+      // Bridge/apply compose from the manifest; one written here would make
+      // bridge excise a `.tf` block for a resource that was never emitted.
+      expect(listCarveManifests(out)).toEqual([]);
+      expect(existsSync(out)).toBe(false);
+      // No false "Adopted live" line on the failure path.
+      expect(formatCarveEmit(res)).not.toContain("Adopted live");
+    });
+  });
+
+  test("a type emit cannot carve is refused identically on --state and --env (#2015)", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const li = fakeImport();
+      const live = await carveEmit(
+        { from: dir, select: "kubernetes_config_map.demo", env: "prod" },
+        { plugins: noPlugins, liveImport: li },
+      );
+      const state = await carveEmit(
+        { from: dir, select: "kubernetes_config_map.demo", statePath: join(dir, "terraform.tfstate") },
+        { plugins: noPlugins, liveImport: li },
+      );
+
+      expect(live.ok).toBe(false);
+      expect(state.ok).toBe(false);
+      expect(live.error).toBe(state.error);
+      expect(live.error).toContain("kubernetes_config_map cannot be emitted yet");
+      // advise ranks it (tier 2), so it gets past resolveTier — the emit gate
+      // is what refuses it, before the AWS exporter is ever reached.
+      expect(li).not.toHaveBeenCalled();
+    });
+  });
+
   test("--live-name narrows the live selector to a CFN logical id", async () => {
     if (!parserAvailable) return;
     await withEstate(async (dir) => {

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

@@ -16,20 +16,22 @@ import { existsSync, statSync, writeFileSync, mkdirSync } from "fs";
 import { basename, join, resolve } from "path";
 import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
 import { boundaryReport, deferredParamName, type CarveReport } from "../../terraform/carve";
-import { resolveTier } from "../../terraform/tier-map";
+import { canCarveEmit, carveEmitTypes, resolveTier } from "../../terraform/tier-map";
 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";
 
+/**
+ * The lexicon emit targets. `canCarveEmit` admits only AWS carve-table types,
+ * so both the scaffolded project and the live import are AWS. Widening this
+ * needs the lexicon-agnostic emit seam (#999, #2016) — deriving it from
+ * `tier.mapsTo` does not work: a `k8s:Namespace` mapping has no `::` to split.
+ */
+const EMIT_LEXICON = "aws";
+
 export interface CarveEmitOptions {
   /** Terraform estate directory (`--from`). */
   from?: string;
@@ -112,19 +114,24 @@ export async function carveEmit(opts: CarveEmitOptions, deps: CarveEmitDeps): Pr
     };
   }
 
+  // `carve advise` ranks every type in the tier map; emit produces source only
+  // for the ones with a native constructor mapping. 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.
+  if (!canCarveEmit(tfType!)) {
+    return {
+      ok: false,
+      error:
+        `${tfType} cannot be emitted yet (no native constructor mapping).\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 +156,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, EMIT_LEXICON, params);
 
     const manifestPath = persistManifest(outDir, opts, report, tfType, "tfstate", [outPath], params);
     return {
@@ -178,9 +184,26 @@ export async function carveEmit(opts: CarveEmitOptions, deps: CarveEmitDeps): Pr
     environment: opts.env!,
     selector,
     output: opts.output,
-    lexicon: tier.mapsTo.split("::")[0]?.toLowerCase() === "aws" ? "aws" : undefined,
+    lexicon: EMIT_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/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");
+  });
+});

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

@@ -0,0 +1,196 @@
+/**
+ * `chant import --agents` — re-express this machine's agent configuration as
+ * chant code.
+ *
+ * Shares its front half with `chant audit --agents` (the same scan, the same
+ * normalized sites) and its back half with every other import path (a lexicon's
+ * `templateGenerator()` turning IR into TypeScript). The only new step is the
+ * middle: `LexiconPlugin.agentConfigImporter()`, which maps sites onto the
+ * lexicon's own resource types.
+ *
+ * The command is loud about what it changed. Re-expression here is lossy in
+ * three specific ways — a skipped runtime, a defaulted model, a redacted
+ * secret — and each one is something the user would otherwise find only by
+ * diffing the generated code against their real config. Printing them is not
+ * politeness; it is the difference between generated code you can trust and
+ * generated code you have to re-verify by hand.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+import { scanAgentConfigs } from "../../agents/discover";
+import type { AgentRuntime, AgentScope } from "../../agents/types";
+import type { AgentImportOutcome } from "../../agents/importer";
+import type { LexiconPlugin } from "../../lexicon";
+import { loadPlugin } from "../plugins";
+
+/** The lexicon used when `--lexicon` isn't given: the one that models agent workloads. */
+export const DEFAULT_AGENT_LEXICON = "fountain";
+
+/**
+ * Loads the lexicon plugin. Injectable so this command can be unit-tested
+ * without a built lexicon package on disk — the same seam `audit.ts` uses for
+ * its `ChecksProvider`.
+ */
+export type PluginLoader = (name: string) => Promise<LexiconPlugin>;
+
+export interface ImportAgentsOptions {
+  /** Lexicon to re-express into. Defaults to {@link DEFAULT_AGENT_LEXICON}. */
+  lexicon?: string;
+  /** Injectable plugin loader (testing). Defaults to the real one. */
+  pluginLoader?: PluginLoader;
+  /** Output directory. Defaults to `./infra/agents`. */
+  output?: string;
+  force?: boolean;
+  scopes?: readonly AgentScope[];
+  runtimes?: readonly AgentRuntime[];
+  projectRoots?: string[];
+  home?: string;
+  platform?: NodeJS.Platform;
+}
+
+export interface ImportAgentsResult {
+  success: boolean;
+  generatedFiles: string[];
+  /** Sites found, mapped, and deliberately not mapped. */
+  summary: { discovered: number; mapped: number };
+  outcome?: AgentImportOutcome;
+  warnings: string[];
+  error?: string;
+}
+
+/**
+ * Scan, re-express, and write.
+ *
+ * Refuses to overwrite existing files without `--force`, matching `chant
+ * import` — generated agent code is likely to be edited by hand after the
+ * first run, and silently reverting those edits would be the worst possible
+ * behavior for a command whose whole purpose is capturing hand-tuned config.
+ */
+export async function importAgentsCommand(opts: ImportAgentsOptions = {}): Promise<ImportAgentsResult> {
+  const lexiconName = opts.lexicon ?? DEFAULT_AGENT_LEXICON;
+  const outputDir = resolve(opts.output ?? join("infra", "agents"));
+  const warnings: string[] = [];
+
+  const scan = scanAgentConfigs({
+    scopes: opts.scopes,
+    runtimes: opts.runtimes,
+    projectRoots: opts.projectRoots,
+    home: opts.home ?? homedir(),
+    platform: opts.platform,
+  });
+
+  if (scan.sites.length === 0) {
+    return {
+      success: false,
+      generatedFiles: [],
+      summary: { discovered: 0, mapped: 0 },
+      warnings,
+      error: "No agent configuration found to import.",
+    };
+  }
+
+  let plugin: LexiconPlugin;
+  try {
+    plugin = await (opts.pluginLoader ?? loadPlugin)(lexiconName);
+  } catch (err) {
+    return {
+      success: false,
+      generatedFiles: [],
+      summary: { discovered: scan.sites.length, mapped: 0 },
+      warnings,
+      error:
+        `Could not load the ${lexiconName} lexicon: ${err instanceof Error ? err.message : String(err)}\n` +
+        `Install it with: npm i @intentius/chant-lexicon-${lexiconName}`,
+    };
+  }
+
+  const importer = plugin.agentConfigImporter?.();
+  if (!importer) {
+    return {
+      success: false,
+      generatedFiles: [],
+      summary: { discovered: scan.sites.length, mapped: 0 },
+      warnings,
+      error: `The ${lexiconName} lexicon cannot express agent configuration (no agentConfigImporter). Try --lexicon ${DEFAULT_AGENT_LEXICON}.`,
+    };
+  }
+
+  const generator = plugin.templateGenerator?.();
+  if (!generator) {
+    return {
+      success: false,
+      generatedFiles: [],
+      summary: { discovered: scan.sites.length, mapped: 0 },
+      warnings,
+      error: `The ${lexiconName} lexicon has no templateGenerator, so it cannot emit TypeScript.`,
+    };
+  }
+
+  const outcome = importer.toTemplateIR(scan.sites);
+
+  for (const skip of outcome.skipped) warnings.push(`Skipped ${skip.siteId}: ${skip.reason}`);
+  if (outcome.unmappedModel.length > 0) {
+    warnings.push(
+      `No model was pinned in the local config for ${outcome.unmappedModel.join(", ")}; a default was written. Edit it before applying.`,
+    );
+  }
+  if (outcome.redactedSecrets.length > 0) {
+    warnings.push(
+      `Literal credentials in ${outcome.redactedSecrets.join(", ")} were replaced with \`\${VAR}\` references — the values were NOT copied into the generated code. Supply them via a Vault or the environment.`,
+    );
+  }
+
+  if (outcome.ir.resources.length === 0) {
+    return {
+      success: false,
+      generatedFiles: [],
+      summary: { discovered: scan.sites.length, mapped: 0 },
+      outcome,
+      warnings,
+      error: `Found ${scan.sites.length} agent config(s), but none could be expressed as ${lexiconName} resources.`,
+    };
+  }
+
+  const files = generator.generate(outcome.ir);
+
+  const existing = files.map((f) => join(outputDir, f.path)).filter((p) => existsSync(p));
+  if (existing.length > 0 && !opts.force) {
+    return {
+      success: false,
+      generatedFiles: [],
+      summary: { discovered: scan.sites.length, mapped: outcome.ir.resources.length },
+      outcome,
+      warnings,
+      error: `Refusing to overwrite ${existing.join(", ")}. Re-run with --force to replace.`,
+    };
+  }
+
+  const generatedFiles: string[] = [];
+  try {
+    mkdirSync(outputDir, { recursive: true });
+    for (const file of files) {
+      const full = join(outputDir, file.path);
+      writeFileSync(full, file.content, "utf-8");
+      generatedFiles.push(full);
+    }
+  } catch (err) {
+    return {
+      success: false,
+      generatedFiles,
+      summary: { discovered: scan.sites.length, mapped: outcome.ir.resources.length },
+      outcome,
+      warnings,
+      error: `Failed to write generated files: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  return {
+    success: true,
+    generatedFiles,
+    summary: { discovered: scan.sites.length, mapped: outcome.ir.resources.length },
+    outcome,
+    warnings,
+  };
+}

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

@@ -16,6 +16,8 @@ export async function runCarveEmit(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
 
   // Load plugins only for the live path; the offline --state path needs none.
+  // aws is the only lexicon emit can adopt into (`canCarveEmit`), so it is the
+  // only one loaded here.
   let plugins = ctx.plugins;
   if (!args.statePath && args.env) {
     try {