toolmoat 0.0.0-stage → 0.1.0

package/dist/proxy/framing.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Framing for the MCP stdio transport: newline-delimited JSON-RPC 2.0
+ * messages. Lines are split on raw bytes, so chunks may break a line or a
+ * multi-byte character anywhere, and lines may end with \n or \r\n.
+ */
+export interface Line {
+    /** The line's bytes without the terminating \n (a trailing \r is kept, so the line can be forwarded byte for byte). */
+    raw: Buffer;
+    /** The line decoded as UTF-8, without its \n or \r\n terminator. */
+    text: string;
+}
+/** Splits a byte stream into lines without quadratic copying, however the stream is chunked. */
+export declare class LineDecoder {
+    private pending;
+    /** Feeds one chunk and returns every line it completed. */
+    push(chunk: Buffer): Line[];
+    /** Returns the unterminated last line at end of stream, if there is one. */
+    flush(): Line | undefined;
+}
+export type JsonRpcId = string | number;
+/** A JSON-RPC message as parsed from the wire. Fields are unvalidated: the peer may be hostile. */
+export type JsonRpcMessage = Record<string, unknown>;
+export type ParsedLine = {
+    kind: 'message';
+    message: JsonRpcMessage;
+} | {
+    kind: 'batch';
+    items: unknown[];
+}
+/** Starts like JSON but does not parse. A lenient reader at the other end might still accept it. */
+ | {
+    kind: 'invalid';
+} | {
+    kind: 'raw';
+};
+/** Classifies a line as a JSON-RPC message, a batch (JSON array), JSON-looking garbage, or anything else (logs, blank lines). */
+export declare function parseLine(text: string): ParsedLine;
+/** Serializes one message for the wire. JSON.stringify never emits a raw newline, so the framing stays intact. */
+export declare function encodeMessage(value: unknown): string;
+/** A request expects a response: it has a method and a string or numeric id. */
+export declare function isRequest(message: JsonRpcMessage): boolean;
+export declare function isNotification(message: JsonRpcMessage): boolean;
+export declare function isResponse(message: JsonRpcMessage): boolean;
+/** Map key for a request id that keeps 1 and "1" apart. */
+export declare function idKey(id: unknown): string;

package/dist/proxy/framing.js

@@ -0,0 +1,86 @@
+/**
+ * Framing for the MCP stdio transport: newline-delimited JSON-RPC 2.0
+ * messages. Lines are split on raw bytes, so chunks may break a line or a
+ * multi-byte character anywhere, and lines may end with \n or \r\n.
+ */
+const NEWLINE = 0x0a;
+/** Splits a byte stream into lines without quadratic copying, however the stream is chunked. */
+export class LineDecoder {
+    pending = [];
+    /** Feeds one chunk and returns every line it completed. */
+    push(chunk) {
+        const lines = [];
+        let start = 0;
+        let newline = chunk.indexOf(NEWLINE, start);
+        while (newline !== -1) {
+            const piece = chunk.subarray(start, newline);
+            if (this.pending.length > 0) {
+                this.pending.push(piece);
+                lines.push(toLine(Buffer.concat(this.pending)));
+                this.pending = [];
+            }
+            else {
+                lines.push(toLine(piece));
+            }
+            start = newline + 1;
+            newline = chunk.indexOf(NEWLINE, start);
+        }
+        if (start < chunk.length)
+            this.pending.push(chunk.subarray(start));
+        return lines;
+    }
+    /** Returns the unterminated last line at end of stream, if there is one. */
+    flush() {
+        if (this.pending.length === 0)
+            return undefined;
+        const raw = Buffer.concat(this.pending);
+        this.pending = [];
+        return raw.length > 0 ? toLine(raw) : undefined;
+    }
+}
+function toLine(raw) {
+    const text = raw.toString('utf8');
+    return { raw, text: text.endsWith('\r') ? text.slice(0, -1) : text };
+}
+/** Anything that begins, after any whitespace, with an object or array opener. JSON.parse allows less whitespace than other parsers do, so this is deliberately wide. */
+const JSON_LIKE = /^\s*[{[]/;
+/** Classifies a line as a JSON-RPC message, a batch (JSON array), JSON-looking garbage, or anything else (logs, blank lines). */
+export function parseLine(text) {
+    // .NET and PowerShell servers can start their output with a byte order mark; clients that tolerate it must keep working.
+    const body = text.startsWith('') ? text.replace(/^+/, '') : text;
+    if (!JSON_LIKE.test(body))
+        return { kind: 'raw' };
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch {
+        return { kind: 'invalid' };
+    }
+    if (Array.isArray(value))
+        return { kind: 'batch', items: value };
+    if (value !== null && typeof value === 'object')
+        return { kind: 'message', message: value };
+    return { kind: 'invalid' };
+}
+/** Serializes one message for the wire. JSON.stringify never emits a raw newline, so the framing stays intact. */
+export function encodeMessage(value) {
+    return JSON.stringify(value);
+}
+function hasId(message) {
+    return typeof message.id === 'string' || typeof message.id === 'number';
+}
+/** A request expects a response: it has a method and a string or numeric id. */
+export function isRequest(message) {
+    return typeof message.method === 'string' && hasId(message);
+}
+export function isNotification(message) {
+    return typeof message.method === 'string' && !('id' in message);
+}
+export function isResponse(message) {
+    return message.method === undefined && hasId(message) && ('result' in message || 'error' in message);
+}
+/** Map key for a request id that keeps 1 and "1" apart. */
+export function idKey(id) {
+    return typeof id === 'number' ? `n:${id}` : `s:${String(id)}`;
+}

package/dist/proxy/lockfile.d.ts

@@ -0,0 +1,58 @@
+import type { Severity } from '../types.js';
+import type { ToolDefinition } from './fingerprint.js';
+/**
+ * The lockfile pins every MCP tool definition the proxy has accepted, and
+ * holds definitions waiting for a human decision. It is plain, sorted JSON so
+ * it can be reviewed and committed.
+ */
+export interface PinnedTool {
+    hash: string;
+    definition: ToolDefinition;
+    pinnedAt: string;
+}
+export type PendingReason = 'changed' | 'new' | 'flagged';
+export interface FindingSummary {
+    ruleId: string;
+    severity: Severity;
+    message: string;
+}
+export interface PendingTool {
+    hash: string;
+    definition: ToolDefinition;
+    detectedAt: string;
+    reason: PendingReason;
+    findings: FindingSummary[];
+}
+export interface ServerEntry {
+    command: string;
+    firstSeen: string;
+    updated: string;
+    tools: Record<string, PinnedTool>;
+    pending: Record<string, PendingTool>;
+}
+export interface Lockfile {
+    version: 1;
+    servers: Record<string, ServerEntry>;
+}
+export declare class LockfileError extends Error {
+    name: string;
+}
+/** <toolmoat home>/lock.json */
+export declare function defaultLockPath(): string;
+export declare function emptyLockfile(): Lockfile;
+/** Reads and validates a lockfile. A missing file is an empty lockfile; a corrupt one throws LockfileError. */
+export declare function readLockfile(file: string): Lockfile;
+/** Serializes with stable key order so the file diffs cleanly in version control. */
+export declare function serializeLockfile(lock: Lockfile): string;
+/** Writes the whole lockfile atomically: temp file in the same directory, fsync, rename. */
+export declare function writeLockfile(file: string, lock: Lockfile): void;
+/**
+ * Read-modify-write of one server's entry under an advisory lock. The file is
+ * re-read inside the lock and only this server's entry is replaced, so
+ * several proxies (and `toolmoat approve`) can share one lockfile. `mutate`
+ * gets a private copy of the current entry and returns the new one, or
+ * undefined to remove the server. Returns the entry that was written.
+ */
+export declare function updateServer(file: string, name: string, mutate: (current: ServerEntry | undefined) => ServerEntry | undefined): ServerEntry | undefined;
+/** Runs fn while holding <file>.lock, created with O_EXCL. Locks left by dead processes are broken. */
+export declare function withFileLock<T>(file: string, fn: () => T): T;

package/dist/proxy/lockfile.js

@@ -0,0 +1,258 @@
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { toolmoatHome } from '../util/paths.js';
+import { canonicalJson, getOwn, setOwn } from './canonical.js';
+export class LockfileError extends Error {
+    name = 'LockfileError';
+}
+/** <toolmoat home>/lock.json */
+export function defaultLockPath() {
+    return path.join(toolmoatHome(), 'lock.json');
+}
+export function emptyLockfile() {
+    return { version: 1, servers: {} };
+}
+/** Reads and validates a lockfile. A missing file is an empty lockfile; a corrupt one throws LockfileError. */
+export function readLockfile(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return emptyLockfile();
+        throw new LockfileError(`cannot read lockfile ${file}: ${errorMessage(error)}`);
+    }
+    if (text.trim() === '')
+        return emptyLockfile();
+    let data;
+    try {
+        data = JSON.parse(text.replace(/^/, ''));
+    }
+    catch (error) {
+        throw new LockfileError(`lockfile ${file} is not valid JSON: ${errorMessage(error)}`);
+    }
+    return validateLockfile(data, file);
+}
+function validateLockfile(data, file) {
+    if (!isObject(data))
+        throw new LockfileError(`lockfile ${file} must contain a JSON object`);
+    if (data.version !== 1)
+        throw new LockfileError(`lockfile ${file} has unsupported version ${JSON.stringify(data.version)} (expected 1)`);
+    const servers = data.servers ?? {};
+    if (!isObject(servers))
+        throw new LockfileError(`lockfile ${file}: "servers" must be an object`);
+    const out = emptyLockfile();
+    for (const [name, entry] of Object.entries(servers)) {
+        if (!isObject(entry))
+            throw new LockfileError(`lockfile ${file}: server "${name}" must be an object`);
+        setOwn(out.servers, name, normalizeEntry(entry));
+    }
+    return out;
+}
+function normalizeEntry(entry) {
+    return {
+        command: typeof entry.command === 'string' ? entry.command : '',
+        firstSeen: typeof entry.firstSeen === 'string' ? entry.firstSeen : '',
+        updated: typeof entry.updated === 'string' ? entry.updated : '',
+        tools: recordOf(entry.tools, normalizePinned),
+        pending: recordOf(entry.pending, normalizePending),
+    };
+}
+function recordOf(value, normalize) {
+    const out = {};
+    if (!isObject(value))
+        return out;
+    for (const [key, item] of Object.entries(value)) {
+        const normalized = isObject(item) ? normalize(item) : undefined;
+        if (normalized !== undefined)
+            setOwn(out, key, normalized);
+    }
+    return out;
+}
+function normalizePinned(item) {
+    if (typeof item.hash !== 'string' || !isObject(item.definition))
+        return undefined;
+    return { hash: item.hash, definition: item.definition, pinnedAt: typeof item.pinnedAt === 'string' ? item.pinnedAt : '' };
+}
+function normalizePending(item) {
+    if (typeof item.hash !== 'string' || !isObject(item.definition))
+        return undefined;
+    if (item.reason !== 'changed' && item.reason !== 'new' && item.reason !== 'flagged')
+        return undefined;
+    return {
+        hash: item.hash,
+        definition: item.definition,
+        detectedAt: typeof item.detectedAt === 'string' ? item.detectedAt : '',
+        reason: item.reason,
+        findings: Array.isArray(item.findings) ? item.findings.filter(isObject) : [],
+    };
+}
+/** Serializes with stable key order so the file diffs cleanly in version control. */
+export function serializeLockfile(lock) {
+    const servers = {};
+    for (const name of Object.keys(lock.servers).sort()) {
+        const entry = lock.servers[name];
+        setOwn(servers, name, {
+            command: entry.command,
+            firstSeen: entry.firstSeen,
+            updated: entry.updated,
+            tools: sortedRecord(entry.tools),
+            pending: sortedRecord(entry.pending),
+        });
+    }
+    return `${JSON.stringify({ version: 1, servers }, null, 2)}\n`;
+}
+function sortedRecord(record) {
+    const out = {};
+    for (const key of Object.keys(record).sort())
+        setOwn(out, key, JSON.parse(canonicalJson(record[key])));
+    return out;
+}
+/** Writes the whole lockfile atomically: temp file in the same directory, fsync, rename. */
+export function writeLockfile(file, lock) {
+    atomicWrite(file, serializeLockfile(lock));
+}
+/**
+ * Read-modify-write of one server's entry under an advisory lock. The file is
+ * re-read inside the lock and only this server's entry is replaced, so
+ * several proxies (and `toolmoat approve`) can share one lockfile. `mutate`
+ * gets a private copy of the current entry and returns the new one, or
+ * undefined to remove the server. Returns the entry that was written.
+ */
+export function updateServer(file, name, mutate) {
+    return withFileLock(file, () => {
+        const lock = readLockfile(file);
+        const before = getOwn(lock.servers, name);
+        const next = mutate(before === undefined ? undefined : structuredClone(before));
+        if (canonicalJson(next ?? null) === canonicalJson(before ?? null))
+            return before;
+        if (next === undefined)
+            delete lock.servers[name];
+        else
+            setOwn(lock.servers, name, next);
+        writeLockfile(file, lock);
+        return next;
+    });
+}
+const RETRYABLE = new Set(['EPERM', 'EBUSY', 'EACCES']);
+function atomicWrite(file, data) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    const fd = fs.openSync(tmp, 'w');
+    try {
+        fs.writeSync(fd, data);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    for (let attempt = 0;; attempt++) {
+        try {
+            fs.renameSync(tmp, file);
+            return;
+        }
+        catch (error) {
+            if (attempt < 10 && RETRYABLE.has(errorCode(error) ?? '')) {
+                sleepSync(Math.min(10 * 2 ** attempt, 200));
+                continue;
+            }
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch {
+                // The temp file may already be gone; the original error is what matters.
+            }
+            throw error;
+        }
+    }
+}
+const LOCK_TIMEOUT_MS = 3000;
+const STALE_LOCK_MS = 10_000;
+/** Runs fn while holding <file>.lock, created with O_EXCL. Locks left by dead processes are broken. */
+export function withFileLock(file, fn) {
+    const lockPath = `${file}.lock`;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    for (let attempt = 0;; attempt++) {
+        try {
+            const fd = fs.openSync(lockPath, 'wx');
+            fs.writeSync(fd, String(process.pid));
+            fs.closeSync(fd);
+            break;
+        }
+        catch (error) {
+            const code = errorCode(error);
+            if (code !== 'EEXIST' && !RETRYABLE.has(code ?? ''))
+                throw error;
+            if (code === 'EEXIST' && isStaleLock(lockPath)) {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    // Another process broke the stale lock first.
+                }
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new LockfileError(`lockfile ${file} is locked by another process (${lockPath})`);
+            sleepSync(Math.min(5 + attempt * 2, 25));
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch {
+            // Nothing useful to do if the lock vanished.
+        }
+    }
+}
+/**
+ * A lock is stale when it is too old or its owner process is gone. The file is
+ * checked again after the liveness probe: the owner may have released the lock
+ * and exited while we looked, and the path may now hold another process's
+ * live lock, which must not be broken.
+ */
+function isStaleLock(lockPath) {
+    try {
+        const before = fs.statSync(lockPath);
+        const owner = fs.readFileSync(lockPath, 'utf8');
+        const pid = Number.parseInt(owner, 10);
+        const expired = Date.now() - before.mtimeMs > STALE_LOCK_MS;
+        const orphaned = Number.isInteger(pid) && pid > 0 && pid !== process.pid && !processAlive(pid);
+        if (!expired && !orphaned)
+            return false;
+        const after = fs.statSync(lockPath);
+        return after.ino === before.ino && after.mtimeMs === before.mtimeMs && fs.readFileSync(lockPath, 'utf8') === owner;
+    }
+    catch {
+        return false;
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return errorCode(error) === 'EPERM';
+    }
+}
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+    Atomics.wait(sleepCell, 0, 0, ms);
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function errorCode(error) {
+    return isObject(error) && typeof error.code === 'string' ? error.code : undefined;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/proxy/names.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Derives a stable lockfile id from a server command: the npm/PyPI package
+ * for package runners (npx -y @scope/pkg@1.2 -> @scope/pkg), the script name
+ * for interpreters (node path/to/weather-server.js -> weather-server), the
+ * image for docker run, otherwise the executable's base name.
+ */
+export declare function deriveServerName(command: string, args: readonly string[]): string;
+/** A file name for the server's audit log: no separators or characters Windows rejects. */
+export declare function fileSafeName(name: string): string;
+/** Quotes an argument for display in a copy-pasteable command when it needs it. */
+export declare function shellQuote(arg: string): string;
+/** The command line as stored in the lockfile and shown to users. */
+export declare function formatCommand(command: string, args: readonly string[]): string;
+/**
+ * Masks credentials in a command line before it is stored in the lockfile (meant to be
+ * reviewed and committed) or the audit log: known token formats, passwords inside URLs,
+ * bearer and basic credentials, and the values of options and variables whose names say
+ * token, secret, password, key or auth.
+ */
+export declare function redactCommandLine(line: string): string;
+/**
+ * Makes attacker-controlled text (tool names, descriptions, rule messages)
+ * safe for a terminal: control, C1, bidi, zero-width and tag characters
+ * become visible escapes, so nothing can move the cursor, recolor output or
+ * hide inside a line. Optionally truncates.
+ */
+export declare function safeText(text: string, max?: number): string;

package/dist/proxy/names.js

@@ -0,0 +1,175 @@
+import path from 'node:path';
+import { redactSecrets } from '../patterns/secrets.js';
+import { printable, truncate } from '../util/text.js';
+/** Package runners whose first positional argument names the package that is the server. */
+const PACKAGE_RUNNERS = new Set(['npx', 'bunx', 'uvx', 'pnpx']);
+/** Runners that take a subcommand first: `pnpm dlx pkg`, `npm exec pkg`, `pipx run pkg`. */
+const SUBCOMMAND_RUNNERS = {
+    pnpm: ['dlx', 'exec'],
+    yarn: ['dlx', 'exec'],
+    npm: ['exec', 'x'],
+    pipx: ['run'],
+    bun: ['x', 'run'],
+    uv: ['run', 'tool'],
+};
+/** Interpreters whose first positional argument is the server script. */
+const INTERPRETERS = new Set(['node', 'nodejs', 'python', 'python3', 'py', 'deno', 'tsx', 'ts-node', 'bun', 'ruby', 'php', 'java']);
+/** Options of runners and interpreters that consume the next argument. */
+const VALUE_OPTIONS = new Set([
+    '-p', '--package', '--from', '--with', '--python', '--directory', '--project', '--index-url', '--spec', '--registry',
+    '--cache', '--userconfig', '-r', '--require', '--import', '--loader', '--env-file', '-c', '--config', '--cwd',
+    '-e', '--env', '-v', '--volume', '--name', '--network', '-w', '--workdir', '-u', '--user', '--mount', '--entrypoint',
+    '--platform', '-l', '--label', '--publish', '--add-host', '--cpus', '-m', '--memory',
+]);
+/** Script names too generic to identify a server; the closest meaningful directory is used instead. */
+const GENERIC_SCRIPTS = new Set(['index', 'main', 'server', 'cli', 'app', 'run', 'start', '__main__', 'mod', 'bin']);
+const BUILD_DIRS = new Set(['dist', 'build', 'out', 'lib', 'src', 'bin', 'build-output', '.']);
+/**
+ * Derives a stable lockfile id from a server command: the npm/PyPI package
+ * for package runners (npx -y @scope/pkg@1.2 -> @scope/pkg), the script name
+ * for interpreters (node path/to/weather-server.js -> weather-server), the
+ * image for docker run, otherwise the executable's base name.
+ */
+export function deriveServerName(command, args) {
+    const base = executableName(command);
+    let rest = [...args];
+    const subcommands = SUBCOMMAND_RUNNERS[base];
+    if (subcommands && rest[0] !== undefined && subcommands.includes(rest[0])) {
+        rest = rest.slice(1);
+        const target = firstPositional(rest);
+        if (target !== undefined && looksLikeScript(target))
+            return cleanName(scriptName(rest) ?? base);
+        return cleanName(packageName(rest) ?? base);
+    }
+    if (PACKAGE_RUNNERS.has(base))
+        return cleanName(packageName(rest) ?? base);
+    if (base === 'docker' || base === 'podman')
+        return cleanName(imageName(rest) ?? base);
+    if (INTERPRETERS.has(base))
+        return cleanName(scriptName(rest) ?? base);
+    return cleanName(base);
+}
+function executableName(command) {
+    const name = path.win32.basename(path.posix.basename(command));
+    return name.replace(/\.(?:exe|cmd|bat|com|ps1|sh)$/i, '').toLowerCase();
+}
+function packageName(args) {
+    const explicit = optionValue(args, ['-p', '--package', '--from']);
+    const spec = explicit ?? firstPositional(args);
+    return spec === undefined ? undefined : stripVersion(spec);
+}
+function stripVersion(spec) {
+    const scoped = spec.startsWith('@');
+    const at = spec.indexOf('@', scoped ? 1 : 0);
+    let name = at > 0 ? spec.slice(0, at) : spec;
+    name = name.replace(/(?:==|>=|<=|~=|!=)[^\s]{0,100}$/, '').replace(/\[[^\]]{0,100}\]$/, '');
+    return name || spec;
+}
+function imageName(args) {
+    const runIndex = args.findIndex((a) => a === 'run');
+    const image = firstPositional(runIndex === -1 ? args : args.slice(runIndex + 1));
+    if (!image)
+        return undefined;
+    const last = image.split('/').pop() ?? image;
+    return last.replace(/[:@][^/]{0,200}$/, '') || last;
+}
+function scriptName(args) {
+    const moduleName = optionValue(args, ['-m']);
+    if (moduleName)
+        return moduleName;
+    const script = firstPositional(args);
+    if (!script)
+        return undefined;
+    const parts = script.split(/[\\/]+/).filter(Boolean);
+    const file = parts.pop() ?? script;
+    const stem = file.replace(/\.(?:[cm]?[jt]s|py|rb|php|jar)$/i, '');
+    if (!GENERIC_SCRIPTS.has(stem.toLowerCase()))
+        return stem;
+    for (let i = parts.length - 1; i >= 0; i--) {
+        const dir = parts[i];
+        if (!BUILD_DIRS.has(dir.toLowerCase()) && !/^[a-z]:$/i.test(dir))
+            return dir;
+    }
+    return stem;
+}
+function looksLikeScript(arg) {
+    if (arg.startsWith('@'))
+        return false;
+    return /[\\/]/.test(arg) || /\.(?:[cm]?[jt]s|py|rb|php|jar)$/i.test(arg);
+}
+function firstPositional(args) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--')
+            return args[i + 1];
+        if (!arg.startsWith('-'))
+            return arg;
+        if (!arg.includes('=') && VALUE_OPTIONS.has(arg))
+            i++;
+    }
+    return undefined;
+}
+function optionValue(args, names) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--')
+            return undefined;
+        for (const name of names) {
+            if (arg === name)
+                return args[i + 1];
+            if (arg.startsWith(`${name}=`))
+                return arg.slice(name.length + 1);
+        }
+    }
+    return undefined;
+}
+function cleanName(name) {
+    const cleaned = name.replace(/[^A-Za-z0-9@/._-]+/g, '-').replace(/^-+|-+$/g, '');
+    return cleaned.slice(0, 120) || 'mcp-server';
+}
+/** A file name for the server's audit log: no separators or characters Windows rejects. */
+export function fileSafeName(name) {
+    const safe = name.replace(/[^A-Za-z0-9._@-]+/g, '_').replace(/^[.]+/, '');
+    return safe.slice(0, 120) || 'server';
+}
+/** Quotes an argument for display in a copy-pasteable command when it needs it. */
+export function shellQuote(arg) {
+    if (arg !== '' && /^[A-Za-z0-9@%+=:,./_~-]+$/.test(arg))
+        return arg;
+    return `"${arg.replace(/(["\\$`])/g, '\\$1')}"`;
+}
+/** The command line as stored in the lockfile and shown to users. */
+export function formatCommand(command, args) {
+    return [command, ...args].map(shellQuote).join(' ');
+}
+const SECRET_NAME = '(?<![a-z])(?:token|secret|passw(?:or)?d|pwd|api[-_]?key|credential|auth(?:orization)?)s?(?![a-z])';
+const SECRET_VALUE = `("[^"]*"|'[^']*'|[^\\s"'&-][^\\s"'&]*)`;
+/** name=value, as in KEY=..., --key=... and ?key=... */
+const SECRET_ASSIGNMENT = new RegExp(`((?:^|[\\s"'?&;])[\\w.-]*${SECRET_NAME}[\\w.-]*)(=)${SECRET_VALUE}`, 'gi');
+/** --key value: only for options, since a bare name followed by a word is usually a variable passed by name (docker -e TOKEN image). */
+const SECRET_OPTION = new RegExp(`((?:^|\\s)--?[\\w.-]*${SECRET_NAME}[\\w.-]*)(\\s+)${SECRET_VALUE}`, 'gi');
+/**
+ * Masks credentials in a command line before it is stored in the lockfile (meant to be
+ * reviewed and committed) or the audit log: known token formats, passwords inside URLs,
+ * bearer and basic credentials, and the values of options and variables whose names say
+ * token, secret, password, key or auth.
+ */
+export function redactCommandLine(line) {
+    return redactSecrets(line)
+        .replace(/\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@"']+:)[^\s@/"']+@/gi, '$1[redacted]@')
+        .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, '$1 [redacted]')
+        .replace(SECRET_ASSIGNMENT, '$1$2[redacted]')
+        .replace(SECRET_OPTION, '$1$2[redacted]');
+}
+/**
+ * Makes attacker-controlled text (tool names, descriptions, rule messages)
+ * safe for a terminal: control, C1, bidi, zero-width and tag characters
+ * become visible escapes, so nothing can move the cursor, recolor output or
+ * hide inside a line. Optionally truncates.
+ */
+export function safeText(text, max) {
+    let out = printable(text).replace(/[\u0080-\u009f]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
+    if (max !== undefined)
+        out = truncate(out, max);
+    return out;
+}