toolmoat 0.0.0-stage → 0.1.0

package/dist/proxy/policy.d.ts

@@ -0,0 +1,72 @@
+import type { Finding } from '../types.js';
+import type { ToolDefinition } from './fingerprint.js';
+import type { FindingSummary, PendingReason, PinnedTool, ServerEntry } from './lockfile.js';
+/** enforce hides and blocks; warn only reports and records. */
+export type Mode = 'enforce' | 'warn';
+/** What happens to a tool that shows up on a server that is already pinned. */
+export type OnNew = 'block' | 'allow';
+export interface ToolInput {
+    name: string;
+    hash: string;
+    definition: ToolDefinition;
+    /** The pinned definition for this tool name, if there is one. */
+    pinned?: PinnedTool;
+    /** True while the server is being seen for the first time (trust on first use). */
+    firstUse: boolean;
+    onNew: OnNew;
+    /** Scans the definition. Called only when the tool does not match its pin. */
+    scan: () => Finding[];
+}
+interface DecisionBase {
+    name: string;
+    hash: string;
+    definition: ToolDefinition;
+}
+export type ToolDecision = 
+/** The definition matches its pin. */
+(DecisionBase & {
+    action: 'allow';
+})
+/** Not pinned yet and accepted: trust on first use, or --on-new allow. */
+ | (DecisionBase & {
+    action: 'pin';
+    why: 'first-use' | 'on-new-allow';
+    warnings: FindingSummary[];
+})
+/** Held for human review. */
+ | (DecisionBase & {
+    action: 'block';
+    reason: PendingReason;
+    findings: FindingSummary[];
+});
+/**
+ * Decides one tool. A tool that matches its pin is allowed without
+ * rescanning (a human or first use already accepted exactly this
+ * definition). A changed definition is always held. An unpinned tool with a
+ * high or critical finding is held as flagged even on first use or with
+ * --on-new allow; otherwise first use pins it and later arrivals follow onNew.
+ */
+export declare function decideTool(input: ToolInput): ToolDecision;
+/** High and critical findings keep an unpinned tool away from the model. */
+export declare function isBlocking(finding: {
+    severity: Finding['severity'];
+}): boolean;
+/** Medium findings let the tool through with a warning. */
+export declare function isWarning(finding: {
+    severity: Finding['severity'];
+}): boolean;
+/** Findings worth keeping in the lockfile: everything above info. */
+export declare function summarize(findings: readonly Finding[]): FindingSummary[];
+export interface ApplyContext {
+    command: string;
+    now: string;
+}
+/**
+ * Folds a list of decisions into a server's lock entry: pins accepted tools
+ * and records held ones as pending. A pending entry that already holds the
+ * same definition keeps its original detection time. Pure: returns a new entry.
+ */
+export declare function applyDecisions(current: ServerEntry | undefined, decisions: readonly ToolDecision[], ctx: ApplyContext): ServerEntry;
+/** Pinned tools that a complete listing no longer contains. */
+export declare function removedTools(entry: ServerEntry | undefined, listed: ReadonlySet<string>): string[];
+export {};

package/dist/proxy/policy.js

@@ -0,0 +1,86 @@
+import { atLeast } from '../types.js';
+import { getOwn, setOwn } from './canonical.js';
+/**
+ * Decides one tool. A tool that matches its pin is allowed without
+ * rescanning (a human or first use already accepted exactly this
+ * definition). A changed definition is always held. An unpinned tool with a
+ * high or critical finding is held as flagged even on first use or with
+ * --on-new allow; otherwise first use pins it and later arrivals follow onNew.
+ */
+export function decideTool(input) {
+    const base = { name: input.name, hash: input.hash, definition: input.definition };
+    if (input.pinned && input.pinned.hash === input.hash)
+        return { ...base, action: 'allow' };
+    const findings = summarize(input.scan());
+    if (input.pinned)
+        return { ...base, action: 'block', reason: 'changed', findings };
+    if (findings.some((f) => isBlocking(f)))
+        return { ...base, action: 'block', reason: 'flagged', findings };
+    if (input.firstUse)
+        return { ...base, action: 'pin', why: 'first-use', warnings: findings.filter(isWarning) };
+    if (input.onNew === 'allow')
+        return { ...base, action: 'pin', why: 'on-new-allow', warnings: findings.filter(isWarning) };
+    return { ...base, action: 'block', reason: 'new', findings };
+}
+/** High and critical findings keep an unpinned tool away from the model. */
+export function isBlocking(finding) {
+    return atLeast(finding.severity, 'high');
+}
+/** Medium findings let the tool through with a warning. */
+export function isWarning(finding) {
+    return atLeast(finding.severity, 'medium') && !isBlocking(finding);
+}
+/** Findings worth keeping in the lockfile: everything above info. */
+export function summarize(findings) {
+    return findings
+        .filter((f) => atLeast(f.severity, 'low'))
+        .map((f) => ({ ruleId: f.ruleId, severity: f.severity, message: f.message }));
+}
+/**
+ * Folds a list of decisions into a server's lock entry: pins accepted tools
+ * and records held ones as pending. A pending entry that already holds the
+ * same definition keeps its original detection time. Pure: returns a new entry.
+ */
+export function applyDecisions(current, decisions, ctx) {
+    const entry = current
+        ? { ...current, tools: { ...current.tools }, pending: { ...current.pending } }
+        : { command: ctx.command, firstSeen: ctx.now, updated: ctx.now, tools: {}, pending: {} };
+    let dirty = current === undefined || current.command !== ctx.command;
+    entry.command = ctx.command;
+    for (const decision of decisions) {
+        if (decision.action === 'pin') {
+            setOwn(entry.tools, decision.name, { hash: decision.hash, definition: decision.definition, pinnedAt: ctx.now });
+            delete entry.pending[decision.name];
+            dirty = true;
+        }
+        else if (decision.action === 'allow') {
+            // The server serves the pinned definition again, so a change recorded earlier is obsolete.
+            if (getOwn(entry.pending, decision.name) !== undefined) {
+                delete entry.pending[decision.name];
+                dirty = true;
+            }
+        }
+        else {
+            const existing = getOwn(entry.pending, decision.name);
+            if (existing && existing.hash === decision.hash && existing.reason === decision.reason)
+                continue;
+            setOwn(entry.pending, decision.name, {
+                hash: decision.hash,
+                definition: decision.definition,
+                detectedAt: existing?.hash === decision.hash ? existing.detectedAt : ctx.now,
+                reason: decision.reason,
+                findings: decision.findings,
+            });
+            dirty = true;
+        }
+    }
+    if (dirty)
+        entry.updated = ctx.now;
+    return dirty ? entry : current;
+}
+/** Pinned tools that a complete listing no longer contains. */
+export function removedTools(entry, listed) {
+    if (!entry)
+        return [];
+    return Object.keys(entry.tools).filter((name) => !listed.has(name)).sort();
+}

package/dist/proxy/proxy.d.ts

@@ -0,0 +1,18 @@
+import type { ProxyOptions } from './firewall.js';
+export type { ProxyOptions } from './firewall.js';
+export interface RunProxyOptions extends ProxyOptions {
+    /** The server executable as written in the client config, e.g. "npx". */
+    command: string;
+    args: readonly string[];
+    /** JSONL audit log; undefined disables auditing. */
+    auditPath?: string;
+}
+/** Writes one prefixed diagnostic line to stderr, the only place toolmoat may talk while proxying. */
+export declare function stderrDiag(message: string): void;
+/**
+ * Runs an MCP stdio server behind the firewall: spawns it, pumps
+ * newline-delimited JSON-RPC between this process's stdio and the server's,
+ * and resolves with the exit code to use (the server's own, or 1 when it
+ * could not start). stdout carries protocol messages only.
+ */
+export declare function runProxy(options: RunProxyOptions): Promise<number>;

package/dist/proxy/proxy.js

@@ -0,0 +1,237 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import { AuditLog } from './audit.js';
+import { Firewall } from './firewall.js';
+import { LineDecoder } from './framing.js';
+import { redactCommandLine } from './names.js';
+import { killServer, planSpawn } from './spawn.js';
+const NEWLINE = Buffer.from('\n');
+/** How long the server may keep running after the client closed stdin. */
+const STDIN_EOF_GRACE_MS = 5000;
+/** How long to wait for the server's last output after it exited. */
+const DRAIN_AFTER_EXIT_MS = 1500;
+const LOCK_POLL_MS = 1000;
+/** Writes one prefixed diagnostic line to stderr, the only place toolmoat may talk while proxying. */
+export function stderrDiag(message) {
+    try {
+        process.stderr.write(`[toolmoat] ${message}\n`);
+    }
+    catch {
+        // stderr is gone; nothing else to try.
+    }
+}
+/**
+ * Runs an MCP stdio server behind the firewall: spawns it, pumps
+ * newline-delimited JSON-RPC between this process's stdio and the server's,
+ * and resolves with the exit code to use (the server's own, or 1 when it
+ * could not start). stdout carries protocol messages only.
+ */
+export async function runProxy(options) {
+    const diag = options.diag ?? stderrDiag;
+    const audit = options.auditPath ? new AuditLog(options.auditPath, options.server, diag) : undefined;
+    let firewall;
+    try {
+        firewall = new Firewall({ ...options, diag, audit });
+    }
+    catch (error) {
+        diag(`${errorMessage(error)}. Fix or delete the lockfile; refusing to start '${options.server}' unverified.`);
+        await audit?.close();
+        return 1;
+    }
+    const plan = planSpawn(options.command, options.args, { platform: process.platform, env: process.env, cwd: process.cwd() });
+    if ('error' in plan) {
+        diag(`could not start MCP server '${options.server}': ${plan.error}`);
+        await audit?.close();
+        return 1;
+    }
+    audit?.write({ event: 'start', decision: options.mode ?? 'enforce', detail: redactCommandLine(options.commandLine) });
+    let child;
+    try {
+        child = spawn(plan.file, plan.args, {
+            stdio: ['pipe', 'pipe', 'inherit'],
+            env: process.env,
+            windowsHide: true,
+            windowsVerbatimArguments: plan.windowsVerbatimArguments,
+        });
+    }
+    catch (error) {
+        diag(`could not start MCP server '${options.server}': ${errorMessage(error)}`);
+        await audit?.close();
+        return 1;
+    }
+    return supervise(child, firewall, audit, diag, options);
+}
+function supervise(child, firewall, audit, diag, options) {
+    const clientIn = process.stdin;
+    const clientOut = process.stdout;
+    const serverIn = child.stdin;
+    const serverOut = child.stdout;
+    const fromClient = new LineDecoder();
+    const fromServer = new LineDecoder();
+    return new Promise((resolve) => {
+        let finished = false;
+        let signals = 0;
+        let graceTimer;
+        let clientPaused = false;
+        let serverPaused = false;
+        const toServer = (chunks) => {
+            if (chunks.length === 0 || serverIn.destroyed || serverIn.writableEnded)
+                return;
+            if (!serverIn.write(Buffer.concat(chunks)) && !clientPaused) {
+                clientPaused = true;
+                clientIn.pause();
+                serverIn.once('drain', () => {
+                    clientPaused = false;
+                    clientIn.resume();
+                });
+            }
+        };
+        const toClient = (chunks) => {
+            if (chunks.length === 0 || clientOut.destroyed)
+                return;
+            if (!clientOut.write(Buffer.concat(chunks)) && !serverPaused) {
+                serverPaused = true;
+                serverOut.pause();
+                clientOut.once('drain', () => {
+                    serverPaused = false;
+                    serverOut.resume();
+                });
+            }
+        };
+        const route = (lines, from) => {
+            const onward = [];
+            const back = [];
+            for (const line of lines) {
+                const routed = safeRoute(firewall, line.text, from, options.mode ?? 'enforce', diag);
+                if (routed.passOriginal)
+                    onward.push(line.raw, NEWLINE);
+                for (const text of routed.onward)
+                    onward.push(Buffer.from(`${text}\n`, 'utf8'));
+                for (const text of routed.back)
+                    back.push(Buffer.from(`${text}\n`, 'utf8'));
+            }
+            if (from === 'client') {
+                toServer(onward);
+                toClient(back);
+            }
+            else {
+                toClient(onward);
+                toServer(back);
+            }
+        };
+        const onClientData = (chunk) => route(fromClient.push(chunk), 'client');
+        const onClientEnd = () => {
+            const last = fromClient.flush();
+            if (last)
+                route([last], 'client');
+            if (!serverIn.destroyed)
+                serverIn.end();
+            graceTimer ??= setTimeout(() => killServer(child), STDIN_EOF_GRACE_MS);
+        };
+        clientIn.on('data', onClientData);
+        clientIn.once('end', onClientEnd);
+        clientIn.once('error', onClientEnd);
+        serverOut.on('data', (chunk) => route(fromServer.push(chunk), 'server'));
+        serverOut.once('end', () => {
+            const last = fromServer.flush();
+            if (last)
+                route([last], 'server');
+        });
+        serverIn.on('error', () => {
+            // EPIPE once the server has exited; its exit is handled below.
+        });
+        clientOut.on('error', () => {
+            diag('the MCP client closed stdout; stopping the server');
+            killServer(child);
+        });
+        const onLockChange = (current, previous) => {
+            if (current.mtimeMs === previous.mtimeMs && current.size === previous.size)
+                return;
+            const lines = firewall.lockChanged();
+            toClient(lines.map((text) => Buffer.from(`${text}\n`, 'utf8')));
+        };
+        fs.watchFile(options.lockPath, { interval: LOCK_POLL_MS, persistent: false }, onLockChange);
+        const onSignal = (signal) => {
+            signals++;
+            if (process.platform === 'win32' || signals > 1)
+                killServer(child);
+            else
+                child.kill(signal);
+        };
+        const signalNames = process.platform === 'win32' ? ['SIGINT', 'SIGTERM'] : ['SIGINT', 'SIGTERM', 'SIGHUP'];
+        for (const name of signalNames)
+            process.on(name, onSignal);
+        const onProcessExit = () => killServer(child);
+        process.on('exit', onProcessExit);
+        const finish = async (code) => {
+            if (finished)
+                return;
+            finished = true;
+            if (graceTimer)
+                clearTimeout(graceTimer);
+            fs.unwatchFile(options.lockPath, onLockChange);
+            for (const name of signalNames)
+                process.off(name, onSignal);
+            clientIn.off('data', onClientData);
+            clientIn.pause();
+            clientIn.destroy();
+            audit?.write({ event: 'exit', code });
+            await withTimeout(firewall.idle(), 1000);
+            await audit?.close();
+            await withTimeout(new Promise((done) => clientOut.write('', () => done())), 1000);
+            process.off('exit', onProcessExit);
+            resolve(code);
+        };
+        child.once('error', (error) => {
+            if (child.pid !== undefined)
+                return;
+            diag(`could not start MCP server '${options.server}': ${errorMessage(error)}`);
+            void finish(1);
+        });
+        child.once('exit', (code, signal) => {
+            const exitCode = code ?? signalExitCode(signal);
+            if (serverOut.readableEnded || serverOut.destroyed) {
+                void finish(exitCode);
+                return;
+            }
+            const timer = setTimeout(() => void finish(exitCode), DRAIN_AFTER_EXIT_MS);
+            serverOut.once('close', () => {
+                clearTimeout(timer);
+                void finish(exitCode);
+            });
+        });
+    });
+}
+/** Routes one line, failing closed in enforce mode if the firewall itself throws. */
+function safeRoute(firewall, text, from, mode, diag) {
+    try {
+        return from === 'client' ? firewall.fromClient(text) : firewall.fromServer(text);
+    }
+    catch (error) {
+        diag(`internal error while checking a message from the ${from}: ${errorMessage(error)}; ${mode === 'enforce' ? 'dropping it' : 'forwarding it'}`);
+        return { passOriginal: mode !== 'enforce', onward: [], back: [] };
+    }
+}
+function signalExitCode(signal) {
+    if (!signal)
+        return 1;
+    const number = os.constants.signals[signal];
+    return typeof number === 'number' ? 128 + number : 1;
+}
+function withTimeout(promise, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref();
+        promise.then(() => {
+            clearTimeout(timer);
+            resolve();
+        }, () => {
+            clearTimeout(timer);
+            resolve();
+        });
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/proxy/spawn.d.ts

@@ -0,0 +1,51 @@
+import type { ChildProcess } from 'node:child_process';
+/** How to start the MCP server: the file to execute and its exact arguments. */
+export interface SpawnPlan {
+    file: string;
+    args: string[];
+    /** Set when args are a pre-escaped cmd.exe command line that Node must not quote again. */
+    windowsVerbatimArguments: boolean;
+    /** The server runs under cmd.exe, so stopping it means stopping a process tree. */
+    viaShell: boolean;
+}
+export interface PlanContext {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    /** Whether a path is a regular file. Defaults to the real file system; tests inject one to plan for Windows anywhere. */
+    isFile?: (candidate: string) => boolean;
+}
+/**
+ * Works out how to launch a server command. Elsewhere Node resolves PATH
+ * itself. On Windows the command is resolved through PATH and PATHEXT here,
+ * because most MCP servers start through .cmd shims (npx.cmd, pnpm.cmd...)
+ * that Node refuses to spawn without a shell since the CVE-2024-27980 fix;
+ * those run through cmd.exe with every argument escaped for it.
+ */
+export declare function planSpawn(command: string, args: readonly string[], ctx: PlanContext): SpawnPlan | {
+    error: string;
+};
+/** Case-insensitive environment lookup, as Windows itself does. */
+export declare function envValue(env: NodeJS.ProcessEnv, name: string): string | undefined;
+/**
+ * Finds the file Windows would run for a command, trying each PATHEXT
+ * extension in each PATH directory. Paths containing a separator resolve
+ * against cwd. Unlike cmd.exe, a bare name is never looked up in the current
+ * directory, so a planted npx.cmd in a project cannot hijack the server.
+ */
+export declare function resolveWindowsCommand(command: string, env: NodeJS.ProcessEnv, cwd: string, exists?: (candidate: string) => boolean): string | undefined;
+/** Escapes the program path of a cmd.exe command line by putting a caret before every metacharacter (as cross-spawn does). */
+export declare function escapeCmdCommand(command: string): string;
+/**
+ * Escapes one argument for `cmd.exe /d /s /c "<line>"` when the target is a
+ * batch file: quote it the way CommandLineToArgvW expects
+ * (https://qntm.org/cmd), then caret-escape metacharacters twice, because
+ * cmd.exe parses the line once to start the batch file and again when the
+ * batch file expands %* (npx.cmd, npm and pnpm shims all do). Escaping only
+ * once lets an argument such as `say "hi" & calc` run calc.
+ */
+export declare function escapeCmdArgument(arg: string): string;
+/** Quotes an argument so CommandLineToArgvW reads it back unchanged: backslashes before a quote or the end are doubled. */
+export declare function quoteForArgv(arg: string): string;
+/** Stops the server. On Windows the whole tree goes, since killing cmd.exe alone would orphan the real server. */
+export declare function killServer(child: ChildProcess, platform?: NodeJS.Platform): void;

package/dist/proxy/spawn.js

@@ -0,0 +1,110 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Works out how to launch a server command. Elsewhere Node resolves PATH
+ * itself. On Windows the command is resolved through PATH and PATHEXT here,
+ * because most MCP servers start through .cmd shims (npx.cmd, pnpm.cmd...)
+ * that Node refuses to spawn without a shell since the CVE-2024-27980 fix;
+ * those run through cmd.exe with every argument escaped for it.
+ */
+export function planSpawn(command, args, ctx) {
+    if (ctx.platform !== 'win32')
+        return { file: command, args: [...args], windowsVerbatimArguments: false, viaShell: false };
+    const resolved = resolveWindowsCommand(command, ctx.env, ctx.cwd, ctx.isFile);
+    if (!resolved)
+        return { error: `command not found: ${command} (searched PATH with PATHEXT)` };
+    if (!/\.(?:cmd|bat)$/i.test(resolved))
+        return { file: resolved, args: [...args], windowsVerbatimArguments: false, viaShell: false };
+    const unsafe = [resolved, ...args].find((arg) => /[\r\n\0]/.test(arg));
+    if (unsafe !== undefined)
+        return { error: 'cannot pass an argument containing a line break or NUL to a .cmd/.bat server through cmd.exe' };
+    const line = [escapeCmdCommand(resolved), ...args.map(escapeCmdArgument)].join(' ');
+    return {
+        file: envValue(ctx.env, 'ComSpec') ?? 'cmd.exe',
+        args: ['/d', '/s', '/c', `"${line}"`],
+        windowsVerbatimArguments: true,
+        viaShell: true,
+    };
+}
+/** Case-insensitive environment lookup, as Windows itself does. */
+export function envValue(env, name) {
+    const upper = name.toUpperCase();
+    for (const [key, value] of Object.entries(env))
+        if (key.toUpperCase() === upper && value !== undefined)
+            return value;
+    return undefined;
+}
+/**
+ * Finds the file Windows would run for a command, trying each PATHEXT
+ * extension in each PATH directory. Paths containing a separator resolve
+ * against cwd. Unlike cmd.exe, a bare name is never looked up in the current
+ * directory, so a planted npx.cmd in a project cannot hijack the server.
+ */
+export function resolveWindowsCommand(command, env, cwd, exists = isFile) {
+    const win = path.win32;
+    const exts = (envValue(env, 'PATHEXT') ?? '.COM;.EXE;.BAT;.CMD').split(';').map((e) => e.trim()).filter(Boolean);
+    const ext = win.extname(command);
+    const hasKnownExt = ext !== '' && exts.some((e) => e.toLowerCase() === ext.toLowerCase());
+    const names = hasKnownExt ? [command] : [...exts.map((e) => command + e.toLowerCase()), ...(ext ? [command] : [])];
+    const hasSeparator = /[\\/]/.test(command) || win.isAbsolute(command);
+    const dirs = hasSeparator
+        ? [cwd]
+        : (envValue(env, 'PATH') ?? '').split(';').map((d) => d.trim().replace(/^"(.*)"$/, '$1')).filter(Boolean);
+    for (const dir of dirs) {
+        for (const name of names) {
+            const candidate = win.resolve(dir, name);
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+function isFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+/** Escapes the program path of a cmd.exe command line by putting a caret before every metacharacter (as cross-spawn does). */
+export function escapeCmdCommand(command) {
+    return path.win32.normalize(command).replace(CMD_META, '^$1');
+}
+/**
+ * Escapes one argument for `cmd.exe /d /s /c "<line>"` when the target is a
+ * batch file: quote it the way CommandLineToArgvW expects
+ * (https://qntm.org/cmd), then caret-escape metacharacters twice, because
+ * cmd.exe parses the line once to start the batch file and again when the
+ * batch file expands %* (npx.cmd, npm and pnpm shims all do). Escaping only
+ * once lets an argument such as `say "hi" & calc` run calc.
+ */
+export function escapeCmdArgument(arg) {
+    return quoteForArgv(arg).replace(CMD_META, '^$1').replace(CMD_META, '^$1');
+}
+/** Quotes an argument so CommandLineToArgvW reads it back unchanged: backslashes before a quote or the end are doubled. */
+export function quoteForArgv(arg) {
+    let out = '"';
+    let slashes = 0;
+    for (const ch of arg) {
+        if (ch === '\\') {
+            slashes++;
+            continue;
+        }
+        out += ch === '"' ? `${'\\'.repeat(slashes * 2 + 1)}"` : `${'\\'.repeat(slashes)}${ch}`;
+        slashes = 0;
+    }
+    return `${out}${'\\'.repeat(slashes * 2)}"`;
+}
+/** Stops the server. On Windows the whole tree goes, since killing cmd.exe alone would orphan the real server. */
+export function killServer(child, platform = process.platform) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    if (platform === 'win32' && child.pid !== undefined) {
+        spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+        return;
+    }
+    child.kill('SIGTERM');
+}

package/dist/report/index.d.ts

@@ -0,0 +1,35 @@
+import type { ScanResult, Severity } from '../types.js';
+export type ReportFormat = 'text' | 'json' | 'sarif' | 'markdown';
+export declare const REPORT_FORMATS: readonly ReportFormat[];
+export declare function isReportFormat(value: string): value is ReportFormat;
+/** Context shared by every reporter. Reporters are pure: everything they print comes from the result and these options. */
+export interface ReportOptions {
+    /** Version printed in the report. Defaults to the running toolmoat version. */
+    version?: string;
+    /** Scan roots shown in the text header: display paths, or absolute paths that get shortened. */
+    roots?: readonly string[];
+    /** Directory paths are shown relative to, and the SARIF %SRCROOT%. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Text only: emit ANSI colors. */
+    color?: boolean;
+    /** Text only: list skipped files and every scan root. */
+    verbose?: boolean;
+    /** Text only: print findings and nothing else, and nothing at all when clean. */
+    quiet?: boolean;
+    /** The --min-severity the result was filtered with. */
+    minSeverity?: Severity;
+    /** How many findings were dropped for being below minSeverity. */
+    hidden?: number;
+    /** How many findings the user's ignore file suppressed. */
+    suppressed?: number;
+    /** Display path of the ignore file that was applied, if any. */
+    ignoreFile?: string;
+    /** Maps a finding's display path to its absolute path, so SARIF can emit exact URIs. */
+    filePaths?: ReadonlyMap<string, string>;
+}
+/** Renders a scan result in the requested format. The returned string ends with a newline unless it is empty. */
+export declare function renderReport(format: ReportFormat, result: ScanResult, options?: ReportOptions): string;
+export { renderJson, toJsonFinding } from './json.js';
+export { escapeCell, renderMarkdown } from './markdown.js';
+export { buildSarif, renderSarif, sarifArtifactLocation } from './sarif.js';
+export { renderText, shortPath } from './text.js';

package/dist/report/index.js

@@ -0,0 +1,25 @@
+import { renderJson } from './json.js';
+import { renderMarkdown } from './markdown.js';
+import { renderSarif } from './sarif.js';
+import { renderText } from './text.js';
+export const REPORT_FORMATS = ['text', 'json', 'sarif', 'markdown'];
+export function isReportFormat(value) {
+    return REPORT_FORMATS.includes(value);
+}
+/** Renders a scan result in the requested format. The returned string ends with a newline unless it is empty. */
+export function renderReport(format, result, options = {}) {
+    switch (format) {
+        case 'text':
+            return renderText(result, options);
+        case 'json':
+            return renderJson(result, options);
+        case 'sarif':
+            return renderSarif(result, options);
+        case 'markdown':
+            return renderMarkdown(result, options);
+    }
+}
+export { renderJson, toJsonFinding } from './json.js';
+export { escapeCell, renderMarkdown } from './markdown.js';
+export { buildSarif, renderSarif, sarifArtifactLocation } from './sarif.js';
+export { renderText, shortPath } from './text.js';

package/dist/report/json.d.ts

@@ -0,0 +1,22 @@
+import type { Finding, ScanResult, Severity } from '../types.js';
+import type { ReportOptions } from './index.js';
+export interface JsonReport {
+    tool: 'toolmoat';
+    version: string;
+    summary: {
+        filesScanned: number;
+        /** Names of the distinct targets (skills, plugins, servers) that were scanned. */
+        targets: string[];
+        durationMs: number;
+        counts: Record<Severity, number>;
+    };
+    findings: Finding[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+}
+/** Machine-readable report with a stable key order and 2-space indentation. */
+export declare function renderJson(result: ScanResult, options?: ReportOptions): string;
+/** Copies a finding with its keys in a fixed order, leaving out absent optional fields. */
+export declare function toJsonFinding(finding: Finding): Finding;