simt-dev 0.7.1 → 0.8.0

package/src/mcp/schemas.mjs

@@ -0,0 +1,512 @@
+// The MCP schemas and the two helpers every tool handler shares.
+//
+// Split out of tools.mjs, which crossed the repository ceiling carrying the tool list
+// and the shapes it answers with. The shapes are data a client validates against; the
+// handlers are the tools. A tool module imports both and defines neither.
+
+import { loadRegistry } from '../graph/load.mjs';
+import { provenanceDigest } from '../projection/project.mjs';
+import { discover } from '../compare/discover.mjs';
+import { buildRows, resolveConcurrency, summarise } from '../compare/row.mjs';
+import { GATES } from '../hooks/gates.mjs';
+import { checkRepo } from '../commands/sync.mjs';
+import { diagnose, serialisedFindings } from '../commands/doctor.mjs';
+import { rulesCatalogue, rulesWhyFacts } from '../commands/rules.mjs';
+import { skillsBriefFacts, skillsFindFacts, skillsShowFacts, skillsWhyFacts } from '../commands/skills.mjs';
+import { assembleBrief } from '../brief/assemble.mjs';
+import { DEFAULT_BRIEF_BYTES } from '../brief/packet.mjs';
+import { federationAccess, readFederation } from '../federation/config.mjs';
+import { consult } from '../federation/query.mjs';
+import { planNext, planDone } from '../plan/index.mjs';
+import { buildPrBody } from '../prbody.mjs';
+import { configPaths, readUserConfig, resolveWorkspace } from '../workspace.mjs';
+import { measureSkill } from '../graph/load.mjs';
+import { CLI } from '../name.mjs';
+
+export const GATE_KINDS = new Map(Object.entries(GATES).map(([name, g]) => [name, g.kind]));
+
+/** A schema with no required fields still needs the object declared. */
+export const noArgs = { type: 'object', properties: {}, required: [] };
+
+/**
+ * Output schemas, one per tool, describing what a SUCCESSFUL call returns.
+ *
+ * Every one of these tools is a reader: none writes, and none writes twice. The
+ * annotations say so, and the schemas say what comes back — because a client that can
+ * validate an answer against a declared shape catches a wrong answer at the boundary,
+ * while one handed a bag of JSON has to trust that the tool meant it.
+ *
+ * Properties are required unless the payload can legitimately omit them: `error` is
+ * absent when there is none, `body` is null when there is none, and a schema that
+ * required the exception would describe a shape that never occurs. `additionalProperties`
+ * is left open, which is what the 2026-07-28 revision permits and what a reader wants:
+ * these payloads are data, and a new field from a future release should not make an
+ * older client's validation fail.
+ */
+/**
+ * The shape of a failure, exported because a client validating an answer needs it and
+ * because the test that checks every tool's answer needs it for the failures. Two
+ * copies of this schema would drift, and the copy that drifted would be the one nobody
+ * validates against - which is exactly how a remedy quietly stops being a string.
+ */
+export const ERROR_SHAPE = {
+  type: 'object',
+  properties: { error: { type: 'string' }, remedy: { type: ['string', 'null'] } },
+  required: ['error'],
+};
+
+export const output = {
+  doctor: {
+    // The `doctor --json` document minus its envelope: the same findings, the
+    // same workspace answer, the same fingerprint. (Q15)
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      stack: { type: 'array', items: { type: 'string' } },
+      facts: { type: 'array', items: { type: 'string' } },
+      factEvidence: { type: 'object', additionalProperties: { type: ['string', 'null'] } },
+      signals: { type: 'array', items: { type: 'string' } },
+      // One entry per signal, naming the file that proved it. The payload is a list of
+      // paths, not of records - `fingerprint` returns evidence as the paths themselves.
+      evidence: { type: 'array', items: { type: 'string' } },
+      manifest: { type: ['object', 'null'] },
+      error: { type: ['string', 'null'] },
+      workspace: {
+        type: 'object',
+        properties: {
+          // Null is the honest value for a repository that is not inside a workspace:
+          // there is no root to name, and naming the repository as one would be a claim
+          // about the reader's directory layout that nothing established.
+          root: { type: ['string', 'null'] },
+          source: { type: ['string', 'null'] },
+          detail: { type: ['string', 'null'] },
+          error: { type: ['string', 'null'] },
+        },
+        required: ['root', 'source'],
+      },
+      shared: { type: ['object', 'null'] },
+      findings: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            severity: { type: 'string' },
+            detail: { type: 'string' },
+            remedy: { type: ['string', 'null'] },
+            why: { type: ['string', 'null'] },
+            safe: { type: 'boolean' },
+            fixed: { type: 'boolean' },
+          },
+          required: ['id', 'severity', 'detail', 'safe', 'fixed'],
+        },
+      },
+      fix: {
+        type: 'object',
+        properties: {
+          requested: { type: 'boolean' },
+          applied: { type: 'boolean' },
+          fixed: { type: 'array', items: { type: 'string' } },
+          failed: { type: 'array', items: { type: 'object' } },
+        },
+        required: ['requested', 'applied', 'fixed', 'failed'],
+      },
+      remedy: { type: ['string', 'null'] },
+    },
+    required: ['root', 'workspace', 'stack', 'facts', 'signals', 'evidence', 'findings'],
+  },
+  skills_index: {
+    type: 'object',
+    properties: {
+      skills: { type: 'number' },
+      totalBytes: { type: 'number' },
+      deferred: { type: 'array', items: { type: 'string' } },
+      workspace: { type: 'object' },
+      verified: { type: 'boolean' },
+      entries: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            summary: { type: 'string' },
+            bytes: { type: 'number' },
+            stack: { type: 'array', items: { type: 'string' } },
+            deferred: { type: 'boolean' },
+          },
+          required: ['name', 'bytes'],
+        },
+      },
+    },
+    required: ['skills', 'totalBytes', 'entries'],
+  },
+  // The `skills brief --json` document minus its envelope, or the `--all` one.
+  // The CLI keeps its field names; this adopts them. (Q15)
+  skills_brief: {
+    anyOf: [
+      {
+        type: 'object',
+        properties: {
+          repo: {
+            type: 'object',
+            properties: {
+              root: { type: 'string' },
+              stack: { type: 'array', items: { type: 'string' } },
+              facts: { type: 'array', items: { type: 'string' } },
+            },
+            required: ['root', 'stack', 'facts'],
+          },
+          workspace: { type: 'string' },
+          task: { type: ['string', 'null'] },
+          budget: { type: 'number' },
+          inlineBytes: { type: 'number' },
+          resolved: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                name: { type: 'string' },
+                bytes: { type: 'number' },
+                summary: { type: 'string' },
+                why: { type: 'array', items: { type: 'string' } },
+              },
+              required: ['name', 'bytes', 'why'],
+            },
+          },
+          deferred: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: { name: { type: 'string' }, bytes: { type: 'number' }, reason: { type: 'string' } },
+              required: ['name', 'bytes', 'reason'],
+            },
+          },
+          excluded: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: { name: { type: 'string' }, reason: { type: 'string' } },
+              required: ['name', 'reason'],
+            },
+          },
+          warning: { type: 'string' },
+        },
+        required: ['repo', 'budget', 'inlineBytes', 'resolved', 'deferred', 'excluded'],
+      },
+      {
+        type: 'object',
+        properties: {
+          all: { type: 'boolean', enum: [true] },
+          repoStack: { type: 'array', items: { type: 'string' } },
+          inline: { type: 'array', items: { type: 'string' } },
+          deferred: { type: 'array', items: { type: 'string' } },
+          warning: { type: 'string' },
+        },
+        required: ['all', 'repoStack', 'inline', 'deferred'],
+      },
+    ],
+  },
+  // The `skills show --json` document minus its envelope, plus the body text the
+  // command prints below the metadata. (Q15)
+  skills_show: {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      summary: { type: 'string' },
+      bytes: { type: 'number' },
+      capabilities: { type: 'array', items: { type: 'string' } },
+      stack: { type: 'array', items: { type: 'string' } },
+      keywords: { type: 'array', items: { type: 'string' } },
+      deferred: { type: 'boolean' },
+      requires: { type: 'array', items: { type: 'string' } },
+      variants: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: { id: { type: 'string' }, stack: { type: 'array', items: { type: 'string' } }, bytes: { type: 'number' } },
+          required: ['id'],
+        },
+      },
+      sources: { type: 'array', items: { type: 'object' } },
+      aliasOf: { type: ['string', 'null'] },
+      variantOf: { type: ['string', 'null'] },
+      workspace: { type: 'string' },
+      body: { type: ['string', 'null'] },
+      bodyFrom: { type: 'string' },
+      bodyText: { type: ['string', 'null'] },
+      reason: { type: ['string', 'null'], description: 'why there is no body, when there is none' },
+    },
+    required: ['name', 'bytes', 'body', 'bodyFrom', 'bodyText', 'reason', 'requires', 'variants'],
+  },
+  skills_find: {
+    type: 'object',
+    properties: {
+      query: { type: 'string' },
+      results: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            score: { type: 'number' },
+            summary: { type: 'string' },
+            reasons: { type: 'array', items: { type: 'string' } },
+          },
+          required: ['name', 'score', 'reasons'],
+        },
+      },
+    },
+    required: ['query', 'results'],
+  },
+  // The `skills why --json` document minus its envelope. (Q15)
+  skills_why: {
+    type: 'object',
+    properties: {
+      skill: { type: 'string' },
+      score: { type: 'number' },
+      compatible: { type: 'boolean' },
+      gate: { type: 'string' },
+      repo: {
+        type: 'object',
+        properties: {
+          root: { type: 'string' },
+          stack: { type: 'array', items: { type: 'string' } },
+          facts: { type: 'array', items: { type: 'string' } },
+          evidence: { type: 'array', items: { type: 'string' } },
+        },
+      },
+      workspace: { type: 'object' },
+      paths: { type: 'array', items: { type: 'string' } },
+      taskTokens: { type: 'array', items: { type: 'string' } },
+      signals: { type: 'array', items: { type: 'string' } },
+      variants: { type: 'array', items: { type: 'object' } },
+      aliasOf: { type: ['string', 'null'] },
+      variantOf: { type: ['string', 'null'] },
+      requires: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['skill', 'score', 'compatible', 'signals'],
+  },
+  rules_list: {
+    type: 'object',
+    properties: {
+      sha: { type: 'string' },
+      notes: { type: 'array', items: { type: 'string' } },
+      rules: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            id: { type: ['string', 'null'] },
+            title: { type: ['string', 'null'] },
+            // A profile may name one signal or several, and the frontmatter keeps both
+            // spellings. Describing only the list would make a conforming rule look
+            // broken.
+            applies: { anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }] },
+            origin: { type: 'string' },
+            source: { type: 'string' },
+            bytes: { type: 'number' },
+            adrs: { type: 'array', items: { type: 'string' } },
+            error: { type: ['string', 'null'] },
+            fallback: { type: 'boolean' },
+            selected: { type: ['boolean', 'null'] },
+          },
+          required: ['source', 'bytes', 'selected'],
+        },
+      },
+    },
+    required: ['sha', 'rules'],
+  },
+  // The `rules why --json` document minus its envelope, either direction. (Q15)
+  rules_why: {
+    type: 'object',
+    properties: {
+      direction: { type: 'string', enum: ['rule', 'decision'] },
+      id: { type: 'string' },
+      rule: { type: 'string' },
+      title: { type: ['string', 'null'] },
+      source: { type: 'string' },
+      origin: { type: 'string' },
+      adrs: { type: 'array', items: { type: 'object' } },
+      uncited: { type: 'boolean' },
+      others: { type: 'array', items: { type: 'string' } },
+      adr: { type: 'object' },
+      supersededBy: { type: ['object', 'null'] },
+      inForce: { type: 'object' },
+      rules: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['direction', 'id'],
+  },
+  check: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      ok: { type: 'boolean' },
+      findings: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            file: { type: 'string' },
+            status: { type: 'string' },
+            detail: { type: ['string', 'null'] },
+            remedy: { type: ['string', 'null'] },
+          },
+          required: ['file', 'status'],
+        },
+      },
+    },
+    required: ['root', 'ok', 'findings'],
+  },
+  compare: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      shape: { type: 'string', enum: ['repo', 'workspace'] },
+      expectedSha: { type: 'string' },
+      summary: { type: 'object' },
+      repos: { type: 'array', items: { type: 'object' } },
+      worktrees: { type: 'array', items: { type: 'object' } },
+      directories: { type: 'array', items: { type: 'string' } },
+      partial: { type: 'boolean' },
+      cursor: { type: ['string', 'null'] },
+      total: { type: 'number' },
+    },
+    required: ['root', 'shape', 'expectedSha', 'summary', 'repos'],
+  },
+  plan_next: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      next: { type: ['object', 'null'] },
+      reason: { type: ['string', 'null'] },
+    },
+    required: ['root', 'next', 'reason'],
+  },
+  plan_done: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      id: { type: 'string' },
+      doc: { type: 'string' },
+      line: { type: 'number' },
+      from: { type: 'string' },
+      to: { type: 'string' },
+      wouldChange: { type: 'boolean' },
+      dryRun: { type: 'boolean' },
+      remedy: { type: ['string', 'null'] },
+    },
+    required: ['root', 'id', 'wouldChange', 'dryRun'],
+  },
+  brief: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      kind: { type: 'string' },
+      basis: { type: 'string' },
+      task: { type: 'string' },
+      scope: { type: 'array', items: { type: 'string' } },
+      budget: { type: 'number' },
+      bytes: { type: 'number' },
+      before: { type: 'number' },
+      floorHeld: { type: 'boolean' },
+      cut: { type: 'array', items: { type: 'string' } },
+      sections: { type: 'object', additionalProperties: { type: 'array', items: { type: 'string' } } },
+      text: { type: 'string' },
+      note: { type: ['string', 'null'] },
+    },
+    required: ['root', 'kind', 'basis', 'task', 'scope', 'budget', 'bytes', 'before', 'floorHeld', 'cut', 'sections', 'text'],
+  },
+  pr_body: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      base: { type: ['string', 'null'] },
+      tree: { type: ['string', 'null'] },
+      verdict: { type: 'string' },
+      unreviewed: { type: 'array', items: { type: 'string' } },
+      paths: { type: 'array', items: { type: 'string' } },
+      decisions: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            id: { type: 'string' },
+            title: { type: 'string' },
+            status: { type: 'string' },
+          },
+          required: ['path', 'id', 'title', 'status'],
+        },
+      },
+      gates: {
+        type: 'object',
+        properties: {
+          declared: { type: 'array', items: { type: 'string' } },
+          evidenceMode: { type: ['string', 'null'] },
+          run: { type: ['object', 'null'] },
+          rulesOk: { type: ['boolean', 'null'] },
+          hooksOk: { type: ['boolean', 'null'] },
+          blocking: { type: 'number' },
+          warnings: { type: 'number' },
+          cached: { type: 'boolean' },
+        },
+        required: ['declared', 'blocking', 'warnings', 'cached'],
+      },
+      evidence: {
+        type: 'object',
+        properties: {
+          entries: { type: 'array', items: { type: 'object' } },
+          errors: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['entries', 'errors'],
+      },
+    },
+    required: ['root', 'base', 'tree', 'verdict', 'unreviewed', 'decisions', 'gates', 'evidence', 'paths'],
+  },
+  federation_query: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      query: { type: 'string' },
+      servers: { type: 'array', items: { type: 'string' } },
+      answers: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            server: { type: 'string' },
+            tool: { type: 'string' },
+            query: { type: 'string' },
+            text: { type: 'string' },
+          },
+          required: ['server', 'tool', 'query', 'text'],
+        },
+      },
+      findings: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['root', 'query', 'servers', 'answers', 'findings'],
+  },
+  /** The shape of every tool failure, which is a result and not a protocol error. */
+  error: ERROR_SHAPE,
+};
+
+export const rootArg = {
+  type: 'object',
+  properties: { root: { type: 'string', description: 'repository root; defaults to the editor cwd' } },
+  required: [],
+};
+
+
+export function rootOf(args) {
+  return typeof args?.root === 'string' && args.root.length > 0 ? args.root : process.cwd();
+}
+
+export async function registry(args) {
+  const { registry, errors, ok, verified, workspace } = await loadRegistry(null, args ?? {});
+  if (!ok) {
+    throw Object.assign(new Error(errors[0]), {
+      remedy: `run: ${CLI} graph lint`,
+    });
+  }
+  return { registry, verified, workspace };
+}

package/src/mcp/server.mjs

@@ -24,6 +24,7 @@ import { createInterface } from 'node:readline';
 import { CLI } from '../name.mjs';
 import { getPrompt, PROMPTS } from './prompts.mjs';
 import { RESOURCE_TEMPLATES, listResources, readResource } from './resources.mjs';
+import { paginate } from './paginate.mjs';
 import { check } from './schema.mjs';
 
 /**
@@ -207,11 +208,15 @@ export async function handle(request, tools, { packageVersion, state, root, sign
       }
       return reply({});
 
-    case 'tools/list':
+    case 'tools/list': {
+      const page = paginate(tools, params?.cursor);
+      if (page === null) return badCursor(id);
       return reply({
-        tools: tools.map((t) => describe(t, v)),
+        tools: page.items.map((t) => describe(t, v)),
+        ...nextPage(page),
         ...(cacheable(v) ? LIST_CACHE : {}),
       });
+    }
 
     case 'tools/call': {
       const name = params?.name;
@@ -265,16 +270,22 @@ export async function handle(request, tools, { packageVersion, state, root, sign
       }
     }
 
-    case 'resources/list':
+    case 'resources/list': {
+      const page = paginate(await listResources(root), params?.cursor);
+      if (page === null) return badCursor(id);
       return reply(
-        cacheable(v) ? { resources: await listResources(root), ...LIST_CACHE } : { resources: await listResources(root) },
+        cacheable(v) ? { resources: page.items, ...nextPage(page), ...LIST_CACHE } : { resources: page.items, ...nextPage(page) },
       );
-    case 'resources/templates/list':
+    }
+    case 'resources/templates/list': {
+      const page = paginate(RESOURCE_TEMPLATES, params?.cursor);
+      if (page === null) return badCursor(id);
       return reply(
         cacheable(v)
-          ? { resourceTemplates: RESOURCE_TEMPLATES, ...LIST_CACHE }
-          : { resourceTemplates: RESOURCE_TEMPLATES },
+          ? { resourceTemplates: page.items, ...nextPage(page), ...LIST_CACHE }
+          : { resourceTemplates: page.items, ...nextPage(page) },
       );
+    }
     case 'resources/read': {
       // The code for a resource that is not there CHANGED, and a server that answers
       // with one code to both revisions is a server that is wrong to whichever half of
@@ -288,10 +299,13 @@ export async function handle(request, tools, { packageVersion, state, root, sign
         cacheable(v) ? { contents: [found], ...LIST_CACHE } : { contents: [found] },
       );
     }
-    case 'prompts/list':
+    case 'prompts/list': {
+      const page = paginate(PROMPTS, params?.cursor);
+      if (page === null) return badCursor(id);
       return reply(
-        cacheable(v) ? { prompts: PROMPTS, ...LIST_CACHE } : { prompts: PROMPTS },
+        cacheable(v) ? { prompts: page.items, ...nextPage(page), ...LIST_CACHE } : { prompts: page.items, ...nextPage(page) },
       );
+    }
     case 'prompts/get': {
       const name = params?.name;
       // `getPrompt` returns null only for a prompt this server does not have: its
@@ -304,6 +318,16 @@ export async function handle(request, tools, { packageVersion, state, root, sign
       if (found === null) return error(id, RPC.METHOD, `no prompt named "${String(name)}"; call prompts/list first`);
       return reply(found);
     }
+    case 'resources/subscribe':
+    case 'resources/unsubscribe':
+      // A named refusal, not `unknown method`. The capability block above says `resources:
+      // {}` - no subscriptions - so a well-behaved client never asks; one that asks anyway
+      // is asking a protocol question and deserves the reason rather than a message that
+      // reads as a typo and sends it hunting for a spelling.
+      return isNotification
+        ? null
+        : error(id, RPC.METHOD, `${method} is not supported: this server has no change source; resources/list is always current`);
+
     default:
       return isNotification ? null : error(id, RPC.METHOD, `unknown method "${method}"`);
   }
@@ -383,6 +407,22 @@ function decorate(value, version, { packageVersion }) {
   };
 }
 
+/** The cursor field, present only when there is a next page. */
+function nextPage(page) {
+  return page.nextCursor === null ? {} : { nextCursor: page.nextCursor };
+}
+
+/**
+ * A cursor this server did not issue.
+ *
+ * A protocol error, not an empty page: an empty page reads as "the list ended", which is
+ * a different fact from "your cursor is stale" and leads the client to show a partial
+ * estate as a complete one.
+ */
+function badCursor(id) {
+  return error(id, RPC.INVALID_PARAMS, 'invalid cursor: omit it to start at the first page');
+}
+
 function describe(tool, version) {
   const entry = {
     name: tool.name,