specguard-mcp 0.1.3 → 0.1.4

package/README.md

@@ -32,9 +32,9 @@ refuses to boot and takes the tools that needed no configuration down with it.
 
 | Variable | Needed by | Default | What it is |
 | --- | --- | --- | --- |
-| `SPECGUARD_ENDPOINT` | `get_repository_overview`, `list_repositories` | — | your SpecGuard instance's root URL, **including the scheme** — e.g. `https://specguard.example.com`, or `http://localhost:3000`. A value with no scheme is refused by name (`SPECGUARD_ENDPOINT is not a usable URL: "sg.example.com"`) rather than surfacing later as an opaque failure. `SPECGUARD_URL` is accepted as an alias, and is the name every message uses when it is the one you set. A blank value counts as unset, so leaving `SPECGUARD_ENDPOINT` empty in a templated config falls through to `SPECGUARD_URL` instead of suppressing it |
+| `SPECGUARD_ENDPOINT` | `get_repository_overview`, `list_repositories`, `add_repository`, `registrable_repositories` | — | your SpecGuard instance's root URL, **including the scheme** — e.g. `https://specguard.example.com`, or `http://localhost:3000`. A value with no scheme is refused by name (`SPECGUARD_ENDPOINT is not a usable URL: "sg.example.com"`) rather than surfacing later as an opaque failure. `SPECGUARD_URL` is accepted as an alias, and is the name every message uses when it is the one you set. A blank value counts as unset, so leaving `SPECGUARD_ENDPOINT` empty in a templated config falls through to `SPECGUARD_URL` instead of suppressing it |
 | `SPECGUARD_API_KEY` | `get_repository_overview` | — | an agent/CI API key (`sgk_…`) issued by that deployment |
-| `SPECGUARD_USER_API_KEY` | `list_repositories` | — | a **user** API key (`sgu_…`), minted from that deployment's account page. A different credential from the one above, not a second place to put the same value: SpecGuard decides which of them a request may use from the token's prefix, before it reads anything, and answers `401` for the other one. Set whichever your tools need — both, if you use both |
+| `SPECGUARD_USER_API_KEY` | `list_repositories`, `add_repository`, `registrable_repositories`, `remove_repository`, `create_repository_api_key`, `revoke_repository_api_key` | — | a **user** API key (`sgu_…`), minted from that deployment's account page. A different credential from the one above, not a second place to put the same value: SpecGuard decides which of them a request may use from the token's prefix, before it reads anything, and answers `401` for the other one. Set whichever your tools need — both, if you use both |
 | `SPECGUARD_LINT_COMMAND` | `lint_intent_annotations` | `specguard-lint` | the command that runs the linter. Most Ruby projects need `bundle exec specguard-lint` |
 | `SPECGUARD_TIMEOUT_MS` | HTTP tools | `30000` | how long a call to SpecGuard may take |
 
@@ -351,10 +351,11 @@ decides which table is consulted before any of them is read — so the two are n
 setting one does not stand in for the other. Every message this tool produces names the variable
 *it* reads, so a `401` here never sends you to check the key `get_repository_overview` uses.
 
-Registering a repository is now `add_repository`, below — it reads the same `sgu_…` key and takes the
-`full_name` this tool reports. Revoking keys and the rest of the user-scoped surface are still absent,
-because their endpoints have not shipped: a tool here is a promise the agent will act on, so it waits
-for the capability rather than the other way round.
+Registering a repository is `add_repository`, below — it reads the same `sgu_…` key and takes the
+`full_name` this tool reports. Removal and the key lifecycle (`remove_repository`,
+`create_repository_api_key`, `revoke_repository_api_key`) are below too, on the same key; a tool
+here is a promise the agent will act on, so each waits for the capability rather than the other way
+round.
 
 ### `add_repository`
 
@@ -398,6 +399,105 @@ as this bridge rejecting a name the platform would have accepted.
 It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and a
 different one from the `sgk_…` key `get_repository_overview` uses.
 
+### `registrable_repositories`
+
+Lists the GitHub repositories the person behind `SPECGUARD_USER_API_KEY` **could** register with
+SpecGuard — the set the registration gate would consult, read out loud in advance, so an agent can
+pick a `full_name` for `add_repository` from a real answer rather than by guessing. `list_repositories`
+reports what *is* registered; this reports what could be, and the two answer different questions.
+
+The body comes back as SpecGuard serves it: `{"repositories": […]}` with each entry carrying
+`full_name` and `registered`, ordered by `full_name` ascending, plus a `grant` block (`captured_at`,
+`expires_at`, `stale`) describing the stored record of this person's GitHub permissions.
+
+**`registered` is asked globally, not just of your own repositories.** An entry marked
+`registered: true` was registered by *somebody* — possibly someone else — and a POST naming it will
+be refused with `has already been taken`. That is exactly why entries are *marked* rather than
+excluded: a reading scoped to what you can open would send you at a name nobody can register.
+
+**A name appearing here is not a promise the write will succeed.** This is the set the gate would
+consult at the moment of the read; the repository may be registered by someone else between this
+call and your POST.
+
+**A missing or stale grant is not an error — it is the modal first answer.** SpecGuard fails closed
+when it has no current record of your GitHub permissions, which is every person who has not opened
+SpecGuard in a browser recently. The call then answers `403` with SpecGuard's own sentence naming
+the fix: *sign in to SpecGuard in a browser and reconnect GitHub, then try again*. On that refusal
+the body still carries `grant`, and it distinguishes the two cases: `grant: null` means there never
+was one (first-time setup), a populated grant with `stale: true` means an existing connection lapsed
+— same remedy, very different urgency. Read it before telling the person what to do.
+
+**This tool takes no arguments** — the credential is the whole of the scope. The endpoint takes no
+parameters; which repositories are in the answer is decided by SpecGuard from the person the key
+speaks for.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `remove_repository`
+
+Removes a repository from SpecGuard — and with it **every key, run and intent on it**. This is the
+destructive gesture in this toolset: irreversible, no undo, and a `204` means the repository and its
+history are gone short of re-registering from scratch. Confirm with the user before calling.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository to remove — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+
+Authorization is the `repo.delete` capability at **either surface** — an owner, or a member granted
+`repo.delete`, may remove the repository. A member without it is refused `403` with SpecGuard's own
+sentence, verbatim. The repository's CI keys stop authenticating the moment it succeeds.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `create_repository_api_key`
+
+Mints a new CI API key (`sgk_…`) for a SpecGuard repository and returns it alongside the
+repository's existing keys. Minting does not disturb existing keys — each key on a repository
+authenticates independently until revoked.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository to mint the key for — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `name` | an optional label for the key; omit it to let SpecGuard use its default name |
+
+The body comes back as SpecGuard serves it: an `api_key` block (`name`, `token`, `hint`,
+`created_at`) — the same shape `add_repository` serves.
+
+> ⚠️ **`api_key.token` is shown once and never again.** Nothing stores it and no endpoint can
+> re-serve it. Hand it to the person you are working for in your reply. If it is dropped, the
+> recovery is minting another key with this same tool — the platform has no regenerate — then
+> revoking the orphaned one with `revoke_repository_api_key`.
+
+Authorization is the `keys_manage` capability; a member without it is refused `403` with SpecGuard's
+own sentence, verbatim.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `revoke_repository_api_key`
+
+Revokes one CI API key on a SpecGuard repository. The key stops authenticating immediately; every
+**other** key on the repository keeps working, so CI keeps ingesting if it holds a surviving key.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository the key belongs to — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `key_id` | the id of the key to revoke, as served in the `api_key` block of `add_repository` or `create_repository_api_key` |
+
+The `key_id` is scoped to `repository_id`: a key id belonging to a different repository is refused
+`404`, never a cross-repository delete. Authorization is the `keys_manage` capability; a member
+without it is refused `403` with SpecGuard's own sentence, verbatim.
+
+**Key rotation is mint-then-revoke, in that order.** The platform has no regenerate, so mint a
+replacement with `create_repository_api_key` and deploy it BEFORE revoking the old one — revoke
+first and the repository's CI is locked out until a human mints a new key in a browser. A `204`
+means the key is revoked.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
 ## How it works
 
 ```

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

@@ -25,6 +25,23 @@ export declare function getJson(api: ApiConfig, path: string, query: Record<stri
  * 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>;
+/**
+ * `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 declare function deleteJson(api: ApiConfig, path: string, fetchImpl: typeof globalThis.fetch): Promise<string>;
 /**
  * `postJson`, narrowed exactly as `getJsonObject` narrows `getJson`.
  *

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

@@ -38,6 +38,28 @@ export async function postJson(api, path, body, fetchImpl) {
         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`.
  *
@@ -245,8 +267,8 @@ 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) {
-        const message = badRequestMessage(body);
+    if (status === 400 || status === 403) {
+        const message = refusalMessage(body, status);
         if (message !== undefined)
             return new ApiError(message, status);
     }
@@ -262,6 +284,13 @@ function describeFailure(status, body, api) {
  * `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 —
  *
@@ -283,7 +312,7 @@ function describeFailure(status, body, api) {
  * 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) {
+function refusalMessage(body, status) {
     let parsed;
     try {
         parsed = JSON.parse(body);
@@ -296,7 +325,7 @@ function badRequestMessage(body) {
     const message = parsed["message"];
     if (typeof message !== "string" || message.trim() === "")
         return undefined;
-    return `SpecGuard refused the request (400): ${message.trim()}`;
+    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/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;

package/dist/src/tools/create-repository-api-key.js

@@ -0,0 +1,83 @@
+import { postJsonObject, requireUserApiConfig } from "../support/specguard-api.js";
+import { optionalString, requireString } from "./args.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.
+ */
+const createRepositoryApiKey = {
+    name: "create_repository_api_key",
+    title: "Create repository API key",
+    description: "Mints a new CI API key (an sgk_… key) for a SpecGuard repository, and returns it " +
+        "alongside the repository's existing keys. " +
+        "⚠️ `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. If it is dropped, the recovery is minting another key with " +
+        "this same tool (the platform has no regenerate), then revoking the orphaned one. " +
+        "On success the response carries an `api_key` block (`name`, `token`, `hint`, " +
+        "`created_at`) — the same reveal-once shape `add_repository` serves. " +
+        "Minting does not disturb existing keys: each key on a repository authenticates " +
+        "independently until revoked. " +
+        "Takes `repository_id` (the numeric id `list_repositories` reports) and an optional " +
+        "`name`, which the server defaults when omitted. " +
+        "Authorization is the `keys_manage` capability — a member without it is refused 403 " +
+        "in SpecGuard's own words. " +
+        "Needs SPECGUARD_USER_API_KEY (an sgu_… key), the same credential `add_repository` " +
+        "writes with and a DIFFERENT one from the sgk_… repository key " +
+        "`get_repository_overview` uses.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repository_id: {
+                type: "string",
+                description: "The repository to mint the key for — its numeric id, as `add_repository` " +
+                    "returns and `list_repositories` reports, not the `org/repo` handle.",
+            },
+            name: {
+                type: "string",
+                description: "An optional label for the key. Omit it to let SpecGuard use its default name. " +
+                    "The server validates the name and refuses an unusable one in its own words.",
+            },
+        },
+        required: ["repository_id"],
+        // Closed for the reason every tool here states — and on a WRITE, a silently
+        // dropped misspelled argument still mints something, just possibly mislabeled.
+        additionalProperties: false,
+    },
+    async run(args, context) {
+        const repositoryId = requireString(args["repository_id"], "repository_id");
+        const name = optionalString(args["name"], "name");
+        const api = requireUserApiConfig(context.config);
+        // `name` omitted when absent rather than sent as null, so the server's own
+        // `ApiKey::DEFAULT_NAME` default applies — this bridge expresses "no
+        // preference", it does not choose on the server's behalf.
+        const created = await postJsonObject(api, `/api/v1/repositories/${encodeURIComponent(repositoryId)}/api_keys`, name === undefined ? {} : { name }, context.fetch);
+        // Unreshaped, for the reason `add_repository` states at its own return:
+        // `api_key.token` exists nowhere else, so any reshaping on this hop is a
+        // value that cannot be recovered.
+        return {
+            text: JSON.stringify(created, null, 2),
+            structured: created,
+        };
+    },
+};
+export default createRepositoryApiKey;
+//# sourceMappingURL=create-repository-api-key.js.map

package/dist/src/tools/create-repository-api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-repository-api-key.js","sourceRoot":"","sources":["../../../src/tools/create-repository-api-key.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,sBAAsB,GAAmB;IAC7C,IAAI,EAAE,2BAA2B;IACjC,KAAK,EAAE,2BAA2B;IAClC,WAAW,EACT,mFAAmF;QACnF,4CAA4C;QAC5C,mFAAmF;QACnF,sFAAsF;QACtF,sFAAsF;QACtF,mFAAmF;QACnF,+EAA+E;QAC/E,sEAAsE;QACtE,iFAAiF;QACjF,+BAA+B;QAC/B,qFAAqF;QACrF,kDAAkD;QAClD,qFAAqF;QACrF,4BAA4B;QAC5B,oFAAoF;QACpF,gEAAgE;QAChE,iCAAiC;IACnC,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,aAAa,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,2EAA2E;oBAC3E,qEAAqE;aACxE;YACD,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,gFAAgF;oBAChF,6EAA6E;aAChF;SACF;QACD,QAAQ,EAAE,CAAC,eAAe,CAAC;QAC3B,4EAA4E;QAC5E,+EAA+E;QAC/E,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO;QACrB,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC,CAAC;QAC3E,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;QAElD,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,2EAA2E;QAC3E,qEAAqE;QACrE,0DAA0D;QAC1D,MAAM,OAAO,GAAG,MAAM,cAAc,CAClC,GAAG,EACH,wBAAwB,kBAAkB,CAAC,YAAY,CAAC,WAAW,EACnE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAClC,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,wEAAwE;QACxE,yEAAyE;QACzE,kCAAkC;QAClC,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,sBAAsB,CAAC"}

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

@@ -56,11 +56,52 @@ import type { ToolDefinition } from "./types.js";
  * 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.
+ * The standing rule is unchanged and still binding. What once kept `DELETE
+ * /api/v1/repositories/:id` and the API-key endpoints out under it — "not on
+ * `origin/main`, so they may not be wrapped" — stopped being true when SPGD-754
+ * shipped them, and the sixth-through-eighth section below records their
+ * wrapping. What moved was the platform, not the bar.
+ *
+ * == The fifth: the read half of the registration gate
+ *
+ *   - `registrable_repositories` wraps `GET /api/v1/repositories/registrable`
+ *     (shipped: `specguard/config/routes.rb:117`,
+ *     `Api::V1::UserRepositoriesController#registrable`).
+ *
+ * `list_repositories` says what IS registered; this says what COULD be — the
+ * set the gate would consult, read out in advance, so an agent can pick a
+ * `full_name` for `add_repository` from a real answer. Landing it also
+ * generalised the 400 branch in `describeFailure` into a status-parameterised
+ * extractor, because this endpoint's modal first answer is a 403 (`not_granted`)
+ * carrying the same `{error, message}` contract — the identical defect, given
+ * the identical remedy.
+ *
+ * The user-scoped surface as it now stands is therefore three tools: read the
+ * list, read the gate's answer, write a registration. The standing rule is
+ * unchanged and still binding, which is what keeps the rest 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.
+ *
+ * == The sixth through eighth: removal and the key lifecycle
+ *
+ *   - `remove_repository` wraps `DELETE /api/v1/repositories/:id`, and
+ *     `create_repository_api_key` / `revoke_repository_api_key` wrap the two
+ *     `api_keys` endpoints (all shipped: SPGD-754, `specguard@origin/main`).
+ *
+ * The closing fence the two paragraphs above share — "the DELETE and API-key
+ * endpoints are NOT on `origin/main`, so they may not be wrapped" — stopped
+ * being true when SPGD-754 landed, and these three entries are what became
+ * wrappable the moment it did. They also forced the transport's third verb:
+ * both DELETE endpoints answer `204` with NO body, the one response in the
+ * `sgu_` surface that is deliberately not JSON, which is why `deleteJson`
+ * returns the raw body text instead of routing an empty 204 through
+ * `requestJson`'s JSON parse.
+ *
+ * The standing rule itself is unchanged and still binding — which still keeps
+ * out `/check-intent`, duplicate clustering, member management and rename: none
+ * of their backing endpoints has shipped, and a tool advertised in `tools/list`
+ * remains a promise an agent will act on.
  */
 export declare const TOOLS: readonly ToolDefinition[];
 export type { ToolContext, ToolDefinition, ToolResult } from "./types.js";

package/dist/src/tools/index.js

@@ -1,7 +1,11 @@
 import addRepository from "./add-repository.js";
+import createRepositoryApiKey from "./create-repository-api-key.js";
 import lintIntentAnnotations from "./lint-intent-annotations.js";
 import listRepositories from "./list-repositories.js";
 import getRepositoryOverview from "./repository-overview.js";
+import registrableRepositories from "./registrable-repositories.js";
+import removeRepository from "./remove-repository.js";
+import revokeRepositoryApiKey from "./revoke-repository-api-key.js";
 /**
  * THE REGISTRY — the one file that changes when the toolset grows.
  *
@@ -59,16 +63,61 @@ import getRepositoryOverview from "./repository-overview.js";
  * 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.
+ * The standing rule is unchanged and still binding. What once kept `DELETE
+ * /api/v1/repositories/:id` and the API-key endpoints out under it — "not on
+ * `origin/main`, so they may not be wrapped" — stopped being true when SPGD-754
+ * shipped them, and the sixth-through-eighth section below records their
+ * wrapping. What moved was the platform, not the bar.
+ *
+ * == The fifth: the read half of the registration gate
+ *
+ *   - `registrable_repositories` wraps `GET /api/v1/repositories/registrable`
+ *     (shipped: `specguard/config/routes.rb:117`,
+ *     `Api::V1::UserRepositoriesController#registrable`).
+ *
+ * `list_repositories` says what IS registered; this says what COULD be — the
+ * set the gate would consult, read out in advance, so an agent can pick a
+ * `full_name` for `add_repository` from a real answer. Landing it also
+ * generalised the 400 branch in `describeFailure` into a status-parameterised
+ * extractor, because this endpoint's modal first answer is a 403 (`not_granted`)
+ * carrying the same `{error, message}` contract — the identical defect, given
+ * the identical remedy.
+ *
+ * The user-scoped surface as it now stands is therefore three tools: read the
+ * list, read the gate's answer, write a registration. The standing rule is
+ * unchanged and still binding, which is what keeps the rest 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.
+ *
+ * == The sixth through eighth: removal and the key lifecycle
+ *
+ *   - `remove_repository` wraps `DELETE /api/v1/repositories/:id`, and
+ *     `create_repository_api_key` / `revoke_repository_api_key` wrap the two
+ *     `api_keys` endpoints (all shipped: SPGD-754, `specguard@origin/main`).
+ *
+ * The closing fence the two paragraphs above share — "the DELETE and API-key
+ * endpoints are NOT on `origin/main`, so they may not be wrapped" — stopped
+ * being true when SPGD-754 landed, and these three entries are what became
+ * wrappable the moment it did. They also forced the transport's third verb:
+ * both DELETE endpoints answer `204` with NO body, the one response in the
+ * `sgu_` surface that is deliberately not JSON, which is why `deleteJson`
+ * returns the raw body text instead of routing an empty 204 through
+ * `requestJson`'s JSON parse.
+ *
+ * The standing rule itself is unchanged and still binding — which still keeps
+ * out `/check-intent`, duplicate clustering, member management and rename: none
+ * of their backing endpoints has shipped, and a tool advertised in `tools/list`
+ * remains a promise an agent will act on.
  */
 export const TOOLS = [
     lintIntentAnnotations,
     getRepositoryOverview,
     listRepositories,
     addRepository,
+    registrableRepositories,
+    removeRepository,
+    createRepositoryApiKey,
+    revokeRepositoryApiKey,
 ];
 //# 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,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,qBAAqB,CAAC;AAChD,OAAO,sBAAsB,MAAM,gCAAgC,CAAC;AACpE,OAAO,qBAAqB,MAAM,8BAA8B,CAAC;AACjE,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AACtD,OAAO,qBAAqB,MAAM,0BAA0B,CAAC;AAC7D,OAAO,uBAAuB,MAAM,+BAA+B,CAAC;AACpE,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AACtD,OAAO,sBAAsB,MAAM,gCAAgC,CAAC;AAGpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuGG;AACH,MAAM,CAAC,MAAM,KAAK,GAA8B;IAC9C,qBAAqB;IACrB,qBAAqB;IACrB,gBAAgB;IAChB,aAAa;IACb,uBAAuB;IACvB,gBAAgB;IAChB,sBAAsB;IACtB,sBAAsB;CACvB,CAAC"}

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

@@ -0,0 +1,51 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `GET /api/v1/repositories/registrable` as a tool — shipped today in the
+ * platform (`specguard/config/routes.rb:117`, served by
+ * `Api::V1::UserRepositoriesController#registrable`).
+ *
+ * == What it answers, and why `list_repositories` does not
+ *
+ * `list_repositories` reports what is already registered; this reports what
+ * COULD be — the repositories the registration gate would consult, read out
+ * loud in advance. It exists so an agent can pick a `full_name` for
+ * `add_repository` from a real answer rather than by guessing, and so a
+ * `has already been taken` refusal can be explained rather than merely
+ * retried.
+ *
+ * == Two controller decisions the description carries, because both are
+ *    counter-intuitive and both are stated in the controller's own comments
+ *
+ * `registered` is asked of `Repository` GLOBALLY, not of what this person can
+ * open. The controller says why: a repository somebody ELSE registered still
+ * refuses this person's POST with `has already been taken`, so a reading
+ * scoped to what they can see would mark it `registered: false` and send them
+ * at a name that cannot be registered by anyone. An entry is therefore
+ * MARKED, not excluded — `registered: true` is the answer to "why did my POST
+ * say has already been taken".
+ *
+ * And a name appearing here is NOT a promise the write will succeed. This is
+ * the set the gate would consult at the moment of the read; the repository may
+ * be registered by someone else between the two calls.
+ *
+ * == The modal first answer is a 403, and that is why `describeFailure` grew
+ *
+ * `#registrable` fails closed on the two states `GrantVerifier` refuses on and
+ * renders `status: :forbidden` — NOT the 400 path the other refusals use. A
+ * nil grant is, in the controller's own words, "an ordinary state and not an
+ * error: it is every person who has not opened SpecGuard in a browser since
+ * this shipped" — so the 403 is the modal first answer this tool gives, and
+ * the sentence it carries (sign in, reconnect GitHub, retry) reaches the agent
+ * through the 403 branch in `specguard-api.ts`, which this tool is the reason
+ * for. On refusal the body still carries `grant`: `null` when there never was
+ * one, populated with `stale: true` when it lapsed — "yours lapsed four days
+ * ago" is a different fact from "you never had one", and the tool description
+ * is where an agent learns to branch on it.
+ *
+ * == No arguments, for the same reason `list_repositories` has none
+ *
+ * The credential is the whole of the scope. The endpoint takes no parameters,
+ * and nothing an argument could select reaches this answer.
+ */
+declare const registrableRepositories: ToolDefinition;
+export default registrableRepositories;

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

@@ -0,0 +1,92 @@
+import { getJsonObject, requireUserApiConfig } from "../support/specguard-api.js";
+/**
+ * `GET /api/v1/repositories/registrable` as a tool — shipped today in the
+ * platform (`specguard/config/routes.rb:117`, served by
+ * `Api::V1::UserRepositoriesController#registrable`).
+ *
+ * == What it answers, and why `list_repositories` does not
+ *
+ * `list_repositories` reports what is already registered; this reports what
+ * COULD be — the repositories the registration gate would consult, read out
+ * loud in advance. It exists so an agent can pick a `full_name` for
+ * `add_repository` from a real answer rather than by guessing, and so a
+ * `has already been taken` refusal can be explained rather than merely
+ * retried.
+ *
+ * == Two controller decisions the description carries, because both are
+ *    counter-intuitive and both are stated in the controller's own comments
+ *
+ * `registered` is asked of `Repository` GLOBALLY, not of what this person can
+ * open. The controller says why: a repository somebody ELSE registered still
+ * refuses this person's POST with `has already been taken`, so a reading
+ * scoped to what they can see would mark it `registered: false` and send them
+ * at a name that cannot be registered by anyone. An entry is therefore
+ * MARKED, not excluded — `registered: true` is the answer to "why did my POST
+ * say has already been taken".
+ *
+ * And a name appearing here is NOT a promise the write will succeed. This is
+ * the set the gate would consult at the moment of the read; the repository may
+ * be registered by someone else between the two calls.
+ *
+ * == The modal first answer is a 403, and that is why `describeFailure` grew
+ *
+ * `#registrable` fails closed on the two states `GrantVerifier` refuses on and
+ * renders `status: :forbidden` — NOT the 400 path the other refusals use. A
+ * nil grant is, in the controller's own words, "an ordinary state and not an
+ * error: it is every person who has not opened SpecGuard in a browser since
+ * this shipped" — so the 403 is the modal first answer this tool gives, and
+ * the sentence it carries (sign in, reconnect GitHub, retry) reaches the agent
+ * through the 403 branch in `specguard-api.ts`, which this tool is the reason
+ * for. On refusal the body still carries `grant`: `null` when there never was
+ * one, populated with `stale: true` when it lapsed — "yours lapsed four days
+ * ago" is a different fact from "you never had one", and the tool description
+ * is where an agent learns to branch on it.
+ *
+ * == No arguments, for the same reason `list_repositories` has none
+ *
+ * The credential is the whole of the scope. The endpoint takes no parameters,
+ * and nothing an argument could select reaches this answer.
+ */
+const registrableRepositories = {
+    name: "registrable_repositories",
+    title: "Registrable repositories",
+    description: "Lists the GitHub repositories the person behind this server's user API key could register " +
+        "with SpecGuard — the set the registration gate would consult, read out in advance, so an " +
+        "agent can pick a `full_name` for `add_repository` from a real answer rather than by " +
+        "guessing. Each entry carries `full_name` and `registered`. `registered` is asked GLOBALLY, " +
+        "not just of this person's own repositories: an entry marked `registered: true` was " +
+        "registered by SOMEBODY — possibly someone else — and a POST naming it will be refused with " +
+        "`has already been taken`, which is exactly the question this flag answers. Entries are " +
+        "marked, not excluded, for that reason. The response also carries a `grant` block " +
+        "(`captured_at`, `expires_at`, `stale`) describing the stored record of this person's GitHub " +
+        "permissions. A MISSING or STALE grant is not an error — it is every person who has not " +
+        "opened SpecGuard in a browser recently — and the call then answers 403 with SpecGuard's own " +
+        "sentence naming the fix: sign in to SpecGuard in a browser and reconnect GitHub, then try " +
+        "again. On that refusal the body's `grant` distinguishes the two cases: `grant: null` means " +
+        "there never was one (first-time setup), a populated grant with `stale: true` means an " +
+        "existing connection lapsed (same remedy, likely faster to complete) — branch on it before " +
+        "telling the person what to do. A name appearing in the list is not a promise the write " +
+        "will succeed: someone may register it between this read and the POST. Ordered by " +
+        "`full_name` ascending, which is stable across calls. Needs SPECGUARD_USER_API_KEY (an " +
+        "sgu_… key), the same credential `list_repositories` and `add_repository` read and a " +
+        "DIFFERENT one from the sgk_… repository key `get_repository_overview` uses.",
+    inputSchema: {
+        type: "object",
+        // No properties, deliberately — see this file's header. Still CLOSED rather
+        // than merely empty, for the reason `list-repositories.ts` gives inline:
+        // `server.ts` forwards `arguments` unvalidated and `run` ignores them, so
+        // an open schema would have an invented 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/registrable", {}, context.fetch);
+        return {
+            text: JSON.stringify(listing, null, 2),
+            structured: listing,
+        };
+    },
+};
+export default registrableRepositories;
+//# sourceMappingURL=registrable-repositories.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registrable-repositories.js","sourceRoot":"","sources":["../../../src/tools/registrable-repositories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,uBAAuB,GAAmB;IAC9C,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,0BAA0B;IACjC,WAAW,EACT,4FAA4F;QAC5F,2FAA2F;QAC3F,sFAAsF;QACtF,6FAA6F;QAC7F,qFAAqF;QACrF,6FAA6F;QAC7F,yFAAyF;QACzF,mFAAmF;QACnF,8FAA8F;QAC9F,yFAAyF;QACzF,8FAA8F;QAC9F,4FAA4F;QAC5F,6FAA6F;QAC7F,wFAAwF;QACxF,4FAA4F;QAC5F,yFAAyF;QACzF,mFAAmF;QACnF,wFAAwF;QACxF,sFAAsF;QACtF,6EAA6E;IAC/E,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,4EAA4E;QAC5E,yEAAyE;QACzE,0EAA0E;QAC1E,0EAA0E;QAC1E,4CAA4C;QAC5C,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,CACjC,GAAG,EACH,kCAAkC,EAClC,EAAE,EACF,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,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,uBAAuB,CAAC"}

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

@@ -0,0 +1,33 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `DELETE /api/v1/repositories/:id` as a tool — shipped in the platform
+ * (`specguard/config/routes.rb:152`, `Api::V1::UserRepositoriesController#destroy`,
+ * SPGD-754).
+ *
+ * == The destructive gesture in the whole surface
+ *
+ * Everything else here reads, registers, or mints. This one removes a
+ * repository AND every key, run and intent on it (`memberships_helper.rb`:
+ * "Delete the repository, and every key, run and intent on it"), and there is no
+ * undo. The description therefore carries the hazard BEFORE the call: it is
+ * prompt material, read when the agent is deciding whether to act, not a
+ * footnote discovered after.
+ *
+ * == Authorization is `repo.delete` at either surface
+ *
+ * The controller authorizes through `RepositoryAuthorization`'s `:repo_delete`
+ * fork — deliberately NOT `:owner` — so a member granted `repo.delete` may
+ * remove the repository from either surface. The tool does not probe for the
+ * capability client-side: the server is the gate, and a member without it
+ * receives a 403 whose sentence arrives verbatim through the landed
+ * `refusalMessage` branch in `describeFailure`.
+ *
+ * == 204 with no body
+ *
+ * This is the one response in the `sgu_` surface that is deliberately not a
+ * JSON body — which is why `deleteJson` exists: routing an empty-body 204
+ * through `requestJson`'s JSON parse would turn a successful delete into
+ * "the body was not JSON". Here, no body IS the success.
+ */
+declare const removeRepository: ToolDefinition;
+export default removeRepository;

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

@@ -0,0 +1,81 @@
+import { deleteJson, requireUserApiConfig } from "../support/specguard-api.js";
+import { requireString } from "./args.js";
+/**
+ * `DELETE /api/v1/repositories/:id` as a tool — shipped in the platform
+ * (`specguard/config/routes.rb:152`, `Api::V1::UserRepositoriesController#destroy`,
+ * SPGD-754).
+ *
+ * == The destructive gesture in the whole surface
+ *
+ * Everything else here reads, registers, or mints. This one removes a
+ * repository AND every key, run and intent on it (`memberships_helper.rb`:
+ * "Delete the repository, and every key, run and intent on it"), and there is no
+ * undo. The description therefore carries the hazard BEFORE the call: it is
+ * prompt material, read when the agent is deciding whether to act, not a
+ * footnote discovered after.
+ *
+ * == Authorization is `repo.delete` at either surface
+ *
+ * The controller authorizes through `RepositoryAuthorization`'s `:repo_delete`
+ * fork — deliberately NOT `:owner` — so a member granted `repo.delete` may
+ * remove the repository from either surface. The tool does not probe for the
+ * capability client-side: the server is the gate, and a member without it
+ * receives a 403 whose sentence arrives verbatim through the landed
+ * `refusalMessage` branch in `describeFailure`.
+ *
+ * == 204 with no body
+ *
+ * This is the one response in the `sgu_` surface that is deliberately not a
+ * JSON body — which is why `deleteJson` exists: routing an empty-body 204
+ * through `requestJson`'s JSON parse would turn a successful delete into
+ * "the body was not JSON". Here, no body IS the success.
+ */
+const removeRepository = {
+    name: "remove_repository",
+    title: "Remove repository",
+    description: "Removes a repository from SpecGuard, DELETING every key, run and intent on it. " +
+        "This is IRREVERSIBLE: the repository's CI keys stop authenticating and its recorded " +
+        "runs and intents are gone, with no undo and no way to recover them short of " +
+        "re-registering from scratch. A 204 means it is deleted. " +
+        "Authorization is the `repo.delete` capability at either surface — an owner, or a " +
+        "member granted it, may remove the repository; a member without it is refused 403 in " +
+        "SpecGuard's own words. Confirm with the user before calling: this is the destructive " +
+        "gesture in this toolset, and once it returns 204 the repository and its history " +
+        "cannot be brought back. " +
+        "Takes `repository_id` — the numeric id `add_repository` and `list_repositories` " +
+        "report, not the `org/repo` handle. " +
+        "Needs SPECGUARD_USER_API_KEY (an sgu_… key), the same credential `add_repository` " +
+        "writes with and a DIFFERENT one from the sgk_… repository key " +
+        "`get_repository_overview` uses.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repository_id: {
+                type: "string",
+                description: "The id of the repository to remove — the numeric id `add_repository` returns " +
+                    "and `list_repositories` reports, not the `org/repo` handle. SpecGuard scopes " +
+                    "the lookup to repositories you may act on and answers 404 otherwise.",
+            },
+        },
+        required: ["repository_id"],
+        // Closed for the reason every tool here states: `server.ts` forwards
+        // `arguments` unvalidated, and on the DESTRUCTIVE path a silently-dropped
+        // argument is the worst case of the write-path argument — the call still
+        // deletes something, just not what the agent believed it named.
+        additionalProperties: false,
+    },
+    async run(args, context) {
+        const repositoryId = requireString(args["repository_id"], "repository_id");
+        const api = requireUserApiConfig(context.config);
+        const body = await deleteJson(api, `/api/v1/repositories/${encodeURIComponent(repositoryId)}`, context.fetch);
+        // 204 with no body. Nothing upstream to pass through, so the result says
+        // what the verb did — in the tool's own words, because the deployment's
+        // whole answer was "no content".
+        return {
+            text: body === "" ? "Repository removed (204). Every key, run and intent on it is deleted." : body,
+            structured: { repository_id: repositoryId, deleted: true },
+        };
+    },
+};
+export default removeRepository;
+//# sourceMappingURL=remove-repository.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remove-repository.js","sourceRoot":"","sources":["../../../src/tools/remove-repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,gBAAgB,GAAmB;IACvC,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EACT,iFAAiF;QACjF,sFAAsF;QACtF,8EAA8E;QAC9E,0DAA0D;QAC1D,mFAAmF;QACnF,sFAAsF;QACtF,uFAAuF;QACvF,kFAAkF;QAClF,0BAA0B;QAC1B,kFAAkF;QAClF,qCAAqC;QACrC,oFAAoF;QACpF,gEAAgE;QAChE,iCAAiC;IACnC,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,aAAa,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,+EAA+E;oBAC/E,+EAA+E;oBAC/E,sEAAsE;aACzE;SACF;QACD,QAAQ,EAAE,CAAC,eAAe,CAAC;QAC3B,qEAAqE;QACrE,0EAA0E;QAC1E,yEAAyE;QACzE,gEAAgE;QAChE,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO;QACrB,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC,CAAC;QAE3E,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,IAAI,GAAG,MAAM,UAAU,CAC3B,GAAG,EACH,wBAAwB,kBAAkB,CAAC,YAAY,CAAC,EAAE,EAC1D,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,yEAAyE;QACzE,wEAAwE;QACxE,iCAAiC;QACjC,OAAO;YACL,IAAI,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,uEAAuE,CAAC,CAAC,CAAC,IAAI;YAClG,UAAU,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE;SAC3D,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,gBAAgB,CAAC"}

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

@@ -0,0 +1,29 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `DELETE /api/v1/repositories/:repository_id/api_keys/:id` as a tool —
+ * shipped in the platform (`specguard/config/routes.rb:159`,
+ * `user_repository_api_keys_controller#destroy`, SPGD-754).
+ *
+ * == Replacement-mint-then-revoke is the rotation model
+ *
+ * The platform ships no `#regenerate`. Rotating a compromised key is therefore
+ * two calls with tools this slice lands together: mint a replacement
+ * (`create_repository_api_key`), deploy it, then revoke the old one here. That
+ * ordering is stated in the description because it is the one thing an agent
+ * must know before it revokes — revoke-first locks the repository's CI out
+ * until a human intervenes.
+ *
+ * == The id is scoped to the repository
+ *
+ * `repository.api_keys.find(params[:id])` — a key id belonging to a DIFFERENT
+ * repository is a 404, not a cross-repository delete. The bridge relies on that
+ * scoping entirely and adds no client-side check of its own, for the reason
+ * every tool here states: the server is the gate.
+ *
+ * == 204 with no body
+ *
+ * The same empty-body success `remove_repository` serves; the same reason
+ * `deleteJson` exists rather than routing a 204 through `requestJson`.
+ */
+declare const revokeRepositoryApiKey: ToolDefinition;
+export default revokeRepositoryApiKey;

package/dist/src/tools/revoke-repository-api-key.js

@@ -0,0 +1,85 @@
+import { deleteJson, requireUserApiConfig } from "../support/specguard-api.js";
+import { requireString } from "./args.js";
+/**
+ * `DELETE /api/v1/repositories/:repository_id/api_keys/:id` as a tool —
+ * shipped in the platform (`specguard/config/routes.rb:159`,
+ * `user_repository_api_keys_controller#destroy`, SPGD-754).
+ *
+ * == Replacement-mint-then-revoke is the rotation model
+ *
+ * The platform ships no `#regenerate`. Rotating a compromised key is therefore
+ * two calls with tools this slice lands together: mint a replacement
+ * (`create_repository_api_key`), deploy it, then revoke the old one here. That
+ * ordering is stated in the description because it is the one thing an agent
+ * must know before it revokes — revoke-first locks the repository's CI out
+ * until a human intervenes.
+ *
+ * == The id is scoped to the repository
+ *
+ * `repository.api_keys.find(params[:id])` — a key id belonging to a DIFFERENT
+ * repository is a 404, not a cross-repository delete. The bridge relies on that
+ * scoping entirely and adds no client-side check of its own, for the reason
+ * every tool here states: the server is the gate.
+ *
+ * == 204 with no body
+ *
+ * The same empty-body success `remove_repository` serves; the same reason
+ * `deleteJson` exists rather than routing a 204 through `requestJson`.
+ */
+const revokeRepositoryApiKey = {
+    name: "revoke_repository_api_key",
+    title: "Revoke repository API key",
+    description: "Revokes one CI API key on a SpecGuard repository. The key stops authenticating " +
+        "immediately; every OTHER key on the repository keeps working, so CI keeps " +
+        "ingesting if it holds a surviving key. " +
+        "The `key_id` is scoped to `repository_id`: a key id belonging to a different " +
+        "repository is refused 404, never a cross-repository delete. " +
+        "Key rotation is mint-then-revoke, in that order: the platform has no regenerate, " +
+        "so mint a replacement with `create_repository_api_key` and deploy it BEFORE " +
+        "revoking the old one — revoke first and the repository's CI is locked out until " +
+        "a human mints a new key in a browser. " +
+        "Authorization is the `keys_manage` capability — a member without it is refused " +
+        "403 in SpecGuard's own words. A 204 means the key is revoked. " +
+        "Takes `repository_id` (the numeric id `list_repositories` reports) and `key_id` " +
+        "(the id from `add_repository`'s or `create_repository_api_key`'s response). " +
+        "Needs SPECGUARD_USER_API_KEY (an sgu_… key), the same credential " +
+        "`add_repository` writes with and a DIFFERENT one from the sgk_… repository key " +
+        "`get_repository_overview` uses.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repository_id: {
+                type: "string",
+                description: "The repository the key belongs to — its numeric id, as `add_repository` " +
+                    "returns and `list_repositories` reports, not the `org/repo` handle.",
+            },
+            key_id: {
+                type: "string",
+                description: "The id of the key to revoke, as served in the `api_key` block of " +
+                    "`add_repository` or `create_repository_api_key` (or the repository's " +
+                    "API-keys page). Scoped to `repository_id`: a foreign key id is refused 404.",
+            },
+        },
+        required: ["repository_id", "key_id"],
+        // Closed for the reason every tool here states — and on a DESTRUCTIVE path,
+        // a silently dropped misspelled argument must not be able to leave the
+        // agent believing it revoked a key the call never named.
+        additionalProperties: false,
+    },
+    async run(args, context) {
+        const repositoryId = requireString(args["repository_id"], "repository_id");
+        const keyId = requireString(args["key_id"], "key_id");
+        const api = requireUserApiConfig(context.config);
+        const body = await deleteJson(api, `/api/v1/repositories/${encodeURIComponent(repositoryId)}/api_keys/${encodeURIComponent(keyId)}`, context.fetch);
+        // 204 with no body — the tool's own words, because the deployment's whole
+        // answer was "no content".
+        return {
+            text: body === ""
+                ? `Key ${keyId} revoked (204). Other keys on the repository keep authenticating.`
+                : body,
+            structured: { repository_id: repositoryId, key_id: keyId, revoked: true },
+        };
+    },
+};
+export default revokeRepositoryApiKey;
+//# sourceMappingURL=revoke-repository-api-key.js.map

package/dist/src/tools/revoke-repository-api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revoke-repository-api-key.js","sourceRoot":"","sources":["../../../src/tools/revoke-repository-api-key.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,sBAAsB,GAAmB;IAC7C,IAAI,EAAE,2BAA2B;IACjC,KAAK,EAAE,2BAA2B;IAClC,WAAW,EACT,iFAAiF;QACjF,4EAA4E;QAC5E,yCAAyC;QACzC,+EAA+E;QAC/E,8DAA8D;QAC9D,mFAAmF;QACnF,8EAA8E;QAC9E,kFAAkF;QAClF,wCAAwC;QACxC,iFAAiF;QACjF,gEAAgE;QAChE,kFAAkF;QAClF,8EAA8E;QAC9E,mEAAmE;QACnE,iFAAiF;QACjF,iCAAiC;IACnC,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,aAAa,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,0EAA0E;oBAC1E,qEAAqE;aACxE;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,mEAAmE;oBACnE,uEAAuE;oBACvE,6EAA6E;aAChF;SACF;QACD,QAAQ,EAAE,CAAC,eAAe,EAAE,QAAQ,CAAC;QACrC,4EAA4E;QAC5E,uEAAuE;QACvE,yDAAyD;QACzD,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO;QACrB,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC,CAAC;QAC3E,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;QAEtD,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,IAAI,GAAG,MAAM,UAAU,CAC3B,GAAG,EACH,wBAAwB,kBAAkB,CAAC,YAAY,CAAC,aAAa,kBAAkB,CAAC,KAAK,CAAC,EAAE,EAChG,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,0EAA0E;QAC1E,2BAA2B;QAC3B,OAAO;YACL,IAAI,EACF,IAAI,KAAK,EAAE;gBACT,CAAC,CAAC,OAAO,KAAK,mEAAmE;gBACjF,CAAC,CAAC,IAAI;YACV,UAAU,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;SAC1E,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,sBAAsB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specguard-mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "MCP server exposing SpecGuard suite intelligence to AI coding agents",
   "license": "ISC",
   "type": "module",