specguard-mcp 0.1.1 → 0.1.3

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

@@ -68,6 +68,48 @@ export declare const DEFAULT_COMMAND_TIMEOUT_MS = 120000;
  * descriptor costs a truncated tail instead of a call that never returns.
  */
 export declare const EXIT_CLOSE_GRACE_MS = 1000;
+/**
+ * The pids of every run currently spawned and not yet reaped.
+ *
+ * Exported for the teardown handler's diagnostics. A PROJECTION, not the set:
+ * it drops entries whose spawn never produced a process, because a `undefined`
+ * pid is not something a diagnostic can name or a caller can signal.
+ *
+ * That filter makes it the WRONG observer for asserting the set does not leak —
+ * see `outstandingRunCount`.
+ */
+export declare function outstandingRunPids(): readonly number[];
+/**
+ * How many runs are registered, counting those whose spawn produced no pid.
+ *
+ * The unfiltered companion to `outstandingRunPids`, and the one a leak test must
+ * use. The distinction is not pedantic: the spawn-failure path registers a child
+ * whose `pid` is `undefined`, so it is invisible to `outstandingRunPids` BY
+ * EXACTLY THE PROPERTY THAT MAKES IT A LEAK. A test asserting that path through
+ * the pid projection holds whether or not the deregistration happens, and would
+ * stay green if a refactor dropped it.
+ *
+ * The leak is memory-only — `killRun` returns `false` for an undefined pid, so a
+ * stranded entry is skipped by the drain rather than mis-signalled — but it is
+ * one entry per failed spawn for the life of the server, and it is only ever
+ * observable from outside. Hence a reader of the set itself.
+ */
+export declare function outstandingRunCount(): number;
+/**
+ * Kills every run still in flight, and answers how many it signalled.
+ *
+ * The teardown path. SYNCHRONOUS AND UNBOUNDED BY NOTHING — it sends signals and
+ * returns, it never waits for a child to die. That is deliberate: this runs from
+ * a SIGINT/SIGTERM handler, where anything that waits is something that can hang
+ * the shutdown it was supposed to perform. SIGKILL is not refusable, so there is
+ * no acknowledgement worth waiting for.
+ *
+ * It reuses `killRun` rather than re-deriving the kill, so the group-vs-child
+ * fallback and the spawn-failure guard have exactly one implementation. The set
+ * is snapshotted before iterating because `killRun` can drive an `exit` that
+ * mutates it.
+ */
+export declare function killOutstandingRuns(): number;
 /**
  * Runs a program with an argument LIST, never through a shell.
  *

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

@@ -15,6 +15,95 @@ export const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
  * descriptor costs a truncated tail instead of a call that never returns.
  */
 export const EXIT_CLOSE_GRACE_MS = 1_000;
+/**
+ * The runs that are spawned and not yet reaped.
+ *
+ * This exists because `detached: true` below buys the reach of the timeout kill
+ * and PAYS for it: a detached child is in 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. The
+ * run is then orphaned, and orphaned WITHOUT A DEADLINE: the 120s ceiling is a
+ * parent-side `setTimeout`, so killing the parent destroys the only thing that
+ * was going to stop it. On a 20k-example suite that is a full lint's worth of
+ * CPU held by a process attached to nothing. `killOutstandingRuns` is the
+ * teardown path that closes it, and this set is what tells it whom to signal.
+ *
+ * MEMBERSHIP MEANS "NOT YET REAPED", and that is load-bearing rather than
+ * descriptive: `killRun` signals a raw negated pid, which has no liveness check
+ * of its own, so a stale entry is a SIGKILL aimed at whatever recycled that pid.
+ * Entries are therefore removed on the child's own `exit` — the reap — and NOT
+ * at settle, which on the grace-backstop path happens up to EXIT_CLOSE_GRACE_MS
+ * later. Deleting at settle would leave exactly the window in which a drain
+ * would signal a freed pid.
+ *
+ * The accepted consequence is the one this file already takes at `killRun`: a
+ * straggler outliving an already-exited child is not killed at teardown. That
+ * trade is deliberate and is not widened here.
+ */
+const liveChildren = new Set();
+/**
+ * The pids of every run currently spawned and not yet reaped.
+ *
+ * Exported for the teardown handler's diagnostics. A PROJECTION, not the set:
+ * it drops entries whose spawn never produced a process, because a `undefined`
+ * pid is not something a diagnostic can name or a caller can signal.
+ *
+ * That filter makes it the WRONG observer for asserting the set does not leak —
+ * see `outstandingRunCount`.
+ */
+export function outstandingRunPids() {
+    const pids = [];
+    for (const child of liveChildren) {
+        if (child.pid !== undefined)
+            pids.push(child.pid);
+    }
+    return pids;
+}
+/**
+ * How many runs are registered, counting those whose spawn produced no pid.
+ *
+ * The unfiltered companion to `outstandingRunPids`, and the one a leak test must
+ * use. The distinction is not pedantic: the spawn-failure path registers a child
+ * whose `pid` is `undefined`, so it is invisible to `outstandingRunPids` BY
+ * EXACTLY THE PROPERTY THAT MAKES IT A LEAK. A test asserting that path through
+ * the pid projection holds whether or not the deregistration happens, and would
+ * stay green if a refactor dropped it.
+ *
+ * The leak is memory-only — `killRun` returns `false` for an undefined pid, so a
+ * stranded entry is skipped by the drain rather than mis-signalled — but it is
+ * one entry per failed spawn for the life of the server, and it is only ever
+ * observable from outside. Hence a reader of the set itself.
+ */
+export function outstandingRunCount() {
+    return liveChildren.size;
+}
+/**
+ * Kills every run still in flight, and answers how many it signalled.
+ *
+ * The teardown path. SYNCHRONOUS AND UNBOUNDED BY NOTHING — it sends signals and
+ * returns, it never waits for a child to die. That is deliberate: this runs from
+ * a SIGINT/SIGTERM handler, where anything that waits is something that can hang
+ * the shutdown it was supposed to perform. SIGKILL is not refusable, so there is
+ * no acknowledgement worth waiting for.
+ *
+ * It reuses `killRun` rather than re-deriving the kill, so the group-vs-child
+ * fallback and the spawn-failure guard have exactly one implementation. The set
+ * is snapshotted before iterating because `killRun` can drive an `exit` that
+ * mutates it.
+ */
+export function killOutstandingRuns() {
+    const children = [...liveChildren];
+    let signalled = 0;
+    for (const child of children) {
+        // Removed FIRST, so the entry is gone even if the kill throws. A registry
+        // that kept a child it had already tried to kill would hand a second drain
+        // the same stale pid.
+        liveChildren.delete(child);
+        if (killRun(child))
+            signalled += 1;
+    }
+    return signalled;
+}
 /**
  * Runs a program with an argument LIST, never through a shell.
  *
@@ -128,6 +217,11 @@ export const runCommand = (argv, options = {}) => {
         child.stdout.on("data", (chunk) => stdout.push(chunk));
         child.stderr.on("data", (chunk) => stderr.push(chunk));
         child.on("error", (error) => {
+            // The spawn-failure path: there is no process, and `child.pid` is
+            // `undefined`, so this entry can never be a legitimate kill target. Dropped
+            // here because `exit` does not always follow an `error` — leaving it would
+            // strand an unkillable entry in the registry for the life of the server.
+            liveChildren.delete(child);
             finish(() => reject(new CommandError(describeSpawnFailure(program, error, options))));
         });
         /**
@@ -153,6 +247,20 @@ export const runCommand = (argv, options = {}) => {
             // 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;
+            // Deregistered HERE — at the reap, alongside `exited`, and deliberately not
+            // at the settle below. The two are not the same instant: on the grace
+            // backstop `exit` fires and `settleWith` follows up to EXIT_CLOSE_GRACE_MS
+            // later, so a registry keyed on settle would hold a child whose pid the
+            // kernel has already freed, and a teardown drain landing in that window
+            // would fire `process.kill(-pid)` at whatever now owns that number. That
+            // is the unrecoverable, aimed-at-a-stranger hazard `killRun` documents and
+            // refuses to pay; membership must mean "not yet reaped" so its precondition
+            // holds by construction.
+            //
+            // Placed BEFORE the `settled` early-return for the same reason: the
+            // already-settled path is a reap too, and returning first would leak the
+            // entry.
+            liveChildren.delete(child);
             if (settled)
                 return;
             graceTimer = setTimeout(() => {
@@ -224,7 +332,7 @@ function killRun(child) {
  * promise losing the child's type.
  */
 function spawnChild(program, args, options) {
-    return spawn(program, [...args], {
+    const child = spawn(program, [...args], {
         cwd: options.cwd,
         stdio: ["ignore", "pipe", "pipe"],
         // Explicitly off. Stated rather than defaulted, because this is the line
@@ -240,15 +348,23 @@ function spawnChild(program, args, options) {
         // 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.
+        // `kill -- -PGID` — no longer reaches a lint run in flight. Such a run would
+        // be orphaned where it would previously have died alongside us, and orphaned
+        // without a deadline, since the ceiling above is a parent-side timer.
+        //
+        // That is the debt this line used to carry, and it is now PAID rather than
+        // merely disclosed: the run is registered in `liveChildren` below, and
+        // `bin/specguard-mcp.ts` installs SIGINT/SIGTERM handlers that call
+        // `killOutstandingRuns` before exiting. The trade the kill's reach was
+        // bought with is closed; do not remove either half without restoring the
+        // other.
         detached: true,
     });
+    // Registered at the single spawn call site, so a run cannot enter the world
+    // unregistered. Removed again on the child's own `exit` — see `liveChildren`
+    // for why the reap, and not the settle, is the moment that matters.
+    liveChildren.add(child);
+    return child;
 }
 /**
  * Which thing failed to run — asked rather than assumed.

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

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

@@ -1,4 +1,4 @@
-import { requireApiConfig, type ApiConfig } from "../config.js";
+import { requireApiConfig, requireUserApiConfig, type ApiConfig } from "../config.js";
 /**
  * The SpecGuard HTTP client — a Bearer key and a path, and nothing else.
  *
@@ -8,4 +8,55 @@ import { requireApiConfig, type ApiConfig } from "../config.js";
  * 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 };
+/**
+ * `POST` with a JSON body — the write half of the transport, and deliberately
+ * the SAME function underneath.
+ *
+ * It shares `fetchWithTimeout` rather than standing beside it. The one-total-
+ * budget deadline, the explicit race, the `unref`'d timer, the abort and the
+ * "reached and stopped" vs "could not reach" split are the expensive part of
+ * this module and every argument for them is written above them — none of it is
+ * about the verb. A second transport re-deriving them is how the two come to
+ * disagree about what `SPECGUARD_TIMEOUT_MS` bounds, and the write path is the
+ * one where a call that never returns costs the most: the agent has already
+ * committed to a registration by the time it hangs.
+ *
+ * The body is serialized HERE rather than taken as a string, so no caller can
+ * send a body whose `Content-Type` says JSON and whose bytes are not.
+ */
+export declare function postJson(api: ApiConfig, path: string, body: Record<string, unknown>, fetchImpl: typeof globalThis.fetch): Promise<unknown>;
+/**
+ * `postJson`, narrowed exactly as `getJsonObject` narrows `getJson`.
+ *
+ * The write path needs the same guard for the same reason, and the reason is not
+ * about reading: `ToolResult.structured` is a `Record<string, unknown>`, so a
+ * body that is an array or a bare scalar is not something a tool can pass
+ * through whichever verb fetched it. Shipping only the raw `postJson` would
+ * leave the first write tool to re-type the three-clause check and its sentence
+ * — which is precisely the duplication `getJsonObject`'s header says no tool
+ * should have to repeat.
+ *
+ * The pair is mirrored rather than collapsed for the reason the read pair is:
+ * `postJson` stays exported un-narrowed for an endpoint that legitimately
+ * answers with an array.
+ */
+export declare function postJsonObject(api: ApiConfig, path: string, body: Record<string, unknown>, fetchImpl: typeof globalThis.fetch): Promise<Record<string, unknown>>;
+/**
+ * `getJson`, narrowed to the object every tool here actually asks it for.
+ *
+ * MCP hands a tool result back as an object, so an array or a bare JSON scalar
+ * is not something a tool can pass through: it surfaces as a protocol error
+ * rather than as something the agent can read. Every HTTP tool therefore
+ * needed the same three-clause guard, and the same sentence, immediately after
+ * its own `getJson` call — which made both the check and its wording the one
+ * thing each new tool had to remember to write for itself, and get identical.
+ *
+ * It belongs here for the reason `requireApiConfig` parses the endpoint rather
+ * than leaving that to callers: every HTTP-backed tool added later comes
+ * through this function and inherits the check, the same way it inherits the
+ * URL check and the 401 wording. `getJson` stays exported un-narrowed for an
+ * endpoint that legitimately serves an array — the point is not that objects
+ * are the only legal body, it is that no tool re-types this guard.
+ */
+export declare function getJsonObject(api: ApiConfig, path: string, query: Record<string, string | undefined>, fetchImpl: typeof globalThis.fetch): Promise<Record<string, unknown>>;
+export { requireApiConfig, requireUserApiConfig };

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

@@ -1,4 +1,4 @@
-import { requireApiConfig } from "../config.js";
+import { requireApiConfig, requireUserApiConfig } from "../config.js";
 import { ApiError } from "../errors.js";
 /**
  * The SpecGuard HTTP client — a Bearer key and a path, and nothing else.
@@ -14,7 +14,59 @@ export async function getJson(api, path, query, fetchImpl) {
         if (value !== undefined)
             url.searchParams.set(key, value);
     }
-    const { response, body } = await fetchWithTimeout(url, api, fetchImpl);
+    return requestJson(url, api, fetchImpl, { method: "GET" });
+}
+/**
+ * `POST` with a JSON body — the write half of the transport, and deliberately
+ * the SAME function underneath.
+ *
+ * It shares `fetchWithTimeout` rather than standing beside it. The one-total-
+ * budget deadline, the explicit race, the `unref`'d timer, the abort and the
+ * "reached and stopped" vs "could not reach" split are the expensive part of
+ * this module and every argument for them is written above them — none of it is
+ * about the verb. A second transport re-deriving them is how the two come to
+ * disagree about what `SPECGUARD_TIMEOUT_MS` bounds, and the write path is the
+ * one where a call that never returns costs the most: the agent has already
+ * committed to a registration by the time it hangs.
+ *
+ * The body is serialized HERE rather than taken as a string, so no caller can
+ * send a body whose `Content-Type` says JSON and whose bytes are not.
+ */
+export async function postJson(api, path, body, fetchImpl) {
+    return requestJson(new URL(`${api.endpoint}${path}`), api, fetchImpl, {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+}
+/**
+ * `postJson`, narrowed exactly as `getJsonObject` narrows `getJson`.
+ *
+ * The write path needs the same guard for the same reason, and the reason is not
+ * about reading: `ToolResult.structured` is a `Record<string, unknown>`, so a
+ * body that is an array or a bare scalar is not something a tool can pass
+ * through whichever verb fetched it. Shipping only the raw `postJson` would
+ * leave the first write tool to re-type the three-clause check and its sentence
+ * — which is precisely the duplication `getJsonObject`'s header says no tool
+ * should have to repeat.
+ *
+ * The pair is mirrored rather than collapsed for the reason the read pair is:
+ * `postJson` stays exported un-narrowed for an endpoint that legitimately
+ * answers with an array.
+ */
+export async function postJsonObject(api, path, body, fetchImpl) {
+    return asJsonObject(await postJson(api, path, body, fetchImpl));
+}
+/**
+ * Everything both verbs do with a response, in one place.
+ *
+ * Extracted when the write path landed rather than copied into it: the status
+ * check, the "reached and refused" hand-off to `describeFailure` and the
+ * not-JSON sentence are identical for a `GET` and a `POST`, and the not-JSON
+ * sentence in particular is a diagnosis an operator acts on — a second copy is a
+ * second wording waiting to drift from this one.
+ */
+async function requestJson(url, api, fetchImpl, request) {
+    const { response, body } = await fetchWithTimeout(url, api, fetchImpl, request);
     if (!response.ok)
         throw describeFailure(response.status, body, api);
     try {
@@ -26,6 +78,33 @@ export async function getJson(api, path, query, fetchImpl) {
             "or login page.", response.status);
     }
 }
+/** The three-clause guard both `*JsonObject` narrowings share. */
+function asJsonObject(body) {
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        throw new ApiError("SpecGuard returned a JSON value that was not an object.");
+    }
+    return body;
+}
+/**
+ * `getJson`, narrowed to the object every tool here actually asks it for.
+ *
+ * MCP hands a tool result back as an object, so an array or a bare JSON scalar
+ * is not something a tool can pass through: it surfaces as a protocol error
+ * rather than as something the agent can read. Every HTTP tool therefore
+ * needed the same three-clause guard, and the same sentence, immediately after
+ * its own `getJson` call — which made both the check and its wording the one
+ * thing each new tool had to remember to write for itself, and get identical.
+ *
+ * It belongs here for the reason `requireApiConfig` parses the endpoint rather
+ * than leaving that to callers: every HTTP-backed tool added later comes
+ * through this function and inherits the check, the same way it inherits the
+ * URL check and the 401 wording. `getJson` stays exported un-narrowed for an
+ * endpoint that legitimately serves an array — the point is not that objects
+ * are the only legal body, it is that no tool re-types this guard.
+ */
+export async function getJsonObject(api, path, query, fetchImpl) {
+    return asJsonObject(await getJson(api, path, query, fetchImpl));
+}
 /**
  * Tells "the deadline won the race" apart from any value a phase could produce.
  *
@@ -65,7 +144,7 @@ const TIMED_OUT = Symbol("specguard-api deadline");
  * 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) {
+async function fetchWithTimeout(url, api, fetchImpl, request) {
     const controller = new AbortController();
     let timer;
     const deadline = new Promise((resolve) => {
@@ -80,12 +159,17 @@ async function fetchWithTimeout(url, api, fetchImpl) {
     try {
         const response = await Promise.race([
             fetchImpl(url, {
-                method: "GET",
+                method: request.method,
                 headers: {
                     Authorization: `Bearer ${api.apiKey}`,
                     Accept: "application/json",
                     "User-Agent": "specguard-mcp",
+                    // Sent only when there IS a body. A `Content-Type` on a GET announces
+                    // a payload that is not there, and some deployments and proxies treat
+                    // that as a malformed request rather than as a harmless header.
+                    ...(request.body === undefined ? {} : { "Content-Type": "application/json" }),
                 },
+                ...(request.body === undefined ? {} : { body: request.body }),
                 signal: controller.signal,
             }),
             deadline,
@@ -140,18 +224,79 @@ function timedOut(api) {
  * 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.
+ *
+ * WHICH VARIABLE AND WHICH PREFIX ARE READ OFF `api.credential`, never spelled
+ * out here. SpecGuard has two credential kinds that refuse each other's tokens
+ * before any table is read, so this one branch is reached by tools reading two
+ * different variables — and the sentence it used to hardcode ("SPECGUARD_API_KEY
+ * must be an sgk_… key … keys are per-repository") is false in all three of its
+ * claims for a user-scoped tool, naming a variable its operator may never have
+ * touched. That is the same defect `endpointVariable` fixes one branch down, and
+ * it gets the same remedy rather than a second hardcoded string: a tool added
+ * later inherits correct naming from the `require*` helper it already calls.
  */
 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);
+        const { variable, prefix, rejection } = api.credential;
+        return new ApiError(`SpecGuard rejected the API key (401). ${variable} must be an ${prefix}… key issued by ` +
+            `${api.endpoint} ${rejection}.`, 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);
     }
+    if (status === 400) {
+        const message = badRequestMessage(body);
+        if (message !== undefined)
+            return new ApiError(message, status);
+    }
     return new ApiError(`SpecGuard answered ${status}${body.trim() === "" ? "" : `: ${body.trim().slice(0, 500)}`}`, status);
 }
-export { requireApiConfig };
+/**
+ * The sentence SpecGuard already wrote, or nothing.
+ *
+ * `Api::BaseController#render_bad_request` is a CONTRACT, not an ad-hoc body:
+ * `{error:, message:, details:}`, where `details` carries every validation
+ * failure and `message` repeats the first "so a client that reads only the two
+ * conventional keys still learns which spec is at fault". Both callers of it on
+ * `origin/main` route here, so this branch serves the API surface rather than
+ * one tool.
+ *
+ * SURFACING IT IS THE OPPOSITE OF RESHAPING IT. The generic branch below turns
+ * the most useful sentence in this direction —
+ *
+ *   "cannot be registered from an API key — SpecGuard has no current record of
+ *    your GitHub permissions. Sign in to SpecGuard in a browser and reconnect
+ *    GitHub, then try again."
+ *
+ * — into a JSON blob glued to "SpecGuard answered 400" and truncated at 500
+ * characters. That sentence names the operator's exact next move, and it is the
+ * MODAL first answer this endpoint gives: `GrantVerifier` fails closed on a
+ * missing or stale grant, which is every person who has not opened SpecGuard in
+ * a browser since the feature shipped. `:not_administered`, `:not_in_installation`
+ * and "has already been taken" arrive the same way. This branch does not author
+ * a sentence the way the 401 and 404 branches must — it stops DISCARDING one.
+ *
+ * Returns `undefined` rather than a fallback string, so the decision about what
+ * to say when the body is not that shape stays in one place. A 400 from
+ * somewhere that is not this contract — a proxy's HTML, a bare string, JSON
+ * whose `message` is absent or is not a string — still gets the generic
+ * sentence, which at least shows the operator what actually came back.
+ */
+function badRequestMessage(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const message = parsed["message"];
+    if (typeof message !== "string" || message.trim() === "")
+        return undefined;
+    return `SpecGuard refused the request (400): ${message.trim()}`;
+}
+export { requireApiConfig, requireUserApiConfig };
 //# sourceMappingURL=specguard-api.js.map

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

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

package/dist/src/support/teardown.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Kill the runs we started before going away.
+ *
+ * `run-command.ts` spawns every run `detached`, which is what lets a timeout
+ * signal the whole process tree rather than only the process we forked. The
+ * cost is that a detached child is in its own session, outside this server's
+ * controlling terminal, so a signal aimed at OUR group — an interactive Ctrl-C,
+ * a supervisor's `kill -- -PGID` — does not reach a lint run in flight. Without
+ * the handlers below such a run is not merely orphaned but UNBOUNDED: the
+ * `DEFAULT_COMMAND_TIMEOUT_MS` ceiling is a parent-side timer, so killing the
+ * parent destroys the only thing that was ever going to stop it, and a lint of a
+ * 20k-example suite goes on burning CPU with nobody waiting for its answer.
+ *
+ * == Why this is not written inline in `bin/specguard-mcp.ts`
+ *
+ * It lives here so a test can install the REAL handler. `bin/` runs `main()` on
+ * import, so a test that imported it would connect a transport rather than
+ * exercise a teardown, and the alternative — retyping the handler inside a test
+ * fixture — would assert that a COPY of the logic works while the shipped one
+ * went unread. `bin/` is left as the one place the policy is applied, which is
+ * the same split it already makes for the transport.
+ *
+ * DIAGNOSTICS GO TO STDERR, without exception. On stdio, stdout IS the JSON-RPC
+ * protocol channel: a line written there is framed as a message on the way out
+ * and corrupts the stream the client is still reading, surfacing as an
+ * unexplained disconnect rather than as the shutdown it actually was.
+ *
+ * NOTHING HERE WAITS. `killOutstandingRuns` sends SIGKILL and returns; SIGKILL
+ * cannot be refused, so there is no acknowledgement worth blocking a shutdown
+ * for. A teardown path that waits is a teardown path that can hang, which is the
+ * failure this handler exists to prevent rather than one to introduce.
+ */
+export declare function installTeardown(): void;

package/dist/src/support/teardown.js

@@ -0,0 +1,56 @@
+import { killOutstandingRuns } from "./run-command.js";
+/**
+ * Kill the runs we started before going away.
+ *
+ * `run-command.ts` spawns every run `detached`, which is what lets a timeout
+ * signal the whole process tree rather than only the process we forked. The
+ * cost is that a detached child is in its own session, outside this server's
+ * controlling terminal, so a signal aimed at OUR group — an interactive Ctrl-C,
+ * a supervisor's `kill -- -PGID` — does not reach a lint run in flight. Without
+ * the handlers below such a run is not merely orphaned but UNBOUNDED: the
+ * `DEFAULT_COMMAND_TIMEOUT_MS` ceiling is a parent-side timer, so killing the
+ * parent destroys the only thing that was ever going to stop it, and a lint of a
+ * 20k-example suite goes on burning CPU with nobody waiting for its answer.
+ *
+ * == Why this is not written inline in `bin/specguard-mcp.ts`
+ *
+ * It lives here so a test can install the REAL handler. `bin/` runs `main()` on
+ * import, so a test that imported it would connect a transport rather than
+ * exercise a teardown, and the alternative — retyping the handler inside a test
+ * fixture — would assert that a COPY of the logic works while the shipped one
+ * went unread. `bin/` is left as the one place the policy is applied, which is
+ * the same split it already makes for the transport.
+ *
+ * DIAGNOSTICS GO TO STDERR, without exception. On stdio, stdout IS the JSON-RPC
+ * protocol channel: a line written there is framed as a message on the way out
+ * and corrupts the stream the client is still reading, surfacing as an
+ * unexplained disconnect rather than as the shutdown it actually was.
+ *
+ * NOTHING HERE WAITS. `killOutstandingRuns` sends SIGKILL and returns; SIGKILL
+ * cannot be refused, so there is no acknowledgement worth blocking a shutdown
+ * for. A teardown path that waits is a teardown path that can hang, which is the
+ * failure this handler exists to prevent rather than one to introduce.
+ */
+export function installTeardown() {
+    let tearingDown = false;
+    const teardown = (signal, status) => {
+        // A second Ctrl-C while the first is still unwinding must not re-enter the
+        // drain — the registry is already empty and the pids in it already spent.
+        if (tearingDown)
+            return;
+        tearingDown = true;
+        const killed = killOutstandingRuns();
+        if (killed > 0) {
+            process.stderr.write(`specguard-mcp: ${signal} received, killed ${killed} run${killed === 1 ? "" : "s"} still in flight\n`);
+        }
+        // The conventional 128 + signo, so a supervisor reads "died on SIGINT"
+        // rather than an ordinary failure. Exiting explicitly rather than restoring
+        // the default disposition and re-signalling ourselves: we hold no other
+        // teardown obligation, and an explicit status cannot be lost to a handler
+        // installed elsewhere.
+        process.exit(status);
+    };
+    process.on("SIGINT", () => teardown("SIGINT", 130));
+    process.on("SIGTERM", () => teardown("SIGTERM", 143));
+}
+//# sourceMappingURL=teardown.js.map

package/dist/src/support/teardown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teardown.js","sourceRoot":"","sources":["../../../src/support/teardown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,WAAW,GAAG,KAAK,CAAC;IAExB,MAAM,QAAQ,GAAG,CAAC,MAA4B,EAAE,MAAc,EAAE,EAAE;QAChE,2EAA2E;QAC3E,0EAA0E;QAC1E,IAAI,WAAW;YAAE,OAAO;QACxB,WAAW,GAAG,IAAI,CAAC;QAEnB,MAAM,MAAM,GAAG,mBAAmB,EAAE,CAAC;QAErC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,kBAAkB,MAAM,qBAAqB,MAAM,OAAO,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,oBAAoB,CACtG,CAAC;QACJ,CAAC;QAED,uEAAuE;QACvE,4EAA4E;QAC5E,wEAAwE;QACxE,0EAA0E;QAC1E,uBAAuB;QACvB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;AACxD,CAAC"}