@intentius/chant 0.52.1 → 0.52.2

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

@@ -0,0 +1,260 @@
+/**
+ * The command's job is to keep `chant audit --agents` reading like a chant
+ * audit report while auditing a different subject, and to be honest about the
+ * edges of what it scanned.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, writeFileSync, rmSync, readFileSync } from "fs";
+import { join } from "path";
+import { fileURLToPath } from "url";
+import { tmpdir } from "os";
+import Ajv from "ajv";
+import { auditAgentsCommand, toAuditFindings, siteSummary } from "./audit-agents";
+import type { AgentConfigSite } from "../../agents/types";
+
+let home: string;
+let project: 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-aa-home-${Math.random().toString(36).slice(2)}`);
+  project = join(tmpdir(), `chant-aa-proj-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(home, { recursive: true });
+  mkdirSync(project, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(home, { recursive: true, force: true });
+  rmSync(project, { recursive: true, force: true });
+});
+
+const run = (opts: Parameters<typeof auditAgentsCommand>[0] = {}) =>
+  auditAgentsCommand({ home, projectRoots: [project], platform: "linux", now: "2026-01-01T00:00:00Z", toolVersion: "1.2.3", ...opts });
+
+/** A config with one unpinned MCP server — an AGT001 error. */
+function seedUnpinned(): void {
+  writeIn(home, ".claude/mcp.json", JSON.stringify({ mcpServers: { a: { command: "npx", args: ["-y", "floating-server"] } } }));
+}
+
+describe("toAuditFindings", () => {
+  test("projects an agent finding onto the shared audit shape", () => {
+    const [f] = toAuditFindings([
+      { checkId: "AGT001", severity: "error", message: "m", file: "/f", siteId: "user-claude", scope: "user", runtime: "claude", entity: "srv" },
+    ]);
+    expect(f).toEqual({ checkId: "AGT001", severity: "error", message: "m", file: "/f", lexicon: "agents", entity: "user-claude › srv" });
+  });
+
+  test("falls back to the site id when a finding names no entity", () => {
+    const [f] = toAuditFindings([
+      { checkId: "AGT005", severity: "error", message: "m", file: "/f", siteId: "user-claude", scope: "user", runtime: "claude" },
+    ]);
+    expect(f.entity).toBe("user-claude");
+  });
+});
+
+describe("siteSummary", () => {
+  test("pluralizes and omits empty categories", () => {
+    const base: AgentConfigSite = {
+      id: "x", scope: "user", runtime: "claude", root: "/", sources: [],
+      instructions: [{ path: "/a", content: "x", bytes: 1 }],
+      mcpServers: [{ name: "a", transport: "stdio", source: "/c" }],
+      skills: [], subagents: [], commands: [], plugins: [], env: {}, settings: {},
+    };
+    expect(siteSummary(base)).toBe("1 instruction file · 1 MCP server");
+  });
+
+  test("says so when a site carries nothing", () => {
+    const empty: AgentConfigSite = {
+      id: "x", scope: "user", runtime: "claude", root: "/", sources: [],
+      instructions: [], mcpServers: [], skills: [], subagents: [], commands: [], plugins: [], env: {}, settings: {},
+    };
+    expect(siteSummary(empty)).toBe("no content");
+  });
+});
+
+describe("stylish output", () => {
+  test("leads with the inventory, so a clean machine still reports what is configured", () => {
+    writeIn(home, "CLAUDE.md", "be brief");
+    const result = run();
+    expect(result.output).toContain("Found 1 agent config");
+    expect(result.output).toContain("user:");
+    expect(result.output).toContain("1 instruction file");
+  });
+
+  test("says plainly when nothing is configured", () => {
+    expect(run().output).toContain("No agent configuration found.");
+  });
+
+  test("separates merge-worthy from report-only", () => {
+    seedUnpinned();
+    const output = run().output;
+    expect(output).toContain("Merge-worthy:");
+    expect(output).toContain("AGT001");
+  });
+});
+
+describe("coverage notes", () => {
+  test("reports registered projects it did not visit", () => {
+    const a = join(project, "a");
+    const b = join(project, "b");
+    mkdirSync(a, { recursive: true });
+    mkdirSync(b, { recursive: true });
+    writeIn(home, ".claude.json", JSON.stringify({ projects: { [a]: {}, [b]: {} } }));
+    writeIn(home, "CLAUDE.md", "x");
+    expect(run().output).toContain("2 more are registered in ~/.claude.json");
+  });
+
+  test("does not count registrations whose directory is gone", () => {
+    // A deleted project is not a gap the user can close, so counting it would
+    // overstate what the scan missed.
+    writeIn(home, ".claude.json", JSON.stringify({ projects: { "/definitely/not/here": {} } }));
+    writeIn(home, "CLAUDE.md", "x");
+    expect(run().output).not.toContain("registered in ~/.claude.json");
+  });
+
+  test("reports a file it could not parse", () => {
+    writeIn(home, ".claude/settings.json", "{ broken");
+    writeIn(home, "CLAUDE.md", "x");
+    expect(run().output).toContain("could not be parsed");
+  });
+
+  test("names the scopes it was told to skip", () => {
+    writeIn(home, "CLAUDE.md", "x");
+    expect(run({ scopes: ["user"] }).output).toContain("Scopes not scanned: system, project");
+  });
+
+  test("points at --all-projects when projects were missed", () => {
+    writeIn(home, ".claude.json", JSON.stringify({ projects: { [home]: {} } }));
+    writeIn(home, "CLAUDE.md", "x");
+    expect(run().output).toContain("--all-projects");
+  });
+
+  test("states the breadth when many roots were scanned and none were missed", () => {
+    // With --all-projects there is no gap to report, but "5 findings" reads very
+    // differently across one project than across sixty-five.
+    const a = join(project, "a");
+    const b = join(project, "b");
+    mkdirSync(a, { recursive: true });
+    mkdirSync(b, { recursive: true });
+    writeIn(a, "CLAUDE.md", "x");
+    const output = run({ projectRoots: [a, b] }).output;
+    expect(output).toContain("Scanned 2 project roots");
+    expect(output).not.toContain("--all-projects");
+  });
+});
+
+describe("tier and fail-on", () => {
+  test("--tier merge-worthy drops report-only findings", () => {
+    seedUnpinned();
+    const all = run({ tier: "all" }).findings.length;
+    const mw = run({ tier: "merge-worthy" }).findings;
+    expect(mw.length).toBeLessThan(all);
+    expect(mw.every((f) => f.checkId !== "AGT006")).toBe(true);
+  });
+
+  test("exit code is 0 by default even with findings — the scan is read-only friendly", () => {
+    seedUnpinned();
+    expect(run().exitCode).toBe(0);
+  });
+
+  test("--fail-on merge-worthy exits 1 when a merge-worthy finding exists", () => {
+    seedUnpinned();
+    expect(run({ failOn: "merge-worthy" }).exitCode).toBe(1);
+  });
+
+  test("--fail-on merge-worthy exits 0 on a clean machine", () => {
+    expect(run({ failOn: "merge-worthy" }).exitCode).toBe(0);
+  });
+});
+
+describe("formats", () => {
+  test("json carries the full inventory alongside the findings", () => {
+    seedUnpinned();
+    const report = JSON.parse(run({ format: "json" }).output);
+    expect(report.subject).toBe("agent-configuration");
+    expect(report.tool.version).toBe("1.2.3");
+    expect(report.sites[0].id).toBe("user-claude");
+    expect(report.sites[0].mcpServers[0].name).toBe("a");
+    expect(report.coverage.probed.length).toBeGreaterThan(0);
+  });
+
+  test("json reports env var names, never their values", () => {
+    writeIn(home, ".claude/settings.json", JSON.stringify({ env: { SECRET_THING: "hunter2" } }));
+    const report = JSON.parse(run({ format: "json" }).output);
+    expect(report.sites[0].env).toEqual(["SECRET_THING"]);
+    expect(run({ format: "json" }).output).not.toContain("hunter2");
+  });
+
+  test("sarif is valid and links each rule to its docs anchor", () => {
+    seedUnpinned();
+    const sarif = JSON.parse(run({ format: "sarif" }).output);
+    expect(sarif.version).toBe("2.1.0");
+    const rule = sarif.runs[0].tool.driver.rules.find((r: { id: string }) => r.id === "AGT001");
+    expect(rule.helpUri).toBe("https://intentius.io/chant/lint-rules/audit-rules/#agt001");
+  });
+
+  test("sarif carries the same tier/dimension property bag the repository audit emits (#442, #444)", () => {
+    seedUnpinned();
+    const sarif = JSON.parse(run({ format: "sarif" }).output) as {
+      runs: Array<{
+        tool: { driver: { rules: Array<{ id: string; help?: { text: string }; properties?: { category?: string; dimension?: string } }> } };
+        results: Array<{ ruleId: string; properties?: { tier?: string } }>;
+      }>;
+    };
+    const one = sarif.runs[0];
+    expect(one.results.length).toBeGreaterThan(0);
+    for (const r of one.results) expect(r.properties?.tier).toMatch(/^(merge-worthy|report-only)$/);
+    expect(one.tool.driver.rules.length).toBeGreaterThan(0);
+    for (const rule of one.tool.driver.rules) {
+      expect(rule.properties?.category).toMatch(/^(security|correctness|best-practice|efficiency)$/);
+      expect(rule.properties?.dimension).toBe(rule.properties?.category);
+      expect(rule.help?.text.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("sarif validates against the real, vendored SARIF 2.1.0 JSON Schema", () => {
+    seedUnpinned();
+    const schemaPath = fileURLToPath(new URL("./__fixtures__/schemas/sarif-2.1.0.schema.json", import.meta.url));
+    const ajv = new Ajv({ strict: false, allErrors: true });
+    const validate = ajv.compile(JSON.parse(readFileSync(schemaPath, "utf-8")) as object);
+    const valid = validate(JSON.parse(run({ format: "sarif" }).output));
+    if (!valid) throw new Error(ajv.errorsText(validate.errors));
+    expect(valid).toBe(true);
+  });
+
+  test("markdown and html render without throwing", () => {
+    seedUnpinned();
+    expect(run({ format: "markdown" }).output).toContain("# Agent configuration audit");
+    expect(run({ format: "html" }).output).toContain("<html");
+  });
+
+  test("markdown is one document — the embedded findings report is a section, not a second H1", () => {
+    seedUnpinned();
+    const md = run({ format: "markdown" }).output;
+    expect(md.split("\n").filter((l) => /^# /.test(l))).toEqual(["# Agent configuration audit"]);
+    expect(md).toContain("## Inventory");
+    expect(md).toContain("## Findings");
+  });
+});
+
+describe("--output", () => {
+  test("writes the report to a file instead of returning it for stdout", () => {
+    writeIn(home, "CLAUDE.md", "x");
+    const out = join(project, "report.md");
+    const result = run({ format: "markdown", output: out });
+    expect(result.wroteTo).toBe(out);
+    expect(readFileSync(out, "utf-8")).toContain("Agent configuration audit");
+  });
+
+  test("reports a write failure instead of throwing", () => {
+    const result = run({ output: join(project, "no", "such", "dir", "r.txt") });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Failed to write");
+  });
+});

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

@@ -0,0 +1,387 @@
+/**
+ * `chant audit --agents` — audit the agent configuration on this machine.
+ *
+ * This is a different *subject* from the rest of `chant audit` (a machine, not
+ * a repo) but deliberately the same *product*: the same tiering, the same
+ * five output formats, the same rule-catalog links. A reader who already knows
+ * how to read a chant audit report can read this one, and the HTML/SARIF/JSON
+ * consumers downstream need no changes.
+ *
+ * The bridge is {@link toAuditFindings}: an `AgentFinding` is projected onto
+ * the `AuditFinding` shape the renderers already take, with the site id in
+ * `entity` so a reader can tell which configuration a finding came from.
+ *
+ * Two things this command adds that a repo audit has no need for:
+ *
+ *  - **An inventory.** "What is configured on this machine" is the primary
+ *    question here; findings are secondary. A clean scan should still print
+ *    the sites it found, because most users have never seen the full list.
+ *  - **Coverage honesty.** The scan probes a fixed set of locations, so it can
+ *    state what it looked for and didn't find, what it couldn't parse, and how
+ *    many registered projects it did not visit. An inventory that quietly
+ *    omits half the machine is worse than no inventory.
+ */
+
+import { writeFileSync } from "fs";
+import { homedir } from "os";
+import { resolve } from "path";
+import { scanAgentConfigs, unscannedProjectCount } from "../../agents/discover";
+import { checkAgentConfigs } from "../../agents/checks";
+import type { AgentConfigSite, AgentFinding, AgentRuntime, AgentScanResult, AgentScope } from "../../agents/types";
+import { AGENT_RUNTIMES, AGENT_SCOPES } from "../../agents/types";
+import type { AuditFinding } from "../../audit/core";
+import { RULE_CATALOG, ruleDocUrl, type RuleMeta } from "../../audit/catalog";
+import { renderMarkdown } from "../../audit/report";
+import { renderHtml, type ReportTheme } from "../../audit/report-html";
+import { buildReportJson, type AuditSnapshot } from "../../audit/report-model";
+import type { AuditFailOn, AuditFormat, AuditTier } from "./audit";
+
+export interface AuditAgentsOptions {
+  format?: AuditFormat;
+  tier?: AuditTier;
+  failOn?: AuditFailOn;
+  /** Scopes to scan. Defaults to all three. */
+  scopes?: readonly AgentScope[];
+  /** Harnesses to scan. Defaults to all five. */
+  runtimes?: readonly AgentRuntime[];
+  /** Project roots to scan at project scope. Defaults to `[cwd]`. */
+  projectRoots?: string[];
+  /** Home directory override — injectable so tests scan a fixture tree. */
+  home?: string;
+  platform?: NodeJS.Platform;
+  /** Write the report here instead of returning it for stdout. */
+  output?: string;
+  theme?: ReportTheme;
+  template?: string;
+  now?: string;
+  toolVersion?: string;
+}
+
+export interface AuditAgentsResult {
+  success: boolean;
+  output: string;
+  findings: AgentFinding[];
+  scan: AgentScanResult;
+  exitCode: number;
+  wroteTo?: string;
+  error?: string;
+}
+
+/**
+ * Project an agent finding onto the audit renderers' finding shape.
+ *
+ * `lexicon` is set to `"agents"` — the renderers only use it as a grouping
+ * label, and calling this family what it is keeps a mixed report readable.
+ */
+export function toAuditFindings(findings: AgentFinding[]): AuditFinding[] {
+  return findings.map((f) => ({
+    checkId: f.checkId,
+    severity: f.severity,
+    message: f.message,
+    file: f.file,
+    lexicon: "agents",
+    entity: f.entity ? `${f.siteId} › ${f.entity}` : f.siteId,
+  }));
+}
+
+function isMergeWorthy(f: AuditFinding, catalog: Record<string, RuleMeta>): boolean {
+  return catalog[f.checkId]?.tier === "merge-worthy";
+}
+
+function exitCodeFor(findings: AuditFinding[], failOn: AuditFailOn, catalog: Record<string, RuleMeta>): number {
+  if (failOn === "merge-worthy") return findings.some((f) => isMergeWorthy(f, catalog)) ? 1 : 0;
+  if (failOn === "warning") return findings.some((f) => f.severity === "error" || f.severity === "warning") ? 1 : 0;
+  return 0;
+}
+
+/** One-line summary of what a site carries, e.g. `3 MCP servers · 11 skills`. */
+export function siteSummary(site: AgentConfigSite): string {
+  const parts: string[] = [];
+  const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+  if (site.instructions.length > 0) parts.push(plural(site.instructions.length, "instruction file"));
+  if (site.mcpServers.length > 0) parts.push(plural(site.mcpServers.length, "MCP server"));
+  if (site.skills.length > 0) parts.push(plural(site.skills.length, "skill"));
+  if (site.subagents.length > 0) parts.push(plural(site.subagents.length, "subagent"));
+  if (site.commands.length > 0) parts.push(plural(site.commands.length, "command"));
+  if (site.plugins.length > 0) parts.push(plural(site.plugins.length, "plugin"));
+  const envCount = Object.keys(site.env).length;
+  if (envCount > 0) parts.push(plural(envCount, "env var"));
+  if (site.model) parts.push(`model ${site.model}`);
+  return parts.length > 0 ? parts.join(" · ") : "no content";
+}
+
+/**
+ * Coverage caveats. Stated even when empty-ish, because the value of an
+ * inventory depends entirely on the reader knowing its edges.
+ */
+export function agentCoverageNotes(scan: AgentScanResult, opts: { home: string; projectRoots: string[]; scopes: readonly AgentScope[] }): string[] {
+  const notes: string[] = [];
+
+  if (opts.scopes.includes("project")) {
+    const roots = opts.projectRoots.length;
+    const unscanned = unscannedProjectCount(opts.home, opts.projectRoots);
+    if (unscanned > 0) {
+      notes.push(
+        `Scanned ${roots} project root${roots === 1 ? "" : "s"}; ` +
+          `${unscanned} more ${unscanned === 1 ? "is" : "are"} registered in ~/.claude.json and ${unscanned === 1 ? "was" : "were"} not visited. ` +
+          // The path is positional (`chant audit <path>`), not a `--path` flag.
+          `Scan one with \`chant audit --agents --scope project <dir>\`, or all of them with \`--all-projects\`.`,
+      );
+    } else if (roots > 1) {
+      // Breadth is worth stating even when nothing was missed — a reader
+      // seeing four findings should know whether that was across one project
+      // or sixty-five.
+      notes.push(`Scanned ${roots} project roots — every project registered in ~/.claude.json whose directory still exists.`);
+    }
+  }
+
+  if (scan.unreadable.length > 0) {
+    notes.push(
+      `${scan.unreadable.length} file${scan.unreadable.length === 1 ? "" : "s"} existed but could not be parsed, so ` +
+        `${scan.unreadable.length === 1 ? "its" : "their"} contents are not covered: ` +
+        scan.unreadable.map((u) => `${u.path} (${u.reason})`).join("; "),
+    );
+  }
+
+  const skippedScopes = AGENT_SCOPES.filter((s) => !opts.scopes.includes(s));
+  if (skippedScopes.length > 0) notes.push(`Scope${skippedScopes.length === 1 ? "" : "s"} not scanned: ${skippedScopes.join(", ")}.`);
+
+  return notes;
+}
+
+/** Render the inventory section — what was found, before any judgement about it. */
+function renderInventory(scan: AgentScanResult): string[] {
+  const lines: string[] = [];
+  if (scan.sites.length === 0) {
+    lines.push("No agent configuration found.");
+    return lines;
+  }
+  lines.push(`Found ${scan.sites.length} agent config${scan.sites.length === 1 ? "" : "s"}:`);
+  let lastScope: AgentScope | undefined;
+  for (const site of scan.sites) {
+    if (site.scope !== lastScope) {
+      lines.push("", `  ${site.scope}:`);
+      lastScope = site.scope;
+    }
+    lines.push(`    ${site.runtime.padEnd(9)} ${site.root}`);
+    lines.push(`      ${siteSummary(site)}`);
+    lines.push(`      from ${site.sources.length} file${site.sources.length === 1 ? "" : "s"}`);
+  }
+  return lines;
+}
+
+function renderStylish(scan: AgentScanResult, findings: AuditFinding[], notes: string[], catalog: Record<string, RuleMeta>): string {
+  const lines: string[] = [...renderInventory(scan), ""];
+
+  for (const note of notes) lines.push(`Note: ${note}`);
+  if (notes.length > 0) lines.push("");
+
+  const mw = findings.filter((f) => isMergeWorthy(f, catalog));
+  const ro = findings.filter((f) => !isMergeWorthy(f, catalog));
+  lines.push(`${findings.length} finding${findings.length === 1 ? "" : "s"} (${mw.length} merge-worthy, ${ro.length} report-only).`);
+
+  const section = (title: string, list: AuditFinding[]) => {
+    if (list.length === 0) return;
+    lines.push("", title);
+    for (const f of list) {
+      lines.push(`  [${f.checkId}] ${f.severity}  ${f.entity}`);
+      lines.push(`    ${f.message}`);
+      lines.push(`    ${f.file}`);
+    }
+  };
+  section("Merge-worthy:", mw);
+  section("Report-only:", ro);
+  return lines.join("\n");
+}
+
+/**
+ * Provenance for the machine-readable and HTML reports. `target` is the home
+ * directory rather than a repo URL, and `files` lists the config sources that
+ * contributed — the machine-scope analogue of "which workflow files were read".
+ */
+function buildSnapshot(scan: AgentScanResult, home: string, opts: AuditAgentsOptions): AuditSnapshot {
+  return {
+    target: home,
+    files: scan.sites.flatMap((s) => s.sources),
+    generatedAt: opts.now ?? new Date().toISOString(),
+    toolVersion: opts.toolVersion ?? "0.0.0",
+  };
+}
+
+/** The JSON report: the full inventory plus findings, so a consumer can do its own analysis. */
+function renderJson(
+  scan: AgentScanResult,
+  agentFindings: AgentFinding[],
+  findings: AuditFinding[],
+  notes: string[],
+  catalog: Record<string, RuleMeta>,
+  snapshot: AuditSnapshot,
+): string {
+  const base = buildReportJson(findings, { snapshot, toolVersion: snapshot.toolVersion, catalog });
+  return JSON.stringify(
+    {
+      ...base,
+      subject: "agent-configuration",
+      notes,
+      sites: scan.sites.map((site) => ({
+        id: site.id,
+        scope: site.scope,
+        runtime: site.runtime,
+        root: site.root,
+        sources: site.sources,
+        summary: siteSummary(site),
+        instructions: site.instructions.map((i) => ({ path: i.path, bytes: i.bytes })),
+        mcpServers: site.mcpServers,
+        skills: site.skills.map((s) => ({ name: s.name, origin: s.origin, path: s.path, source: s.source, ref: s.ref })),
+        subagents: site.subagents,
+        commands: site.commands,
+        plugins: site.plugins,
+        env: Object.keys(site.env),
+        permissions: site.permissions,
+        model: site.model,
+      })),
+      agentFindings,
+      coverage: { probed: scan.probed, unreadable: scan.unreadable },
+    },
+    null,
+    2,
+  );
+}
+
+/**
+ * SARIF (2.1.0) export for the agent scan. Same property bag the repository
+ * audit emits (#442, #444) — `category`/`dimension` per rule and `tier` per
+ * result — so a consumer that triages one SARIF file can triage the other
+ * without special-casing the driver. `helpUri` points at the rule's own docs
+ * anchor rather than its authority citation: an AGT finding is about a local
+ * file, and the chant page is what explains what to do with it.
+ */
+function renderSarif(findings: AuditFinding[], catalog: Record<string, RuleMeta>): string {
+  const ids = [...new Set(findings.map((f) => f.checkId))].sort();
+  return JSON.stringify(
+    {
+      $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+      version: "2.1.0",
+      runs: [
+        {
+          tool: {
+            driver: {
+              name: "chant audit --agents",
+              informationUri: "https://intentius.io/chant/cli/audit/",
+              rules: ids.map((id) => {
+                const m = catalog[id];
+                return {
+                  id,
+                  name: m?.title ?? id,
+                  shortDescription: { text: m?.title ?? id },
+                  fullDescription: { text: m?.remediation ?? "" },
+                  ...(m?.remediation ? { help: { text: m.remediation } } : {}),
+                  helpUri: ruleDocUrl(id),
+                  ...(m?.category ? { properties: { category: m.category, dimension: m.category } } : {}),
+                };
+              }),
+            },
+          },
+          results: findings.map((f) => {
+            const tier = catalog[f.checkId]?.tier;
+            return {
+              ruleId: f.checkId,
+              level: f.severity === "error" ? "error" : f.severity === "warning" ? "warning" : "note",
+              message: { text: f.message },
+              locations: [{ physicalLocation: { artifactLocation: { uri: f.file } } }],
+              ...(tier ? { properties: { tier } } : {}),
+            };
+          }),
+        },
+      ],
+    },
+    null,
+    2,
+  );
+}
+
+/**
+ * Scan the machine's agent configuration and render a report.
+ *
+ * Pure with respect to the filesystem apart from the scan itself and an
+ * optional `--output` write, so it can be driven from tests against a fixture
+ * home directory.
+ */
+export function auditAgentsCommand(opts: AuditAgentsOptions = {}): AuditAgentsResult {
+  const home = opts.home ?? homedir();
+  const scopes = opts.scopes ?? AGENT_SCOPES;
+  const runtimes = opts.runtimes ?? AGENT_RUNTIMES;
+  const projectRoots = (opts.projectRoots ?? [process.cwd()]).map((p) => resolve(p));
+  const format = opts.format ?? "stylish";
+  const tier = opts.tier ?? "all";
+  const failOn = opts.failOn ?? "none";
+  const catalog = RULE_CATALOG;
+
+  const scan = scanAgentConfigs({ scopes, runtimes, projectRoots, home, platform: opts.platform });
+  const all = checkAgentConfigs(scan);
+  const agentFindings = tier === "merge-worthy" ? all.filter((f) => catalog[f.checkId]?.tier === "merge-worthy") : all;
+  const findings = toAuditFindings(agentFindings);
+  const notes = agentCoverageNotes(scan, { home, projectRoots, scopes });
+
+  const snapshot = buildSnapshot(scan, home, opts);
+
+  let output: string;
+  switch (format) {
+    case "json":
+      output = renderJson(scan, agentFindings, findings, notes, catalog, snapshot);
+      break;
+    case "sarif":
+      output = renderSarif(findings, catalog);
+      break;
+    case "markdown":
+      output = [
+        "# Agent configuration audit",
+        "",
+        "## Inventory",
+        "",
+        "```",
+        renderInventory(scan).join("\n"),
+        "```",
+        "",
+        renderMarkdown(findings, { target: home, notes, catalog, title: "Findings", headingLevel: 2 }),
+      ].join("\n");
+      break;
+    case "html":
+      output = renderHtml(findings, {
+        notes,
+        catalog,
+        snapshot,
+        theme: opts.theme,
+        template: opts.template,
+      });
+      break;
+    default:
+      output = renderStylish(scan, findings, notes, catalog);
+  }
+
+  let wroteTo: string | undefined;
+  if (opts.output) {
+    try {
+      writeFileSync(opts.output, output, "utf-8");
+      wroteTo = opts.output;
+    } catch (err) {
+      return {
+        success: false,
+        output: "",
+        findings: agentFindings,
+        scan,
+        exitCode: 1,
+        error: `Failed to write ${opts.output}: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+
+  return {
+    success: true,
+    output,
+    findings: agentFindings,
+    scan,
+    exitCode: exitCodeFor(findings, failOn, catalog),
+    wroteTo,
+  };
+}

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

@@ -194,6 +194,36 @@ describe("carveBridge", () => {
     }
   });
 
+  test("refuses a target whose identity attribute is a dotted path (#2015)", async () => {
+    if (!parserAvailable) return;
+    const dir = mkdtempSync(join(tmpdir(), "chant-bridge-k8s-"));
+    try {
+      // `kubernetes_manifest` identifies itself by `manifest.metadata.name`.
+      // Rendering that into a data body produced `manifest.metadata.name = "x"`,
+      // which is not valid HCL — and the provider has no manifest data source.
+      writeFileSync(
+        join(dir, "main.tf"),
+        `resource "kubernetes_manifest" "demo" {\n` +
+          `  manifest = {\n` +
+          `    apiVersion = "v1"\n` +
+          `    kind       = "ConfigMap"\n` +
+          `    metadata = { name = "demo-config" }\n` +
+          `  }\n` +
+          `}\n`,
+      );
+      const out = join(dir, "carveout");
+      const res = await carveBridge({ from: dir, select: "kubernetes_manifest.demo", output: out });
+
+      expect(res.ok).toBe(false);
+      expect(res.error).toContain("cannot be bridged");
+      expect(res.error).toContain("manifest.metadata.name");
+      expect(res.plan).toBeUndefined();
+      expect(existsSync(out)).toBe(false);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   test("formatCarveBridge summarizes data sources, rewires, and safety", async () => {
     if (!parserAvailable) return;
     await withEstate(async (dir) => {