specguard-mcp 0.1.2 → 0.1.3

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/support/teardown.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Kill the runs we started before going away.
+ *
+ * `run-command.ts` spawns every run `detached`, which is what lets a timeout
+ * signal the whole process tree rather than only the process we forked. The
+ * cost is that a detached child is in its own session, outside this server's
+ * controlling terminal, so a signal aimed at OUR group — an interactive Ctrl-C,
+ * a supervisor's `kill -- -PGID` — does not reach a lint run in flight. Without
+ * the handlers below such a run is not merely orphaned but UNBOUNDED: the
+ * `DEFAULT_COMMAND_TIMEOUT_MS` ceiling is a parent-side timer, so killing the
+ * parent destroys the only thing that was ever going to stop it, and a lint of a
+ * 20k-example suite goes on burning CPU with nobody waiting for its answer.
+ *
+ * == Why this is not written inline in `bin/specguard-mcp.ts`
+ *
+ * It lives here so a test can install the REAL handler. `bin/` runs `main()` on
+ * import, so a test that imported it would connect a transport rather than
+ * exercise a teardown, and the alternative — retyping the handler inside a test
+ * fixture — would assert that a COPY of the logic works while the shipped one
+ * went unread. `bin/` is left as the one place the policy is applied, which is
+ * the same split it already makes for the transport.
+ *
+ * DIAGNOSTICS GO TO STDERR, without exception. On stdio, stdout IS the JSON-RPC
+ * protocol channel: a line written there is framed as a message on the way out
+ * and corrupts the stream the client is still reading, surfacing as an
+ * unexplained disconnect rather than as the shutdown it actually was.
+ *
+ * NOTHING HERE WAITS. `killOutstandingRuns` sends SIGKILL and returns; SIGKILL
+ * cannot be refused, so there is no acknowledgement worth blocking a shutdown
+ * for. A teardown path that waits is a teardown path that can hang, which is the
+ * failure this handler exists to prevent rather than one to introduce.
+ */
+export declare function installTeardown(): void;

package/dist/src/support/teardown.js

@@ -0,0 +1,56 @@
+import { killOutstandingRuns } from "./run-command.js";
+/**
+ * Kill the runs we started before going away.
+ *
+ * `run-command.ts` spawns every run `detached`, which is what lets a timeout
+ * signal the whole process tree rather than only the process we forked. The
+ * cost is that a detached child is in its own session, outside this server's
+ * controlling terminal, so a signal aimed at OUR group — an interactive Ctrl-C,
+ * a supervisor's `kill -- -PGID` — does not reach a lint run in flight. Without
+ * the handlers below such a run is not merely orphaned but UNBOUNDED: the
+ * `DEFAULT_COMMAND_TIMEOUT_MS` ceiling is a parent-side timer, so killing the
+ * parent destroys the only thing that was ever going to stop it, and a lint of a
+ * 20k-example suite goes on burning CPU with nobody waiting for its answer.
+ *
+ * == Why this is not written inline in `bin/specguard-mcp.ts`
+ *
+ * It lives here so a test can install the REAL handler. `bin/` runs `main()` on
+ * import, so a test that imported it would connect a transport rather than
+ * exercise a teardown, and the alternative — retyping the handler inside a test
+ * fixture — would assert that a COPY of the logic works while the shipped one
+ * went unread. `bin/` is left as the one place the policy is applied, which is
+ * the same split it already makes for the transport.
+ *
+ * DIAGNOSTICS GO TO STDERR, without exception. On stdio, stdout IS the JSON-RPC
+ * protocol channel: a line written there is framed as a message on the way out
+ * and corrupts the stream the client is still reading, surfacing as an
+ * unexplained disconnect rather than as the shutdown it actually was.
+ *
+ * NOTHING HERE WAITS. `killOutstandingRuns` sends SIGKILL and returns; SIGKILL
+ * cannot be refused, so there is no acknowledgement worth blocking a shutdown
+ * for. A teardown path that waits is a teardown path that can hang, which is the
+ * failure this handler exists to prevent rather than one to introduce.
+ */
+export function installTeardown() {
+    let tearingDown = false;
+    const teardown = (signal, status) => {
+        // A second Ctrl-C while the first is still unwinding must not re-enter the
+        // drain — the registry is already empty and the pids in it already spent.
+        if (tearingDown)
+            return;
+        tearingDown = true;
+        const killed = killOutstandingRuns();
+        if (killed > 0) {
+            process.stderr.write(`specguard-mcp: ${signal} received, killed ${killed} run${killed === 1 ? "" : "s"} still in flight\n`);
+        }
+        // The conventional 128 + signo, so a supervisor reads "died on SIGINT"
+        // rather than an ordinary failure. Exiting explicitly rather than restoring
+        // the default disposition and re-signalling ourselves: we hold no other
+        // teardown obligation, and an explicit status cannot be lost to a handler
+        // installed elsewhere.
+        process.exit(status);
+    };
+    process.on("SIGINT", () => teardown("SIGINT", 130));
+    process.on("SIGTERM", () => teardown("SIGTERM", 143));
+}
+//# sourceMappingURL=teardown.js.map

package/dist/src/support/teardown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teardown.js","sourceRoot":"","sources":["../../../src/support/teardown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,WAAW,GAAG,KAAK,CAAC;IAExB,MAAM,QAAQ,GAAG,CAAC,MAA4B,EAAE,MAAc,EAAE,EAAE;QAChE,2EAA2E;QAC3E,0EAA0E;QAC1E,IAAI,WAAW;YAAE,OAAO;QACxB,WAAW,GAAG,IAAI,CAAC;QAEnB,MAAM,MAAM,GAAG,mBAAmB,EAAE,CAAC;QAErC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,kBAAkB,MAAM,qBAAqB,MAAM,OAAO,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,oBAAoB,CACtG,CAAC;QACJ,CAAC;QAED,uEAAuE;QACvE,4EAA4E;QAC5E,wEAAwE;QACxE,0EAA0E;QAC1E,uBAAuB;QACvB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;AACxD,CAAC"}

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

@@ -0,0 +1,55 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * `POST /api/v1/repositories` as a tool — shipped today in the platform
+ * (`specguard/config/routes.rb`, `Api::V1::UserRepositoriesController#create`).
+ *
+ * == The first tool here that WRITES, and what that changed
+ *
+ * Everything before this read. The registry's standing rule is that a tool in
+ * `tools/list` is a promise an agent will act on, and this endpoint has existed
+ * on the platform for some time — what was missing was on THIS side: `getJson`
+ * hardcoded `method: "GET"` and took no body. `tools/index.ts` and
+ * `list-repositories.ts` both said so, and said the transport should land with
+ * the first write tool so it could be designed against a real request body and a
+ * real 4xx surface rather than invented for a caller that did not exist. This is
+ * that tool, and `postJson`/`postJsonObject` are that transport.
+ *
+ * == The request body is top-level, because the caller is an agent
+ *
+ * `{"github_full_name": "org/repo"}`, not `{"repository": {…}}`. The controller
+ * permits it that way and says why: this is a JSON API being driven by an agent,
+ * not a Rails form being submitted by a browser, and the top-level shape is what
+ * a caller writing curl by hand will send.
+ *
+ * == The format is NOT re-validated here, deliberately
+ *
+ * `Repository` validates `org/repo` itself, and a refusal now arrives through
+ * the 400 branch in `describeFailure` in SpecGuard's own words. A second format
+ * rule on this side is exactly what "a thin client that reshapes its upstream is
+ * not thin" forbids — it would be a rule with no owner, free to drift from the
+ * one that actually decides, and its divergence would surface as this bridge
+ * refusing a name the platform would have accepted. Checking that `full_name` is
+ * a present, non-blank string is the whole of the bridge's business: that is a
+ * shape check, which is why it is `requireString` from `args.ts` and not a
+ * hand-rolled one here.
+ *
+ * == The MODAL first answer is a 400, and it is the useful one
+ *
+ * `RepositoryRegistration::GrantVerifier` fails closed on a grant that is
+ * missing or stale, which is every person who has not opened SpecGuard in a
+ * browser since this shipped — the controller records that this is "an ordinary
+ * state and not an error". The sentence that comes back names the operator's
+ * exact next move (sign in, reconnect GitHub, retry), and reaching the agent
+ * intact is what the 400 branch in `specguard-api.ts` is for.
+ *
+ * == Why the description carries a hazard paragraph
+ *
+ * `types.ts` calls the description "prompt material, not documentation … the
+ * entire basis on which a model decides whether to call the tool". This tool is
+ * NOT idempotent and its 201 carries a reveal-once token, so an agent that
+ * learns those facts by hitting them has already lost the token. They are stated
+ * where they are read BEFORE the call is committed to, rather than left to be
+ * discovered from a failure.
+ */
+declare const addRepository: ToolDefinition;
+export default addRepository;

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

@@ -0,0 +1,114 @@
+import { postJsonObject, requireUserApiConfig } from "../support/specguard-api.js";
+import { requireString } from "./args.js";
+/**
+ * `POST /api/v1/repositories` as a tool — shipped today in the platform
+ * (`specguard/config/routes.rb`, `Api::V1::UserRepositoriesController#create`).
+ *
+ * == The first tool here that WRITES, and what that changed
+ *
+ * Everything before this read. The registry's standing rule is that a tool in
+ * `tools/list` is a promise an agent will act on, and this endpoint has existed
+ * on the platform for some time — what was missing was on THIS side: `getJson`
+ * hardcoded `method: "GET"` and took no body. `tools/index.ts` and
+ * `list-repositories.ts` both said so, and said the transport should land with
+ * the first write tool so it could be designed against a real request body and a
+ * real 4xx surface rather than invented for a caller that did not exist. This is
+ * that tool, and `postJson`/`postJsonObject` are that transport.
+ *
+ * == The request body is top-level, because the caller is an agent
+ *
+ * `{"github_full_name": "org/repo"}`, not `{"repository": {…}}`. The controller
+ * permits it that way and says why: this is a JSON API being driven by an agent,
+ * not a Rails form being submitted by a browser, and the top-level shape is what
+ * a caller writing curl by hand will send.
+ *
+ * == The format is NOT re-validated here, deliberately
+ *
+ * `Repository` validates `org/repo` itself, and a refusal now arrives through
+ * the 400 branch in `describeFailure` in SpecGuard's own words. A second format
+ * rule on this side is exactly what "a thin client that reshapes its upstream is
+ * not thin" forbids — it would be a rule with no owner, free to drift from the
+ * one that actually decides, and its divergence would surface as this bridge
+ * refusing a name the platform would have accepted. Checking that `full_name` is
+ * a present, non-blank string is the whole of the bridge's business: that is a
+ * shape check, which is why it is `requireString` from `args.ts` and not a
+ * hand-rolled one here.
+ *
+ * == The MODAL first answer is a 400, and it is the useful one
+ *
+ * `RepositoryRegistration::GrantVerifier` fails closed on a grant that is
+ * missing or stale, which is every person who has not opened SpecGuard in a
+ * browser since this shipped — the controller records that this is "an ordinary
+ * state and not an error". The sentence that comes back names the operator's
+ * exact next move (sign in, reconnect GitHub, retry), and reaching the agent
+ * intact is what the 400 branch in `specguard-api.ts` is for.
+ *
+ * == Why the description carries a hazard paragraph
+ *
+ * `types.ts` calls the description "prompt material, not documentation … the
+ * entire basis on which a model decides whether to call the tool". This tool is
+ * NOT idempotent and its 201 carries a reveal-once token, so an agent that
+ * learns those facts by hitting them has already lost the token. They are stated
+ * where they are read BEFORE the call is committed to, rather than left to be
+ * discovered from a failure.
+ */
+const addRepository = {
+    name: "add_repository",
+    title: "Add repository",
+    description: "Registers a GitHub repository with SpecGuard for the person behind this server's user API " +
+        "key, and returns the repository along with its first CI API key. " +
+        "Takes `full_name` as `org/repo` — the same handle `list_repositories` reports and every other " +
+        "SpecGuard surface names a repository by. " +
+        "On success the response carries a `repository` block (`id`, `full_name`, `name`, " +
+        "`registered_at`) and an `api_key` block (`name`, `token`, `hint`, `created_at`). " +
+        "⚠️ `api_key.token` is shown THIS ONCE AND NEVER AGAIN — nothing stores it and no endpoint can " +
+        "re-serve it, so hand it to the user in your reply rather than assuming it can be fetched " +
+        "later. " +
+        "⚠️ This tool is NOT idempotent and it WRITES. If the call times out (SPECGUARD_TIMEOUT_MS) " +
+        "the registration may still have succeeded on the server, taking its one-time token with it; " +
+        "retrying then fails with `has already been taken`, which is the honest answer, and the " +
+        "recovery is SpecGuard's API-keys page in a browser. Do not retry a timeout blindly. " +
+        "Requires a CURRENT record of the caller's GitHub permissions, which only a browser session " +
+        "creates: a person who has not signed in to SpecGuard and connected GitHub recently is refused " +
+        "with a message saying exactly that, and the fix is theirs to perform in a browser — no " +
+        "argument to this tool can substitute for it. The repository must also be one the SpecGuard " +
+        "GitHub App is installed on and that this person administers. " +
+        "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: {
+            full_name: {
+                type: "string",
+                description: "The repository to register, as `org/repo` (for example `acme/billing`) — the same " +
+                    "handle `list_repositories` reports. Not a URL and not a bare repository name. " +
+                    "SpecGuard validates the format and refuses an unusable one in its own words.",
+            },
+        },
+        required: ["full_name"],
+        // Closed for the reason `list_repositories` states: `server.ts` forwards
+        // `arguments` unvalidated, so an open schema would let a misspelled argument
+        // be dropped silently and the call answered as though it had been honoured.
+        // On a WRITE that is worse than on a read — the call still registers
+        // something, just not what the agent believed it was asking for.
+        additionalProperties: false,
+    },
+    async run(args, context) {
+        // Argument shape FIRST, before the config is resolved and before anything is
+        // sent: a malformed call is the one failure the agent can fix unaided, and
+        // it must not cost a write attempt to discover.
+        const fullName = requireString(args["full_name"], "full_name");
+        const api = requireUserApiConfig(context.config);
+        const registration = await postJsonObject(api, "/api/v1/repositories", { github_full_name: fullName }, context.fetch);
+        // Passed through exactly as `list_repositories` passes its listing through.
+        // It matters more here: `api_key.token` exists nowhere else, so any reshaping
+        // on this hop is a value that cannot be recovered rather than a field that
+        // can be re-fetched.
+        return {
+            text: JSON.stringify(registration, null, 2),
+            structured: registration,
+        };
+    },
+};
+export default addRepository;
+//# sourceMappingURL=add-repository.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"add-repository.js","sourceRoot":"","sources":["../../../src/tools/add-repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,aAAa,GAAmB;IACpC,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,gBAAgB;IACvB,WAAW,EACT,4FAA4F;QAC5F,mEAAmE;QACnE,gGAAgG;QAChG,2CAA2C;QAC3C,mFAAmF;QACnF,mFAAmF;QACnF,gGAAgG;QAChG,2FAA2F;QAC3F,SAAS;QACT,6FAA6F;QAC7F,8FAA8F;QAC9F,yFAAyF;QACzF,sFAAsF;QACtF,6FAA6F;QAC7F,gGAAgG;QAChG,yFAAyF;QACzF,6FAA6F;QAC7F,+DAA+D;QAC/D,6FAA6F;QAC7F,mFAAmF;IACrF,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,SAAS,EAAE;gBACT,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,oFAAoF;oBACpF,gFAAgF;oBAChF,8EAA8E;aACjF;SACF;QACD,QAAQ,EAAE,CAAC,WAAW,CAAC;QACvB,yEAAyE;QACzE,6EAA6E;QAC7E,4EAA4E;QAC5E,qEAAqE;QACrE,iEAAiE;QACjE,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO;QACrB,6EAA6E;QAC7E,2EAA2E;QAC3E,gDAAgD;QAChD,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,YAAY,GAAG,MAAM,cAAc,CACvC,GAAG,EACH,sBAAsB,EACtB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,EAC9B,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,4EAA4E;QAC5E,8EAA8E;QAC9E,2EAA2E;QAC3E,qBAAqB;QACrB,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3C,UAAU,EAAE,YAAY;SACzB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,aAAa,CAAC"}

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

@@ -45,4 +45,24 @@
  * A non-blank string, or nothing.
  */
 export declare function optionalString(value: unknown, field: string): string | undefined;
+/**
+ * A non-blank string, and nothing else will do.
+ *
+ * The mandatory counterpart of `optionalString`, and it belongs here for the
+ * reason stated above rather than in the first tool that needs one: "is it
+ * present and a non-blank string" is a check about the SHAPE of a value, whose
+ * failure is always `ArgumentError`. Hand-rolling it inside a tool is the exact
+ * copy-paste this file was created to end — and the copy would have to re-pick
+ * the error class, which is the one thing the two `optionalString` copies got
+ * wrong.
+ *
+ * Trimmed like its optional sibling, and for the same reason: a value an agent
+ * produced by concatenating strings arrives with whitespace that is not part of
+ * what it meant to send.
+ *
+ * The two refusals are separate sentences on purpose. "You sent a number" and
+ * "you sent nothing" are different mistakes with different fixes, and a single
+ * message covering both would leave the agent to work out which it made.
+ */
+export declare function requireString(value: unknown, field: string): string;
 export declare function optionalBoolean(value: unknown, field: string): boolean | undefined;

package/dist/src/tools/args.js

@@ -56,6 +56,36 @@ export function optionalString(value, field) {
     const trimmed = value.trim();
     return trimmed === "" ? undefined : trimmed;
 }
+/**
+ * A non-blank string, and nothing else will do.
+ *
+ * The mandatory counterpart of `optionalString`, and it belongs here for the
+ * reason stated above rather than in the first tool that needs one: "is it
+ * present and a non-blank string" is a check about the SHAPE of a value, whose
+ * failure is always `ArgumentError`. Hand-rolling it inside a tool is the exact
+ * copy-paste this file was created to end — and the copy would have to re-pick
+ * the error class, which is the one thing the two `optionalString` copies got
+ * wrong.
+ *
+ * Trimmed like its optional sibling, and for the same reason: a value an agent
+ * produced by concatenating strings arrives with whitespace that is not part of
+ * what it meant to send.
+ *
+ * The two refusals are separate sentences on purpose. "You sent a number" and
+ * "you sent nothing" are different mistakes with different fixes, and a single
+ * message covering both would leave the agent to work out which it made.
+ */
+export function requireString(value, field) {
+    if (value === undefined || value === null) {
+        throw new ArgumentError(`\`${field}\` is required.`);
+    }
+    if (typeof value !== "string")
+        throw new ArgumentError(`\`${field}\` must be a string.`);
+    const trimmed = value.trim();
+    if (trimmed === "")
+        throw new ArgumentError(`\`${field}\` must not be blank.`);
+    return trimmed;
+}
 export function optionalBoolean(value, field) {
     if (value === undefined || value === null)
         return undefined;

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

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

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

@@ -41,13 +41,26 @@ import type { ToolDefinition } from "./types.js";
  * and fails on use, which is worse than not offering the tool, because the
  * agent has already committed to a plan by the time it finds out.
  *
- * The user-scoped WRITE endpoints are absent for a different reason, and it is
- * worth stating so nobody re-derives the wrong one: `POST /api/v1/repositories`
- * exists on the platform today. What this bridge does not have is a way to call
- * it — `support/specguard-api.ts` offers `getJson`, which hardcodes
- * `method: "GET"` and takes no body. That transport lands with the first write
- * tool, designed against a real request body and a real 4xx surface, rather
- * than being invented here for a tool that does not yet exist.
+ * == The fourth: the first tool that WRITES
+ *
+ *   - `add_repository` wraps `POST /api/v1/repositories` (shipped:
+ *     `specguard/config/routes.rb`, `Api::V1::UserRepositoriesController#create`).
+ *
+ * The endpoint had shipped for a while; what this bridge lacked was a way to
+ * CALL it — `support/specguard-api.ts` offered only `getJson`, which hardcoded
+ * `method: "GET"` and took no body. The reservation recorded here was that the
+ * write transport should land WITH the first write tool, designed against a real
+ * request body and a real 4xx surface rather than invented for a caller that did
+ * not exist. That is what happened: `postJson`/`postJsonObject` arrived with
+ * this entry, sharing `fetchWithTimeout` with the read path rather than standing
+ * beside it, and `describeFailure` grew the `400` branch that surfaces
+ * SpecGuard's own refusal sentence — the modal answer this endpoint gives.
+ *
+ * The standing rule is unchanged and still binding, which is what keeps the rest
+ * of the user-scoped write surface out: `DELETE /api/v1/repositories/:id` and
+ * the API-key endpoints (SPGD-754) are NOT on `origin/main`, so they may not be
+ * wrapped here however useful a tool for them would be. What moved was the
+ * platform, not the bar.
  */
 export declare const TOOLS: readonly ToolDefinition[];
 export type { ToolContext, ToolDefinition, ToolResult } from "./types.js";

package/dist/src/tools/index.js

@@ -1,3 +1,4 @@
+import addRepository from "./add-repository.js";
 import lintIntentAnnotations from "./lint-intent-annotations.js";
 import listRepositories from "./list-repositories.js";
 import getRepositoryOverview from "./repository-overview.js";
@@ -43,17 +44,31 @@ import getRepositoryOverview from "./repository-overview.js";
  * and fails on use, which is worse than not offering the tool, because the
  * agent has already committed to a plan by the time it finds out.
  *
- * The user-scoped WRITE endpoints are absent for a different reason, and it is
- * worth stating so nobody re-derives the wrong one: `POST /api/v1/repositories`
- * exists on the platform today. What this bridge does not have is a way to call
- * it — `support/specguard-api.ts` offers `getJson`, which hardcodes
- * `method: "GET"` and takes no body. That transport lands with the first write
- * tool, designed against a real request body and a real 4xx surface, rather
- * than being invented here for a tool that does not yet exist.
+ * == The fourth: the first tool that WRITES
+ *
+ *   - `add_repository` wraps `POST /api/v1/repositories` (shipped:
+ *     `specguard/config/routes.rb`, `Api::V1::UserRepositoriesController#create`).
+ *
+ * The endpoint had shipped for a while; what this bridge lacked was a way to
+ * CALL it — `support/specguard-api.ts` offered only `getJson`, which hardcoded
+ * `method: "GET"` and took no body. The reservation recorded here was that the
+ * write transport should land WITH the first write tool, designed against a real
+ * request body and a real 4xx surface rather than invented for a caller that did
+ * not exist. That is what happened: `postJson`/`postJsonObject` arrived with
+ * this entry, sharing `fetchWithTimeout` with the read path rather than standing
+ * beside it, and `describeFailure` grew the `400` branch that surfaces
+ * SpecGuard's own refusal sentence — the modal answer this endpoint gives.
+ *
+ * The standing rule is unchanged and still binding, which is what keeps the rest
+ * of the user-scoped write surface out: `DELETE /api/v1/repositories/:id` and
+ * the API-key endpoints (SPGD-754) are NOT on `origin/main`, so they may not be
+ * wrapped here however useful a tool for them would be. What moved was the
+ * platform, not the bar.
  */
 export const TOOLS = [
     lintIntentAnnotations,
     getRepositoryOverview,
     listRepositories,
+    addRepository,
 ];
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,MAAM,8BAA8B,CAAC;AACjE,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AACtD,OAAO,qBAAqB,MAAM,0BAA0B,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,CAAC,MAAM,KAAK,GAA8B;IAC9C,qBAAqB;IACrB,qBAAqB;IACrB,gBAAgB;CACjB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,qBAAqB,CAAC;AAChD,OAAO,qBAAqB,MAAM,8BAA8B,CAAC;AACjE,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AACtD,OAAO,qBAAqB,MAAM,0BAA0B,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,CAAC,MAAM,KAAK,GAA8B;IAC9C,qBAAqB;IACrB,qBAAqB;IACrB,gBAAgB;IAChB,aAAa;CACd,CAAC"}

package/dist/src/tools/list-repositories.d.ts

@@ -13,13 +13,20 @@ import type { ToolDefinition } from "./types.js";
  * answer, and it is the whole of what this tool does.
  *
  * It is also the tool that proves the second credential slot works end to end,
- * which is why it ships alone. The registry's standing rule (`tools/index.ts`)
- * is that a tool in `tools/list` is a promise an agent acts on, so the other
- * user-scoped endpoints wait for the transport they need: `POST /api/v1/repositories`
- * EXISTS on the platform today, and `getJson` hardcodes `method: "GET"` and
- * takes no body, so registering a repository is blocked on a write transport
- * rather than on a missing endpoint. That transport belongs with the first write
- * tool, where it can be designed against a real body and a real 4xx surface.
+ * which is why it shipped alone. It no longer IS alone: `add_repository`
+ * (SPGD-764) reads the same `sgu_` key and wraps `POST /api/v1/repositories`,
+ * which arrived once this bridge had a write transport to call it with —
+ * `postJson`/`postJsonObject` in `support/specguard-api.ts`, landed with that
+ * tool and designed against a real request body and a real 4xx surface, exactly
+ * as the reservation recorded here asked. The registry's standing rule
+ * (`tools/index.ts`) is unchanged and still binding: a tool in `tools/list` is a
+ * promise an agent acts on, so the REST of the user-scoped surface — removing a
+ * repository, minting or revoking keys — stays out until those endpoints ship.
+ *
+ * What this tool still uniquely answers is the question above: which
+ * repositories there ARE. `add_repository` extends that surface rather than
+ * replacing it, and the two share a handle — the `full_name` reported here is
+ * the `full_name` that one takes.
  *
  * == It reads the OTHER key, and that is the point
  *

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

@@ -13,13 +13,20 @@ import { getJsonObject, requireUserApiConfig } from "../support/specguard-api.js
  * answer, and it is the whole of what this tool does.
  *
  * It is also the tool that proves the second credential slot works end to end,
- * which is why it ships alone. The registry's standing rule (`tools/index.ts`)
- * is that a tool in `tools/list` is a promise an agent acts on, so the other
- * user-scoped endpoints wait for the transport they need: `POST /api/v1/repositories`
- * EXISTS on the platform today, and `getJson` hardcodes `method: "GET"` and
- * takes no body, so registering a repository is blocked on a write transport
- * rather than on a missing endpoint. That transport belongs with the first write
- * tool, where it can be designed against a real body and a real 4xx surface.
+ * which is why it shipped alone. It no longer IS alone: `add_repository`
+ * (SPGD-764) reads the same `sgu_` key and wraps `POST /api/v1/repositories`,
+ * which arrived once this bridge had a write transport to call it with —
+ * `postJson`/`postJsonObject` in `support/specguard-api.ts`, landed with that
+ * tool and designed against a real request body and a real 4xx surface, exactly
+ * as the reservation recorded here asked. The registry's standing rule
+ * (`tools/index.ts`) is unchanged and still binding: a tool in `tools/list` is a
+ * promise an agent acts on, so the REST of the user-scoped surface — removing a
+ * repository, minting or revoking keys — stays out until those endpoints ship.
+ *
+ * What this tool still uniquely answers is the question above: which
+ * repositories there ARE. `add_repository` extends that surface rather than
+ * replacing it, and the two share a handle — the `full_name` reported here is
+ * the `full_name` that one takes.
  *
  * == It reads the OTHER key, and that is the point
  *

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

@@ -1 +1 @@
-{"version":3,"file":"list-repositories.js","sourceRoot":"","sources":["../../../src/tools/list-repositories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,MAAM,gBAAgB,GAAmB;IACvC,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EACT,2FAA2F;QAC3F,2FAA2F;QAC3F,6DAA6D;QAC7D,6FAA6F;QAC7F,wDAAwD;QACxD,mFAAmF;QACnF,2FAA2F;QAC3F,uDAAuD;QACvD,kEAAkE;QAClE,6FAA6F;QAC7F,8FAA8F;QAC9F,wFAAwF;QACxF,4FAA4F;QAC5F,QAAQ;IACV,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,4EAA4E;QAC5E,oEAAoE;QACpE,wEAAwE;QACxE,sEAAsE;QACtE,2EAA2E;QAC3E,uEAAuE;QACvE,uCAAuC;QACvC,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO;QACtB,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,sBAAsB,EAAE,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAEpF,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACtC,UAAU,EAAE,OAAO;SACpB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"list-repositories.js","sourceRoot":"","sources":["../../../src/tools/list-repositories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,gBAAgB,GAAmB;IACvC,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EACT,2FAA2F;QAC3F,2FAA2F;QAC3F,6DAA6D;QAC7D,6FAA6F;QAC7F,wDAAwD;QACxD,mFAAmF;QACnF,2FAA2F;QAC3F,uDAAuD;QACvD,kEAAkE;QAClE,6FAA6F;QAC7F,8FAA8F;QAC9F,wFAAwF;QACxF,4FAA4F;QAC5F,QAAQ;IACV,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,4EAA4E;QAC5E,oEAAoE;QACpE,wEAAwE;QACxE,sEAAsE;QACtE,2EAA2E;QAC3E,uEAAuE;QACvE,uCAAuC;QACvC,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO;QACtB,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,sBAAsB,EAAE,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAEpF,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACtC,UAAU,EAAE,OAAO;SACpB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,gBAAgB,CAAC"}

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

@@ -449,9 +449,17 @@ const getRepositoryOverview = {
         "branch's: pass `commit_sha` to be answered about ONE named run instead — after pushing a " +
         "commit and waiting for CI, say — then read `run_anchor` to confirm which run you were served, " +
         "because an unknown sha falls back to the newest rather than erroring. " +
-        "Pass `unannotated_examples: true` to list the individual tests SpecGuard CANNOT see — the " +
+        "Pass `unannotated_examples: true` to list the individual tests carrying no `@intent` — the " +
         "examples behind the annotated ratio, which is otherwise a percentage with nothing to act on — " +
         "and, in the same answer, which AREAS of the suite carry the most of them. " +
+        "HOW MUCH OF THE SUITE SPECGUARD CAN READ IS A DIFFERENT QUESTION FROM HOW MUCH IS ANNOTATED, " +
+        "and `latest_run.intent_readings` answers it on every response with no flag to pass. A test " +
+        "written in the ordinary `Class#method behavior` shape yields an entity, an action and a " +
+        "behavior from its own description, so SpecGuard reads it even with no annotation: " +
+        "`intent_readings.derived` counts those, `authored` counts the annotated ones, and `unreadable` " +
+        "is the ONLY figure on this endpoint that means tests SpecGuard can say nothing about. Never " +
+        "read `total_specs - annotated_specs` as that population — on a suite that has never been " +
+        "annotated it is the whole suite, and almost all of it is readable. " +
         "TWO BLOCKS COME BACK ON EVERY RESPONSE — no parameter to pass, no flag to set — and they " +
         "answer what everything above silently depends on: is SpecGuard still being fed? " +
         "`delivery_health` is why the figures may be STALE: `refusing` is a comparison of stamps, not a " +
@@ -667,10 +675,22 @@ const getRepositoryOverview = {
             unannotated_examples: {
                 type: "boolean",
                 description: "Open a run's UNANNOTATED examples — the individual tests behind `latest_run`'s " +
-                    "`total_specs` MINUS `annotated_specs`, the subtraction the dashboard renders as " +
-                    "\"SpecGuard cannot see the other N tests\". Every other population this endpoint reports " +
+                    "`total_specs` MINUS `annotated_specs`. Every other population this endpoint reports " +
                     "can be walked down to the examples it counts; annotation coverage was the exception, so " +
                     "`annotated_ratio` told you how far you had to go and not one test to annotate. " +
+                    "UNANNOTATED IS NOT THE SAME AS UNREADABLE, and this block reports both. Every row here " +
+                    "lacks an `@intent`, which is exact — and most of them SpecGuard READS anyway, from the " +
+                    "test's own description. Each row carries `reading` (`\"derived\"` or `\"unreadable\"`) and " +
+                    "`derived_intent` (the `entity`/`action`/`behavior` it got, or `null`), and the block " +
+                    "carries `derived_count` and `unreadable_count` beside `recorded_count`. Only " +
+                    "`unreadable_count` is a count of tests SpecGuard can say nothing about; treat the rest " +
+                    "as annotation debt, not as blindness. THE UNREADABLE ROWS COME FIRST in the list, ahead " +
+                    "of the derived ones, so the cap cannot hide them. " +
+                    "A derived reading is WEAKER than an authored one and must never be presented as " +
+                    "equivalent: it carries no preconditions, its behavior is prose somebody wrote for a test " +
+                    "runner's output rather than a declared statement of what the test is for, and its layer " +
+                    "is inferred from the directory rather than declared — which is why `derived_intent` " +
+                    "carries no `layer` key at all. " +
                     "THIS ONE IS A FLAG, NOT A NAME — the only argument here that takes `true` rather than a " +
                     "value. The others open the rows behind a LINE of a ranking and so carry that line's key; " +
                     "this opens a POPULATION, which is a subtraction on the run and has no line to name. " +
@@ -681,8 +701,9 @@ const getRepositoryOverview = {
                     "one is additional, not instead. " +
                     "Asking populates `latest_run.unannotated_examples` — up to 100 of the unannotated " +
                     "examples OF WHATEVER YOU ASKED FOR, each with `name`, `file_path`, `line_number` and " +
-                    "`spec_file_path` (FOUR fields: no `duration_seconds` and no `outcome`, unlike the " +
-                    "per-example drill-ins above), plus that same population's own `recorded_count`, the " +
+                    "`spec_file_path`, `reading` and `derived_intent` (SIX fields: no `duration_seconds` and " +
+                    "no `outcome`, unlike the per-example drill-ins above), plus that same population's own " +
+                    "`recorded_count`, `derived_count` and `unreadable_count`, the " +
                     "`limit` the row list was cut at, and `spec_file`/`spec_directory` ECHOED BACK as the " +
                     "server READ them — `null` for each one you did not send. " +
                     "READ THE ECHO BEFORE YOU READ THE COUNT. `unannotated_examples.recorded_count` — the " +
@@ -700,13 +721,17 @@ const getRepositoryOverview = {
                     "THE DEBT IS — one run's annotation debt rolled up by code AREA, which is what you pick " +
                     "the next `spec_directory` narrowing FROM. Both come from this ONE flag: there is no " +
                     "second parameter to send and no new value. " +
-                    "The map's rows carry `path`, `unannotated_count` and the `recorded_count` that area was " +
-                    "counted against (the operands, never a fraction), plus `directory_count` — EVERY area " +
+                    "The map's rows carry `path`, `unannotated_count`, the `recorded_count` that area was " +
+                    "counted against, and the same three-way split as the worklist — `authored_count`, " +
+                    "`derived_count` and `unreadable_count`, which sum to `recorded_count` while the last two " +
+                    "sum to `unannotated_count` (the operands, never a fraction), plus `directory_count` — EVERY area " +
                     "the run touched, not every area with debt, and not `rows.size` — and its OWN `limit`, " +
                     "which is 10 and NOT the worklist's 100. Two caps under one ask, and the difference is " +
                     "the kind of list: 100 caps a WORKLIST to work through, 10 caps a RANKING to pick from. " +
                     "The orders differ for the same reason — the worklist is file-navigable, the map is " +
-                    "ranked `unannotated_count` DESC with `path` as a tiebreak only. A fully-annotated area " +
+                    "ranked `unreadable_count` DESC, then `unannotated_count` DESC, with `path` as a tiebreak " +
+                    "only — the areas SpecGuard cannot read lead, because a ten-row ranking led by debt on an " +
+                    "unannotated suite is a ranking by area SIZE and the dark corners never surface. A fully-annotated area " +
                     "is a real ROW with `unannotated_count: 0`, never an omission. Those rows sort last " +
                     "COLLECTIVELY, so on a run with more areas than the cap they are cut and never seen, " +
                     "but on a run inside the cap they ARE LISTED and listed is correct. So `rows.size` is " +