specguard-mcp 0.1.4 → 0.1.6

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

@@ -0,0 +1,99 @@
+import { patchJsonObject, requireUserApiConfig } from "../support/specguard-api.js";
+import { requireString } from "./args.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.
+ */
+const renameRepository = {
+    name: "rename_repository",
+    title: "Rename repository",
+    description: "Renames a SpecGuard repository — changes the `org/repo` GitHub full name it is registered " +
+        "under — WITHOUT destroying anything. This is the alternative to the remove-and-re-register " +
+        "path: that one deletes every API key, run and intent on the 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 in " +
+        "SpecGuard's own words, and that sentence names the fix (re-grant via the browser). " +
+        "A name another repository already holds is refused 400 — `taken`, not 409 — with " +
+        "SpecGuard's own sentence. The 200 body is `{repository: …}` in the same shape " +
+        "`list_repositories` serves. " +
+        "Takes `repository_id` — the numeric id `add_repository` returns and `list_repositories` " +
+        "reports, not the `org/repo` handle — and `github_full_name`, the new `org/repo` name. " +
+        "Needs SPECGUARD_USER_API_KEY (an sgu_… key), the same credential `add_repository` " +
+        "writes with and a DIFFERENT one from the sgk_… repository key `get_repository_overview` uses.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repository_id: {
+                type: "string",
+                description: "The id of the repository to rename — the numeric id `add_repository` returns and " +
+                    "`list_repositories` reports, not the `org/repo` handle. SpecGuard scopes the lookup " +
+                    "to repositories you own and answers 404 otherwise.",
+            },
+            github_full_name: {
+                type: "string",
+                description: "The repository's new GitHub full name, `org/repo` — sent TOP-LEVEL in the request " +
+                    "body, not nested under `repository`. A name another repository already holds is " +
+                    "refused 400 (`taken`).",
+            },
+        },
+        required: ["repository_id", "github_full_name"],
+        // Closed for the reason every tool here states: `server.ts` forwards
+        // `arguments` unvalidated, and a silently dropped misspelled argument on
+        // a WRITE must not be able to leave the agent believing it renamed to a
+        // name the call never carried.
+        additionalProperties: false,
+    },
+    async run(args, context) {
+        const repositoryId = requireString(args["repository_id"], "repository_id");
+        const githubFullName = requireString(args["github_full_name"], "github_full_name");
+        const api = requireUserApiConfig(context.config);
+        const updated = await patchJsonObject(api, `/api/v1/repositories/${encodeURIComponent(repositoryId)}`, { github_full_name: githubFullName }, context.fetch);
+        // Unreshaped, the standing rule — the 200 body (`{repository: serialize}` ,
+        // the `list_repositories` shape) is this verb's whole answer.
+        return {
+            text: JSON.stringify(updated, null, 2),
+            structured: updated,
+        };
+    },
+};
+export default renameRepository;
+//# sourceMappingURL=rename-repository.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rename-repository.js","sourceRoot":"","sources":["../../../src/tools/rename-repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,gBAAgB,GAAmB;IACvC,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EACT,4FAA4F;QAC5F,6FAA6F;QAC7F,2FAA2F;QAC3F,eAAe;QACf,wFAAwF;QACxF,uFAAuF;QACvF,wFAAwF;QACxF,qFAAqF;QACrF,mFAAmF;QACnF,gFAAgF;QAChF,8BAA8B;QAC9B,0FAA0F;QAC1F,wFAAwF;QACxF,oFAAoF;QACpF,+FAA+F;IACjG,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,aAAa,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,mFAAmF;oBACnF,sFAAsF;oBACtF,oDAAoD;aACvD;YACD,gBAAgB,EAAE;gBAChB,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,oFAAoF;oBACpF,kFAAkF;oBAClF,wBAAwB;aAC3B;SACF;QACD,QAAQ,EAAE,CAAC,eAAe,EAAE,kBAAkB,CAAC;QAC/C,qEAAqE;QACrE,yEAAyE;QACzE,wEAAwE;QACxE,+BAA+B;QAC/B,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,cAAc,GAAG,aAAa,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC,CAAC;QAEnF,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAG,MAAM,eAAe,CACnC,GAAG,EACH,wBAAwB,kBAAkB,CAAC,YAAY,CAAC,EAAE,EAC1D,EAAE,gBAAgB,EAAE,cAAc,EAAE,EACpC,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,4EAA4E;QAC5E,8DAA8D;QAC9D,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACtC,UAAU,EAAE,OAAO;SACpB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,gBAAgB,CAAC"}

package/dist/src/tools/update-repository-member-permissions.d.ts

@@ -0,0 +1,30 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `PATCH /api/v1/repositories/:repository_id/members/:id` as a tool — shipped
+ * in the platform (`specguard/config/routes.rb`,
+ * `Api::V1::UserRepositoryMembersController#update`, SPGD-875).
+ *
+ * == The body is `{permissions: []}` and nothing else
+ *
+ * The controller permits exactly that one key, and the ARRAY form because the
+ * column is `text[]`: a scalar permit silently drops the array server-side.
+ * This tool therefore REQUIRES a string array — a scalar or nested value is
+ * refused client-side as a shape error before anything is sent.
+ *
+ * == The id is a MEMBERSHIP id, scoped to the repository
+ *
+ * `find_membership!` looks the row up THROUGH the repository, so a membership
+ * id belonging to a different repository is a 404, never a cross-repository
+ * write. The bridge adds no client-side check of that scoping: the server is
+ * the gate.
+ *
+ * == Known limitation: no endpoint serves the id
+ *
+ * `#serialize` deliberately omits the membership id from both the list and the
+ * 201 body, so an agent that adds a member has no machine-readable way to
+ * learn the id for this call. Today the id is obtained from the platform's web
+ * members page. That gap is a platform-side follow-up, not something this
+ * bridge can work around — there is no name-based lookup.
+ */
+declare const updateRepositoryMemberPermissions: ToolDefinition;
+export default updateRepositoryMemberPermissions;

package/dist/src/tools/update-repository-member-permissions.js

@@ -0,0 +1,97 @@
+import { patchJsonObject, requireUserApiConfig } from "../support/specguard-api.js";
+import { requireString, requireStringArray } from "./args.js";
+/**
+ * `PATCH /api/v1/repositories/:repository_id/members/:id` as a tool — shipped
+ * in the platform (`specguard/config/routes.rb`,
+ * `Api::V1::UserRepositoryMembersController#update`, SPGD-875).
+ *
+ * == The body is `{permissions: []}` and nothing else
+ *
+ * The controller permits exactly that one key, and the ARRAY form because the
+ * column is `text[]`: a scalar permit silently drops the array server-side.
+ * This tool therefore REQUIRES a string array — a scalar or nested value is
+ * refused client-side as a shape error before anything is sent.
+ *
+ * == The id is a MEMBERSHIP id, scoped to the repository
+ *
+ * `find_membership!` looks the row up THROUGH the repository, so a membership
+ * id belonging to a different repository is a 404, never a cross-repository
+ * write. The bridge adds no client-side check of that scoping: the server is
+ * the gate.
+ *
+ * == Known limitation: no endpoint serves the id
+ *
+ * `#serialize` deliberately omits the membership id from both the list and the
+ * 201 body, so an agent that adds a member has no machine-readable way to
+ * learn the id for this call. Today the id is obtained from the platform's web
+ * members page. That gap is a platform-side follow-up, not something this
+ * bridge can work around — there is no name-based lookup.
+ */
+const updateRepositoryMemberPermissions = {
+    name: "update_repository_member_permissions",
+    title: "Update repository member permissions",
+    description: "Replaces one member's permission set on a SpecGuard repository. The member is named by " +
+        "`member_id` — a MEMBERSHIP id, not a user id — and the id is SCOPED to `repository_id`: " +
+        "a membership id belonging to a different repository is refused 404, never a " +
+        "cross-repository write. " +
+        "⚠️ `permissions` REPLACES the whole set — it is not merged with what the member holds " +
+        "today, so name every permission the member should end with. Values are strings from " +
+        "SpecGuard's own set (`view`, `keys.manage`, `members.manage`, `repo.delete`); an unknown " +
+        "value is refused in SpecGuard's own words. " +
+        "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. " +
+        "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 edit — 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.",
+            },
+            permissions: {
+                type: "array",
+                items: { type: "string" },
+                description: "The member's COMPLETE new permission set, replacing what they hold today — e.g. " +
+                    "[\"view\", \"keys.manage\"]. Not merged. An empty array removes every additional " +
+                    "permission while keeping the membership.",
+            },
+        },
+        required: ["repository_id", "member_id", "permissions"],
+        // Closed for the reason every tool here states — and on a WRITE that
+        // REPLACES a permission set, a silently dropped misspelled argument must
+        // not be able to leave the agent believing it granted a permission the
+        // call never carried.
+        additionalProperties: false,
+    },
+    async run(args, context) {
+        const repositoryId = requireString(args["repository_id"], "repository_id");
+        const memberId = requireString(args["member_id"], "member_id");
+        // REQUIRED, and required as an ARRAY: the server column is `text[]` and a
+        // scalar on the wire is silently dropped server-side, so the shape error is
+        // caught here — before a write — rather than persisted as a member holding
+        // nothing.
+        const permissions = requireStringArray(args["permissions"], "permissions");
+        const api = requireUserApiConfig(context.config);
+        const updated = await patchJsonObject(api, `/api/v1/repositories/${encodeURIComponent(repositoryId)}/members/${encodeURIComponent(memberId)}`, { permissions }, context.fetch);
+        // Unreshaped, the standing rule — the 200 body is this verb's whole answer.
+        return {
+            text: JSON.stringify(updated, null, 2),
+            structured: updated,
+        };
+    },
+};
+export default updateRepositoryMemberPermissions;
+//# sourceMappingURL=update-repository-member-permissions.js.map

package/dist/src/tools/update-repository-member-permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-repository-member-permissions.js","sourceRoot":"","sources":["../../../src/tools/update-repository-member-permissions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAG9D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,iCAAiC,GAAmB;IACxD,IAAI,EAAE,sCAAsC;IAC5C,KAAK,EAAE,sCAAsC;IAC7C,WAAW,EACT,yFAAyF;QACzF,0FAA0F;QAC1F,8EAA8E;QAC9E,0BAA0B;QAC1B,wFAAwF;QACxF,sFAAsF;QACtF,2FAA2F;QAC3F,6CAA6C;QAC7C,uFAAuF;QACvF,mFAAmF;QACnF,yFAAyF;QACzF,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,iFAAiF;oBACjF,qEAAqE;aACxE;YACD,SAAS,EAAE;gBACT,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,mFAAmF;oBACnF,qFAAqF;oBACrF,gEAAgE;aACnE;YACD,WAAW,EAAE;gBACX,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EACT,kFAAkF;oBAClF,mFAAmF;oBACnF,0CAA0C;aAC7C;SACF;QACD,QAAQ,EAAE,CAAC,eAAe,EAAE,WAAW,EAAE,aAAa,CAAC;QACvD,qEAAqE;QACrE,yEAAyE;QACzE,uEAAuE;QACvE,sBAAsB;QACtB,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;QAC/D,0EAA0E;QAC1E,4EAA4E;QAC5E,2EAA2E;QAC3E,WAAW;QACX,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,CAAC;QAE3E,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAG,MAAM,eAAe,CACnC,GAAG,EACH,wBAAwB,kBAAkB,CAAC,YAAY,CAAC,YAAY,kBAAkB,CAAC,QAAQ,CAAC,EAAE,EAClG,EAAE,WAAW,EAAE,EACf,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,4EAA4E;QAC5E,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,iCAAiC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specguard-mcp",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "MCP server exposing SpecGuard suite intelligence to AI coding agents",
   "license": "ISC",
   "type": "module",
@@ -28,6 +28,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.19.0",
+    "specguard-ts": "github:yatfa-ai/specguard-ts",
     "typescript": "^5.6.0"
   },
   "repository": {