@intentius/chant 0.124.12 → 0.124.14

package/dist/cli/build-params-cli.js

@@ -0,0 +1,139 @@
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import { resolveBuildParams } from "../build-params.js";
+import { formatError, formatInfo } from "./format.js";
+/**
+ * Shared CLI-layer wiring for chant #1064's build-time parameters, factored
+ * out (chant #1108) so every command that discovers project source before
+ * running it resolves `chant.config.ts`'s declared `buildParams` the exact
+ * same way: `chant build` (`../commands/build.ts`'s `buildCommand`), the
+ * component deploy driver (`./handlers/run.ts`'s `chant run --components`),
+ * and generate mode (`./handlers/build.ts`'s
+ * `chant build --components --generate <lexicon>`).
+ *
+ * Before #1108, only `buildCommand` ran this sequence — `chant run
+ * --components` never resolved `--param`/`--params-file`/a declared `env`
+ * mapping at all, so a `*.component.ts` file reading `params.<name>`
+ * (`@intentius/chant/params`) always saw `{}`, no matter what a CI job
+ * exported into the environment. See ../build-params.ts's module doc for the
+ * full precedence rules this wraps.
+ */
+/** Parse repeated `--param name=value` flags into a flat `{ name: value }` record — the raw (unvalidated) strings {@link resolveCliBuildParams} resolves against a project's declared `buildParams`. `undefined` when no `--param` flag was given, matching `resolveBuildParams`'s "no cli input" shape. */
+export function parseParamFlags(entries) {
+    if (!entries?.length)
+        return undefined;
+    return Object.fromEntries(entries.map((entry) => {
+        const eq = entry.indexOf("=");
+        return eq === -1 ? [entry, ""] : [entry.slice(0, eq), entry.slice(eq + 1)];
+    }));
+}
+/**
+ * Resolve this invocation's declared build-time parameters (`chant.config.ts`'s
+ * `buildParams`) against `args`/the process environment, and log each
+ * resolved value — the identical resolution + logging sequence `chant build`
+ * runs (`../commands/build.ts`'s `buildCommand`), factored out so every other
+ * command that discovers project source runs it too (chant #1108).
+ *
+ * A resolution failure (an unknown `--param`/`--params-file` name, a missing
+ * required value, a type/enum mismatch, or an unreadable `--params-file`) is
+ * returned as `{ success: false, errors }` — never thrown — so the caller can
+ * print each message and exit non-zero exactly like a build error, matching
+ * chant #1064's acceptance criterion that this never surfaces as a thrown
+ * error from inside user source.
+ *
+ * On success, the resolution is summarized on one `console.error` line —
+ * `N build parameters resolved (a default, b from cli, ...); --verbose to
+ * list` — so silence never means "no parameters reached us", and the count
+ * by source says whether an override arrived. Under `--verbose` (or
+ * `CHANT_PARAM_ECHO=all`) every parameter is listed as
+ * `[param] <name> = <value> (<source>)` instead (#1424).
+ */
+export function resolveCliBuildParams(buildParamsConfig, args) {
+    const errors = [];
+    let fromFile;
+    if (args.paramsFile) {
+        try {
+            fromFile = JSON.parse(readFileSync(resolve(args.paramsFile), "utf-8"));
+        }
+        catch (err) {
+            errors.push(formatError({
+                message: `Failed to read/parse --params-file "${args.paramsFile}": ${err instanceof Error ? err.message : String(err)}`,
+            }));
+        }
+    }
+    const resolution = resolveBuildParams(buildParamsConfig, {
+        cli: args.cli,
+        fromFile,
+        env: process.env,
+    });
+    for (const message of resolution.errors) {
+        errors.push(formatError({ message }));
+    }
+    if (errors.length > 0) {
+        return { success: false, provenance: [], errors };
+    }
+    // #1424 — one line by default. A project with two dozen declared
+    // parameters printed two dozen grey lines on every build, ahead of the
+    // warnings the reader actually needed. The count by source still answers
+    // "did my override reach the build" (the failure mode
+    // warnIfParamsCannotReachProject exists for); --verbose names every value.
+    const verbose = args.verbose === true || process.env.CHANT_PARAM_ECHO === "all";
+    if (verbose) {
+        for (const p of resolution.provenance) {
+            console.error(formatInfo(`[param] ${p.name} = ${JSON.stringify(p.value)} (${p.source})`));
+        }
+    }
+    else if (resolution.provenance.length > 0) {
+        console.error(formatInfo(summarizeBuildParams(resolution.provenance)));
+    }
+    return { success: true, provenance: resolution.provenance, errors: [] };
+}
+/**
+ * `N build parameters resolved (1 from cli, 3 default); --verbose to list` —
+ * the non-verbose echo of a successful resolution (#1424). Sources appear in
+ * precedence order; a source nobody used is left out.
+ */
+export function summarizeBuildParams(provenance) {
+    const counts = new Map();
+    for (const p of provenance)
+        counts.set(p.source, (counts.get(p.source) ?? 0) + 1);
+    const order = ["cli", "params-file", "env", "default"];
+    const rank = (s) => (order.includes(s) ? order.indexOf(s) : order.length);
+    const parts = [...counts.keys()]
+        .sort((a, b) => rank(a) - rank(b))
+        .map((source) => (source === "default" ? `${counts.get(source)} default` : `${counts.get(source)} from ${source}`));
+    const n = provenance.length;
+    return `${n} build parameter${n === 1 ? "" : "s"} resolved (${parts.join(", ")}); --verbose to list`;
+}
+/**
+ * Resolve a command's declared build-time parameters, the same way `chant
+ * build` does, so a `build()`/`discover()` on the declared side sees the values
+ * the source will actually read.
+ *
+ * Every command that reads declared source needs this and only `chant build`
+ * had it. `chant graph` was fixed in #1483; the lifecycle family — `diff`,
+ * `snapshot`, `plan`, and `components status --live` — built the declared side
+ * on parameter *defaults* while the live side was whatever is really deployed.
+ *
+ * For a project whose parameters choose which resources *exist* that is not a
+ * near miss. `chant lifecycle diff dev --live` on kubemicrovm-ops returned
+ * byte-identical output at `KMV_TIER=minimal` and `KMV_TIER=prod-ha`, and
+ * reported the tier label itself as drift — `minimal → prod-ha`, declared
+ * against live — which is the comparison announcing it is against the wrong
+ * declaration.
+ *
+ * Returns `undefined` when resolution failed, having printed why: the caller
+ * should stop rather than compare against source that will not build.
+ */
+export async function commandBuildParams(buildParamsConfig, args) {
+    const resolution = resolveCliBuildParams(buildParamsConfig, {
+        cli: parseParamFlags(args.param),
+        paramsFile: args.paramsFile,
+    });
+    if (!resolution.success) {
+        for (const message of resolution.errors)
+            console.error(message);
+        return undefined;
+    }
+    return resolution.provenance;
+}

package/dist/cli/command-group.js

@@ -0,0 +1,123 @@
+/**
+ * Top-level command words core's own static registry already owns
+ * (`packages/core/src/cli/main.ts`'s `registry`). A lexicon's `commands()`
+ * group name colliding with one of these is always unreachable — core's own
+ * registry is resolved first, unconditionally — so `checkConflicts`
+ * (./conflict-check.ts) treats a collision as a hard, loud failure at
+ * plugin-load time rather than a silently-ignored command group. Hand
+ * maintained alongside the registry; update both together.
+ *
+ * `workspace` is reserved before core has the command (#2529, #2524 D12), so
+ * no lexicon can claim the word first and later be shadowed by it. Only a
+ * command-group name is reserved: a lexicon's own config field or flag
+ * called `workspace` (the terraform lexicon's root config has one) is
+ * untouched.
+ */
+export const RESERVED_COMMAND_NAMES = new Set([
+    "build", "lint", "list", "describe", "import", "audit", "migrate", "carve",
+    "init", "update", "doctor", "dev", "run", "graph", "vendor", "lifecycle",
+    "lc", "components", "emulator", "serve", "operator", "approve",
+    "workspace",
+]);
+/**
+ * chant #1127 — split a joined `--flag=value` token into two array elements
+ * (`--flag`, `value`), the same discipline core's own `parseArgs` applies,
+ * generalized so a lexicon's mounted command can reuse it for its own flag
+ * vocabulary instead of reimplementing the split. Throws the same shape of
+ * error as core's parser when `flag` is declared boolean but was given a
+ * value — a boolean has nothing to assign, and silently reinterpreting the
+ * joined value as the next positional would be exactly the silent misparse
+ * #1127 closed for core's own flags.
+ */
+export function splitJoinedFlags(args, booleanFlags = new Set()) {
+    const out = [];
+    for (const arg of args) {
+        if (arg.startsWith("--") && arg.includes("=")) {
+            const eq = arg.indexOf("=");
+            const flag = arg.slice(0, eq);
+            const value = arg.slice(eq + 1);
+            if (booleanFlags.has(flag)) {
+                throw new Error(`${arg} — ${flag} is a boolean flag and does not take a value. Pass ${flag} on its own.`);
+            }
+            out.push(flag, value);
+        }
+        else {
+            out.push(arg);
+        }
+    }
+    return out;
+}
+/**
+ * Same "Unknown flag" error shape core's own `parseArgs` throws (#1127), for
+ * a mounted command's own flag vocabulary — core doesn't know that
+ * vocabulary, so it can't produce this error itself; the handler does, using
+ * this helper for a consistent message.
+ */
+export function unknownFlagError(flag, hint = `Run "chant --help" to see supported flags.`) {
+    return new Error(`Unknown flag: ${flag}\n${hint}`);
+}
+/**
+ * Find the plugin (if any) whose `commands()` group is named `groupName`,
+ * and the verb within it named `verbName`. Pure — does no I/O, calls
+ * `plugin.commands()` at most once per plugin (registration, not execution:
+ * this never invokes a verb's handler).
+ */
+export function resolveCommandGroupVerb(plugins, groupName, verbName) {
+    for (const plugin of plugins) {
+        const group = plugin.commands?.();
+        if (!group || group.name !== groupName)
+            continue;
+        if (verbName === undefined)
+            return { kind: "no-verb", group };
+        const command = group.commands.find((c) => c.name === verbName);
+        if (!command)
+            return { kind: "unknown-verb", group };
+        return { kind: "matched", plugin, group, command };
+    }
+    return { kind: "no-group" };
+}
+/** Every command group contributed by the given loaded plugins, in plugin order. */
+export function collectCommandGroups(plugins) {
+    const groups = [];
+    for (const plugin of plugins) {
+        const group = plugin.commands?.();
+        if (group)
+            groups.push(group);
+    }
+    return groups;
+}
+/**
+ * Resolve `groupName`/`verbName` against the loaded plugins and, if matched,
+ * run the verb's handler with `rawArgs`. Returns `{ kind: "no-group" }` when
+ * nothing claims `groupName` at all — the caller's cue to fall back to its
+ * own "unknown command" handling — and a printable usage error when the
+ * group matched but the verb didn't (or was omitted).
+ */
+export async function dispatchCommandGroup(plugins, groupName, verbName, rawArgs) {
+    const lookup = resolveCommandGroupVerb(plugins, groupName, verbName);
+    if (lookup.kind === "no-group")
+        return { kind: "no-group" };
+    if (lookup.kind === "matched") {
+        const exitCode = await lookup.command.handler({ verb: verbName, rawArgs });
+        return { kind: "ran", exitCode };
+    }
+    const verbs = lookup.group.commands.map((c) => `  ${c.name.padEnd(14)} ${c.description}`).join("\n");
+    const message = lookup.kind === "unknown-verb"
+        ? `Unknown ${groupName} subcommand: ${verbName}`
+        : `Usage: chant ${groupName} <verb> [args...]`;
+    return { kind: "usage-error", message, hint: `Available verbs:\n${verbs}` };
+}
+/**
+ * Render the `--help` section listing every lexicon-contributed command
+ * group. Empty string when there are none, so a caller can splice it in
+ * unconditionally without an extra length check.
+ */
+export function formatCommandGroupsHelp(groups) {
+    if (groups.length === 0)
+        return "";
+    const lines = groups.flatMap((g) => [
+        `  ${g.name.padEnd(20)}  ${g.description}`,
+        ...g.commands.map((c) => `    ${g.name} ${c.name.padEnd(Math.max(1, 17 - g.name.length))}${c.description}`),
+    ]);
+    return `Lexicon commands:\n${lines.join("\n")}\n`;
+}

package/dist/cli/commands/audit-agents.js

@@ -0,0 +1,326 @@
+/**
+ * `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.js";
+import { checkAgentConfigs } from "../../agents/checks.js";
+import { AGENT_RUNTIMES, AGENT_SCOPES } from "../../agents/types.js";
+import { RULE_CATALOG, ruleDocUrl } from "../../audit/catalog.js";
+import { renderMarkdown } from "../../audit/report.js";
+import { renderHtml } from "../../audit/report-html.js";
+import { buildReportJson } from "../../audit/report-model.js";
+/**
+ * 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) {
+    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, catalog) {
+    return catalog[f.checkId]?.tier === "merge-worthy";
+}
+function exitCodeFor(findings, failOn, catalog) {
+    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) {
+    const parts = [];
+    const plural = (n, one, 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, opts) {
+    const notes = [];
+    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) {
+    const lines = [];
+    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;
+    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, findings, notes, catalog) {
+    const lines = [...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, list) => {
+        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, home, opts) {
+    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, agentFindings, findings, notes, catalog, snapshot) {
+    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, catalog) {
+    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 = {}) {
+    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;
+    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;
+    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,
+    };
+}