toolmoat 0.0.0-stage → 0.1.0

package/dist/clients/configs.js

@@ -0,0 +1,403 @@
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { isRecord, parseJsonc, stripComments } from '../util/jsonc.js';
+import { appDataDir, homeDir } from '../util/paths.js';
+import { joinKeyPath, parseToml } from '../util/toml-lite.js';
+const MIB = 1024 * 1024;
+export const CLIENT_CONFIGS = [
+    {
+        id: 'claude-desktop',
+        client: 'claude-desktop',
+        label: 'Claude Desktop',
+        scope: 'user',
+        format: 'json',
+        serversKeys: ['mcpServers'],
+        resolve: () => path.join(appDataDir(), 'Claude', 'claude_desktop_config.json'),
+    },
+    {
+        id: 'claude-code-user',
+        client: 'claude-code',
+        label: 'Claude Code (user)',
+        scope: 'user',
+        format: 'json',
+        serversKeys: ['mcpServers', 'projects.*.mcpServers'],
+        maxBytes: 20 * MIB,
+        resolve: () => path.join(homeDir(), '.claude.json'),
+    },
+    {
+        id: 'claude-code-project',
+        client: 'claude-code',
+        label: 'Claude Code (project .mcp.json)',
+        scope: 'project',
+        format: 'json',
+        serversKeys: ['mcpServers'],
+        resolve: (cwd) => path.join(cwd, '.mcp.json'),
+    },
+    {
+        id: 'cursor-user',
+        client: 'cursor',
+        label: 'Cursor',
+        scope: 'user',
+        format: 'json',
+        serversKeys: ['mcpServers'],
+        resolve: () => path.join(homeDir(), '.cursor', 'mcp.json'),
+    },
+    {
+        id: 'cursor-project',
+        client: 'cursor',
+        label: 'Cursor (project)',
+        scope: 'project',
+        format: 'json',
+        serversKeys: ['mcpServers'],
+        resolve: (cwd) => path.join(cwd, '.cursor', 'mcp.json'),
+    },
+    {
+        id: 'vscode-user',
+        client: 'vscode',
+        label: 'VS Code',
+        scope: 'user',
+        format: 'json',
+        serversKeys: ['servers'],
+        resolve: () => path.join(appDataDir(), 'Code', 'User', 'mcp.json'),
+    },
+    {
+        id: 'vscode-project',
+        client: 'vscode',
+        label: 'VS Code (project)',
+        scope: 'project',
+        format: 'json',
+        serversKeys: ['servers'],
+        resolve: (cwd) => path.join(cwd, '.vscode', 'mcp.json'),
+    },
+    {
+        id: 'windsurf',
+        client: 'windsurf',
+        label: 'Windsurf',
+        scope: 'user',
+        format: 'json',
+        serversKeys: ['mcpServers'],
+        resolve: () => path.join(homeDir(), '.codeium', 'windsurf', 'mcp_config.json'),
+    },
+    {
+        id: 'codex',
+        client: 'codex',
+        label: 'Codex',
+        scope: 'user',
+        format: 'toml',
+        serversKeys: ['mcp_servers'],
+        resolve: () => path.join(homeDir(), '.codex', 'config.toml'),
+    },
+    {
+        id: 'gemini-user',
+        client: 'gemini',
+        label: 'Gemini CLI',
+        scope: 'user',
+        format: 'json',
+        serversKeys: ['mcpServers'],
+        resolve: () => path.join(homeDir(), '.gemini', 'settings.json'),
+    },
+    {
+        id: 'gemini-project',
+        client: 'gemini',
+        label: 'Gemini CLI (project)',
+        scope: 'project',
+        format: 'json',
+        serversKeys: ['mcpServers'],
+        resolve: (cwd) => path.join(cwd, '.gemini', 'settings.json'),
+    },
+];
+/** Normalised form of a path for equality checks and dedupe: resolved, and lower-cased on Windows. */
+export function pathKey(p) {
+    const resolved = path.resolve(p);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+/** The known client config at exactly this path, if any. */
+export function findClientConfig(absPath, cwd) {
+    const key = pathKey(absPath);
+    return CLIENT_CONFIGS.find((location) => pathKey(location.resolve(cwd)) === key);
+}
+function compact(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+/**
+ * Configs selected by one --client value. An exact id or label picks that one
+ * config; a client family such as "cursor" picks the family's user-level configs.
+ */
+export function matchClientConfigs(query) {
+    const q = compact(query);
+    if (!q)
+        return [];
+    const exact = CLIENT_CONFIGS.filter((l) => compact(l.id) === q || compact(l.label) === q);
+    if (exact.length > 0)
+        return exact;
+    return CLIENT_CONFIGS.filter((l) => compact(l.client) === q && l.scope === 'user');
+}
+/** Values --client accepts, for usage messages. */
+export function clientChoices() {
+    return [...new Set([...CLIENT_CONFIGS.map((l) => l.client), ...CLIENT_CONFIGS.map((l) => l.id)])];
+}
+/** Reads and parses a JSON or JSONC config. Throws an Error with a readable message. */
+export function readJsonConfig(file) {
+    const text = fs.readFileSync(file, 'utf8');
+    const source = text.startsWith('') ? text.slice(1) : text;
+    const data = source.trim() === '' ? {} : parseJsonc(source);
+    if (!isRecord(data))
+        throw new Error(`${file} is not valid JSON (or not a JSON object)`);
+    const stripped = stripComments(source);
+    return { path: file, text, data, hasComments: stripped !== source, lossyNumber: findLossyNumber(stripped) };
+}
+/** The first integer literal longer than 15 digits that a parse and re-serialise would round, or a number that overflows to null. */
+function findLossyNumber(text) {
+    for (const match of text.matchAll(/"(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g)) {
+        const token = match[0];
+        if (token.startsWith('"'))
+            continue;
+        if (!Number.isFinite(Number(token)))
+            return token;
+        if (/^-?\d{16,}$/.test(token) && String(Number(token)) !== token)
+            return token;
+    }
+    return null;
+}
+/** Every server entry under the given keys, in file order. */
+export function listServers(data, keys) {
+    const out = [];
+    const collect = (servers, section, project) => {
+        if (!isRecord(servers))
+            return;
+        for (const [name, server] of Object.entries(servers)) {
+            if (!isRecord(server))
+                continue;
+            out.push(project === undefined ? { name, section, server } : { name, section, project, server });
+        }
+    };
+    for (const key of keys) {
+        if (key !== 'projects.*.mcpServers') {
+            collect(data[key], key);
+            continue;
+        }
+        const projects = data.projects;
+        if (!isRecord(projects))
+            continue;
+        for (const [project, value] of Object.entries(projects)) {
+            if (isRecord(value))
+                collect(value.mcpServers, `projects[${JSON.stringify(project)}].mcpServers`, project);
+        }
+    }
+    return out;
+}
+const REMOTE_TYPES = new Set(['http', 'sse', 'streamable-http', 'streamablehttp', 'ws', 'websocket']);
+/** True for servers reached over the network (url, serverUrl, httpUrl or an http/sse type). */
+export function isRemoteServer(server) {
+    if (typeof server.url === 'string' || typeof server.serverUrl === 'string' || typeof server.httpUrl === 'string')
+        return true;
+    return typeof server.type === 'string' && REMOTE_TYPES.has(server.type.toLowerCase()) && typeof server.command !== 'string';
+}
+/** The command line of a stdio server, or a reason it cannot be read as one. */
+export function readLaunch(server) {
+    const { command, args } = server;
+    if (typeof command !== 'string' || command.trim() === '')
+        return { error: 'no command (not a stdio server)' };
+    if (args === undefined)
+        return { command, args: [] };
+    if (!Array.isArray(args) || !args.every((a) => typeof a === 'string')) {
+        return { error: 'args is not a list of strings' };
+    }
+    return { command, args: [...args] };
+}
+/** Options of `toolmoat proxy` that take a value, so a value such as "--" is not read as the separator. */
+const PROXY_VALUE_FLAGS = new Set(['--name', '--lock', '--mode', '--on-new', '--audit-log', '--allow-secret']);
+const PROXY_BOOLEAN_FLAGS = new Set(['--no-audit', '--log-args']);
+function commandName(command) {
+    return path.basename(command.replace(/\\/g, '/')).toLowerCase().replace(/\.(cmd|exe|ps1|bat)$/, '');
+}
+/**
+ * The original command line inside an toolmoat-wrapped one ([command, ...args]
+ * after the "--"), or null when the command line was not written by wrap. An
+ * empty array means the entry is wrapped but has nothing after "--".
+ * Recognised launchers: <node> <.../cli.js> proxy, npx -y toolmoat@<version> proxy, toolmoat proxy.
+ * Only options of `toolmoat proxy` may stand between "proxy" and "--", so
+ * another program's `node tool/cli.js proxy --stdio -- upstream` is not taken
+ * for a wrapped server (unwrap would otherwise rewrite it).
+ */
+export function splitWrapped(command, args) {
+    const at = args.indexOf('proxy');
+    if (at === -1)
+        return null;
+    const viaCli = at === 1 && /(?:^|[\\/])cli\.js$/i.test(args[0]);
+    const viaPackage = args.slice(0, at).some((arg) => /^toolmoat(?:@[^\s]{1,64})?$/.test(arg));
+    const viaBin = at === 0 && commandName(command) === 'toolmoat';
+    if (!viaCli && !viaPackage && !viaBin)
+        return null;
+    for (let i = at + 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--')
+            return args.slice(i + 1);
+        if (PROXY_VALUE_FLAGS.has(arg))
+            i++;
+        else if (!PROXY_BOOLEAN_FLAGS.has(arg) && !PROXY_VALUE_FLAGS.has(arg.split('=')[0]))
+            return null;
+    }
+    return null;
+}
+/**
+ * The command line a wrapped server really runs, or null when the launch is
+ * not wrapped by toolmoat (or wraps nothing). Rules that judge a server's
+ * command should look at this rather than at the toolmoat launcher.
+ */
+export function originalLaunch(launch) {
+    const inner = splitWrapped(launch.command, launch.args);
+    if (!inner || inner.length === 0)
+        return null;
+    return { command: inner[0], args: inner.slice(1) };
+}
+/** The stdio servers of a parsed JSON config with their command lines. */
+export function stdioServers(data, keys) {
+    const out = [];
+    for (const entry of listServers(data, keys)) {
+        if (isRemoteServer(entry.server))
+            continue;
+        const launch = readLaunch(entry.server);
+        if (!('error' in launch))
+            out.push({ ...entry, launch });
+    }
+    return out;
+}
+/** Path of the one-time backup kept next to a config before toolmoat first changes it. */
+export function backupPath(file) {
+    return `${file}.toolmoat.bak`;
+}
+/**
+ * Writes config.data back to config.path, keeping the original indentation,
+ * line endings, BOM and trailing newline. Creates "<file>.toolmoat.bak" the
+ * first time, writes a temp file in the same directory and renames it over the
+ * original, so a crash never leaves a half-written config. Refuses when the
+ * file changed on disk since it was read (clients rewrite their configs).
+ * Returns the backup path when this call created it.
+ */
+export function writeJsonConfig(config) {
+    const target = realTarget(config.path);
+    const current = fs.readFileSync(target, 'utf8');
+    if (current !== config.text) {
+        throw new Error(`${config.path} changed on disk while toolmoat was editing it; run the command again`);
+    }
+    const backup = backupPath(target);
+    let created = null;
+    if (!fs.existsSync(backup)) {
+        fs.copyFileSync(target, backup, fs.constants.COPYFILE_EXCL);
+        created = backup;
+    }
+    atomicWrite(target, serializeLike(config.data, config.text));
+    return { backup: created };
+}
+function realTarget(file) {
+    try {
+        return fs.realpathSync(file);
+    }
+    catch {
+        return file;
+    }
+}
+/** JSON.stringify with the indentation, line endings, BOM and final newline of the original text. */
+export function serializeLike(data, original) {
+    const bom = original.startsWith('') ? '' : '';
+    const eol = original.includes('\r\n') ? '\r\n' : '\n';
+    const trailing = /\n[ \t]*$/.test(original) || original.trim() === '' ? eol : '';
+    let json = JSON.stringify(data, null, detectIndent(original));
+    if (eol !== '\n')
+        json = json.replace(/\n/g, eol);
+    return `${bom}${json}${trailing}`;
+}
+function detectIndent(text) {
+    const body = text.trim();
+    if (body !== '' && !body.includes('\n'))
+        return 0;
+    const match = /\n([ \t]{1,16})\S/.exec(text);
+    if (!match)
+        return 2;
+    const indent = match[1];
+    return indent.startsWith('\t') ? '\t' : indent.length;
+}
+function atomicWrite(target, content) {
+    const mode = fs.statSync(target).mode & 0o777;
+    const temp = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`);
+    try {
+        const fd = fs.openSync(temp, 'wx', mode);
+        try {
+            fs.writeFileSync(fd, content, 'utf8');
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        if (process.platform !== 'win32')
+            fs.chmodSync(temp, mode);
+        renameWithRetry(temp, target);
+    }
+    catch (error) {
+        fs.rmSync(temp, { force: true });
+        throw error;
+    }
+}
+/** Windows briefly locks files that editors, antivirus or the client itself have open. */
+function renameWithRetry(from, to) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            fs.renameSync(from, to);
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            const transient = code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+            if (process.platform !== 'win32' || !transient || attempt >= 5)
+                throw error;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50 * (attempt + 1));
+        }
+    }
+}
+/**
+ * Reads the servers of a Codex config.toml with toml-lite. wrap prints
+ * replacement lines for a server's own [mcp_servers.<name>] table, so servers
+ * defined inline or with dotted keys are marked unparsed. It never rewrites
+ * the file.
+ */
+export function readTomlServers(text) {
+    const doc = parseToml(text);
+    const table = doc.data.mcp_servers;
+    if (!isRecord(table))
+        return [];
+    const lines = text.split(/\r?\n/);
+    const servers = [];
+    for (const [name, value] of Object.entries(table)) {
+        if (!isRecord(value))
+            continue;
+        const line = doc.lines.get(joinKeyPath(['mcp_servers', name])) ?? 0;
+        const source = (lines[line - 1] ?? '').trim();
+        const server = { name, header: source, line };
+        const { command, args, url } = value;
+        if (typeof command === 'string')
+            server.command = command;
+        else if (command !== undefined)
+            server.unparsed = 'command is not a string';
+        if (Array.isArray(args) && args.every((a) => typeof a === 'string'))
+            server.args = [...args];
+        else if (args !== undefined)
+            server.unparsed = 'args is not a list of strings';
+        if (typeof url === 'string')
+            server.url = url;
+        if (!source.startsWith('['))
+            server.unparsed = 'it is defined inline or with dotted keys rather than in its own [mcp_servers.<name>] table';
+        else if (command === undefined && url === undefined && doc.errors.length > 0) {
+            server.unparsed = `config.toml has syntax toolmoat could not read (line ${doc.errors[0].line})`;
+        }
+        servers.push(server);
+    }
+    return servers;
+}
+/** Formats a string as a TOML value: a literal string when that is safe, else a basic string. */
+export function tomlString(value) {
+    if (!/['\u0000-\u001f\u007f]/.test(value))
+        return `'${value}'`;
+    return JSON.stringify(value);
+}

package/dist/commands/approve.d.ts

@@ -0,0 +1,15 @@
+import type { PendingTool, ServerEntry } from '../proxy/lockfile.js';
+export declare const help = "Usage: toolmoat approve <server> [--tool <tool>]... [--all] [--reset] [--lock <file>]\n\nAccepts tool changes that toolmoat proxy is holding for a server: the\npending definitions become the new pins. Without --tool every pending\nchange is approved. Review them first with toolmoat diff <server>.\nA running proxy picks up the approval within a second and asks the client to\nreload its tool list.\n\nOptions:\n  --tool <tool>   Approve only this tool (repeatable)\n  --all           Approve every pending change (the default without --tool)\n  --reset         Forget the server entirely; its tools are pinned again on the next run\n  --lock <file>   Lockfile (default: <toolmoat home>/lock.json)";
+export interface ApproveResult {
+    approved: Array<{
+        tool: string;
+        reason: PendingTool['reason'];
+    }>;
+    missing: string[];
+}
+/** Moves pending definitions into the pins. Pure: returns the new entry and what happened. */
+export declare function approvePending(entry: ServerEntry, tools: readonly string[] | 'all', now: string): {
+    entry: ServerEntry;
+    result: ApproveResult;
+};
+export declare function run(argv: string[]): Promise<number>;

package/dist/commands/approve.js

@@ -0,0 +1,128 @@
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { getOwn, setOwn } from '../proxy/canonical.js';
+import { defaultLockPath, readLockfile, updateServer } from '../proxy/lockfile.js';
+import { safeText } from '../proxy/names.js';
+import { palette } from '../util/colors.js';
+export const help = `Usage: toolmoat approve <server> [--tool <tool>]... [--all] [--reset] [--lock <file>]
+
+Accepts tool changes that toolmoat proxy is holding for a server: the
+pending definitions become the new pins. Without --tool every pending
+change is approved. Review them first with toolmoat diff <server>.
+A running proxy picks up the approval within a second and asks the client to
+reload its tool list.
+
+Options:
+  --tool <tool>   Approve only this tool (repeatable)
+  --all           Approve every pending change (the default without --tool)
+  --reset         Forget the server entirely; its tools are pinned again on the next run
+  --lock <file>   Lockfile (default: <toolmoat home>/lock.json)`;
+/** Moves pending definitions into the pins. Pure: returns the new entry and what happened. */
+export function approvePending(entry, tools, now) {
+    const next = { ...entry, tools: { ...entry.tools }, pending: { ...entry.pending } };
+    const wanted = tools === 'all' ? Object.keys(entry.pending).sort() : [...new Set(tools)];
+    const result = { approved: [], missing: [] };
+    for (const tool of wanted) {
+        const pending = getOwn(next.pending, tool);
+        if (!pending) {
+            result.missing.push(tool);
+            continue;
+        }
+        setOwn(next.tools, tool, { hash: pending.hash, definition: pending.definition, pinnedAt: now });
+        delete next.pending[tool];
+        result.approved.push({ tool, reason: pending.reason });
+    }
+    if (result.approved.length > 0)
+        next.updated = now;
+    return { entry: next, result };
+}
+export async function run(argv) {
+    let values;
+    let positionals;
+    try {
+        ({ values, positionals } = parseArgs({
+            args: argv,
+            options: { tool: { type: 'string', multiple: true }, all: { type: 'boolean' }, reset: { type: 'boolean' }, lock: { type: 'string' } },
+            allowPositionals: true,
+        }));
+    }
+    catch (error) {
+        return usageError(error instanceof Error ? error.message : String(error));
+    }
+    const name = positionals[0];
+    if (name === undefined || positionals.length > 1)
+        return usageError('expected exactly one server name');
+    if (values.reset && (values.all || values.tool))
+        return usageError('--reset cannot be combined with --tool or --all');
+    if (values.all && values.tool)
+        return usageError('use either --all or --tool, not both');
+    const lockPath = path.resolve(values.lock ?? defaultLockPath());
+    try {
+        return values.reset ? reset(lockPath, name) : approve(lockPath, name, values.tool ?? 'all');
+    }
+    catch (error) {
+        process.stderr.write(`toolmoat approve: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+function approve(lockPath, name, tools) {
+    const c = palette(process.stdout);
+    const shownName = safeText(name, 100);
+    let result = undefined;
+    let pendingBefore = [];
+    updateServer(lockPath, name, (current) => {
+        if (!current)
+            return current;
+        pendingBefore = Object.keys(current.pending).sort();
+        const outcome = approvePending(current, tools, new Date().toISOString());
+        result = outcome.result;
+        return outcome.entry;
+    });
+    if (!result) {
+        process.stderr.write(`toolmoat approve: no server named '${shownName}' in ${lockPath}${knownServers(lockPath)}\n`);
+        return 1;
+    }
+    for (const tool of result.missing) {
+        const others = pendingBefore.length > 0 ? ` (pending: ${pendingBefore.map((t) => safeText(t, 60)).join(', ')})` : '';
+        process.stderr.write(`toolmoat approve: no pending change for tool '${safeText(tool, 100)}' on ${shownName}${others}\n`);
+    }
+    if (result.approved.length === 0) {
+        if (result.missing.length === 0)
+            process.stderr.write(`toolmoat approve: nothing to approve for ${shownName}; every tool matches its pin\n`);
+        return 1;
+    }
+    const lines = [c.green(`Approved ${result.approved.length} tool change${result.approved.length === 1 ? '' : 's'} for ${shownName}:`)];
+    for (const item of result.approved)
+        lines.push(`  ${safeText(item.tool, 100)} (${item.reason})`);
+    lines.push(c.dim(`Pins updated in ${lockPath}. A running proxy reloads them automatically; otherwise restart the MCP server.`));
+    process.stdout.write(`${lines.join('\n')}\n`);
+    return result.missing.length > 0 ? 1 : 0;
+}
+function reset(lockPath, name) {
+    let removed = undefined;
+    updateServer(lockPath, name, (current) => {
+        removed = current;
+        return undefined;
+    });
+    if (!removed) {
+        process.stderr.write(`toolmoat approve: no server named '${safeText(name, 100)}' in ${lockPath}${knownServers(lockPath)}\n`);
+        return 1;
+    }
+    const tools = Object.keys(removed.tools).length;
+    const pending = Object.keys(removed.pending).length;
+    process.stdout.write(`Forgot ${safeText(name, 100)} (${tools} pinned tool${tools === 1 ? '' : 's'}, ${pending} pending). Its tools will be pinned again the next time it runs.\n`);
+    return 0;
+}
+function knownServers(lockPath) {
+    try {
+        const names = Object.keys(readLockfile(lockPath).servers).sort();
+        return names.length > 0 ? ` (known: ${names.map((n) => safeText(n, 60)).join(', ')})` : '';
+    }
+    catch {
+        return '';
+    }
+}
+function usageError(message) {
+    process.stderr.write(`toolmoat approve: ${message}\nUsage: toolmoat approve <server> [--tool <tool>]... [--all] [--reset] [--lock <file>]\n`);
+    return 2;
+}

package/dist/commands/diff.d.ts

@@ -0,0 +1,6 @@
+import type { ServerEntry } from '../proxy/lockfile.js';
+import type { Palette } from '../util/colors.js';
+export declare const help = "Usage: toolmoat diff <server> [--tool <tool>] [--lock <file>]\n\nShows the tool changes toolmoat proxy is holding for a server: why each tool\nwas held, what the scanner found, and a line diff between the pinned\ndefinition and the new one (new or flagged tools are shown in full).\n\nOptions:\n  --tool <tool>   Only this tool\n  --lock <file>   Lockfile (default: <toolmoat home>/lock.json)";
+export declare function run(argv: string[]): Promise<number>;
+/** The review block for one pending tool: reason, findings and a diff against the pin. */
+export declare function renderPending(entry: ServerEntry, tool: string, c: Palette): string[];

package/dist/commands/diff.js

@@ -0,0 +1,114 @@
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { getOwn } from '../proxy/canonical.js';
+import { diffLines, hunks, prettyDefinition } from '../proxy/diff.js';
+import { defaultLockPath, readLockfile } from '../proxy/lockfile.js';
+import { safeText, shellQuote } from '../proxy/names.js';
+import { palette } from '../util/colors.js';
+export const help = `Usage: toolmoat diff <server> [--tool <tool>] [--lock <file>]
+
+Shows the tool changes toolmoat proxy is holding for a server: why each tool
+was held, what the scanner found, and a line diff between the pinned
+definition and the new one (new or flagged tools are shown in full).
+
+Options:
+  --tool <tool>   Only this tool
+  --lock <file>   Lockfile (default: <toolmoat home>/lock.json)`;
+const REASON_TEXT = {
+    changed: 'definition changed since it was pinned',
+    new: 'tool appeared after the server was pinned',
+    flagged: 'definition flagged by the scanner',
+};
+export async function run(argv) {
+    let values;
+    let positionals;
+    try {
+        ({ values, positionals } = parseArgs({ args: argv, options: { tool: { type: 'string' }, lock: { type: 'string' } }, allowPositionals: true }));
+    }
+    catch (error) {
+        return usageError(error instanceof Error ? error.message : String(error));
+    }
+    const name = positionals[0];
+    if (name === undefined || positionals.length > 1)
+        return usageError('expected exactly one server name');
+    const lockPath = path.resolve(values.lock ?? defaultLockPath());
+    let lock;
+    try {
+        lock = readLockfile(lockPath);
+    }
+    catch (error) {
+        process.stderr.write(`toolmoat diff: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    const entry = getOwn(lock.servers, name);
+    if (!entry) {
+        process.stderr.write(`toolmoat diff: no server named '${safeText(name, 100)}' in ${lockPath}${knownServers(lock)}\n`);
+        return 1;
+    }
+    const c = palette(process.stdout);
+    let tools = Object.keys(entry.pending).sort();
+    if (values.tool !== undefined) {
+        if (!getOwn(entry.pending, values.tool)) {
+            const pinned = getOwn(entry.tools, values.tool) ? ' (it is pinned and unchanged)' : '';
+            process.stdout.write(`No pending change for tool '${safeText(values.tool, 100)}' on ${safeText(name, 100)}${pinned}.\n`);
+            return 0;
+        }
+        tools = [values.tool];
+    }
+    if (tools.length === 0) {
+        process.stdout.write(`No pending changes for ${safeText(name, 100)}: all ${Object.keys(entry.tools).length} tools match their pins.\n`);
+        return 0;
+    }
+    const out = [c.bold(`${safeText(name, 100)}: ${tools.length} pending tool change${tools.length === 1 ? '' : 's'}`), c.dim(`lockfile: ${lockPath}`)];
+    for (const tool of tools)
+        out.push('', ...renderPending(entry, tool, c));
+    out.push('', `Approve with: ${c.cyan(`toolmoat approve ${shellQuote(name)}${values.tool !== undefined ? ` --tool ${shellQuote(values.tool)}` : ''}`)}`);
+    process.stdout.write(`${out.join('\n')}\n`);
+    return 0;
+}
+/** The review block for one pending tool: reason, findings and a diff against the pin. */
+export function renderPending(entry, tool, c) {
+    const pending = getOwn(entry.pending, tool);
+    const pinned = getOwn(entry.tools, tool);
+    const out = [`${c.bold(safeText(tool, 100))}  ${c.yellow(pending.reason)}  ${c.dim(`${REASON_TEXT[pending.reason]}, detected ${pending.detectedAt || 'unknown'}`)}`];
+    if (pending.findings.length > 0) {
+        out.push('  findings:');
+        for (const f of pending.findings) {
+            const severity = f.severity === 'critical' || f.severity === 'high' ? c.red(f.severity) : c.yellow(f.severity);
+            out.push(`    ${severity} ${f.ruleId} ${safeText(f.message, 200)}`);
+        }
+    }
+    const after = prettyDefinition(pending.definition).map((line) => safeText(line));
+    if (!pinned) {
+        out.push(`  ${c.dim('definition (not pinned before):')}`);
+        for (const line of after)
+            out.push(c.green(`  + ${line}`));
+        return out;
+    }
+    const before = prettyDefinition(pinned.definition).map((line) => safeText(line));
+    out.push(c.dim(`  --- pinned ${pinned.pinnedAt}`), c.dim(`  +++ pending ${pending.detectedAt}`));
+    const changes = hunks(diffLines(before, after));
+    if (changes.length === 0)
+        out.push(c.dim('  (no visible difference; the definitions differ only in key order or encoding)'));
+    changes.forEach((hunk, index) => {
+        if (index > 0)
+            out.push(c.dim('  ...'));
+        for (const op of hunk.ops) {
+            if (op.type === 'removed')
+                out.push(c.red(`  - ${op.line}`));
+            else if (op.type === 'added')
+                out.push(c.green(`  + ${op.line}`));
+            else
+                out.push(c.dim(`    ${op.line}`));
+        }
+    });
+    return out;
+}
+function knownServers(lock) {
+    const names = Object.keys(lock.servers).sort();
+    return names.length > 0 ? ` (known: ${names.map((n) => safeText(n, 60)).join(', ')})` : '';
+}
+function usageError(message) {
+    process.stderr.write(`toolmoat diff: ${message}\nUsage: toolmoat diff <server> [--tool <tool>] [--lock <file>]\n`);
+    return 2;
+}