specguard-mcp 0.1.0

package/dist/src/config.js

@@ -0,0 +1,172 @@
+import { ConfigError } from "./errors.js";
+export const DEFAULT_LINT_COMMAND = ["specguard-lint"];
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/** Reads config from an environment. Never throws — see the note above. */
+export function loadConfig(env = process.env) {
+    const lintCommand = tokenise(env["SPECGUARD_LINT_COMMAND"]);
+    // WHICH variable is in play is decided ONCE, and the value is then read from
+    // the variable that answer names. An earlier version derived the two
+    // separately — the name via `presence()` (blank is unset) and the value via
+    // `??` (blank is a value) — and the two rules disagreed on exactly one input:
+    // a blank `SPECGUARD_ENDPOINT` alongside a good `SPECGUARD_URL` made `??`
+    // return the empty string, so the alias was never consulted and the operator
+    // was told the endpoint was unset while looking at the one they had set. That
+    // is the silent no-op the alias exists to prevent, and a templated MCP client
+    // `env` block with every key present and only some filled in is the ordinary
+    // way to produce it. Reading through the chosen name makes the two
+    // structurally incapable of disagreeing, rather than agreeing by coincidence.
+    const endpointVariable = presence(env["SPECGUARD_ENDPOINT"]) !== undefined
+        ? "SPECGUARD_ENDPOINT"
+        : presence(env["SPECGUARD_URL"]) !== undefined
+            ? "SPECGUARD_URL"
+            : undefined;
+    return {
+        endpoint: endpointVariable === undefined ? undefined : normaliseEndpoint(env[endpointVariable]),
+        endpointVariable,
+        apiKey: presence(env["SPECGUARD_API_KEY"]),
+        lintCommand: lintCommand.length > 0 ? lintCommand : DEFAULT_LINT_COMMAND,
+        requestTimeoutMs: positiveInteger(env["SPECGUARD_TIMEOUT_MS"]) ?? DEFAULT_REQUEST_TIMEOUT_MS,
+    };
+}
+/**
+ * The name to speak when no variable was set at all — the message is telling
+ * someone to set one, and this is the spelling the rest of the toolchain reads.
+ */
+const DEFAULT_ENDPOINT_VARIABLE = "SPECGUARD_ENDPOINT";
+/**
+ * Both halves or a legible failure — never one half and a surprise later.
+ *
+ * Reported together rather than one at a time: an operator who set neither
+ * should learn that in one round trip instead of fixing a variable, re-calling,
+ * and being told about the next one.
+ *
+ * The endpoint is also PARSED here, not merely counted as present. It is spent
+ * later inside `new URL(...)` in the HTTP client, where a malformed value throws
+ * a bare `TypeError` — which is not a `SpecGuardMcpError`, so the server's error
+ * boundary reads it as a defect and tells the agent "this is a bug in the
+ * bridge, not in your project or configuration". For the commonest config typo
+ * there is (omitting `https://`) that sentence is the exact opposite of the
+ * truth, and it sends an agent looking in the one place the problem is not.
+ * Validating here rather than at the call site is deliberate: every HTTP-backed
+ * tool added later comes through this function and inherits the check.
+ */
+export function requireApiConfig(config) {
+    const endpointVariable = config.endpointVariable ?? DEFAULT_ENDPOINT_VARIABLE;
+    const missing = [];
+    if (config.endpoint === undefined)
+        missing.push(endpointVariable);
+    if (config.apiKey === undefined)
+        missing.push("SPECGUARD_API_KEY");
+    if (missing.length > 0) {
+        throw new ConfigError(`This tool talks to a SpecGuard deployment, and ${missing.join(" and ")} ` +
+            `${missing.length === 1 ? "is" : "are"} not set in the MCP server's environment. ` +
+            "Set them in your MCP client's server config " +
+            `(${endpointVariable} is your deployment's root URL, SPECGUARD_API_KEY an sgk_… key ` +
+            "issued from its API keys page). Tools that do not reach the deployment are unaffected.");
+    }
+    return {
+        endpoint: requireHttpUrl(config.endpoint, endpointVariable),
+        endpointVariable,
+        apiKey: config.apiKey,
+        requestTimeoutMs: config.requestTimeoutMs,
+    };
+}
+/**
+ * An absolute `http(s)` URL, or a `ConfigError` that names the variable and the
+ * value it holds.
+ *
+ * Both failing shapes are worth naming because they fail in different places
+ * without this. `sg.example.com` has no scheme and `new URL` rejects it
+ * outright; `localhost:3000` is *accepted* by `new URL` — as protocol
+ * `localhost:` with path `3000` — and instead dies much later as an unhelpful
+ * transport error. An operator making either mistake made the same mistake, so
+ * they get the same answer.
+ */
+function requireHttpUrl(endpoint, name) {
+    let parsed;
+    try {
+        parsed = new URL(endpoint);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (parsed === undefined || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) {
+        throw new ConfigError(`${name} is not a usable URL: ${JSON.stringify(endpoint)}. It must be your SpecGuard ` +
+            "deployment's root URL including the scheme — for example " +
+            "https://specguard.example.com, or http://localhost:3000 for a local deployment. " +
+            `This is the MCP server's own environment: fix ${name} in your MCP client's server ` +
+            "config. Nothing about your project or your arguments is wrong.");
+    }
+    return endpoint;
+}
+/**
+ * A trailing slash on the endpoint would produce `https://host//api/v1/…` once
+ * joined. Harmless on most servers and confusing in every error message that
+ * echoes the URL back, so it is stripped once here rather than defended against
+ * at each call site.
+ */
+function normaliseEndpoint(raw) {
+    const value = presence(raw);
+    return value === undefined ? undefined : value.replace(/\/+$/, "");
+}
+/**
+ * Blank is unset.
+ *
+ * `SPECGUARD_API_KEY=` in a CI environment file is somebody turning the
+ * integration off, and treating it as a present-but-empty key would send
+ * `Authorization: Bearer ` and turn a configuration mistake into a 401 —
+ * a failure that names the wrong cause. The gem's `ValidatorBackend` collapses
+ * unset and blank for the same reason.
+ */
+function presence(raw) {
+    const trimmed = raw?.trim();
+    return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+function positiveInteger(raw) {
+    const value = Number(presence(raw));
+    return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+/**
+ * Splits a configured command into argv WITHOUT a shell, honouring single and
+ * double quotes so a path with a space survives.
+ *
+ * A shell is not used anywhere in this server, and this function is why it does
+ * not need to be: `spawn` receives a program and a list, so no argument — least
+ * of all a file path an agent passed to a tool — is ever parsed as syntax.
+ */
+export function tokenise(raw) {
+    const value = presence(raw);
+    if (value === undefined)
+        return [];
+    const tokens = [];
+    let current = "";
+    let quote;
+    let started = false;
+    for (const char of value) {
+        if (quote !== undefined) {
+            if (char === quote)
+                quote = undefined;
+            else
+                current += char;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            started = true;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (started)
+                tokens.push(current);
+            current = "";
+            started = false;
+            continue;
+        }
+        current += char;
+        started = true;
+    }
+    if (started)
+        tokens.push(current);
+    return tokens;
+}
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}

package/dist/src/errors.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Typed failures the server knows how to turn into an MCP tool error.
+ *
+ * The distinction that matters here is between a bug (which should crash loudly
+ * and be fixed) and an *expected* failure the calling agent can act on — a
+ * missing API key, a SpecGuard deployment saying 401, a linter binary that is
+ * not on PATH. The second kind must reach the agent as a tool result it can
+ * read, never as a dead stdio pipe: an MCP server that exits on a bad API key
+ * takes every other tool down with it, including the ones that never needed the
+ * key.
+ */
+/** Base for every failure that is a legitimate answer rather than a defect. */
+export declare class SpecGuardMcpError extends Error {
+    readonly name: string;
+}
+/**
+ * The environment does not carry what this tool needs.
+ *
+ * Raised at CALL time, never at boot — see `resolveApiConfig`. The message names
+ * the variable, because "unauthorized" is not something an agent can fix and
+ * "set SPECGUARD_API_KEY" is.
+ */
+export declare class ConfigError extends SpecGuardMcpError {
+    readonly name = "ConfigError";
+}
+/** The SpecGuard deployment was reached and refused, or answered unusably. */
+export declare class ApiError extends SpecGuardMcpError {
+    readonly name = "ApiError";
+    /** The HTTP status, when there was a response at all. */
+    readonly status: number | undefined;
+    constructor(message: string, status?: number);
+}
+/**
+ * The arguments the agent supplied are not the shape the schema advertises.
+ *
+ * What separates this from its two neighbours is WHERE IN THE CALL it is raised:
+ * argument shape is checked first, so this throws BEFORE any config is resolved
+ * and BEFORE any command is spawned. Nothing was reached and refused, so it is
+ * not an `ApiError`; nothing was run and broke, so it is not a `CommandError`.
+ * Both of those say the fault lies somewhere the agent cannot see, and invite a
+ * retry that cannot help. This is the one failure class the agent can fix
+ * unaided, on the next call, from the message alone.
+ *
+ * Deliberately NOT named `TypeError`: `describeError` treats the global
+ * `TypeError` as the canonical non-`SpecGuardMcpError` defect, and shadowing it
+ * would invert that branch.
+ */
+export declare class ArgumentError extends SpecGuardMcpError {
+    readonly name = "ArgumentError";
+}
+/**
+ * A wrapped command could not be run, or broke while running.
+ *
+ * NOT "the command reported a problem with your code" — that is a finding and
+ * goes back as a successful result. This is the tool itself being unusable,
+ * which for `specguard-lint` is precisely its documented exit 2.
+ */
+export declare class CommandError extends SpecGuardMcpError {
+    readonly name = "CommandError";
+}

package/dist/src/errors.js

@@ -0,0 +1,64 @@
+/**
+ * Typed failures the server knows how to turn into an MCP tool error.
+ *
+ * The distinction that matters here is between a bug (which should crash loudly
+ * and be fixed) and an *expected* failure the calling agent can act on — a
+ * missing API key, a SpecGuard deployment saying 401, a linter binary that is
+ * not on PATH. The second kind must reach the agent as a tool result it can
+ * read, never as a dead stdio pipe: an MCP server that exits on a bad API key
+ * takes every other tool down with it, including the ones that never needed the
+ * key.
+ */
+/** Base for every failure that is a legitimate answer rather than a defect. */
+export class SpecGuardMcpError extends Error {
+    name = "SpecGuardMcpError";
+}
+/**
+ * The environment does not carry what this tool needs.
+ *
+ * Raised at CALL time, never at boot — see `resolveApiConfig`. The message names
+ * the variable, because "unauthorized" is not something an agent can fix and
+ * "set SPECGUARD_API_KEY" is.
+ */
+export class ConfigError extends SpecGuardMcpError {
+    name = "ConfigError";
+}
+/** The SpecGuard deployment was reached and refused, or answered unusably. */
+export class ApiError extends SpecGuardMcpError {
+    name = "ApiError";
+    /** The HTTP status, when there was a response at all. */
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * The arguments the agent supplied are not the shape the schema advertises.
+ *
+ * What separates this from its two neighbours is WHERE IN THE CALL it is raised:
+ * argument shape is checked first, so this throws BEFORE any config is resolved
+ * and BEFORE any command is spawned. Nothing was reached and refused, so it is
+ * not an `ApiError`; nothing was run and broke, so it is not a `CommandError`.
+ * Both of those say the fault lies somewhere the agent cannot see, and invite a
+ * retry that cannot help. This is the one failure class the agent can fix
+ * unaided, on the next call, from the message alone.
+ *
+ * Deliberately NOT named `TypeError`: `describeError` treats the global
+ * `TypeError` as the canonical non-`SpecGuardMcpError` defect, and shadowing it
+ * would invert that branch.
+ */
+export class ArgumentError extends SpecGuardMcpError {
+    name = "ArgumentError";
+}
+/**
+ * A wrapped command could not be run, or broke while running.
+ *
+ * NOT "the command reported a problem with your code" — that is a finding and
+ * goes back as a successful result. This is the tool itself being unusable,
+ * which for `specguard-lint` is precisely its documented exit 2.
+ */
+export class CommandError extends SpecGuardMcpError {
+    name = "CommandError";
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,+EAA+E;AAC/E,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACxB,IAAI,GAAW,mBAAmB,CAAC;CACtD;AAED;;;;;;GAMG;AACH,MAAM,OAAO,WAAY,SAAQ,iBAAiB;IAC9B,IAAI,GAAG,aAAa,CAAC;CACxC;AAED,8EAA8E;AAC9E,MAAM,OAAO,QAAS,SAAQ,iBAAiB;IAC3B,IAAI,GAAG,UAAU,CAAC;IAEpC,yDAAyD;IAChD,MAAM,CAAqB;IAEpC,YAAY,OAAe,EAAE,MAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,aAAc,SAAQ,iBAAiB;IAChC,IAAI,GAAG,eAAe,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,MAAM,OAAO,YAAa,SAAQ,iBAAiB;IAC/B,IAAI,GAAG,cAAc,CAAC;CACzC"}

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export { createServer, SERVER_NAME, SERVER_VERSION, type CreateServerOptions } from "./server.js";
+export { loadConfig, requireApiConfig, tokenise, type ApiConfig, type Config } from "./config.js";
+export { ApiError, ArgumentError, CommandError, ConfigError, SpecGuardMcpError } from "./errors.js";
+export { TOOLS } from "./tools/index.js";
+export type { ToolContext, ToolDefinition, ToolResult } from "./tools/types.js";

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+export { loadConfig, requireApiConfig, tokenise } from "./config.js";
+export { ApiError, ArgumentError, CommandError, ConfigError, SpecGuardMcpError } from "./errors.js";
+export { TOOLS } from "./tools/index.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAA4B,MAAM,aAAa,CAAC;AAClG,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,QAAQ,EAA+B,MAAM,aAAa,CAAC;AAClG,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/server.d.ts

@@ -0,0 +1,28 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type Config } from "./config.js";
+import type { ToolContext, ToolDefinition } from "./tools/types.js";
+export declare const SERVER_NAME = "specguard-mcp";
+export declare const SERVER_VERSION = "0.1.0";
+export interface CreateServerOptions {
+    /** Overrides the tools served. Defaults to the registry. Tests pass their own. */
+    readonly tools?: readonly ToolDefinition[];
+    readonly config?: Config;
+    readonly runCommand?: ToolContext["runCommand"];
+    readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * Builds the MCP server: two request handlers over the tool registry, and no
+ * knowledge of any tool in particular.
+ *
+ * Everything a tool touches the world with — config, subprocesses, `fetch` — is
+ * resolved once here and handed down as a `ToolContext`. That is what makes the
+ * whole surface testable without a SpecGuard deployment or an installed gem, and
+ * it is a property a tool added later inherits rather than has to arrange.
+ *
+ * The transport is NOT chosen here. `createServer` returns an unconnected
+ * `Server`, and `bin/specguard-mcp.ts` connects it to stdio. SPGD-310 scopes
+ * stdio only and puts HTTP/SSE in a later follow-up; keeping the choice out of
+ * this file is what makes that follow-up a new entrypoint rather than a change
+ * to the server.
+ */
+export declare function createServer(options?: CreateServerOptions): Server;

package/dist/src/server.js

@@ -0,0 +1,113 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { loadConfig } from "./config.js";
+import { SpecGuardMcpError } from "./errors.js";
+import { runCommand as defaultRunCommand } from "./support/run-command.js";
+import { TOOLS } from "./tools/index.js";
+export const SERVER_NAME = "specguard-mcp";
+export const SERVER_VERSION = "0.1.0";
+/**
+ * Builds the MCP server: two request handlers over the tool registry, and no
+ * knowledge of any tool in particular.
+ *
+ * Everything a tool touches the world with — config, subprocesses, `fetch` — is
+ * resolved once here and handed down as a `ToolContext`. That is what makes the
+ * whole surface testable without a SpecGuard deployment or an installed gem, and
+ * it is a property a tool added later inherits rather than has to arrange.
+ *
+ * The transport is NOT chosen here. `createServer` returns an unconnected
+ * `Server`, and `bin/specguard-mcp.ts` connects it to stdio. SPGD-310 scopes
+ * stdio only and puts HTTP/SSE in a later follow-up; keeping the choice out of
+ * this file is what makes that follow-up a new entrypoint rather than a change
+ * to the server.
+ */
+export function createServer(options = {}) {
+    const tools = options.tools ?? TOOLS;
+    const context = {
+        config: options.config ?? loadConfig(),
+        runCommand: options.runCommand ?? defaultRunCommand,
+        fetch: options.fetch ?? globalThis.fetch,
+    };
+    const byName = indexByName(tools);
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({
+        tools: tools.map(describe),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const tool = byName.get(request.params.name);
+        // An unknown name is a protocol-level error rather than a tool result: the
+        // agent did not call a tool that failed, it called something that is not a
+        // tool, and reporting that as a failed call would invite a retry.
+        if (tool === undefined) {
+            throw new Error(`Unknown tool "${request.params.name}". This server serves: ` +
+                `${tools.map((entry) => entry.name).join(", ")}.`);
+        }
+        return runTool(tool, request.params.arguments ?? {}, context);
+    });
+    return server;
+}
+/**
+ * One tool call, with the error boundary that keeps a bad call from becoming a
+ * dead server.
+ *
+ * The split is between failures the agent can act on and defects it cannot.
+ * A `SpecGuardMcpError` — no API key, a 401, a linter that is not installed, an
+ * argument of the wrong type — comes back as `isError: true` with a sentence
+ * naming the fix, which is a result the model reads and responds to. Anything
+ * else is a bug in this server, and it is reported the same way rather than
+ * thrown, because on stdio an unhandled rejection takes the transport down and
+ * the agent sees "server exited" with no reason at all.
+ */
+async function runTool(tool, args, context) {
+    try {
+        const result = await tool.run(args, context);
+        return {
+            content: [{ type: "text", text: result.text }],
+            ...(result.structured === undefined ? {} : { structuredContent: result.structured }),
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: describeError(tool, error) }],
+        };
+    }
+}
+function describeError(tool, error) {
+    if (error instanceof SpecGuardMcpError)
+        return error.message;
+    const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    // Named as a defect in this bridge rather than as a verdict about the user's
+    // code or configuration — an agent that is told the problem is its input will
+    // keep editing its input.
+    return `specguard-mcp hit an internal error running \`${tool.name}\` — this is a bug in the bridge, not in your project or configuration. ${detail}`;
+}
+/** The registry entry as MCP puts it on the wire. */
+function describe(tool) {
+    return {
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+    };
+}
+/**
+ * Duplicate names are caught at construction, not on first call.
+ *
+ * Two entries sharing a name silently shadow one another in the lookup while
+ * both appear in `tools/list`, so an agent would be offered a tool that can
+ * never be reached. This is the one invariant of the registry the server
+ * enforces itself, because it is the one an added entry can violate by
+ * accident.
+ */
+function indexByName(tools) {
+    const byName = new Map();
+    for (const tool of tools) {
+        if (byName.has(tool.name)) {
+            throw new Error(`Two tools are registered under the name "${tool.name}".`);
+        }
+        byName.set(tool.name, tool);
+    }
+    return byName;
+}
+//# sourceMappingURL=server.js.map

package/dist/src/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"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"}

package/dist/src/support/run-command.d.ts

@@ -0,0 +1,86 @@
+export interface CommandResult {
+    /** The process's exit code, or `null` when a signal killed it. */
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /**
+     * Whether the stream hit `MAX_OUTPUT_BYTES` and lost its tail.
+     *
+     * Reported rather than left to be inferred from the marker in the text: a
+     * caller that parses the output needs to know the difference between "this
+     * program emits garbage" and "we cut its output in half", and only this file
+     * knows which happened.
+     */
+    readonly stdoutTruncated: boolean;
+    readonly stderrTruncated: boolean;
+    /**
+     * Whether the streams were read to their end before this result was produced.
+     *
+     * Normally true: the result is built when the pipes close, so everything the
+     * command wrote is here. It is false only on the backstop path below — the
+     * process has exited but something still holds its pipe open, so we answer
+     * with what was buffered rather than never answering at all.
+     *
+     * A SEPARATE field from `stdoutTruncated` rather than a second way to set it,
+     * because the two have different causes and different remedies, and the caller
+     * acts on the difference: `stdoutTruncated` means the output exceeded
+     * `MAX_OUTPUT_BYTES` and the fix is to ask for less (see
+     * `lint-intent-annotations.ts`'s "narrow the run with `paths`"), which would
+     * be advice about the wrong problem here. This tail was lost to a leaked file
+     * descriptor and asking for less output would not change it.
+     *
+     * Where that difference is acted on, so this stays checkable rather than
+     * merely asserted: `parseReport` in `lint-intent-annotations.ts` consults this
+     * on both of its failure branches — `undrainedPipe` there names the
+     * pipe-holder instead of blaming the linter or `SPECGUARD_LINT_COMMAND`, and
+     * is ordered after the truncation branch for the run that manages both. Note
+     * it is consulted only where something is already missing: false here does NOT
+     * mean the result is incomplete, only that the tail was not waited for, so a
+     * run whose last undrained byte was a newline is an ordinary success.
+     */
+    readonly outputDrained: boolean;
+}
+export interface RunCommandOptions {
+    readonly cwd?: string | undefined;
+    readonly timeoutMs?: number | undefined;
+    /**
+     * Extra guidance appended when the program is not on PATH.
+     *
+     * Supplied by the caller because only the caller knows which env var
+     * configures ITS command. A generic helper that hard-codes one tool's variable
+     * name starts lying the moment a second tool spawns something else.
+     */
+    readonly notFoundHint?: string | undefined;
+}
+export type RunCommand = (argv: readonly string[], options?: RunCommandOptions) => Promise<CommandResult>;
+/** Beyond this, a wrapped command's output is truncated rather than buffered. */
+export declare const MAX_OUTPUT_BYTES: number;
+/** Default ceiling on how long a wrapped command may run. */
+export declare const DEFAULT_COMMAND_TIMEOUT_MS = 120000;
+/**
+ * How long `close` may lag `exit` before the result is produced without it.
+ *
+ * `exit` and `close` are two events, not one: `close` additionally waits for
+ * every writer of the child's stdout/stderr pipes to let go, and a process that
+ * is not the child can be holding them. Long enough that the ordinary
+ * milliseconds-apart drain is never cut short; short enough that a leaked
+ * descriptor costs a truncated tail instead of a call that never returns.
+ */
+export declare const EXIT_CLOSE_GRACE_MS = 1000;
+/**
+ * Runs a program with an argument LIST, never through a shell.
+ *
+ * `spawn` without `shell: true` is the load-bearing detail: tool arguments
+ * arrive from a model, so a file path containing `; rm -rf …` has to be a
+ * path that does not exist rather than a command. There is no escaping to get
+ * right because nothing is ever parsed as syntax.
+ *
+ * A non-zero exit is NOT an error here. `specguard-lint` uses its exit code as
+ * a three-valued verdict — 0 clean, 1 malformed annotations, 2 the tool could
+ * not do its job — so deciding what a code means is the caller's job and this
+ * function reports it. What IS an error is the process never running (missing
+ * binary) or never finishing (timeout): both leave the caller with no verdict
+ * at all, which is the one outcome that must not be mistaken for a clean run.
+ */
+export declare const runCommand: RunCommand;