specguard-mcp 0.1.4 → 0.1.5

package/dist/src/tools/index.js

@@ -1,11 +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.
  *
@@ -41,12 +47,21 @@ import revokeRepositoryApiKey from "./revoke-repository-api-key.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
  *
@@ -106,9 +121,44 @@ import revokeRepositoryApiKey from "./revoke-repository-api-key.js";
  * `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.
+ * 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,
@@ -119,5 +169,11 @@ export const TOOLS = [
     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,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"}
+{"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;

package/dist/src/tools/near-duplicate-clusters.js

@@ -0,0 +1,116 @@
+import { requireApiConfig } from "../config.js";
+import { getJsonObject } from "../support/specguard-api.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.
+ */
+const nearDuplicateClusters = {
+    name: "near_duplicate_clusters",
+    title: "Near-duplicate clusters",
+    description: "Run SpecGuard's near-duplicate census over a repository's tests — which tests READ alike " +
+        "(same body text, whatever file they sit in), clustered by similarity. Answers the refactoring " +
+        "question the overview's per-run rankings cannot: where is the same test written twice, before " +
+        "you delete or merge anything. " +
+        "THIS IS THE EXPENSIVE READ ON THIS BRIDGE: the census is linear but measured in seconds — seven " +
+        "queries at every size, tens of seconds extrapolated at the 20,000-test design point — which is " +
+        "exactly why the server serves it only to a client that asks (`?near_duplicates=`) and answers " +
+        "`near_duplicates: null` on the plain overview. Calling this tool IS the ask; it takes no " +
+        "arguments because nothing about the census is choosable — the clusters are the repository's, " +
+        "computed over every run, and one call returns them all. " +
+        "READ THE DISCLOSURE KEYS BEFORE THE COUNT: `similarity_floor` and `similarity_basis` sit FIRST " +
+        "in the block and qualify every cluster below them — a cluster count without what 'similar' " +
+        "meant is a figure you cannot act on. `truncated: true` means the cluster list was cut at the " +
+        "cap while the counts above it (`cluster_count`, `identity_count`, `clustered_*`) describe the " +
+        "WHOLE census, so never fold `clusters` length as the total. " +
+        "READ EVERY CLUSTER'S FIGURES AT THEIR OWN GRAIN: `member_count` counts texts in the REPOSITORY " +
+        "across every run, `example_count` counts examples in the ONE run `weighed_run_id` names — a " +
+        "three-example table-driven loop is ONE member and THREE examples, and those two numbers beside " +
+        "each other are the whole point. `unobserved_members: true` on a cluster says a member identity " +
+        "the weighed run did not observe (deleted, renamed, deselected) is still listed — do not reconcile " +
+        "the member list against a run's examples and expect it to balance. `similarity_range` is " +
+        "[strongest, weakest]: membership is transitive, similarity is not, and the gap between the edges " +
+        "is the merge risk. `total_seconds` is raw and `null` where nothing was timed — never a zero " +
+        "that would read as free. " +
+        "A quiet answer is a FINDING, not a gap: `clusters: []` with a real `identity_count` is the " +
+        "success state (nothing reads alike), and the three silences — nothing ingested " +
+        "(`recorded_count: 0`), nothing embedded (`identity_count: 0`), nothing alike — are kept " +
+        "distinguishable by those counts rather than collapsed into one empty list. " +
+        "Same credential and endpoint as `get_repository_overview` (an `sgk_` repository key on " +
+        "`GET /api/v1/repository`); the response is that endpoint's full body with the `near_duplicates` " +
+        "block OPENED, passed through unmodified.",
+    inputSchema: {
+        type: "object",
+        // No properties, deliberately — see this file's header. Still CLOSED rather
+        // than merely empty, for the reason `registrable-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 = requireApiConfig(context.config);
+        const overview = await getJsonObject(api, "/api/v1/repository", {
+            // Always sent, always `"true"` — the server reads only that the key is
+            // present (`?near_duplicates=false` opens the block too), and this
+            // tool exists to open it. See this file's header.
+            near_duplicates: "true",
+        }, context.fetch);
+        return {
+            text: JSON.stringify(overview, null, 2),
+            structured: overview,
+        };
+    },
+};
+export default nearDuplicateClusters;
+//# sourceMappingURL=near-duplicate-clusters.js.map

package/dist/src/tools/near-duplicate-clusters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"near-duplicate-clusters.js","sourceRoot":"","sources":["../../../src/tools/near-duplicate-clusters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,qBAAqB,GAAmB;IAC5C,IAAI,EAAE,yBAAyB;IAE/B,KAAK,EAAE,yBAAyB;IAEhC,WAAW,EACT,2FAA2F;QAC3F,gGAAgG;QAChG,gGAAgG;QAChG,gCAAgC;QAChC,kGAAkG;QAClG,iGAAiG;QACjG,gGAAgG;QAChG,2FAA2F;QAC3F,+FAA+F;QAC/F,0DAA0D;QAC1D,iGAAiG;QACjG,6FAA6F;QAC7F,+FAA+F;QAC/F,gGAAgG;QAChG,8DAA8D;QAC9D,iGAAiG;QACjG,8FAA8F;QAC9F,iGAAiG;QACjG,iGAAiG;QACjG,oGAAoG;QACpG,2FAA2F;QAC3F,mGAAmG;QACnG,8FAA8F;QAC9F,2BAA2B;QAC3B,6FAA6F;QAC7F,iFAAiF;QACjF,0FAA0F;QAC1F,6EAA6E;QAC7E,yFAAyF;QACzF,kGAAkG;QAClG,0CAA0C;IAE5C,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,4EAA4E;QAC5E,wEAAwE;QACxE,yEAAyE;QACzE,2EAA2E;QAC3E,oDAAoD;QACpD,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO;QACtB,MAAM,GAAG,GAAG,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAE7C,MAAM,QAAQ,GAAG,MAAM,aAAa,CAClC,GAAG,EACH,oBAAoB,EACpB;YACE,uEAAuE;YACvE,mEAAmE;YACnE,kDAAkD;YAClD,eAAe,EAAE,MAAM;SACxB,EACD,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,UAAU,EAAE,QAAQ;SACrB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,qBAAqB,CAAC"}

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

@@ -0,0 +1,30 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `DELETE /api/v1/repositories/:repository_id/members/:id` as a tool — shipped
+ * in the platform (`specguard/config/routes.rb`,
+ * `Api::V1::UserRepositoryMembersController#destroy`, SPGD-875).
+ *
+ * == The two documented asymmetries, stated BEFORE the call
+ *
+ * Revoking a membership deliberately LEAVES that member's minted CI keys
+ * authenticating (`User has_many :created_api_keys, dependent: :nullify`) —
+ * the lever for those is the API-keys surface, not this one. And
+ * self-revocation is permitted: it is the caller's own access to give up, and
+ * after it the next request to these routes answers 404, not 403 (a former
+ * member is a non-member). Both belong in the description because they are
+ * the facts an agent must know before it commits to the call.
+ *
+ * == The owner row cannot arrive
+ *
+ * An owner membership is structurally impossible
+ * (`RepositoryMembership#user_is_not_the_owner`), so "cannot remove the owner"
+ * is a model invariant, not a guard this bridge re-checks.
+ *
+ * == 204 with no body
+ *
+ * The same empty-body success `remove_repository` and
+ * `revoke_repository_api_key` serve; the same reason `deleteJson` exists
+ * rather than routing a 204 through `requestJson`'s JSON parse.
+ */
+declare const removeRepositoryMember: ToolDefinition;
+export default removeRepositoryMember;

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

@@ -0,0 +1,93 @@
+import { deleteJson, requireUserApiConfig } from "../support/specguard-api.js";
+import { requireString } from "./args.js";
+/**
+ * `DELETE /api/v1/repositories/:repository_id/members/:id` as a tool — shipped
+ * in the platform (`specguard/config/routes.rb`,
+ * `Api::V1::UserRepositoryMembersController#destroy`, SPGD-875).
+ *
+ * == The two documented asymmetries, stated BEFORE the call
+ *
+ * Revoking a membership deliberately LEAVES that member's minted CI keys
+ * authenticating (`User has_many :created_api_keys, dependent: :nullify`) —
+ * the lever for those is the API-keys surface, not this one. And
+ * self-revocation is permitted: it is the caller's own access to give up, and
+ * after it the next request to these routes answers 404, not 403 (a former
+ * member is a non-member). Both belong in the description because they are
+ * the facts an agent must know before it commits to the call.
+ *
+ * == The owner row cannot arrive
+ *
+ * An owner membership is structurally impossible
+ * (`RepositoryMembership#user_is_not_the_owner`), so "cannot remove the owner"
+ * is a model invariant, not a guard this bridge re-checks.
+ *
+ * == 204 with no body
+ *
+ * The same empty-body success `remove_repository` and
+ * `revoke_repository_api_key` serve; the same reason `deleteJson` exists
+ * rather than routing a 204 through `requestJson`'s JSON parse.
+ */
+const removeRepositoryMember = {
+    name: "remove_repository_member",
+    title: "Remove repository member",
+    description: "Revokes one person's access to a SpecGuard repository by removing their membership. " +
+        "The member is named by `member_id` — a MEMBERSHIP id, not a user id — scoped to " +
+        "`repository_id`: a membership id belonging to a different repository is refused 404, " +
+        "never a cross-repository revoke. " +
+        "⚠️ Revoking does NOT revoke that member's minted CI keys — any sgk_… keys they created " +
+        "on the repository keep authenticating by design; the lever for those is the API-keys " +
+        "surface (`revoke_repository_api_key`), not this one. " +
+        "Self-revocation is permitted: a caller may remove their own membership, and their next " +
+        "request to the member routes answers 404 — a former member is a non-member, so this tool " +
+        "cannot read the repository's members afterwards. The repository owner's membership cannot " +
+        "be removed at all (an owner holds everything by construction). " +
+        "KNOWN LIMITATION: no API endpoint serves the membership id — the member list and the " +
+        "add-member response both omit it by design — so the id must be obtained from the " +
+        "platform (today via the repository's web members page); there is no name-based lookup. " +
+        "Authorization is the `members.manage` capability — a member without it is refused 403 in " +
+        "SpecGuard's own words. A 204 means the membership is revoked. " +
+        "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 `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 membership belongs to — its numeric id, as `add_repository` " +
+                    "returns and `list_repositories` reports, not the `org/repo` handle.",
+            },
+            member_id: {
+                type: "string",
+                description: "The id of the MEMBERSHIP row to revoke — not a user id, and not the handle. " +
+                    "Scoped to `repository_id`: a foreign membership id is refused 404. No API endpoint " +
+                    "serves this id today; obtain it from the platform's web members page.",
+            },
+        },
+        required: ["repository_id", "member_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 membership the call never named.
+        additionalProperties: false,
+    },
+    async run(args, context) {
+        const repositoryId = requireString(args["repository_id"], "repository_id");
+        const memberId = requireString(args["member_id"], "member_id");
+        const api = requireUserApiConfig(context.config);
+        const body = await deleteJson(api, `/api/v1/repositories/${encodeURIComponent(repositoryId)}/members/${encodeURIComponent(memberId)}`, context.fetch);
+        // 204 with no body — the tool's own words, because the deployment's whole
+        // answer was "no content". The keys asymmetry is restated here because the
+        // moment of success is the last moment the fact still matters.
+        return {
+            text: body === ""
+                ? `Membership ${memberId} revoked (204). That person's minted CI keys on this ` +
+                    "repository keep authenticating — revoke those separately with " +
+                    "revoke_repository_api_key if that is the intent."
+                : body,
+            structured: { repository_id: repositoryId, member_id: memberId, revoked: true },
+        };
+    },
+};
+export default removeRepositoryMember;
+//# sourceMappingURL=remove-repository-member.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remove-repository-member.js","sourceRoot":"","sources":["../../../src/tools/remove-repository-member.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,sBAAsB,GAAmB;IAC7C,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,0BAA0B;IACjC,WAAW,EACT,sFAAsF;QACtF,kFAAkF;QAClF,uFAAuF;QACvF,mCAAmC;QACnC,yFAAyF;QACzF,uFAAuF;QACvF,uDAAuD;QACvD,yFAAyF;QACzF,2FAA2F;QAC3F,4FAA4F;QAC5F,iEAAiE;QACjE,uFAAuF;QACvF,mFAAmF;QACnF,yFAAyF;QACzF,2FAA2F;QAC3F,gEAAgE;QAChE,yFAAyF;QACzF,UAAU;QACV,oFAAoF;QACpF,+FAA+F;IACjG,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,aAAa,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,iFAAiF;oBACjF,qEAAqE;aACxE;YACD,SAAS,EAAE;gBACT,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,8EAA8E;oBAC9E,qFAAqF;oBACrF,uEAAuE;aAC1E;SACF;QACD,QAAQ,EAAE,CAAC,eAAe,EAAE,WAAW,CAAC;QACxC,4EAA4E;QAC5E,uEAAuE;QACvE,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;QAC3E,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,CAAC;QAE/D,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,IAAI,GAAG,MAAM,UAAU,CAC3B,GAAG,EACH,wBAAwB,kBAAkB,CAAC,YAAY,CAAC,YAAY,kBAAkB,CAAC,QAAQ,CAAC,EAAE,EAClG,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,0EAA0E;QAC1E,2EAA2E;QAC3E,+DAA+D;QAC/D,OAAO;YACL,IAAI,EACF,IAAI,KAAK,EAAE;gBACT,CAAC,CAAC,cAAc,QAAQ,uDAAuD;oBAC7E,gEAAgE;oBAChE,kDAAkD;gBACpD,CAAC,CAAC,IAAI;YACV,UAAU,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE;SAChF,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,sBAAsB,CAAC"}

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

@@ -0,0 +1,44 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `PATCH /api/v1/repositories/:id` as a tool — shipped in the platform
+ * (`specguard/config/routes.rb:186`, `Api::V1::UserRepositoriesController#update`,
+ * SPGD-878, PR #266).
+ *
+ * == Why this tool exists at all
+ *
+ * Before it, the only way to change a repository's `org/repo` name through the
+ * bridge was `remove_repository` plus `add_repository` — which destroys every
+ * API key, every run and every intent on the repository, because that is what
+ * remove does. The platform's rename endpoint keeps all of it; this tool is
+ * the bridge's one-line path to that.
+ *
+ * == Authorization is OWNER-ONLY — deliberately narrower than delete
+ *
+ * The controller gates through `current_repository(:owner)`, NOT the
+ * `repo.delete` capability fork `remove_repository` authorizes through — so a
+ * member granted `repo.delete` may DESTROY the repository but may NOT rename
+ * it. The asymmetry is the platform's, and the description carries it rather
+ * than papering over it.
+ *
+ * == The grant precondition
+ *
+ * The owner check redeems a browser-issued grant that is valid for seven days;
+ * a nil or stale one is a 403 whose own sentence names the fix (re-grant via
+ * the browser). The bridge surfaces that sentence verbatim and adds no
+ * client-side grant handling — the server is the gate.
+ *
+ * == The body is top-level `{github_full_name}` — NOT nested
+ *
+ * `update_params` permits `github_full_name` at the TOP level, not under a
+ * `repository` key; a nested body is silently empty to the server. And a taken
+ * name is a 400 (`render_bad_request`, the `taken` branch), not a 409 — this
+ * description says so because it is the one answer an agent is most likely to
+ * mispredict.
+ *
+ * == The 200 body is the list_repositories shape
+ *
+ * `{repository: serialize(...)}` — the same serializer `list_repositories`
+ * serves, so the response needs no reshaping and gets none.
+ */
+declare const renameRepository: ToolDefinition;
+export default renameRepository;