specguard-mcp 0.1.1 → 0.1.3

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/index.d.ts

@@ -20,6 +20,18 @@ import type { ToolDefinition } from "./types.js";
  * the two halves of the surface — one local subprocess, one authenticated HTTP
  * call — so the shape is proven on both kinds of capability rather than on one.
  *
+ * == The third: the first tool that reads the OTHER credential
+ *
+ *   - `list_repositories` wraps `GET /api/v1/repositories` (shipped:
+ *     `specguard/config/routes.rb`, `Api::V1::UserRepositoriesController`).
+ *
+ * It is the only tool here that answers to an `sgu_` USER key rather than an
+ * `sgk_` repository key, and SpecGuard refuses each credential in the other's
+ * place before it reads a table. So this entry is also what proves the second
+ * variable, the second `require*` helper and the credential-aware diagnostics
+ * work end to end — one tool, over a real endpoint, rather than a seam nothing
+ * exercises.
+ *
  * == What is deliberately absent
  *
  * `/check-intent` and duplicate clustering are NOT here and must not be added
@@ -28,6 +40,27 @@ import type { ToolDefinition } from "./types.js";
  * endpoint that does not exist would produce a server that discovers cleanly
  * and fails on use, which is worse than not offering the tool, because the
  * agent has already committed to a plan by the time it finds out.
+ *
+ * == The fourth: the first tool that WRITES
+ *
+ *   - `add_repository` wraps `POST /api/v1/repositories` (shipped:
+ *     `specguard/config/routes.rb`, `Api::V1::UserRepositoriesController#create`).
+ *
+ * The endpoint had shipped for a while; what this bridge lacked was a way to
+ * CALL it — `support/specguard-api.ts` offered only `getJson`, which hardcoded
+ * `method: "GET"` and took no body. The reservation recorded here was that the
+ * write transport should land WITH the first write tool, designed against a real
+ * request body and a real 4xx surface rather than invented for a caller that did
+ * not exist. That is what happened: `postJson`/`postJsonObject` arrived with
+ * this entry, sharing `fetchWithTimeout` with the read path rather than standing
+ * beside it, and `describeFailure` grew the `400` branch that surfaces
+ * SpecGuard's own refusal sentence — the modal answer this endpoint gives.
+ *
+ * The standing rule is unchanged and still binding, which is what keeps the rest
+ * of the user-scoped write surface out: `DELETE /api/v1/repositories/:id` and
+ * the API-key endpoints (SPGD-754) are NOT on `origin/main`, so they may not be
+ * wrapped here however useful a tool for them would be. What moved was the
+ * platform, not the bar.
  */
 export declare const TOOLS: readonly ToolDefinition[];
 export type { ToolContext, ToolDefinition, ToolResult } from "./types.js";

package/dist/src/tools/index.js

@@ -1,4 +1,6 @@
+import addRepository from "./add-repository.js";
 import lintIntentAnnotations from "./lint-intent-annotations.js";
+import listRepositories from "./list-repositories.js";
 import getRepositoryOverview from "./repository-overview.js";
 /**
  * THE REGISTRY — the one file that changes when the toolset grows.
@@ -21,6 +23,18 @@ import getRepositoryOverview from "./repository-overview.js";
  * the two halves of the surface — one local subprocess, one authenticated HTTP
  * call — so the shape is proven on both kinds of capability rather than on one.
  *
+ * == The third: the first tool that reads the OTHER credential
+ *
+ *   - `list_repositories` wraps `GET /api/v1/repositories` (shipped:
+ *     `specguard/config/routes.rb`, `Api::V1::UserRepositoriesController`).
+ *
+ * It is the only tool here that answers to an `sgu_` USER key rather than an
+ * `sgk_` repository key, and SpecGuard refuses each credential in the other's
+ * place before it reads a table. So this entry is also what proves the second
+ * variable, the second `require*` helper and the credential-aware diagnostics
+ * work end to end — one tool, over a real endpoint, rather than a seam nothing
+ * exercises.
+ *
  * == What is deliberately absent
  *
  * `/check-intent` and duplicate clustering are NOT here and must not be added
@@ -29,6 +43,32 @@ import getRepositoryOverview from "./repository-overview.js";
  * endpoint that does not exist would produce a server that discovers cleanly
  * and fails on use, which is worse than not offering the tool, because the
  * agent has already committed to a plan by the time it finds out.
+ *
+ * == The fourth: the first tool that WRITES
+ *
+ *   - `add_repository` wraps `POST /api/v1/repositories` (shipped:
+ *     `specguard/config/routes.rb`, `Api::V1::UserRepositoriesController#create`).
+ *
+ * The endpoint had shipped for a while; what this bridge lacked was a way to
+ * CALL it — `support/specguard-api.ts` offered only `getJson`, which hardcoded
+ * `method: "GET"` and took no body. The reservation recorded here was that the
+ * write transport should land WITH the first write tool, designed against a real
+ * request body and a real 4xx surface rather than invented for a caller that did
+ * not exist. That is what happened: `postJson`/`postJsonObject` arrived with
+ * this entry, sharing `fetchWithTimeout` with the read path rather than standing
+ * beside it, and `describeFailure` grew the `400` branch that surfaces
+ * SpecGuard's own refusal sentence — the modal answer this endpoint gives.
+ *
+ * The standing rule is unchanged and still binding, which is what keeps the rest
+ * of the user-scoped write surface out: `DELETE /api/v1/repositories/:id` and
+ * the API-key endpoints (SPGD-754) are NOT on `origin/main`, so they may not be
+ * wrapped here however useful a tool for them would be. What moved was the
+ * platform, not the bar.
  */
-export const TOOLS = [lintIntentAnnotations, getRepositoryOverview];
+export const TOOLS = [
+    lintIntentAnnotations,
+    getRepositoryOverview,
+    listRepositories,
+    addRepository,
+];
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,MAAM,8BAA8B,CAAC;AACjE,OAAO,qBAAqB,MAAM,0BAA0B,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,KAAK,GAA8B,CAAC,qBAAqB,EAAE,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,qBAAqB,CAAC;AAChD,OAAO,qBAAqB,MAAM,8BAA8B,CAAC;AACjE,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AACtD,OAAO,qBAAqB,MAAM,0BAA0B,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,CAAC,MAAM,KAAK,GAA8B;IAC9C,qBAAqB;IACrB,qBAAqB;IACrB,gBAAgB;IAChB,aAAa;CACd,CAAC"}

package/dist/src/tools/list-repositories.d.ts

@@ -0,0 +1,75 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `GET /api/v1/repositories` as a tool — shipped today in the platform
+ * (`specguard/config/routes.rb`, `Api::V1::UserRepositoriesController#index`).
+ *
+ * == Why this is the first user-scoped tool, and for now the only one
+ *
+ * Every other tool here answers about ONE repository the caller has already
+ * named — and a bridge that can only answer about a repository you can already
+ * name cannot tell an agent which repositories there ARE. `get_repository_overview`
+ * does not take a repository: its `sgk_` key IS the repository, so the question
+ * "what may I ask about" has no answer anywhere in this server. This is that
+ * answer, and it is the whole of what this tool does.
+ *
+ * It is also the tool that proves the second credential slot works end to end,
+ * which is why it shipped alone. It no longer IS alone: `add_repository`
+ * (SPGD-764) reads the same `sgu_` key and wraps `POST /api/v1/repositories`,
+ * which arrived once this bridge had a write transport to call it with —
+ * `postJson`/`postJsonObject` in `support/specguard-api.ts`, landed with that
+ * tool and designed against a real request body and a real 4xx surface, exactly
+ * as the reservation recorded here asked. The registry's standing rule
+ * (`tools/index.ts`) is unchanged and still binding: a tool in `tools/list` is a
+ * promise an agent acts on, so the REST of the user-scoped surface — removing a
+ * repository, minting or revoking keys — stays out until those endpoints ship.
+ *
+ * What this tool still uniquely answers is the question above: which
+ * repositories there ARE. `add_repository` extends that surface rather than
+ * replacing it, and the two share a handle — the `full_name` reported here is
+ * the `full_name` that one takes.
+ *
+ * == It reads the OTHER key, and that is the point
+ *
+ * `Api::BaseController` decides which credential table to consult from the
+ * token's PREFIX, before any table is read, and answers 401 on a mismatch
+ * without a lookup — so this endpoint refuses the `sgk_` key
+ * `get_repository_overview` uses, and that one refuses this key. Hence
+ * `requireUserApiConfig` rather than `requireApiConfig`: the two are the same
+ * function over different variables, and the `Credential` each carries is what
+ * makes a 401 or an unset variable name the one the OPERATOR of this tool has
+ * to go and fix. See `config.ts`.
+ *
+ * == No arguments, because the credential is the whole question
+ *
+ * The endpoint takes no parameters: the person the `sgu_` key speaks for is the
+ * entire scope of the answer, and `Repository.accessible_by` — owned UNION
+ * shared-through-a-membership — is the platform's read-side boundary rather
+ * than a filter this bridge could widen or narrow. A repository the person
+ * neither owns nor is a member of never enters the response, so there is
+ * nothing here for a parameter to select and nothing an argument could reach.
+ *
+ * == The response is passed through, not re-modelled
+ *
+ * Same rule as every other tool here (`types.ts`: "A thin client that reshapes
+ * its upstream is not thin"), and it has real content on this body. The
+ * controller serves each entry as `id`, `full_name`, `name`, `registered_at`
+ * and `role`, and says why: the first four are DELIBERATELY the same four
+ * fields, under the same names, that `GET /api/v1/repository` serves in its own
+ * `repository` block, so a client that has read one knows how to read the other.
+ * Renaming or flattening anything here would spend that parity on the last hop.
+ *
+ * `role` is the field this surface adds — `"owner"` or `"member"` — because the
+ * list MIXES repositories the person owns with repositories somebody shared
+ * with them and no other field separates the two. An agent that will later
+ * register keys or change settings needs to know which of these it may expect
+ * to administer, so the value is named in the description rather than left to be
+ * discovered from the data.
+ *
+ * The order is `full_name` ascending, which the controller picks as the only
+ * column a client can page or diff against without SpecGuard promising an id
+ * ordering it has not designed. It is stated here for the same reason the other
+ * tool states its orders: a list whose order is a coincidence and a list whose
+ * order is a contract look identical in a response body.
+ */
+declare const listRepositories: ToolDefinition;
+export default listRepositories;

package/dist/src/tools/list-repositories.js

@@ -0,0 +1,112 @@
+import { getJsonObject, requireUserApiConfig } from "../support/specguard-api.js";
+/**
+ * `GET /api/v1/repositories` as a tool — shipped today in the platform
+ * (`specguard/config/routes.rb`, `Api::V1::UserRepositoriesController#index`).
+ *
+ * == Why this is the first user-scoped tool, and for now the only one
+ *
+ * Every other tool here answers about ONE repository the caller has already
+ * named — and a bridge that can only answer about a repository you can already
+ * name cannot tell an agent which repositories there ARE. `get_repository_overview`
+ * does not take a repository: its `sgk_` key IS the repository, so the question
+ * "what may I ask about" has no answer anywhere in this server. This is that
+ * answer, and it is the whole of what this tool does.
+ *
+ * It is also the tool that proves the second credential slot works end to end,
+ * which is why it shipped alone. It no longer IS alone: `add_repository`
+ * (SPGD-764) reads the same `sgu_` key and wraps `POST /api/v1/repositories`,
+ * which arrived once this bridge had a write transport to call it with —
+ * `postJson`/`postJsonObject` in `support/specguard-api.ts`, landed with that
+ * tool and designed against a real request body and a real 4xx surface, exactly
+ * as the reservation recorded here asked. The registry's standing rule
+ * (`tools/index.ts`) is unchanged and still binding: a tool in `tools/list` is a
+ * promise an agent acts on, so the REST of the user-scoped surface — removing a
+ * repository, minting or revoking keys — stays out until those endpoints ship.
+ *
+ * What this tool still uniquely answers is the question above: which
+ * repositories there ARE. `add_repository` extends that surface rather than
+ * replacing it, and the two share a handle — the `full_name` reported here is
+ * the `full_name` that one takes.
+ *
+ * == It reads the OTHER key, and that is the point
+ *
+ * `Api::BaseController` decides which credential table to consult from the
+ * token's PREFIX, before any table is read, and answers 401 on a mismatch
+ * without a lookup — so this endpoint refuses the `sgk_` key
+ * `get_repository_overview` uses, and that one refuses this key. Hence
+ * `requireUserApiConfig` rather than `requireApiConfig`: the two are the same
+ * function over different variables, and the `Credential` each carries is what
+ * makes a 401 or an unset variable name the one the OPERATOR of this tool has
+ * to go and fix. See `config.ts`.
+ *
+ * == No arguments, because the credential is the whole question
+ *
+ * The endpoint takes no parameters: the person the `sgu_` key speaks for is the
+ * entire scope of the answer, and `Repository.accessible_by` — owned UNION
+ * shared-through-a-membership — is the platform's read-side boundary rather
+ * than a filter this bridge could widen or narrow. A repository the person
+ * neither owns nor is a member of never enters the response, so there is
+ * nothing here for a parameter to select and nothing an argument could reach.
+ *
+ * == The response is passed through, not re-modelled
+ *
+ * Same rule as every other tool here (`types.ts`: "A thin client that reshapes
+ * its upstream is not thin"), and it has real content on this body. The
+ * controller serves each entry as `id`, `full_name`, `name`, `registered_at`
+ * and `role`, and says why: the first four are DELIBERATELY the same four
+ * fields, under the same names, that `GET /api/v1/repository` serves in its own
+ * `repository` block, so a client that has read one knows how to read the other.
+ * Renaming or flattening anything here would spend that parity on the last hop.
+ *
+ * `role` is the field this surface adds — `"owner"` or `"member"` — because the
+ * list MIXES repositories the person owns with repositories somebody shared
+ * with them and no other field separates the two. An agent that will later
+ * register keys or change settings needs to know which of these it may expect
+ * to administer, so the value is named in the description rather than left to be
+ * discovered from the data.
+ *
+ * The order is `full_name` ascending, which the controller picks as the only
+ * column a client can page or diff against without SpecGuard promising an id
+ * ordering it has not designed. It is stated here for the same reason the other
+ * tool states its orders: a list whose order is a coincidence and a list whose
+ * order is a contract look identical in a response body.
+ */
+const listRepositories = {
+    name: "list_repositories",
+    title: "List repositories",
+    description: "Lists the SpecGuard repositories the person behind this server's user API key may open — " +
+        "the answer to \"what can I ask about\", which no other tool here can give, because every " +
+        "other tool is already scoped to one repository by its key. " +
+        "Each entry carries `id`, `full_name` (`org/repo`, and the handle every other surface names " +
+        "a repository by), `name`, `registered_at` and `role`. " +
+        "`role` is `owner` or `member`: the list mixes repositories this person owns with " +
+        "repositories somebody shared with them, and nothing else distinguishes the two — read it " +
+        "before assuming a repository is yours to administer. " +
+        "Ordered by `full_name` ascending, which is stable across calls. " +
+        "The set is exactly what this person may see — a repository they neither own nor were given " +
+        "access to is absent rather than filtered, so an empty list means no access, never an error. " +
+        "Needs SPECGUARD_USER_API_KEY (an sgu_… key), which is a DIFFERENT credential from the " +
+        "sgk_… repository key get_repository_overview reads; SpecGuard refuses each in the other's " +
+        "place.",
+    inputSchema: {
+        type: "object",
+        // No properties, deliberately — see this file's header. Still CLOSED rather
+        // than merely empty: `additionalProperties: false` is advertised in
+        // `tools/list`, so a client that honours the schema REJECTS an invented
+        // argument before the call is made. Nothing on this side refuses it —
+        // `server.ts` forwards `arguments` unvalidated and `run` ignores them — so
+        // an open schema would have the argument silently dropped and the call
+        // answered as if it had been honoured.
+        additionalProperties: false,
+    },
+    async run(_args, context) {
+        const api = requireUserApiConfig(context.config);
+        const listing = await getJsonObject(api, "/api/v1/repositories", {}, context.fetch);
+        return {
+            text: JSON.stringify(listing, null, 2),
+            structured: listing,
+        };
+    },
+};
+export default listRepositories;
+//# sourceMappingURL=list-repositories.js.map

package/dist/src/tools/list-repositories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-repositories.js","sourceRoot":"","sources":["../../../src/tools/list-repositories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,gBAAgB,GAAmB;IACvC,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EACT,2FAA2F;QAC3F,2FAA2F;QAC3F,6DAA6D;QAC7D,6FAA6F;QAC7F,wDAAwD;QACxD,mFAAmF;QACnF,2FAA2F;QAC3F,uDAAuD;QACvD,kEAAkE;QAClE,6FAA6F;QAC7F,8FAA8F;QAC9F,wFAAwF;QACxF,4FAA4F;QAC5F,QAAQ;IACV,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,4EAA4E;QAC5E,oEAAoE;QACpE,wEAAwE;QACxE,sEAAsE;QACtE,2EAA2E;QAC3E,uEAAuE;QACvE,uCAAuC;QACvC,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO;QACtB,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,sBAAsB,EAAE,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAEpF,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACtC,UAAU,EAAE,OAAO;SACpB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,gBAAgB,CAAC"}