specguard-mcp 0.1.2 → 0.1.4

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

@@ -41,13 +41,67 @@ import type { ToolDefinition } from "./types.js";
  * 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 user-scoped WRITE endpoints are absent for a different reason, and it is
- * worth stating so nobody re-derives the wrong one: `POST /api/v1/repositories`
- * exists on the platform today. What this bridge does not have is a way to call
- * it — `support/specguard-api.ts` offers `getJson`, which hardcodes
- * `method: "GET"` and takes no body. That transport lands with the first write
- * tool, designed against a real request body and a real 4xx surface, rather
- * than being invented here for a tool that does not yet exist.
+ * == 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. 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,6 +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.
  *
@@ -43,17 +48,76 @@ import getRepositoryOverview from "./repository-overview.js";
  * 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 user-scoped WRITE endpoints are absent for a different reason, and it is
- * worth stating so nobody re-derives the wrong one: `POST /api/v1/repositories`
- * exists on the platform today. What this bridge does not have is a way to call
- * it — `support/specguard-api.ts` offers `getJson`, which hardcodes
- * `method: "GET"` and takes no body. That transport lands with the first write
- * tool, designed against a real request body and a real 4xx surface, rather
- * than being invented here for a tool that does not yet exist.
+ * == 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. 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,qBAAqB,MAAM,8BAA8B,CAAC;AACjE,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AACtD,OAAO,qBAAqB,MAAM,0BAA0B,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,CAAC,MAAM,KAAK,GAA8B;IAC9C,qBAAqB;IACrB,qBAAqB;IACrB,gBAAgB;CACjB,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/list-repositories.d.ts

@@ -13,13 +13,20 @@ import type { ToolDefinition } from "./types.js";
  * 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 ships alone. The registry's standing rule (`tools/index.ts`)
- * is that a tool in `tools/list` is a promise an agent acts on, so the other
- * user-scoped endpoints wait for the transport they need: `POST /api/v1/repositories`
- * EXISTS on the platform today, and `getJson` hardcodes `method: "GET"` and
- * takes no body, so registering a repository is blocked on a write transport
- * rather than on a missing endpoint. That transport belongs with the first write
- * tool, where it can be designed against a real body and a real 4xx surface.
+ * 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
  *

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

@@ -13,13 +13,20 @@ import { getJsonObject, requireUserApiConfig } from "../support/specguard-api.js
  * 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 ships alone. The registry's standing rule (`tools/index.ts`)
- * is that a tool in `tools/list` is a promise an agent acts on, so the other
- * user-scoped endpoints wait for the transport they need: `POST /api/v1/repositories`
- * EXISTS on the platform today, and `getJson` hardcodes `method: "GET"` and
- * takes no body, so registering a repository is blocked on a write transport
- * rather than on a missing endpoint. That transport belongs with the first write
- * tool, where it can be designed against a real body and a real 4xx surface.
+ * 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
  *

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

@@ -1 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;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"}
+{"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"}

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"}