specguard-mcp 0.1.2 → 0.1.4

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

@@ -14,7 +14,81 @@ 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),
+    });
+}
+/**
+ * `DELETE` — the destructive half of the transport, and deliberately the SAME
+ * function underneath `postJson` rather than beside it, for the reason
+ * `postJson`'s header states: everything expensive about this module is about
+ * the deadline, not the verb.
+ *
+ * Returns the RAW BODY TEXT rather than a parsed value, because the endpoints
+ * this serves answer `204` with NO body at all — the one response in the `sgu_`
+ * surface that is deliberately not JSON. `requestJson` JSON-parses every 2xx it
+ * sees, so routing a `204` through it would turn a successful delete into
+ * "answered 204 but the body was not JSON" — the trap this verb specifically
+ * introduces, and the reason the DELETE path has its own success handling
+ * instead of sharing `requestJson`'s. The status check and the
+ * "reached and refused" hand-off to `describeFailure` are still shared
+ * verbatim: only what happens to a SUCCESS body differs.
+ */
+export async function deleteJson(api, path, fetchImpl) {
+    const { response, body } = await fetchWithTimeout(new URL(`${api.endpoint}${path}`), api, fetchImpl, { method: "DELETE" });
+    if (!response.ok)
+        throw describeFailure(response.status, body, api);
+    return 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 +100,13 @@ 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.
  *
@@ -44,11 +125,7 @@ export async function getJson(api, path, query, fetchImpl) {
  * are the only legal body, it is that no tool re-types this guard.
  */
 export async function getJsonObject(api, path, query, fetchImpl) {
-    const body = await getJson(api, path, query, fetchImpl);
-    if (typeof body !== "object" || body === null || Array.isArray(body)) {
-        throw new ApiError("SpecGuard returned a JSON value that was not an object.");
-    }
-    return body;
+    return asJsonObject(await getJson(api, path, query, fetchImpl));
 }
 /**
  * Tells "the deadline won the race" apart from any value a phase could produce.
@@ -89,7 +166,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) => {
@@ -104,12 +181,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,
@@ -185,7 +267,65 @@ function describeFailure(status, body, api) {
         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 || status === 403) {
+        const message = refusalMessage(body, status);
+        if (message !== undefined)
+            return new ApiError(message, status);
+    }
     return new ApiError(`SpecGuard answered ${status}${body.trim() === "" ? "" : `: ${body.trim().slice(0, 500)}`}`, status);
 }
+/**
+ * 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.
+ *
+ * The 403 is the same shape under another status. `UserRepositoriesController#
+ * render_not_granted` renders `{error: "not_granted", message:, grant:}` — the
+ * `grant` block is simply ignored by the extractor, exactly as `details` is.
+ * Same defect (the generic branch truncating the one sentence that names the
+ * fix), same remedy — which is why the helper is ONE function parameterised on
+ * the status rather than two copies beside each other.
+ *
+ * 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 refusalMessage(body, status) {
+    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 (${status}): ${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"}

package/dist/src/tools/add-repository.d.ts

@@ -0,0 +1,55 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `POST /api/v1/repositories` as a tool — shipped today in the platform
+ * (`specguard/config/routes.rb`, `Api::V1::UserRepositoriesController#create`).
+ *
+ * == The first tool here that WRITES, and what that changed
+ *
+ * Everything before this read. The registry's standing rule is that a tool in
+ * `tools/list` is a promise an agent will act on, and this endpoint has existed
+ * on the platform for some time — what was missing was on THIS side: `getJson`
+ * hardcoded `method: "GET"` and took no body. `tools/index.ts` and
+ * `list-repositories.ts` both said so, and said the transport should land with
+ * the first write tool so it could be designed against a real request body and a
+ * real 4xx surface rather than invented for a caller that did not exist. This is
+ * that tool, and `postJson`/`postJsonObject` are that transport.
+ *
+ * == The request body is top-level, because the caller is an agent
+ *
+ * `{"github_full_name": "org/repo"}`, not `{"repository": {…}}`. The controller
+ * permits it that way and says why: this is a JSON API being driven by an agent,
+ * not a Rails form being submitted by a browser, and the top-level shape is what
+ * a caller writing curl by hand will send.
+ *
+ * == The format is NOT re-validated here, deliberately
+ *
+ * `Repository` validates `org/repo` itself, and a refusal now arrives through
+ * the 400 branch in `describeFailure` in SpecGuard's own words. A second format
+ * rule on this side is exactly what "a thin client that reshapes its upstream is
+ * not thin" forbids — it would be a rule with no owner, free to drift from the
+ * one that actually decides, and its divergence would surface as this bridge
+ * refusing a name the platform would have accepted. Checking that `full_name` is
+ * a present, non-blank string is the whole of the bridge's business: that is a
+ * shape check, which is why it is `requireString` from `args.ts` and not a
+ * hand-rolled one here.
+ *
+ * == The MODAL first answer is a 400, and it is the useful one
+ *
+ * `RepositoryRegistration::GrantVerifier` fails closed on a grant that is
+ * missing or stale, which is every person who has not opened SpecGuard in a
+ * browser since this shipped — the controller records that this is "an ordinary
+ * state and not an error". The sentence that comes back names the operator's
+ * exact next move (sign in, reconnect GitHub, retry), and reaching the agent
+ * intact is what the 400 branch in `specguard-api.ts` is for.
+ *
+ * == Why the description carries a hazard paragraph
+ *
+ * `types.ts` calls the description "prompt material, not documentation … the
+ * entire basis on which a model decides whether to call the tool". This tool is
+ * NOT idempotent and its 201 carries a reveal-once token, so an agent that
+ * learns those facts by hitting them has already lost the token. They are stated
+ * where they are read BEFORE the call is committed to, rather than left to be
+ * discovered from a failure.
+ */
+declare const addRepository: ToolDefinition;
+export default addRepository;

package/dist/src/tools/add-repository.js

@@ -0,0 +1,114 @@
+import { postJsonObject, requireUserApiConfig } from "../support/specguard-api.js";
+import { requireString } from "./args.js";
+/**
+ * `POST /api/v1/repositories` as a tool — shipped today in the platform
+ * (`specguard/config/routes.rb`, `Api::V1::UserRepositoriesController#create`).
+ *
+ * == The first tool here that WRITES, and what that changed
+ *
+ * Everything before this read. The registry's standing rule is that a tool in
+ * `tools/list` is a promise an agent will act on, and this endpoint has existed
+ * on the platform for some time — what was missing was on THIS side: `getJson`
+ * hardcoded `method: "GET"` and took no body. `tools/index.ts` and
+ * `list-repositories.ts` both said so, and said the transport should land with
+ * the first write tool so it could be designed against a real request body and a
+ * real 4xx surface rather than invented for a caller that did not exist. This is
+ * that tool, and `postJson`/`postJsonObject` are that transport.
+ *
+ * == The request body is top-level, because the caller is an agent
+ *
+ * `{"github_full_name": "org/repo"}`, not `{"repository": {…}}`. The controller
+ * permits it that way and says why: this is a JSON API being driven by an agent,
+ * not a Rails form being submitted by a browser, and the top-level shape is what
+ * a caller writing curl by hand will send.
+ *
+ * == The format is NOT re-validated here, deliberately
+ *
+ * `Repository` validates `org/repo` itself, and a refusal now arrives through
+ * the 400 branch in `describeFailure` in SpecGuard's own words. A second format
+ * rule on this side is exactly what "a thin client that reshapes its upstream is
+ * not thin" forbids — it would be a rule with no owner, free to drift from the
+ * one that actually decides, and its divergence would surface as this bridge
+ * refusing a name the platform would have accepted. Checking that `full_name` is
+ * a present, non-blank string is the whole of the bridge's business: that is a
+ * shape check, which is why it is `requireString` from `args.ts` and not a
+ * hand-rolled one here.
+ *
+ * == The MODAL first answer is a 400, and it is the useful one
+ *
+ * `RepositoryRegistration::GrantVerifier` fails closed on a grant that is
+ * missing or stale, which is every person who has not opened SpecGuard in a
+ * browser since this shipped — the controller records that this is "an ordinary
+ * state and not an error". The sentence that comes back names the operator's
+ * exact next move (sign in, reconnect GitHub, retry), and reaching the agent
+ * intact is what the 400 branch in `specguard-api.ts` is for.
+ *
+ * == Why the description carries a hazard paragraph
+ *
+ * `types.ts` calls the description "prompt material, not documentation … the
+ * entire basis on which a model decides whether to call the tool". This tool is
+ * NOT idempotent and its 201 carries a reveal-once token, so an agent that
+ * learns those facts by hitting them has already lost the token. They are stated
+ * where they are read BEFORE the call is committed to, rather than left to be
+ * discovered from a failure.
+ */
+const addRepository = {
+    name: "add_repository",
+    title: "Add repository",
+    description: "Registers a GitHub repository with SpecGuard for the person behind this server's user API " +
+        "key, and returns the repository along with its first CI API key. " +
+        "Takes `full_name` as `org/repo` — the same handle `list_repositories` reports and every other " +
+        "SpecGuard surface names a repository by. " +
+        "On success the response carries a `repository` block (`id`, `full_name`, `name`, " +
+        "`registered_at`) and an `api_key` block (`name`, `token`, `hint`, `created_at`). " +
+        "⚠️ `api_key.token` is shown THIS ONCE AND NEVER AGAIN — nothing stores it and no endpoint can " +
+        "re-serve it, so hand it to the user in your reply rather than assuming it can be fetched " +
+        "later. " +
+        "⚠️ This tool is NOT idempotent and it WRITES. If the call times out (SPECGUARD_TIMEOUT_MS) " +
+        "the registration may still have succeeded on the server, taking its one-time token with it; " +
+        "retrying then fails with `has already been taken`, which is the honest answer, and the " +
+        "recovery is SpecGuard's API-keys page in a browser. Do not retry a timeout blindly. " +
+        "Requires a CURRENT record of the caller's GitHub permissions, which only a browser session " +
+        "creates: a person who has not signed in to SpecGuard and connected GitHub recently is refused " +
+        "with a message saying exactly that, and the fix is theirs to perform in a browser — no " +
+        "argument to this tool can substitute for it. The repository must also be one the SpecGuard " +
+        "GitHub App is installed on and that this person administers. " +
+        "Needs SPECGUARD_USER_API_KEY (an sgu_… key), the same credential `list_repositories` reads " +
+        "and a DIFFERENT one from the sgk_… repository key `get_repository_overview` uses.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            full_name: {
+                type: "string",
+                description: "The repository to register, as `org/repo` (for example `acme/billing`) — the same " +
+                    "handle `list_repositories` reports. Not a URL and not a bare repository name. " +
+                    "SpecGuard validates the format and refuses an unusable one in its own words.",
+            },
+        },
+        required: ["full_name"],
+        // Closed for the reason `list_repositories` states: `server.ts` forwards
+        // `arguments` unvalidated, so an open schema would let a misspelled argument
+        // be dropped silently and the call answered as though it had been honoured.
+        // On a WRITE that is worse than on a read — the call still registers
+        // something, just not what the agent believed it was asking for.
+        additionalProperties: false,
+    },
+    async run(args, context) {
+        // Argument shape FIRST, before the config is resolved and before anything is
+        // sent: a malformed call is the one failure the agent can fix unaided, and
+        // it must not cost a write attempt to discover.
+        const fullName = requireString(args["full_name"], "full_name");
+        const api = requireUserApiConfig(context.config);
+        const registration = await postJsonObject(api, "/api/v1/repositories", { github_full_name: fullName }, context.fetch);
+        // Passed through exactly as `list_repositories` passes its listing through.
+        // It matters more here: `api_key.token` exists nowhere else, so any reshaping
+        // on this hop is a value that cannot be recovered rather than a field that
+        // can be re-fetched.
+        return {
+            text: JSON.stringify(registration, null, 2),
+            structured: registration,
+        };
+    },
+};
+export default addRepository;
+//# sourceMappingURL=add-repository.js.map

package/dist/src/tools/add-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-repository.js","sourceRoot":"","sources":["../../../src/tools/add-repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,aAAa,GAAmB;IACpC,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,gBAAgB;IACvB,WAAW,EACT,4FAA4F;QAC5F,mEAAmE;QACnE,gGAAgG;QAChG,2CAA2C;QAC3C,mFAAmF;QACnF,mFAAmF;QACnF,gGAAgG;QAChG,2FAA2F;QAC3F,SAAS;QACT,6FAA6F;QAC7F,8FAA8F;QAC9F,yFAAyF;QACzF,sFAAsF;QACtF,6FAA6F;QAC7F,gGAAgG;QAChG,yFAAyF;QACzF,6FAA6F;QAC7F,+DAA+D;QAC/D,6FAA6F;QAC7F,mFAAmF;IACrF,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,SAAS,EAAE;gBACT,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,oFAAoF;oBACpF,gFAAgF;oBAChF,8EAA8E;aACjF;SACF;QACD,QAAQ,EAAE,CAAC,WAAW,CAAC;QACvB,yEAAyE;QACzE,6EAA6E;QAC7E,4EAA4E;QAC5E,qEAAqE;QACrE,iEAAiE;QACjE,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO;QACrB,6EAA6E;QAC7E,2EAA2E;QAC3E,gDAAgD;QAChD,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,CAAC;QAE/D,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,YAAY,GAAG,MAAM,cAAc,CACvC,GAAG,EACH,sBAAsB,EACtB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,EAC9B,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,4EAA4E;QAC5E,8EAA8E;QAC9E,2EAA2E;QAC3E,qBAAqB;QACrB,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3C,UAAU,EAAE,YAAY;SACzB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,aAAa,CAAC"}

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

@@ -45,4 +45,24 @@
  * A non-blank string, or nothing.
  */
 export declare function optionalString(value: unknown, field: string): string | undefined;
+/**
+ * A non-blank string, and nothing else will do.
+ *
+ * The mandatory counterpart of `optionalString`, and it belongs here for the
+ * reason stated above rather than in the first tool that needs one: "is it
+ * present and a non-blank string" is a check about the SHAPE of a value, whose
+ * failure is always `ArgumentError`. Hand-rolling it inside a tool is the exact
+ * copy-paste this file was created to end — and the copy would have to re-pick
+ * the error class, which is the one thing the two `optionalString` copies got
+ * wrong.
+ *
+ * Trimmed like its optional sibling, and for the same reason: a value an agent
+ * produced by concatenating strings arrives with whitespace that is not part of
+ * what it meant to send.
+ *
+ * The two refusals are separate sentences on purpose. "You sent a number" and
+ * "you sent nothing" are different mistakes with different fixes, and a single
+ * message covering both would leave the agent to work out which it made.
+ */
+export declare function requireString(value: unknown, field: string): string;
 export declare function optionalBoolean(value: unknown, field: string): boolean | undefined;

package/dist/src/tools/args.js

@@ -56,6 +56,36 @@ export function optionalString(value, field) {
     const trimmed = value.trim();
     return trimmed === "" ? undefined : trimmed;
 }
+/**
+ * A non-blank string, and nothing else will do.
+ *
+ * The mandatory counterpart of `optionalString`, and it belongs here for the
+ * reason stated above rather than in the first tool that needs one: "is it
+ * present and a non-blank string" is a check about the SHAPE of a value, whose
+ * failure is always `ArgumentError`. Hand-rolling it inside a tool is the exact
+ * copy-paste this file was created to end — and the copy would have to re-pick
+ * the error class, which is the one thing the two `optionalString` copies got
+ * wrong.
+ *
+ * Trimmed like its optional sibling, and for the same reason: a value an agent
+ * produced by concatenating strings arrives with whitespace that is not part of
+ * what it meant to send.
+ *
+ * The two refusals are separate sentences on purpose. "You sent a number" and
+ * "you sent nothing" are different mistakes with different fixes, and a single
+ * message covering both would leave the agent to work out which it made.
+ */
+export function requireString(value, field) {
+    if (value === undefined || value === null) {
+        throw new ArgumentError(`\`${field}\` is required.`);
+    }
+    if (typeof value !== "string")
+        throw new ArgumentError(`\`${field}\` must be a string.`);
+    const trimmed = value.trim();
+    if (trimmed === "")
+        throw new ArgumentError(`\`${field}\` must not be blank.`);
+    return trimmed;
+}
 export function optionalBoolean(value, field) {
     if (value === undefined || value === null)
         return undefined;

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

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc,EAAE,KAAa;IACzD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,iBAAiB,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,sBAAsB,CAAC,CAAC;IAEzF,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,EAAE;QAAE,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,uBAAuB,CAAC,CAAC;IAE/E,OAAO,OAAO,CAAC;AACjB,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"}

package/dist/src/tools/create-repository-api-key.d.ts

@@ -0,0 +1,26 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `POST /api/v1/repositories/:repository_id/api_keys` as a tool — shipped in
+ * the platform (`specguard/config/routes.rb:158`,
+ * `user_repository_api_keys_controller#create`, SPGD-754).
+ *
+ * == Reveal-once, again
+ *
+ * The 201 body carries `api_key.token` — the raw key, the only time it exists
+ * anywhere — exactly as `add_repository`'s does. The body is therefore passed
+ * through UNRESHAPED in both `text` and `structured` for the same reason that
+ * tool states: any reshaping on this hop is a value that cannot be recovered
+ * rather than a field that can be re-fetched. Recovery for a dropped token is
+ * minting another key — this same tool — because the platform ships no
+ * `#regenerate` and no re-serve.
+ *
+ * == The name is top-level and optional
+ *
+ * `params[:name]` defaults to `ApiKey::DEFAULT_NAME` server-side; `undefined`
+ * here means "let the server name it" and simply omits the key from the POST
+ * body. Not re-validated here for the reason `add_repository` states: a second
+ * format rule on this side is a rule with no owner, free to drift from the one
+ * that actually decides.
+ */
+declare const createRepositoryApiKey: ToolDefinition;
+export default createRepositoryApiKey;