specguard-mcp 0.1.3 → 0.1.5

package/README.md

@@ -32,9 +32,9 @@ refuses to boot and takes the tools that needed no configuration down with it.
 
 | Variable | Needed by | Default | What it is |
 | --- | --- | --- | --- |
-| `SPECGUARD_ENDPOINT` | `get_repository_overview`, `list_repositories` | — | your SpecGuard instance's root URL, **including the scheme** — e.g. `https://specguard.example.com`, or `http://localhost:3000`. A value with no scheme is refused by name (`SPECGUARD_ENDPOINT is not a usable URL: "sg.example.com"`) rather than surfacing later as an opaque failure. `SPECGUARD_URL` is accepted as an alias, and is the name every message uses when it is the one you set. A blank value counts as unset, so leaving `SPECGUARD_ENDPOINT` empty in a templated config falls through to `SPECGUARD_URL` instead of suppressing it |
+| `SPECGUARD_ENDPOINT` | `get_repository_overview`, `list_repositories`, `add_repository`, `registrable_repositories` | — | your SpecGuard instance's root URL, **including the scheme** — e.g. `https://specguard.example.com`, or `http://localhost:3000`. A value with no scheme is refused by name (`SPECGUARD_ENDPOINT is not a usable URL: "sg.example.com"`) rather than surfacing later as an opaque failure. `SPECGUARD_URL` is accepted as an alias, and is the name every message uses when it is the one you set. A blank value counts as unset, so leaving `SPECGUARD_ENDPOINT` empty in a templated config falls through to `SPECGUARD_URL` instead of suppressing it |
 | `SPECGUARD_API_KEY` | `get_repository_overview` | — | an agent/CI API key (`sgk_…`) issued by that deployment |
-| `SPECGUARD_USER_API_KEY` | `list_repositories` | — | a **user** API key (`sgu_…`), minted from that deployment's account page. A different credential from the one above, not a second place to put the same value: SpecGuard decides which of them a request may use from the token's prefix, before it reads anything, and answers `401` for the other one. Set whichever your tools need — both, if you use both |
+| `SPECGUARD_USER_API_KEY` | `list_repositories`, `add_repository`, `registrable_repositories`, `remove_repository`, `create_repository_api_key`, `revoke_repository_api_key`, `list_repository_members`, `add_repository_member`, `update_repository_member_permissions`, `remove_repository_member`, `rename_repository` | — | a **user** API key (`sgu_…`), minted from that deployment's account page. A different credential from the one above, not a second place to put the same value: SpecGuard decides which of them a request may use from the token's prefix, before it reads anything, and answers `401` for the other one. Set whichever your tools need — both, if you use both |
 | `SPECGUARD_LINT_COMMAND` | `lint_intent_annotations` | `specguard-lint` | the command that runs the linter. Most Ruby projects need `bundle exec specguard-lint` |
 | `SPECGUARD_TIMEOUT_MS` | HTTP tools | `30000` | how long a call to SpecGuard may take |
 
@@ -351,10 +351,11 @@ decides which table is consulted before any of them is read — so the two are n
 setting one does not stand in for the other. Every message this tool produces names the variable
 *it* reads, so a `401` here never sends you to check the key `get_repository_overview` uses.
 
-Registering a repository is now `add_repository`, below — it reads the same `sgu_…` key and takes the
-`full_name` this tool reports. Revoking keys and the rest of the user-scoped surface are still absent,
-because their endpoints have not shipped: a tool here is a promise the agent will act on, so it waits
-for the capability rather than the other way round.
+Registering a repository is `add_repository`, below — it reads the same `sgu_…` key and takes the
+`full_name` this tool reports. Removal and the key lifecycle (`remove_repository`,
+`create_repository_api_key`, `revoke_repository_api_key`) are below too, on the same key; a tool
+here is a promise the agent will act on, so each waits for the capability rather than the other way
+round.
 
 ### `add_repository`
 
@@ -398,6 +399,254 @@ as this bridge rejecting a name the platform would have accepted.
 It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and a
 different one from the `sgk_…` key `get_repository_overview` uses.
 
+### `registrable_repositories`
+
+Lists the GitHub repositories the person behind `SPECGUARD_USER_API_KEY` **could** register with
+SpecGuard — the set the registration gate would consult, read out loud in advance, so an agent can
+pick a `full_name` for `add_repository` from a real answer rather than by guessing. `list_repositories`
+reports what *is* registered; this reports what could be, and the two answer different questions.
+
+The body comes back as SpecGuard serves it: `{"repositories": […]}` with each entry carrying
+`full_name` and `registered`, ordered by `full_name` ascending, plus a `grant` block (`captured_at`,
+`expires_at`, `stale`) describing the stored record of this person's GitHub permissions.
+
+**`registered` is asked globally, not just of your own repositories.** An entry marked
+`registered: true` was registered by *somebody* — possibly someone else — and a POST naming it will
+be refused with `has already been taken`. That is exactly why entries are *marked* rather than
+excluded: a reading scoped to what you can open would send you at a name nobody can register.
+
+**A name appearing here is not a promise the write will succeed.** This is the set the gate would
+consult at the moment of the read; the repository may be registered by someone else between this
+call and your POST.
+
+**A missing or stale grant is not an error — it is the modal first answer.** SpecGuard fails closed
+when it has no current record of your GitHub permissions, which is every person who has not opened
+SpecGuard in a browser recently. The call then answers `403` with SpecGuard's own sentence naming
+the fix: *sign in to SpecGuard in a browser and reconnect GitHub, then try again*. On that refusal
+the body still carries `grant`, and it distinguishes the two cases: `grant: null` means there never
+was one (first-time setup), a populated grant with `stale: true` means an existing connection lapsed
+— same remedy, very different urgency. Read it before telling the person what to do.
+
+**This tool takes no arguments** — the credential is the whole of the scope. The endpoint takes no
+parameters; which repositories are in the answer is decided by SpecGuard from the person the key
+speaks for.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `near_duplicate_clusters`
+
+Runs 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 the same test is written twice, before you delete or
+merge anything.
+
+**This is the expensive read in this toolset.** 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 why the platform serves it only to a client that asks (`?near_duplicates=`, shipped by SPGD-703)
+and answers `near_duplicates: null` on the plain overview. Calling this tool **is** the ask;
+`get_repository_overview` never sends it, so an agent reading the overview cannot pay the census by
+accident.
+
+**This tool takes no arguments** — nothing about the census is choosable. The clusters are the
+repository's, computed over every run; one call returns them all. (The server reads only that the
+`near_duplicates` key is *present* — `=false` would open it too — so there is no value for an
+argument to carry.)
+
+Read the response with its own rules in mind:
+
+- `similarity_floor` and `similarity_basis` sit **first** in the block and qualify every figure
+  below them — a cluster count without what "similar" meant is a count you cannot act on.
+- `member_count` (texts in the repository, across every run) and `example_count` (examples in the
+  one run `weighed_run_id` names) are **different grains**: a three-example table-driven loop is
+  one member and three examples. Never fold them.
+- `truncated: true` means the `clusters` list was cut at the cap while the counts above it
+  (`cluster_count`, `identity_count`, `clustered_*`) describe the whole census.
+- `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 that
+  run's examples.
+- `similarity_range` is `[strongest, weakest]`: membership is transitive, similarity is not.
+- `total_seconds` is `null` where nothing was timed — never a zero that would read as free.
+- `clusters: []` with a real `identity_count` is the **success** state (nothing reads alike); the
+  three silences — nothing ingested, nothing embedded, nothing alike — are kept distinguishable by
+  `recorded_count` / `identity_count` / the list itself.
+
+Same credential and endpoint as `get_repository_overview` (`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.
+
+### `remove_repository`
+
+Removes a repository from SpecGuard — and with it **every key, run and intent on it**. This is the
+destructive gesture in this toolset: irreversible, no undo, and a `204` means the repository and its
+history are gone short of re-registering from scratch. Confirm with the user before calling.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository to remove — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+
+Authorization is the `repo.delete` capability at **either surface** — an owner, or a member granted
+`repo.delete`, may remove the repository. A member without it is refused `403` with SpecGuard's own
+sentence, verbatim. The repository's CI keys stop authenticating the moment it succeeds.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `create_repository_api_key`
+
+Mints a new CI API key (`sgk_…`) for a SpecGuard repository and returns it alongside the
+repository's existing keys. Minting does not disturb existing keys — each key on a repository
+authenticates independently until revoked.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository to mint the key for — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `name` | an optional label for the key; omit it to let SpecGuard use its default name |
+
+The body comes back as SpecGuard serves it: an `api_key` block (`name`, `token`, `hint`,
+`created_at`) — the same shape `add_repository` serves.
+
+> ⚠️ **`api_key.token` is shown once and never again.** Nothing stores it and no endpoint can
+> re-serve it. Hand it to the person you are working for in your reply. If it is dropped, the
+> recovery is minting another key with this same tool — the platform has no regenerate — then
+> revoking the orphaned one with `revoke_repository_api_key`.
+
+Authorization is the `keys_manage` capability; a member without it is refused `403` with SpecGuard's
+own sentence, verbatim.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `revoke_repository_api_key`
+
+Revokes one CI API key on a SpecGuard repository. The key stops authenticating immediately; every
+**other** key on the repository keeps working, so CI keeps ingesting if it holds a surviving key.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository the key belongs to — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `key_id` | the id of the key to revoke, as served in the `api_key` block of `add_repository` or `create_repository_api_key` |
+
+The `key_id` is scoped to `repository_id`: a key id belonging to a different repository is refused
+`404`, never a cross-repository delete. Authorization is the `keys_manage` capability; a member
+without it is refused `403` with SpecGuard's own sentence, verbatim.
+
+**Key rotation is mint-then-revoke, in that order.** The platform has no regenerate, so mint a
+replacement with `create_repository_api_key` and deploy it BEFORE revoking the old one — revoke
+first and the repository's CI is locked out until a human mints a new key in a browser. A `204`
+means the key is revoked.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `list_repository_members`
+
+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.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` 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;
+the API-keys tools are the surface for it. The response carries **no membership id**, by design.
+
+Authorization is the `members.manage` capability: a caller who is not a member is refused `404`
+(the repository's existence stays hidden), and a member without `members.manage` is refused `403`
+with SpecGuard's own sentence, verbatim.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `add_repository_member`
+
+Grants a person access to a SpecGuard repository by their GitHub handle, with an optional list of
+permissions.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository to grant access to — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `handle` | the person's GitHub **login** — `octocat`, not a profile URL and not a display name; SpecGuard refuses both with its own sentence |
+| `permissions` | an optional list of permission strings (`view`, `keys.manage`, `members.manage`, `repo.delete`); omit it to grant access with no additional permissions |
+
+Each resolution failure — nobody has signed in as that handle yet, the account is archived, the
+handle is ambiguous, the handle is not a login — arrives as a **distinguishable** 400 message
+naming the exact next move. The grantor recorded on the membership is always the person behind
+`SPECGUARD_USER_API_KEY`; no argument can name a different one.
+
+On success (`201`) the response carries a `member` block (`handle`, `permissions`, `granted_by`,
+`created_at`) — and **no membership id**, by design. Authorization is the `members.manage`
+capability; a member without it is refused `403` with SpecGuard's own sentence, verbatim.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `update_repository_member_permissions`
+
+Replaces one member's permission set on a SpecGuard repository.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository the membership belongs to — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `member_id` | the id of the **membership** row to edit — not a user id, not the handle. Scoped to `repository_id`: a foreign membership id is refused `404` |
+| `permissions` | the member's **complete new** permission set (`view`, `keys.manage`, `members.manage`, `repo.delete`) — it replaces what they hold today, it is not merged |
+
+**`permissions` replaces the whole set** — name every permission the member should end with.
+Values are validated by SpecGuard; an unknown value is refused with its own sentence, verbatim.
+
+**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` with SpecGuard's own sentence,
+verbatim.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `remove_repository_member`
+
+Revokes one person's access to a SpecGuard repository by removing their membership. A `204` means
+it is revoked.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the repository the membership belongs to — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `member_id` | the id of the **membership** row to revoke — not a user id, not the handle. Scoped to `repository_id`: a foreign membership id is refused `404` |
+
+**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 — after it, the caller's
+next request to the member routes answers `404`, not `403`. The repository owner's membership
+cannot be removed at all. The same known limitation as the edit tool applies to `member_id`: no
+endpoint serves it, so it comes from the platform's web members page today. Authorization is the
+`members.manage` capability; a member without it is refused `403` with SpecGuard's own sentence,
+verbatim.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
+### `rename_repository`
+
+Renames a SpecGuard repository — changes the `org/repo` GitHub full name it is registered under —
+keeping every API key, run and intent on it.
+
+| argument | |
+| --- | --- |
+| `repository_id` | the id of the repository to rename — its numeric `id`, as `add_repository` returns and `list_repositories` reports, not the `org/repo` handle |
+| `github_full_name` | the new GitHub full name, `org/repo` — sent top-level in the body, not nested under `repository` |
+
+This is the alternative to the remove-and-re-register path: that one **deletes every API key, run
+and intent** on the repository (`remove_repository`), while this keeps all of them. **Authorization
+is owner-only** — deliberately narrower than removal: a member granted `repo.delete` may destroy
+the repository but may not rename it. The owner check also redeems a browser-issued grant valid for
+7 days; a nil or stale one is refused `403` with SpecGuard's own sentence naming the fix
+(re-grant via the browser). A name another repository already holds is refused `400` — `taken`, not
+`409` — verbatim. The `200` body is `{repository: …}` in the same shape `list_repositories` serves.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and
+`add_repository` and a different one from the `sgk_…` key `get_repository_overview` uses.
+
 ## How it works
 
 ```

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

@@ -25,6 +25,35 @@ export declare function getJson(api: ApiConfig, path: string, query: Record<stri
  * send a body whose `Content-Type` says JSON and whose bytes are not.
  */
 export declare function postJson(api: ApiConfig, path: string, body: Record<string, unknown>, fetchImpl: typeof globalThis.fetch): Promise<unknown>;
+/**
+ * `PATCH` with a JSON body — the mutating-without-replacing half of the
+ * transport, and deliberately the SAME function underneath `postJson`, for the
+ * reason that header states: everything expensive about this module is about
+ * the deadline, not the verb.
+ *
+ * Routed through `requestJson` rather than `deleteJson`'s raw-body handling,
+ * because every PATCH this surface serves answers `200` WITH a JSON body —
+ * `requestJson`'s parse is correct here, and re-deriving success handling would
+ * be a third copy of the one status check.
+ */
+export declare function patchJson(api: ApiConfig, path: string, body: Record<string, unknown>, fetchImpl: typeof globalThis.fetch): Promise<unknown>;
+/**
+ * `DELETE` — the destructive half of the transport, and deliberately the SAME
+ * function underneath `postJson` rather than beside it, for the reason
+ * `postJson`'s header states: everything expensive about this module is about
+ * the deadline, not the verb.
+ *
+ * Returns the RAW BODY TEXT rather than a parsed value, because the endpoints
+ * this serves answer `204` with NO body at all — the one response in the `sgu_`
+ * surface that is deliberately not JSON. `requestJson` JSON-parses every 2xx it
+ * sees, so routing a `204` through it would turn a successful delete into
+ * "answered 204 but the body was not JSON" — the trap this verb specifically
+ * introduces, and the reason the DELETE path has its own success handling
+ * instead of sharing `requestJson`'s. The status check and the
+ * "reached and refused" hand-off to `describeFailure` are still shared
+ * verbatim: only what happens to a SUCCESS body differs.
+ */
+export declare function deleteJson(api: ApiConfig, path: string, fetchImpl: typeof globalThis.fetch): Promise<string>;
 /**
  * `postJson`, narrowed exactly as `getJsonObject` narrows `getJson`.
  *
@@ -41,6 +70,13 @@ export declare function postJson(api: ApiConfig, path: string, body: Record<stri
  * answers with an array.
  */
 export declare function postJsonObject(api: ApiConfig, path: string, body: Record<string, unknown>, fetchImpl: typeof globalThis.fetch): Promise<Record<string, unknown>>;
+/**
+ * `patchJson`, narrowed exactly as `postJsonObject` narrows `postJson` — same
+ * guard, same sentence, same reason: `ToolResult.structured` is a
+ * `Record<string, unknown>`, so no tool should re-type the three-clause check
+ * on this verb either.
+ */
+export declare function patchJsonObject(api: ApiConfig, path: string, body: Record<string, unknown>, fetchImpl: typeof globalThis.fetch): Promise<Record<string, unknown>>;
 /**
  * `getJson`, narrowed to the object every tool here actually asks it for.
  *

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

@@ -38,6 +38,45 @@ export async function postJson(api, path, body, fetchImpl) {
         body: JSON.stringify(body),
     });
 }
+/**
+ * `PATCH` with a JSON body — the mutating-without-replacing half of the
+ * transport, and deliberately the SAME function underneath `postJson`, for the
+ * reason that header states: everything expensive about this module is about
+ * the deadline, not the verb.
+ *
+ * Routed through `requestJson` rather than `deleteJson`'s raw-body handling,
+ * because every PATCH this surface serves answers `200` WITH a JSON body —
+ * `requestJson`'s parse is correct here, and re-deriving success handling would
+ * be a third copy of the one status check.
+ */
+export async function patchJson(api, path, body, fetchImpl) {
+    return requestJson(new URL(`${api.endpoint}${path}`), api, fetchImpl, {
+        method: "PATCH",
+        body: JSON.stringify(body),
+    });
+}
+/**
+ * `DELETE` — the destructive half of the transport, and deliberately the SAME
+ * function underneath `postJson` rather than beside it, for the reason
+ * `postJson`'s header states: everything expensive about this module is about
+ * the deadline, not the verb.
+ *
+ * Returns the RAW BODY TEXT rather than a parsed value, because the endpoints
+ * this serves answer `204` with NO body at all — the one response in the `sgu_`
+ * surface that is deliberately not JSON. `requestJson` JSON-parses every 2xx it
+ * sees, so routing a `204` through it would turn a successful delete into
+ * "answered 204 but the body was not JSON" — the trap this verb specifically
+ * introduces, and the reason the DELETE path has its own success handling
+ * instead of sharing `requestJson`'s. The status check and the
+ * "reached and refused" hand-off to `describeFailure` are still shared
+ * verbatim: only what happens to a SUCCESS body differs.
+ */
+export async function deleteJson(api, path, fetchImpl) {
+    const { response, body } = await fetchWithTimeout(new URL(`${api.endpoint}${path}`), api, fetchImpl, { method: "DELETE" });
+    if (!response.ok)
+        throw describeFailure(response.status, body, api);
+    return body;
+}
 /**
  * `postJson`, narrowed exactly as `getJsonObject` narrows `getJson`.
  *
@@ -56,6 +95,15 @@ export async function postJson(api, path, body, fetchImpl) {
 export async function postJsonObject(api, path, body, fetchImpl) {
     return asJsonObject(await postJson(api, path, body, fetchImpl));
 }
+/**
+ * `patchJson`, narrowed exactly as `postJsonObject` narrows `postJson` — same
+ * guard, same sentence, same reason: `ToolResult.structured` is a
+ * `Record<string, unknown>`, so no tool should re-type the three-clause check
+ * on this verb either.
+ */
+export async function patchJsonObject(api, path, body, fetchImpl) {
+    return asJsonObject(await patchJson(api, path, body, fetchImpl));
+}
 /**
  * Everything both verbs do with a response, in one place.
  *
@@ -245,8 +293,8 @@ function describeFailure(status, body, api) {
         return new ApiError(`${api.endpoint} has no such endpoint (404). Check that ${api.endpointVariable} is the ` +
             "deployment's root URL, without a path.", status);
     }
-    if (status === 400) {
-        const message = badRequestMessage(body);
+    if (status === 400 || status === 403) {
+        const message = refusalMessage(body, status);
         if (message !== undefined)
             return new ApiError(message, status);
     }
@@ -262,6 +310,13 @@ function describeFailure(status, body, api) {
  * `origin/main` route here, so this branch serves the API surface rather than
  * one tool.
  *
+ * The 403 is the same shape under another status. `UserRepositoriesController#
+ * render_not_granted` renders `{error: "not_granted", message:, grant:}` — the
+ * `grant` block is simply ignored by the extractor, exactly as `details` is.
+ * Same defect (the generic branch truncating the one sentence that names the
+ * fix), same remedy — which is why the helper is ONE function parameterised on
+ * the status rather than two copies beside each other.
+ *
  * SURFACING IT IS THE OPPOSITE OF RESHAPING IT. The generic branch below turns
  * the most useful sentence in this direction —
  *
@@ -283,7 +338,7 @@ function describeFailure(status, body, api) {
  * whose `message` is absent or is not a string — still gets the generic
  * sentence, which at least shows the operator what actually came back.
  */
-function badRequestMessage(body) {
+function refusalMessage(body, status) {
     let parsed;
     try {
         parsed = JSON.parse(body);
@@ -296,7 +351,7 @@ function badRequestMessage(body) {
     const message = parsed["message"];
     if (typeof message !== "string" || message.trim() === "")
         return undefined;
-    return `SpecGuard refused the request (400): ${message.trim()}`;
+    return `SpecGuard refused the request (${status}): ${message.trim()}`;
 }
 export { requireApiConfig, requireUserApiConfig };
 //# sourceMappingURL=specguard-api.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"specguard-api.js","sourceRoot":"","sources":["../../../src/support/specguard-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"specguard-api.js","sourceRoot":"","sources":["../../../src/support/specguard-api.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,31 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `POST /api/v1/repositories/:repository_id/members` as a tool — shipped in the
+ * platform (`specguard/config/routes.rb`,
+ * `Api::V1::UserRepositoryMembersController#create`, SPGD-875).
+ *
+ * == The handle is the LOGIN itself
+ *
+ * `User.resolve_by_handle` refuses a profile URL and a display name with its
+ * own sentence ("Send the login itself — octocat, not a profile URL or a
+ * display name"), and each non-`:found` resolution — never-signed-in,
+ * archived, ambiguous, malformed — arrives as a distinguishable 400 sentence
+ * through the landed `refusalMessage` branch. This bridge does not re-derive
+ * that vocabulary: a client-side copy is a rule with no owner, free to drift
+ * from the one that actually decides.
+ *
+ * == The grantor is always the authenticated principal
+ *
+ * `granted_by_user` is stamped server-side from the `sgu_` credential and is
+ * deliberately absent from the permitted params. The tool therefore takes no
+ * grantor argument, and no caller can name one.
+ *
+ * == The 201 body omits the membership id, by server design
+ *
+ * `#serialize` serves `handle`, `permissions`, `granted_by`, `created_at` —
+ * and no id, because ids are not portable between repositories and serving
+ * one invites treating it as portable. See
+ * `update_repository_member_permissions` for where the id comes from today.
+ */
+declare const addRepositoryMember: ToolDefinition;
+export default addRepositoryMember;

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

@@ -0,0 +1,105 @@
+import { postJsonObject, requireUserApiConfig } from "../support/specguard-api.js";
+import { optionalStringArray, requireString } from "./args.js";
+/**
+ * `POST /api/v1/repositories/:repository_id/members` as a tool — shipped in the
+ * platform (`specguard/config/routes.rb`,
+ * `Api::V1::UserRepositoryMembersController#create`, SPGD-875).
+ *
+ * == The handle is the LOGIN itself
+ *
+ * `User.resolve_by_handle` refuses a profile URL and a display name with its
+ * own sentence ("Send the login itself — octocat, not a profile URL or a
+ * display name"), and each non-`:found` resolution — never-signed-in,
+ * archived, ambiguous, malformed — arrives as a distinguishable 400 sentence
+ * through the landed `refusalMessage` branch. This bridge does not re-derive
+ * that vocabulary: a client-side copy is a rule with no owner, free to drift
+ * from the one that actually decides.
+ *
+ * == The grantor is always the authenticated principal
+ *
+ * `granted_by_user` is stamped server-side from the `sgu_` credential and is
+ * deliberately absent from the permitted params. The tool therefore takes no
+ * grantor argument, and no caller can name one.
+ *
+ * == The 201 body omits the membership id, by server design
+ *
+ * `#serialize` serves `handle`, `permissions`, `granted_by`, `created_at` —
+ * and no id, because ids are not portable between repositories and serving
+ * one invites treating it as portable. See
+ * `update_repository_member_permissions` for where the id comes from today.
+ */
+const addRepositoryMember = {
+    name: "add_repository_member",
+    title: "Add repository member",
+    description: "Grants a person access to a SpecGuard repository by their GitHub handle, with an optional " +
+        "list of permissions. " +
+        "The `handle` is the LOGIN itself — `octocat`, not a profile URL and not a display name: " +
+        "SpecGuard refuses each of those with its own sentence, and every other resolution failure " +
+        "(nobody has signed in as that handle yet, the account is archived, the handle is ambiguous) " +
+        "arrives as a distinguishable 400 message naming the exact next move. " +
+        "The grantor recorded on the membership is always the person behind this server's user API " +
+        "key — the server stamps it, and no argument can name a different one. " +
+        "On success (201) the response carries a `member` block (`handle`, `permissions`, " +
+        "`granted_by`, `created_at`). It carries NO membership id, by design: ids are not portable " +
+        "between repositories, and editing or revoking a membership names a membership id obtained " +
+        "from the platform (today only via the web members page) — see the edit/revoke tools. " +
+        "Permissions are strings from SpecGuard's own set (`view`, `keys.manage`, `members.manage`, " +
+        "`repo.delete`); an unknown value is refused in SpecGuard's own words, and omitting the " +
+        "list grants access with no additional permissions. The repository owner cannot be added " +
+        "(they hold everything by construction). " +
+        "Authorization is the `members.manage` capability — a member without it 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 `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 grant access to — its numeric id, as `add_repository` " +
+                    "returns and `list_repositories` reports, not the `org/repo` handle.",
+            },
+            handle: {
+                type: "string",
+                description: "The GitHub login of the person to add, e.g. `octocat` — not a profile URL and not a " +
+                    "display name; SpecGuard refuses both with its own sentence. The person must have " +
+                    "signed in to SpecGuard at least once.",
+            },
+            permissions: {
+                type: "array",
+                items: { type: "string" },
+                description: "An optional list of permission strings from SpecGuard's own set (`view`, " +
+                    "`keys.manage`, `members.manage`, `repo.delete`). Omit it to grant access with no " +
+                    "additional permissions. SpecGuard validates the values and refuses an unknown one " +
+                    "in its own words.",
+            },
+        },
+        required: ["repository_id", "handle"],
+        // Closed for the reason every tool here states — and on a WRITE, a silently
+        // dropped misspelled argument still grants something, just not what the
+        // agent believed it was asking for.
+        additionalProperties: false,
+    },
+    async run(args, context) {
+        const repositoryId = requireString(args["repository_id"], "repository_id");
+        const handle = requireString(args["handle"], "handle");
+        const permissions = optionalStringArray(args["permissions"], "permissions");
+        const api = requireUserApiConfig(context.config);
+        // Top-level `{handle, permissions}` — the shape the controller permits,
+        // matching `add_repository`'s stated rule: this is JSON an agent writes,
+        // not a Rails form. `permissions` omitted when absent so the server's own
+        // default applies; passed through as an ARRAY when present (the column is
+        // `text[]`, and a scalar on the wire is silently dropped server-side).
+        const created = await postJsonObject(api, `/api/v1/repositories/${encodeURIComponent(repositoryId)}/members`, permissions === undefined ? { handle } : { handle, permissions }, context.fetch);
+        // Unreshaped, the standing rule — and the 201 body is the only answer this
+        // verb gives; nothing here exists to re-fetch elsewhere.
+        return {
+            text: JSON.stringify(created, null, 2),
+            structured: created,
+        };
+    },
+};
+export default addRepositoryMember;
+//# sourceMappingURL=add-repository-member.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"add-repository-member.js","sourceRoot":"","sources":["../../../src/tools/add-repository-member.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,mBAAmB,GAAmB;IAC1C,IAAI,EAAE,uBAAuB;IAC7B,KAAK,EAAE,uBAAuB;IAC9B,WAAW,EACT,4FAA4F;QAC5F,uBAAuB;QACvB,0FAA0F;QAC1F,4FAA4F;QAC5F,8FAA8F;QAC9F,uEAAuE;QACvE,4FAA4F;QAC5F,wEAAwE;QACxE,mFAAmF;QACnF,4FAA4F;QAC5F,4FAA4F;QAC5F,uFAAuF;QACvF,6FAA6F;QAC7F,yFAAyF;QACzF,0FAA0F;QAC1F,0CAA0C;QAC1C,2FAA2F;QAC3F,yBAAyB;QACzB,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,0EAA0E;oBAC1E,qEAAqE;aACxE;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,sFAAsF;oBACtF,mFAAmF;oBACnF,uCAAuC;aAC1C;YACD,WAAW,EAAE;gBACX,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EACT,2EAA2E;oBAC3E,mFAAmF;oBACnF,oFAAoF;oBACpF,mBAAmB;aACtB;SACF;QACD,QAAQ,EAAE,CAAC,eAAe,EAAE,QAAQ,CAAC;QACrC,4EAA4E;QAC5E,wEAAwE;QACxE,oCAAoC;QACpC,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,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;QACvD,MAAM,WAAW,GAAG,mBAAmB,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,CAAC;QAE5E,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,wEAAwE;QACxE,yEAAyE;QACzE,0EAA0E;QAC1E,0EAA0E;QAC1E,uEAAuE;QACvE,MAAM,OAAO,GAAG,MAAM,cAAc,CAClC,GAAG,EACH,wBAAwB,kBAAkB,CAAC,YAAY,CAAC,UAAU,EAClE,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAChE,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,2EAA2E;QAC3E,yDAAyD;QACzD,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,mBAAmB,CAAC"}

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

@@ -66,3 +66,29 @@ export declare function optionalString(value: unknown, field: string): string |
  */
 export declare function requireString(value: unknown, field: string): string;
 export declare function optionalBoolean(value: unknown, field: string): boolean | undefined;
+/**
+ * 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 declare function optionalStringArray(value: unknown, field: string): string[] | undefined;
+/**
+ * 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 declare function requireStringArray(value: unknown, field: string): string[];