specguard-mcp 0.1.3 → 0.1.5

package/dist/src/tools/args.js

@@ -93,4 +93,56 @@ export function optionalBoolean(value, field) {
         throw new ArgumentError(`\`${field}\` must be a boolean.`);
     return value;
 }
+/**
+ * An optional array of non-blank strings, or nothing.
+ *
+ * The SHAPE-ONLY sibling of the linter's `optionalStringArray` (which stays in
+ * `lint-intent-annotations.ts` because its refusals — empty list, leading dash
+ * — are about the linter's own argument grammar and throw `CommandError`). This
+ * one answers only "is it an array of strings" and always throws
+ * `ArgumentError`, which is what a pass-through array of permission names
+ * needs: the platform is the authority on which strings are legal, and a
+ * client-side copy of that rule is a rule with no owner, free to drift from the
+ * one that actually decides.
+ */
+export function optionalStringArray(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new ArgumentError(`\`${field}\` must be an array of strings.`);
+    const entries = value.map((entry) => {
+        if (typeof entry !== "string")
+            throw new ArgumentError(`\`${field}\` must contain only strings.`);
+        // Trimmed like its scalar siblings: a value an agent produced by
+        // concatenating strings arrives with whitespace that is not part of what it
+        // meant to send.
+        return entry.trim();
+    });
+    return entries;
+}
+/**
+ * A mandatory array of non-blank strings, and nothing else will do.
+ *
+ * The mandatory counterpart of `optionalStringArray`, added with
+ * `update_repository_member_permissions` (SPGD-885): the server column behind
+ * that call is `text[]`, and a scalar on the wire is silently dropped
+ * server-side — so the array shape is checked HERE, before a write, rather
+ * than persisted as a member holding nothing. Blank entries are dropped rather
+ * than refused: the server's own normalisation does the same, so refusing here
+ * would be a second vocabulary the caller must satisfy before the one that
+ * decides even sees the request.
+ */
+export function requireStringArray(value, field) {
+    if (value === undefined || value === null) {
+        throw new ArgumentError(`\`${field}\` is required.`);
+    }
+    if (!Array.isArray(value))
+        throw new ArgumentError(`\`${field}\` must be an array of strings.`);
+    const entries = value.map((entry) => {
+        if (typeof entry !== "string")
+            throw new ArgumentError(`\`${field}\` must contain only strings.`);
+        return entry.trim();
+    });
+    return entries.filter((entry) => entry !== "");
+}
 //# sourceMappingURL=args.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../../../src/tools/args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,KAAa;IAC1D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,sBAAsB,CAAC,CAAC;IACzF,8EAA8E;IAC9E,gFAAgF;IAChF,2EAA2E;IAC3E,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc,EAAE,KAAa;IACzD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,iBAAiB,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,sBAAsB,CAAC,CAAC;IAEzF,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,EAAE;QAAE,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,uBAAuB,CAAC,CAAC;IAE/E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,KAAa;IAC3D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,aAAa,CAAC,KAAK,KAAK,uBAAuB,CAAC,CAAC;IAC3F,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../../src/tools/args.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

@@ -34,12 +34,21 @@ import type { ToolDefinition } from "./types.js";
  *
  * == What is deliberately absent
  *
- * `/check-intent` and duplicate clustering are NOT here and must not be added
- * until their backing engine and data exist (SPGD-114 / SPGD-115). A tool
- * advertised in `tools/list` is a promise an agent will act on: wrapping an
- * endpoint that does not exist would produce a server that discovers cleanly
- * and fails on use, which is worse than not offering the tool, because the
- * agent has already committed to a plan by the time it finds out.
+ * `/check-intent` is NOT here and must not be added until its backing endpoint
+ * exists — `specguard/config/routes.rb:113` carries it as a comment only, which
+ * is the evidence this forbid rests on. A tool advertised in `tools/list` is a
+ * promise an agent will act on: wrapping an endpoint that does not exist would
+ * produce a server that discovers cleanly and fails on use, which is worse than
+ * not offering the tool, because the agent has already committed to a plan by
+ * the time it finds out.
+ *
+ * Duplicate clustering was once under this same forbid, on the same standing
+ * rule — no tool may wrap what has not shipped. That half retired when the
+ * platform moved: SPGD-703 (`specguard` `c43dc19`, 2026-08-28) shipped
+ * `GET /api/v1/repository?near_duplicates=`, serving
+ * `RepositoryOverview#serialized_near_duplicates` behind an opt-in ask, and
+ * `near_duplicate_clusters` below wraps it. What moved was the platform, not
+ * the bar.
  *
  * == The fourth: the first tool that WRITES
  *
@@ -56,11 +65,87 @@ 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`: it has no backing endpoint (`routes.rb:113` mounts it
+ * as a comment only). A tool advertised in `tools/list` remains a promise an
+ * agent will act on.
+ *
+ * == The ninth through twelfth: member management
+ *
+ *   - `list_repository_members`, `add_repository_member`,
+ *     `update_repository_member_permissions` and `remove_repository_member`
+ *     wrap the four `user_repository_members` endpoints (all shipped: SPGD-875,
+ *     specguard@origin/main).
+ *
+ * They also forced the transport's fourth verb: `update` is a PATCH, which
+ * arrived with `patchJson` in this same slice — 200 with a JSON body, so it
+ * routes through `requestJson` like `postJson` rather than `deleteJson`'s
+ * raw-body handling.
+ *
+ * A known limitation rides with them and is stated in the edit/revoke tool
+ * descriptions rather than papered over: PATCH and DELETE name a membership by
+ * id, but no endpoint serves that id (the platform's `#serialize` deliberately
+ * omits it), so the id comes from the platform's web members page today. That
+ * is a platform-side follow-up, not a client-side workaround — there is no
+ * name-based lookup.
+ *
+ * == The thirteenth: rename
+ *
+ *   - `rename_repository` wraps `PATCH /api/v1/repositories/:id` (shipped:
+ *     SPGD-878, `specguard@origin/main` e026793, PR #266).
+ *
+ * This is the entry the forbid above once named as "the natural next slice" —
+ * the platform moved (SPGD-878 shipped the endpoint), so the forbid retired
+ * exactly as the duplicate-clustering one did. It reuses `patchJson` landed
+ * with the member-management slice rather than minting a transport of its own.
+ * The verb's one asymmetry is carried in the tool description rather than
+ * papered over: rename authorizes OWNER-ONLY, while removal authorizes the
+ * BROADER `repo.delete` capability — a member who may destroy the repository
+ * may not rename it. Before this tool the bridge's only rename path was
+ * remove-and-re-register, which destroys every key, run and intent; this one
+ * keeps them.
  */
 export declare const TOOLS: readonly ToolDefinition[];
 export type { ToolContext, ToolDefinition, ToolResult } from "./types.js";

package/dist/src/tools/index.js

@@ -1,7 +1,17 @@
 import addRepository from "./add-repository.js";
+import addRepositoryMember from "./add-repository-member.js";
+import createRepositoryApiKey from "./create-repository-api-key.js";
 import lintIntentAnnotations from "./lint-intent-annotations.js";
 import listRepositories from "./list-repositories.js";
+import listRepositoryMembers from "./list-repository-members.js";
+import nearDuplicateClusters from "./near-duplicate-clusters.js";
 import getRepositoryOverview from "./repository-overview.js";
+import registrableRepositories from "./registrable-repositories.js";
+import removeRepository from "./remove-repository.js";
+import removeRepositoryMember from "./remove-repository-member.js";
+import renameRepository from "./rename-repository.js";
+import revokeRepositoryApiKey from "./revoke-repository-api-key.js";
+import updateRepositoryMemberPermissions from "./update-repository-member-permissions.js";
 /**
  * THE REGISTRY — the one file that changes when the toolset grows.
  *
@@ -37,12 +47,21 @@ import getRepositoryOverview from "./repository-overview.js";
  *
  * == What is deliberately absent
  *
- * `/check-intent` and duplicate clustering are NOT here and must not be added
- * until their backing engine and data exist (SPGD-114 / SPGD-115). A tool
- * advertised in `tools/list` is a promise an agent will act on: wrapping an
- * endpoint that does not exist would produce a server that discovers cleanly
- * and fails on use, which is worse than not offering the tool, because the
- * agent has already committed to a plan by the time it finds out.
+ * `/check-intent` is NOT here and must not be added until its backing endpoint
+ * exists — `specguard/config/routes.rb:113` carries it as a comment only, which
+ * is the evidence this forbid rests on. A tool advertised in `tools/list` is a
+ * promise an agent will act on: wrapping an endpoint that does not exist would
+ * produce a server that discovers cleanly and fails on use, which is worse than
+ * not offering the tool, because the agent has already committed to a plan by
+ * the time it finds out.
+ *
+ * Duplicate clustering was once under this same forbid, on the same standing
+ * rule — no tool may wrap what has not shipped. That half retired when the
+ * platform moved: SPGD-703 (`specguard` `c43dc19`, 2026-08-28) shipped
+ * `GET /api/v1/repository?near_duplicates=`, serving
+ * `RepositoryOverview#serialized_near_duplicates` behind an opt-in ask, and
+ * `near_duplicate_clusters` below wraps it. What moved was the platform, not
+ * the bar.
  *
  * == The fourth: the first tool that WRITES
  *
@@ -59,16 +78,102 @@ 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`: it has no backing endpoint (`routes.rb:113` mounts it
+ * as a comment only). A tool advertised in `tools/list` remains a promise an
+ * agent will act on.
+ *
+ * == The ninth through twelfth: member management
+ *
+ *   - `list_repository_members`, `add_repository_member`,
+ *     `update_repository_member_permissions` and `remove_repository_member`
+ *     wrap the four `user_repository_members` endpoints (all shipped: SPGD-875,
+ *     specguard@origin/main).
+ *
+ * They also forced the transport's fourth verb: `update` is a PATCH, which
+ * arrived with `patchJson` in this same slice — 200 with a JSON body, so it
+ * routes through `requestJson` like `postJson` rather than `deleteJson`'s
+ * raw-body handling.
+ *
+ * A known limitation rides with them and is stated in the edit/revoke tool
+ * descriptions rather than papered over: PATCH and DELETE name a membership by
+ * id, but no endpoint serves that id (the platform's `#serialize` deliberately
+ * omits it), so the id comes from the platform's web members page today. That
+ * is a platform-side follow-up, not a client-side workaround — there is no
+ * name-based lookup.
+ *
+ * == The thirteenth: rename
+ *
+ *   - `rename_repository` wraps `PATCH /api/v1/repositories/:id` (shipped:
+ *     SPGD-878, `specguard@origin/main` e026793, PR #266).
+ *
+ * This is the entry the forbid above once named as "the natural next slice" —
+ * the platform moved (SPGD-878 shipped the endpoint), so the forbid retired
+ * exactly as the duplicate-clustering one did. It reuses `patchJson` landed
+ * with the member-management slice rather than minting a transport of its own.
+ * The verb's one asymmetry is carried in the tool description rather than
+ * papered over: rename authorizes OWNER-ONLY, while removal authorizes the
+ * BROADER `repo.delete` capability — a member who may destroy the repository
+ * may not rename it. Before this tool the bridge's only rename path was
+ * remove-and-re-register, which destroys every key, run and intent; this one
+ * keeps them.
  */
 export const TOOLS = [
     lintIntentAnnotations,
     getRepositoryOverview,
     listRepositories,
     addRepository,
+    registrableRepositories,
+    removeRepository,
+    createRepositoryApiKey,
+    revokeRepositoryApiKey,
+    nearDuplicateClusters,
+    listRepositoryMembers,
+    addRepositoryMember,
+    updateRepositoryMemberPermissions,
+    removeRepositoryMember,
+    renameRepository,
 ];
 //# 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,mBAAmB,MAAM,4BAA4B,CAAC;AAC7D,OAAO,sBAAsB,MAAM,gCAAgC,CAAC;AACpE,OAAO,qBAAqB,MAAM,8BAA8B,CAAC;AACjE,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AACtD,OAAO,qBAAqB,MAAM,8BAA8B,CAAC;AACjE,OAAO,qBAAqB,MAAM,8BAA8B,CAAC;AACjE,OAAO,qBAAqB,MAAM,0BAA0B,CAAC;AAC7D,OAAO,uBAAuB,MAAM,+BAA+B,CAAC;AACpE,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AACtD,OAAO,sBAAsB,MAAM,+BAA+B,CAAC;AACnE,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AACtD,OAAO,sBAAsB,MAAM,gCAAgC,CAAC;AACpE,OAAO,iCAAiC,MAAM,2CAA2C,CAAC;AAG1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmJG;AACH,MAAM,CAAC,MAAM,KAAK,GAA8B;IAC9C,qBAAqB;IACrB,qBAAqB;IACrB,gBAAgB;IAChB,aAAa;IACb,uBAAuB;IACvB,gBAAgB;IAChB,sBAAsB;IACtB,sBAAsB;IACtB,qBAAqB;IACrB,qBAAqB;IACrB,mBAAmB;IACnB,iCAAiC;IACjC,sBAAsB;IACtB,gBAAgB;CACjB,CAAC"}

package/dist/src/tools/list-repository-members.d.ts

@@ -0,0 +1,32 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `GET /api/v1/repositories/:repository_id/members` as a tool — shipped in the
+ * platform (`specguard/config/routes.rb`, `Api::V1::UserRepositoryMembersController#index`,
+ * SPGD-875).
+ *
+ * == Memberships only, never `keys_minted`
+ *
+ * The endpoint answers the same rows the web members page renders — `handle`,
+ * `permissions`, `granted_by`, `created_at`, ordered by handle — and
+ * deliberately NOTHING else. `keys_minted` is a `keys.manage` disclosure that
+ * page gates separately; this read answers memberships to a `members.manage`
+ * holder and no more. A tool that promised counts here would be promising
+ * something the endpoint refuses to say.
+ *
+ * == No membership id, by design
+ *
+ * The body carries no membership id: ids are not portable between
+ * repositories, and serving one would invite treating it as portable. PATCH
+ * and DELETE still name rows by that id — see
+ * `update_repository_member_permissions` and `remove_repository_member` for
+ * where the id comes from today.
+ *
+ * == No client-side capability probing
+ *
+ * The server gates at `current_repository(:members_manage)`: a non-member gets
+ * 404 (the repository's existence stays hidden), a member without the
+ * capability gets 403 with SpecGuard's own sentence. This tool predicts
+ * neither; it reports what came back.
+ */
+declare const listRepositoryMembers: ToolDefinition;
+export default listRepositoryMembers;

package/dist/src/tools/list-repository-members.js

@@ -0,0 +1,76 @@
+import { getJsonObject, requireUserApiConfig } from "../support/specguard-api.js";
+import { requireString } from "./args.js";
+/**
+ * `GET /api/v1/repositories/:repository_id/members` as a tool — shipped in the
+ * platform (`specguard/config/routes.rb`, `Api::V1::UserRepositoryMembersController#index`,
+ * SPGD-875).
+ *
+ * == Memberships only, never `keys_minted`
+ *
+ * The endpoint answers the same rows the web members page renders — `handle`,
+ * `permissions`, `granted_by`, `created_at`, ordered by handle — and
+ * deliberately NOTHING else. `keys_minted` is a `keys.manage` disclosure that
+ * page gates separately; this read answers memberships to a `members.manage`
+ * holder and no more. A tool that promised counts here would be promising
+ * something the endpoint refuses to say.
+ *
+ * == No membership id, by design
+ *
+ * The body carries no membership id: ids are not portable between
+ * repositories, and serving one would invite treating it as portable. PATCH
+ * and DELETE still name rows by that id — see
+ * `update_repository_member_permissions` and `remove_repository_member` for
+ * where the id comes from today.
+ *
+ * == No client-side capability probing
+ *
+ * The server gates at `current_repository(:members_manage)`: a non-member gets
+ * 404 (the repository's existence stays hidden), a member without the
+ * capability gets 403 with SpecGuard's own sentence. This tool predicts
+ * neither; it reports what came back.
+ */
+const listRepositoryMembers = {
+    name: "list_repository_members",
+    title: "List repository members",
+    description: "Lists who has access to a SpecGuard repository: one row per member with their `handle`, " +
+        "`permissions`, `granted_by` (who last set them) and `created_at`, ordered by handle. " +
+        "The list answers MEMBERSHIPS only and never reports how many CI keys a member has minted " +
+        "(`keys_minted`) — that is a separate `keys.manage` disclosure this endpoint deliberately " +
+        "withholds, and the API-keys tools are the surface for it. " +
+        "Authorization is the `members.manage` capability: a caller who is not a member of the " +
+        "repository is refused 404 (the repository's existence stays hidden), and a member without " +
+        "`members.manage` is refused 403 in SpecGuard's own words. " +
+        "Takes `repository_id` — the numeric id `list_repositories` reports, not the `org/repo` " +
+        "handle. " +
+        "Needs SPECGUARD_USER_API_KEY (an sgu_… key), the same credential `list_repositories` " +
+        "reads and a DIFFERENT one from the sgk_… repository key `get_repository_overview` uses.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repository_id: {
+                type: "string",
+                description: "The repository whose members to list — its numeric id, as `add_repository` " +
+                    "returns and `list_repositories` reports, not the `org/repo` handle.",
+            },
+        },
+        required: ["repository_id"],
+        // Closed for the reason every tool here states: `server.ts` forwards
+        // `arguments` unvalidated, so an open schema would let a misspelled argument
+        // be dropped silently.
+        additionalProperties: false,
+    },
+    async run(args, context) {
+        const repositoryId = requireString(args["repository_id"], "repository_id");
+        const api = requireUserApiConfig(context.config);
+        const members = await getJsonObject(api, `/api/v1/repositories/${encodeURIComponent(repositoryId)}/members`, {}, context.fetch);
+        // Passed through unreshaped, the standing rule (`types.ts`: "A thin client
+        // that reshapes its upstream is not thin") — the endpoint serves the same
+        // four fields the web members page renders, under the same names.
+        return {
+            text: JSON.stringify(members, null, 2),
+            structured: members,
+        };
+    },
+};
+export default listRepositoryMembers;
+//# sourceMappingURL=list-repository-members.js.map

package/dist/src/tools/list-repository-members.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-repository-members.js","sourceRoot":"","sources":["../../../src/tools/list-repository-members.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,qBAAqB,GAAmB;IAC5C,IAAI,EAAE,yBAAyB;IAC/B,KAAK,EAAE,yBAAyB;IAChC,WAAW,EACT,0FAA0F;QAC1F,uFAAuF;QACvF,2FAA2F;QAC3F,2FAA2F;QAC3F,4DAA4D;QAC5D,wFAAwF;QACxF,4FAA4F;QAC5F,4DAA4D;QAC5D,yFAAyF;QACzF,UAAU;QACV,uFAAuF;QACvF,yFAAyF;IAC3F,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,aAAa,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,6EAA6E;oBAC7E,qEAAqE;aACxE;SACF;QACD,QAAQ,EAAE,CAAC,eAAe,CAAC;QAC3B,qEAAqE;QACrE,6EAA6E;QAC7E,uBAAuB;QACvB,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,OAAO,GAAG,MAAM,aAAa,CACjC,GAAG,EACH,wBAAwB,kBAAkB,CAAC,YAAY,CAAC,UAAU,EAClE,EAAE,EACF,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,2EAA2E;QAC3E,0EAA0E;QAC1E,kEAAkE;QAClE,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,qBAAqB,CAAC"}

package/dist/src/tools/near-duplicate-clusters.d.ts

@@ -0,0 +1,58 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `GET /api/v1/repository?near_duplicates=` as a tool — shipped in the
+ * platform by SPGD-703 (`specguard` `c43dc19`, 2026-08-28), which added the
+ * `near_duplicates` block to `RepositoryOverview` behind an opt-in ask.
+ *
+ * == What the block is, and why it is behind an ask at all
+ *
+ * It is the suite-wide near-duplicate census: which tests READ alike — same
+ * body text, not same file — clustered by the engine SPGD-369 shipped
+ * (`specguard` `f7d5352`). It is the first block on that endpoint whose grain
+ * is the REPOSITORY rather than a run or a window of runs, and the first one
+ * gated on COST rather than rows: `NearDuplicateClusters` is linear but
+ * measured in seconds (seven queries at every size; seconds at a few thousand
+ * identities, extrapolating to tens of seconds at the 20,000-identity design
+ * point). `?near_duplicates=` confines that cost to the client that named it —
+ * no ask, key present and `null`, not one query — which is why this block is a
+ * SEPARATE tool rather than a forwarded parameter on
+ * `get_repository_overview`: an agent calling the overview should never pay
+ * the census by accident, and an agent calling this tool has asked for nothing
+ * else. Splitting the tools splits the cost along exactly the line the server
+ * drew.
+ *
+ * == The ask is always sent, and always spelled `"true"`
+ *
+ * The server reads only whether the parameter is PRESENT
+ * (`RequestedNearDuplicatesParam`): `?near_duplicates=false` opens the block
+ * exactly as `=true` does, and a non-String shape is read as no ask at all.
+ * There is no "off" value for a client to send, so this tool has no arguments
+ * — nothing about the census is choosable from here, which is also why the
+ * schema is CLOSED rather than merely empty: `server.ts` forwards `arguments`
+ * unvalidated, and an open schema would let an invented argument ride through
+ * and be silently dropped (see `registrable-repositories.ts` for the same
+ * call). `near_duplicates: "true"` is built rather than stringified for the
+ * same reason `repository-overview.ts` builds its `unannotated_examples` key:
+ * `getJson` omits only `undefined`, so a conditional send is the only honest
+ * way to spell "always" here.
+ *
+ * == The response is passed through, not re-modelled
+ *
+ * Same rule as `repository-overview.ts`: every figure in the block is
+ * annotated in `RepositoryOverview#serialized_near_duplicates` with the reason
+ * for its shape, and several of those reasons are about honesty rather than
+ * convenience — `similarity_floor`/`similarity_basis` served FIRST because a
+ * count without the statement of what the similarity means is a vacuous
+ * figure; `member_count` (texts in the REPOSITORY, across every run) and
+ * `example_count` (examples in the ONE run `weighed_run_id` names) served side
+ * by side because a three-example table-driven loop is one member and three
+ * examples, and flattening them would erase the figure the ranking is built
+ * on; `unobserved_members` disclosing that the member list holds an identity
+ * the weighed run did not observe; `similarity_range` as the `[strongest,
+ * weakest]` pair because membership is transitive while similarity is not.
+ * Reshaping here would discard distinctions the serializer spent that care
+ * preserving, so the body goes back as it arrived — the whole body, which
+ * carries the repository/run context the clusters sit inside.
+ */
+declare const nearDuplicateClusters: ToolDefinition;
+export default nearDuplicateClusters;