specguard-mcp 0.1.0

package/dist/src/support/run-command.js

@@ -0,0 +1,322 @@
+import { spawn } from "node:child_process";
+import { statSync } from "node:fs";
+import { CommandError } from "../errors.js";
+/** Beyond this, a wrapped command's output is truncated rather than buffered. */
+export const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+/** Default ceiling on how long a wrapped command may run. */
+export const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
+/**
+ * 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 const EXIT_CLOSE_GRACE_MS = 1_000;
+/**
+ * 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 const runCommand = (argv, options = {}) => {
+    const [program, ...args] = argv;
+    if (program === undefined) {
+        throw new CommandError("No command was configured to run.");
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+    return new Promise((resolve, reject) => {
+        // Checked before spawning, not diagnosed afterwards. `spawn` reports a
+        // working directory it cannot use by TWO different routes depending on the
+        // errno: an async `error` event (ENOENT, for a directory that is not there)
+        // and a synchronous throw (ENOTDIR, for one that is a file). The synchronous
+        // one is not a `CommandError`, so it would escape this whole file and be
+        // reported to the agent as a bug in the bridge. Asking first collapses both
+        // into one sentence that names the directory.
+        if (options.cwd !== undefined && !isDirectory(options.cwd)) {
+            reject(new CommandError(unusableCwd(program, options.cwd)));
+            return;
+        }
+        let child;
+        try {
+            child = spawnChild(program, args, options);
+        }
+        catch (error) {
+            // Belt and braces for the synchronous route: whatever `spawn` decides to
+            // throw, the agent gets a sentence about a command, never a raw errno that
+            // the error boundary would classify as a defect in this server.
+            reject(new CommandError(describeSpawnFailure(program, error, options)));
+            return;
+        }
+        const stdout = new OutputBuffer();
+        const stderr = new OutputBuffer();
+        let settled = false;
+        let timedOut = false;
+        let exited = false;
+        let graceTimer;
+        const timer = setTimeout(() => {
+            // Whether the RUN is still live — asked of the process, not of the kill.
+            // `exit` and `close` are separate events, so there is a window in which
+            // the process is already gone and a complete result is already on its way.
+            // A deadline landing in there has nothing to time out, and claiming one
+            // would throw the finished run away, exit code and document and all, to
+            // report that it never finished.
+            //
+            // `killRun`'s answer cannot be that test on its own, which is the trap
+            // this guard exists for. It reports whether anything in the process GROUP
+            // was signalled, and the group outlives the child by exactly the
+            // grandchild holding the pipes open — the same grandchild that made the
+            // window wide enough for a deadline to land in it at all. So on the
+            // topology this file is about, the kill SUCCEEDS after the child is gone,
+            // and a `timedOut` read off that answer calls a completed `code: 0` run a
+            // timeout. Only the child's own exit can contradict it.
+            //
+            // Returning rather than killing and discarding the answer: once the child
+            // has been reaped its pid is no longer ours to signal — see `killRun`.
+            if (exited)
+                return;
+            timedOut = killRun(child);
+        }, timeoutMs);
+        // `unref` so a hung command's timer cannot by itself hold the process open.
+        timer.unref?.();
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (graceTimer !== undefined)
+                clearTimeout(graceTimer);
+            fn();
+        };
+        /**
+         * The one place a result is produced, reached from `close` and from the
+         * grace backstop alike — so the two cannot drift into disagreeing about
+         * what a timeout is. `timedOut` still decides reject-vs-resolve on BOTH:
+         * our own deadline is this server's decision and has no verdict to hand
+         * back, while a signal from outside is a fact about the child the caller
+         * has to be able to act on.
+         */
+        const settleWith = (code, signal, drained) => {
+            finish(() => {
+                if (timedOut) {
+                    reject(new CommandError(`\`${program}\` did not finish within ${timeoutMs}ms and was killed, ` +
+                        "so it produced no verdict."));
+                    return;
+                }
+                resolve({
+                    code,
+                    signal,
+                    stdout: stdout.text(),
+                    stderr: stderr.text(),
+                    stdoutTruncated: stdout.truncated,
+                    stderrTruncated: stderr.truncated,
+                    outputDrained: drained,
+                });
+            });
+        };
+        child.stdout.on("data", (chunk) => stdout.push(chunk));
+        child.stderr.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", (error) => {
+            finish(() => reject(new CommandError(describeSpawnFailure(program, error, options))));
+        });
+        /**
+         * The backstop, and the reason this promise no longer depends on `close`.
+         *
+         * `close` fires only once the process has ended AND every writer of its
+         * stdout/stderr pipes has let go. Those descriptors are inherited, so a
+         * grandchild holds them: `bundle exec specguard-lint` — the configuration
+         * this project's README recommends — makes `bundle` the child and the linter
+         * a grandchild, and killing the group can still miss a great-grandchild that
+         * escaped it by double-forking. When that happens `close` never arrives, and
+         * with it as the only settle the promise never settles: in an MCP server
+         * that is a tool call that never returns, and therefore a calling agent that
+         * never returns.
+         *
+         * So `exit` — which needs nothing but the process — starts a short clock.
+         * The normal drain finishes in milliseconds and `close` wins the race; only
+         * a genuinely leaked descriptor reaches the timer, and it pays a truncated
+         * tail rather than the whole session.
+         */
+        child.on("exit", (code, signal) => {
+            // Recorded before anything else, and read by the deadline above: from here
+            // on we hold a real `code`/`signal`, so whatever the timer may still find
+            // alive in the process group, this is not a run that produced no verdict.
+            exited = true;
+            if (settled)
+                return;
+            graceTimer = setTimeout(() => {
+                // Released here rather than left to the garbage collector: the pipe is
+                // still open by definition on this path, so the two buffers behind it
+                // (up to MAX_OUTPUT_BYTES each) would be retained for the life of
+                // whatever is holding the descriptor.
+                child.stdout.destroy();
+                child.stderr.destroy();
+                settleWith(code, signal, false);
+            }, EXIT_CLOSE_GRACE_MS);
+            // Deliberately NOT `unref`'d, unlike the deadline above. That one is a
+            // ceiling on someone else's work and must never be the reason this process
+            // stays up; this one IS the settle — an unref'd timer only fires while
+            // something else holds the loop open, and the thing holding it here is the
+            // very pipe we are giving up on. It is bounded at EXIT_CLOSE_GRACE_MS and
+            // cleared by `finish`, so the most it can cost is one second of shutdown.
+        });
+        child.on("close", (code, signal) => settleWith(code, signal, true));
+    });
+};
+/**
+ * Kills the whole run, and answers whether there was anything to kill.
+ *
+ * `child.kill()` signals the CHILD. With `bundle exec specguard-lint` the child
+ * is `bundle` and the thing doing the work is its grandchild, which survives —
+ * still running, and still holding the pipes that `close` waits on. `detached`
+ * in `spawnChild` makes the child a process-group leader precisely so this
+ * function can signal the negated pid and reach the whole tree.
+ *
+ * The return value is the answer to "was a live process signalled", which is
+ * half of what the caller needs to decide whether a timeout actually happened —
+ * the other half is whether the CHILD has exited, because this group can outlive
+ * it. ESRCH — the group is already gone — is the normal way to learn "no", so it
+ * falls back to `child.kill`, whose `false` says the same thing about the child
+ * alone and whose own liveness check is what makes this safe on a platform where
+ * the group kill is not available.
+ *
+ * ONLY CALLED WHILE THE CHILD IS STILL LIVE, and that is a precondition rather
+ * than a convenience. `child.kill()` is safe by construction — Node reaped the
+ * child, so it knows the handle is spent and no-ops — but `process.kill(-pid)`
+ * is a raw signal at a number with no such check. After the reap that number is
+ * free, and on the one path where the group is ALSO empty (so ESRCH would have
+ * been the honest answer) a recycled pid that now leads some unrelated group
+ * would take a SIGKILL meant for a linter. It needs pid wraparound to land on a
+ * group leader, so it is vanishingly unlikely — but it is unrecoverable and
+ * aimed at a stranger, so the caller checks `exited` first rather than paying
+ * it. The cost of that choice is that stragglers outliving an already-exited
+ * child are left to leave on their own; the grace backstop settles regardless,
+ * and this is what `main` did too, where a kill after the reap was a no-op.
+ */
+function killRun(child) {
+    const pid = child.pid;
+    // Unset when the spawn itself failed; there is no process and no group.
+    if (pid === undefined)
+        return false;
+    try {
+        process.kill(-pid, "SIGKILL");
+        return true;
+    }
+    catch {
+        return child.kill("SIGKILL");
+    }
+}
+/**
+ * The one place `spawn` is called.
+ *
+ * Extracted so the call can be wrapped in a `try` without the surrounding
+ * promise losing the child's type.
+ */
+function spawnChild(program, args, options) {
+    return spawn(program, [...args], {
+        cwd: options.cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        // Explicitly off. Stated rather than defaulted, because this is the line
+        // that keeps a model-supplied argument from reaching a shell.
+        shell: false,
+        // A process group of its own, so the timeout can signal the whole run
+        // rather than only the process this server happens to have spawned — see
+        // `killRun`.
+        //
+        // Deliberately NOT paired with `child.unref()`, so the parent still waits on
+        // this handle rather than handing a linter permission to outlive the server.
+        // That is not the whole lifetime story though, and the honest version is
+        // that detaching buys the reach of the kill and PAYS for it here: a new
+        // group is also a new session, outside this server's controlling terminal,
+        // so a signal aimed at OUR group — an interactive Ctrl-C, a supervisor's
+        // `kill -- -PGID` — no longer reaches a lint run in flight. Nothing in
+        // `bin/specguard-mcp.ts` installs a SIGINT/SIGTERM handler to kill
+        // outstanding children at teardown, so such a run is now orphaned where it
+        // would previously have died alongside us. Worth it, because the failure
+        // being traded away is an agent that never returns rather than a stray
+        // process — but it is a trade, and a teardown handler is what would close
+        // it.
+        detached: true,
+    });
+}
+/**
+ * Which thing failed to run — asked rather than assumed.
+ *
+ * Node reports a non-existent `cwd` as `ENOENT` on the spawn: the same code and
+ * the same shape as a program that is not on PATH. Answering both with "it is not
+ * on this server's PATH" tells an operator whose only mistake was the directory
+ * to go and change the one thing that was right, and the caller of this function
+ * knows the difference is checkable. So on the error path — where an extra `stat`
+ * costs nothing — we ask which of the two is actually missing before naming a
+ * cause.
+ *
+ * This is the same reasoning as the non-zero-exit rule above: an outcome that
+ * leaves the caller with no verdict must not be described as some other outcome.
+ */
+function describeSpawnFailure(program, error, options) {
+    const cwd = options.cwd;
+    // Consulted before the errno, because more than one code means this same thing.
+    if (cwd !== undefined && !isDirectory(cwd))
+        return unusableCwd(program, cwd);
+    if (error.code === "ENOENT") {
+        const hint = options.notFoundHint === undefined ? "" : ` ${options.notFoundHint}`;
+        return `Could not run \`${program}\`: it is not on this server's PATH.${hint}`;
+    }
+    return `Could not run \`${program}\`: ${error.message}`;
+}
+function unusableCwd(program, cwd) {
+    return (`Could not run \`${program}\`: its working directory ${JSON.stringify(cwd)} does not exist, ` +
+        "or is not a directory. The command itself was not the problem.");
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Bounded accumulation of a child's output.
+ *
+ * An unbounded buffer here would let a linter run over a very large suite —
+ * exactly the suites SpecGuard exists for — decide this server's memory
+ * ceiling. Truncation is announced in the returned text rather than silent,
+ * because a JSON document cut in half must not look like a document that ended.
+ */
+class OutputBuffer {
+    #chunks = [];
+    #bytes = 0;
+    #truncated = false;
+    get truncated() {
+        return this.#truncated;
+    }
+    push(chunk) {
+        if (this.#truncated)
+            return;
+        if (this.#bytes + chunk.byteLength > MAX_OUTPUT_BYTES) {
+            this.#chunks.push(chunk.subarray(0, MAX_OUTPUT_BYTES - this.#bytes));
+            this.#truncated = true;
+            this.#bytes = MAX_OUTPUT_BYTES;
+            return;
+        }
+        this.#chunks.push(chunk);
+        this.#bytes += chunk.byteLength;
+    }
+    text() {
+        const body = Buffer.concat(this.#chunks).toString("utf8");
+        return this.#truncated ? `${body}\n[truncated at ${MAX_OUTPUT_BYTES} bytes]` : body;
+    }
+}
+//# sourceMappingURL=run-command.js.map

package/dist/src/support/run-command.js.map

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

package/dist/src/support/specguard-api.d.ts

@@ -0,0 +1,11 @@
+import { requireApiConfig, type ApiConfig } from "../config.js";
+/**
+ * The SpecGuard HTTP client — a Bearer key and a path, and nothing else.
+ *
+ * Authorization is enforced by the deployment (`Api::BaseController`), never
+ * here: this carries the operator's key and reports what came back. The bridge
+ * adds no credentials of its own and makes no access decisions, so there is no
+ * second place for the permission model to be got wrong.
+ */
+export declare function getJson(api: ApiConfig, path: string, query: Record<string, string | undefined>, fetchImpl: typeof globalThis.fetch): Promise<unknown>;
+export { requireApiConfig };

package/dist/src/support/specguard-api.js

@@ -0,0 +1,157 @@
+import { requireApiConfig } from "../config.js";
+import { ApiError } from "../errors.js";
+/**
+ * The SpecGuard HTTP client — a Bearer key and a path, and nothing else.
+ *
+ * Authorization is enforced by the deployment (`Api::BaseController`), never
+ * here: this carries the operator's key and reports what came back. The bridge
+ * adds no credentials of its own and makes no access decisions, so there is no
+ * second place for the permission model to be got wrong.
+ */
+export async function getJson(api, path, query, fetchImpl) {
+    const url = new URL(`${api.endpoint}${path}`);
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined)
+            url.searchParams.set(key, value);
+    }
+    const { response, body } = await fetchWithTimeout(url, api, fetchImpl);
+    if (!response.ok)
+        throw describeFailure(response.status, body, api);
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        throw new ApiError(`${api.endpoint} answered ${response.status} but the body was not JSON. ` +
+            `Check that ${api.endpointVariable} points at a SpecGuard deployment and not, say, a proxy ` +
+            "or login page.", response.status);
+    }
+}
+/**
+ * Tells "the deadline won the race" apart from any value a phase could produce.
+ *
+ * A resolved sentinel rather than a rejecting deadline promise: a promise that
+ * rejects has to be raced against every phase or its rejection is unhandled, and
+ * an unhandled rejection on stdio takes the whole transport down — the failure
+ * mode `errors.ts` exists to avoid.
+ */
+const TIMED_OUT = Symbol("specguard-api deadline");
+/**
+ * Headers AND body under ONE deadline.
+ *
+ * `SPECGUARD_TIMEOUT_MS` is documented in `config.ts` as how long an HTTP call
+ * to SpecGuard may take, and a call is not over when its headers arrive. An
+ * `AbortController` armed only around `fetchImpl` is disarmed the moment the
+ * response object resolves, so a deployment that answers `200 OK` and then
+ * dribbles — or freezes — the body leaves the body read awaiting with no
+ * deadline and no live signal. In an MCP server that is not a slow answer: it is
+ * a tool call, and therefore the agent that called it, which never returns.
+ *
+ * ONE TOTAL BUDGET, not one per phase. `requestTimeoutMs` bounds the whole call:
+ * headers and body share it, so a response whose headers took 29s of a 30s
+ * budget has 1s left in which to deliver its body. The sibling transport in
+ * `specguard-rspec` (`lib/specguard/rspec/transport.rb`) gives each phase its own
+ * full `@timeout` because `Net::HTTP` exposes exactly that knob and no other;
+ * here the deadline is ours to place, and a single total is both stricter and
+ * the thing an operator who set one number actually meant.
+ *
+ * The race is explicit rather than left to the abort signal. Aborting is still
+ * done — it tears a real connection down instead of leaking it — but WHETHER an
+ * aborted signal also errors an already-delivered body stream is a property of
+ * the fetch implementation, and this function takes `fetchImpl` from its caller.
+ * Racing the deadline here is what makes the bound hold for any implementation
+ * rather than for one in particular.
+ *
+ * The body is read HERE, inside the deadline, rather than by the caller one
+ * frame later, so there is no window in which the read is awaiting somewhere the
+ * timer does not reach.
+ */
+async function fetchWithTimeout(url, api, fetchImpl) {
+    const controller = new AbortController();
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            resolve(TIMED_OUT);
+        }, api.requestTimeoutMs);
+        // `unref` so a stalled body's timer cannot by itself hold the process open —
+        // the same reason `run-command.ts` unrefs the timer that kills a hung child.
+        timer.unref?.();
+    });
+    try {
+        const response = await Promise.race([
+            fetchImpl(url, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${api.apiKey}`,
+                    Accept: "application/json",
+                    "User-Agent": "specguard-mcp",
+                },
+                signal: controller.signal,
+            }),
+            deadline,
+        ]);
+        if (response === TIMED_OUT)
+            throw timedOut(api);
+        const body = await Promise.race([response.text(), deadline]);
+        if (body === TIMED_OUT)
+            throw timedOut(api);
+        return { response, body };
+    }
+    catch (error) {
+        // Already diagnosed above — a timeout, converted while the phase that hit it
+        // was still known. Rethrown before the transport branch so a deadline can
+        // never be re-described as "could not reach", which would name a cause that
+        // is the opposite of what happened: the deployment was reached, and stopped.
+        if (error instanceof ApiError)
+            throw error;
+        // A transport failure and a refusal are different problems with different
+        // fixes, and "fetch failed" names neither. The endpoint is echoed because
+        // the commonest cause by far is that it is wrong — and the variable is named
+        // from the config rather than spelled out here, so an operator who set
+        // SPECGUARD_URL is not sent to fix a variable they never set.
+        if (controller.signal.aborted)
+            throw timedOut(api);
+        throw new ApiError(`Could not reach ${api.endpoint}: ${error instanceof Error ? error.message : String(error)}. ` +
+            `Check ${api.endpointVariable} and that the deployment is reachable from this machine.`);
+    }
+    finally {
+        // Cleared on every exit — success, HTTP failure, transport failure and
+        // timeout alike — because the timer now outlives the fetch call itself.
+        clearTimeout(timer);
+    }
+}
+/**
+ * One sentence for both phases, because the operator's move is the same either
+ * way: raise `SPECGUARD_TIMEOUT_MS` or find out why the deployment is slow.
+ *
+ * Deliberately an `ApiError` and deliberately WITHOUT a status. Letting an
+ * `AbortError` escape instead would reach `describeError` in `server.ts` as a
+ * non-`SpecGuardMcpError` and be reported to the agent as "a bug in the bridge,
+ * not in your project or configuration" — exactly inverting the diagnosis for a
+ * peer that stalled. And there was no response, so there is no status to carry.
+ */
+function timedOut(api) {
+    return new ApiError(`${api.endpoint} did not respond within ${api.requestTimeoutMs}ms.`);
+}
+/**
+ * The status turned into something the agent can act on.
+ *
+ * 401 is called out by name because it is the one an operator will actually
+ * hit, and because SpecGuard answers it deliberately flat — "a valid Bearer API
+ * key is required", with no detail about why — so the useful half of the
+ * diagnosis has to be supplied from this side.
+ */
+function describeFailure(status, body, api) {
+    if (status === 401) {
+        return new ApiError("SpecGuard rejected the API key (401). SPECGUARD_API_KEY must be an sgk_… key issued by " +
+            `${api.endpoint} for the repository you are asking about — keys are per-repository, and a ` +
+            "revoked key reads the same as a wrong one.", status);
+    }
+    if (status === 404) {
+        return new ApiError(`${api.endpoint} has no such endpoint (404). Check that ${api.endpointVariable} is the ` +
+            "deployment's root URL, without a path.", status);
+    }
+    return new ApiError(`SpecGuard answered ${status}${body.trim() === "" ? "" : `: ${body.trim().slice(0, 500)}`}`, status);
+}
+export { requireApiConfig };
+//# sourceMappingURL=specguard-api.js.map

package/dist/src/support/specguard-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specguard-api.js","sourceRoot":"","sources":["../../../src/support/specguard-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAkB,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,GAAc,EACd,IAAY,EACZ,KAAyC,EACzC,SAAkC;IAElC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,QAAQ,GAAG,IAAI,EAAE,CAAC,CAAC;IAC9C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS;YAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAEvE,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAEpE,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAChB,GAAG,GAAG,CAAC,QAAQ,aAAa,QAAQ,CAAC,MAAM,8BAA8B;YACvE,cAAc,GAAG,CAAC,gBAAgB,0DAA0D;YAC5F,gBAAgB,EAClB,QAAQ,CAAC,MAAM,CAChB,CAAC;IACJ,CAAC;AACH,CAAC;AAQD;;;;;;;GAOG;AACH,MAAM,SAAS,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,KAAK,UAAU,gBAAgB,CAC7B,GAAQ,EACR,GAAc,EACd,SAAkC;IAElC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,IAAI,KAAgD,CAAC;IAErD,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAmB,CAAC,OAAO,EAAE,EAAE;QACzD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,UAAU,CAAC,KAAK,EAAE,CAAC;YACnB,OAAO,CAAC,SAAS,CAAC,CAAC;QACrB,CAAC,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;QACzB,6EAA6E;QAC7E,6EAA6E;QAC7E,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YAClC,SAAS,CAAC,GAAG,EAAE;gBACb,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE;oBACP,aAAa,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE;oBACrC,MAAM,EAAE,kBAAkB;oBAC1B,YAAY,EAAE,eAAe;iBAC9B;gBACD,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC;YACF,QAAQ;SACT,CAAC,CAAC;QACH,IAAI,QAAQ,KAAK,SAAS;YAAE,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;QAEhD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC7D,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;QAE5C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,6EAA6E;QAC7E,0EAA0E;QAC1E,4EAA4E;QAC5E,6EAA6E;QAC7E,IAAI,KAAK,YAAY,QAAQ;YAAE,MAAM,KAAK,CAAC;QAE3C,0EAA0E;QAC1E,0EAA0E;QAC1E,6EAA6E;QAC7E,uEAAuE;QACvE,8DAA8D;QAC9D,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;YAAE,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;QAEnD,MAAM,IAAI,QAAQ,CAChB,mBAAmB,GAAG,CAAC,QAAQ,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI;YAC5F,SAAS,GAAG,CAAC,gBAAgB,0DAA0D,CAC1F,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,uEAAuE;QACvE,wEAAwE;QACxE,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,QAAQ,CAAC,GAAc;IAC9B,OAAO,IAAI,QAAQ,CAAC,GAAG,GAAG,CAAC,QAAQ,2BAA2B,GAAG,CAAC,gBAAgB,KAAK,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,MAAc,EAAE,IAAY,EAAE,GAAc;IACnE,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,IAAI,QAAQ,CACjB,yFAAyF;YACvF,GAAG,GAAG,CAAC,QAAQ,4EAA4E;YAC3F,4CAA4C,EAC9C,MAAM,CACP,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,IAAI,QAAQ,CACjB,GAAG,GAAG,CAAC,QAAQ,2CAA2C,GAAG,CAAC,gBAAgB,UAAU;YACtF,wCAAwC,EAC1C,MAAM,CACP,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,QAAQ,CACjB,sBAAsB,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,EAC3F,MAAM,CACP,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/src/tools/args.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The tool-agnostic argument coercions — the shape checks every tool needs and
+ * no tool should re-derive.
+ *
+ * == Why this file exists at all
+ *
+ * `optionalString` was written twice, once per tool file, in the same commit
+ * that created both. The copies then diverged on the one thing a copy is most
+ * likely to get wrong: which of the four error classes to throw. One picked
+ * `ApiError`, the other `CommandError`, with byte-identical message strings —
+ * so the same malformed argument was reported as two different kinds of failure
+ * depending on which tool received it. That was repaired by re-pointing both
+ * throws at `ArgumentError`, but repairing two copies is not the same as having
+ * one, and the next tool author still has to choose the class again from
+ * scratch.
+ *
+ * `types.ts` promised, until SPGD-558 narrowed the claim to *wiring* edits,
+ * that adding a tool was "two mechanical edits with no third". Hand-copying
+ * these coercions and re-picking an error class was the unlisted third edit.
+ * This file removes it.
+ *
+ * == What belongs here, and what does not
+ *
+ * Only checks about the SHAPE of a value — is it a string, is it a boolean —
+ * whose failure is always `ArgumentError`, the class meaning "the call was
+ * malformed and the agent can fix it unaided on the next call".
+ *
+ * A check that reasons about what an argument MEANS to one particular wrapped
+ * tool stays with that tool. `optionalStringArray` in
+ * `lint-intent-annotations.ts` is the standing example: its refusals of an
+ * empty list and of a leading dash are about the linter's own argument grammar
+ * — what `paths: []` would make `specguard-lint` audit, what its OptionParser
+ * would read a `-` as — and they throw `CommandError` for that reason. Moving
+ * it here would drag one tool's semantics into a file the next tool imports.
+ *
+ * == Placement
+ *
+ * `src/tools/` rather than `src/support/`. `src/support/` holds injected
+ * outside-world capabilities — `run-command.ts`, `specguard-api.ts` — which
+ * reach tools through `ToolContext` and are substituted in tests. These are
+ * pure functions with no context and nothing to inject: they are part of the
+ * tool-authoring contract, which lives here beside `types.ts`.
+ */
+/**
+ * A non-blank string, or nothing.
+ */
+export declare function optionalString(value: unknown, field: string): string | undefined;
+export declare function optionalBoolean(value: unknown, field: string): boolean | undefined;

package/dist/src/tools/args.js

@@ -0,0 +1,66 @@
+import { ArgumentError } from "../errors.js";
+/**
+ * The tool-agnostic argument coercions — the shape checks every tool needs and
+ * no tool should re-derive.
+ *
+ * == Why this file exists at all
+ *
+ * `optionalString` was written twice, once per tool file, in the same commit
+ * that created both. The copies then diverged on the one thing a copy is most
+ * likely to get wrong: which of the four error classes to throw. One picked
+ * `ApiError`, the other `CommandError`, with byte-identical message strings —
+ * so the same malformed argument was reported as two different kinds of failure
+ * depending on which tool received it. That was repaired by re-pointing both
+ * throws at `ArgumentError`, but repairing two copies is not the same as having
+ * one, and the next tool author still has to choose the class again from
+ * scratch.
+ *
+ * `types.ts` promised, until SPGD-558 narrowed the claim to *wiring* edits,
+ * that adding a tool was "two mechanical edits with no third". Hand-copying
+ * these coercions and re-picking an error class was the unlisted third edit.
+ * This file removes it.
+ *
+ * == What belongs here, and what does not
+ *
+ * Only checks about the SHAPE of a value — is it a string, is it a boolean —
+ * whose failure is always `ArgumentError`, the class meaning "the call was
+ * malformed and the agent can fix it unaided on the next call".
+ *
+ * A check that reasons about what an argument MEANS to one particular wrapped
+ * tool stays with that tool. `optionalStringArray` in
+ * `lint-intent-annotations.ts` is the standing example: its refusals of an
+ * empty list and of a leading dash are about the linter's own argument grammar
+ * — what `paths: []` would make `specguard-lint` audit, what its OptionParser
+ * would read a `-` as — and they throw `CommandError` for that reason. Moving
+ * it here would drag one tool's semantics into a file the next tool imports.
+ *
+ * == Placement
+ *
+ * `src/tools/` rather than `src/support/`. `src/support/` holds injected
+ * outside-world capabilities — `run-command.ts`, `specguard-api.ts` — which
+ * reach tools through `ToolContext` and are substituted in tests. These are
+ * pure functions with no context and nothing to inject: they are part of the
+ * tool-authoring contract, which lives here beside `types.ts`.
+ */
+/**
+ * A non-blank string, or nothing.
+ */
+export function optionalString(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new ArgumentError(`\`${field}\` must be a string.`);
+    // Trimmed, not merely tested for blankness. `project_dir` becomes a `cwd`, so
+    // " /srv/app" — a path an agent produces by concatenating one — would otherwise
+    // be a directory that cannot exist, reported as a directory that does not.
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+export function optionalBoolean(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new ArgumentError(`\`${field}\` must be a boolean.`);
+    return value;
+}
+//# sourceMappingURL=args.js.map

package/dist/src/tools/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../../src/tools/args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,KAAa;IAC1D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,sBAAsB,CAAC,CAAC;IACzF,8EAA8E;IAC9E,gFAAgF;IAChF,2EAA2E;IAC3E,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,KAAa;IAC3D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,uBAAuB,CAAC,CAAC;IAC3F,OAAO,KAAK,CAAC;AACf,CAAC"}