@subseam/mcp 0.4.32 → 0.4.34

package/dist/main.js

@@ -14122,15 +14122,15 @@ async function runWalkGrep(pattern, root, signal) {
   } catch (e) {
     throw new ToolError(`grep: invalid regex: ${e instanceof Error ? e.message : String(e)}`);
   }
-  const hits = [];
+  const hits2 = [];
   let budget = GREP_OUTPUT_LIMIT;
   const push = (line) => {
     budget -= line.length + 1;
     if (budget < 0) {
-      hits.push(`[output truncated at ${GREP_OUTPUT_LIMIT} bytes]`);
+      hits2.push(`[output truncated at ${GREP_OUTPUT_LIMIT} bytes]`);
       return false;
     }
-    hits.push(line);
+    hits2.push(line);
     return true;
   };
   const stat4 = await fs4.stat(root).catch(() => null);
@@ -14141,9 +14141,9 @@ async function runWalkGrep(pattern, root, signal) {
   }
   if (signal?.aborted)
     throw new ToolError("grep: aborted");
-  if (hits.length === 0)
+  if (hits2.length === 0)
     return "no matches";
-  return hits.join("\n");
+  return hits2.join("\n");
 }
 async function grepFile(file2, re, push) {
   const stream = fssync2.createReadStream(file2, { encoding: "utf8" });
@@ -30133,21 +30133,21 @@ function mergeSources(textByRepo, concepts) {
     else arr.push(c);
   }
   const used = /* @__PURE__ */ new Set();
-  const hits = [];
+  const hits2 = [];
   for (const [repo2, matches] of textByRepo) {
     for (const m of matches) {
       const covering = smallestCovering(byFile.get(`${repo2}${SEP}${m.path}`), m.line);
       if (covering !== void 0) {
         used.add(covering);
-        hits.push({ repo: repo2, path: m.path, line: m.line, content: m.content, concept: covering, hitClass: "text+graph" });
+        hits2.push({ repo: repo2, path: m.path, line: m.line, content: m.content, concept: covering, hitClass: "text+graph" });
       } else {
-        hits.push({ repo: repo2, path: m.path, line: m.line, content: m.content, hitClass: "text-only" });
+        hits2.push({ repo: repo2, path: m.path, line: m.line, content: m.content, hitClass: "text-only" });
       }
     }
   }
   for (const c of concepts) {
     if (used.has(c)) continue;
-    hits.push({
+    hits2.push({
       repo: c.repo,
       path: c.location.path,
       line: c.location.startLine,
@@ -30156,7 +30156,7 @@ function mergeSources(textByRepo, concepts) {
       hitClass: "graph-only"
     });
   }
-  return dedupe(hits);
+  return dedupe(hits2);
 }
 function smallestCovering(concepts, line) {
   if (concepts === void 0) return void 0;
@@ -30170,9 +30170,9 @@ function smallestCovering(concepts, line) {
 function span(c) {
   return c.location.endLine - c.location.startLine;
 }
-function dedupe(hits) {
+function dedupe(hits2) {
   const byLoc = /* @__PURE__ */ new Map();
-  for (const h of hits) {
+  for (const h of hits2) {
     const key = `${h.repo}${SEP}${h.path}${SEP}${h.line}`;
     const existing = byLoc.get(key);
     if (existing === void 0 || existing.concept === void 0 && h.concept !== void 0) {
@@ -30184,8 +30184,8 @@ function dedupe(hits) {
 
 // ../explore-tool/src/rank.ts
 init_esm_shims();
-function rankHits(hits) {
-  return [...hits].sort(compare);
+function rankHits(hits2) {
+  return [...hits2].sort(compare);
 }
 function compare(a, b) {
   const ga = a.concept;
@@ -30221,8 +30221,8 @@ function historySummary(c) {
 }
 
 // ../explore-tool/src/project.ts
-function projectHits(hits, stamps) {
-  return hits.map((h) => projectOne(h, stamps.get(h.repo)));
+function projectHits(hits2, stamps) {
+  return hits2.map((h) => projectOne(h, stamps.get(h.repo)));
 }
 function projectOne(h, stamp) {
   const diverged = h.concept !== void 0 && (stamp?.modified.has(h.path) ?? false);
@@ -30340,8 +30340,8 @@ function conceptLine(hit) {
   else if (c.verdict !== null) parts.push(c.verdict);
   return `        \u21B3 ${parts.join(" \xB7 ")}`;
 }
-function stampOf(hits) {
-  return hits[0]?.stamp ?? "unknown";
+function stampOf(hits2) {
+  return hits2[0]?.stamp ?? "unknown";
 }
 function dirOf(path7) {
   const d = dirname13(path7);
@@ -30989,8 +30989,238 @@ function renderSummary(s) {
 
 // ../define/src/tool/show.ts
 init_esm_shims();
+
+// ../define/src/library/entries.ts
+init_esm_shims();
+
+// ../define/src/library/entries/one-integration-point.ts
+init_esm_shims();
+var oneIntegrationPoint = {
+  id: "one-integration-point",
+  practice: "One integration point for each external system",
+  otherNames: [
+    "gateway",
+    "adapter",
+    "ports and adapters",
+    "hexagonal architecture",
+    "API client wrapper",
+    "external API",
+    "third-party API",
+    "repository pattern",
+    "data access layer",
+    "separation of concerns"
+  ],
+  quality: { characteristic: "Maintainability", subcharacteristic: "Modularity" },
+  sources: [
+    { title: 'Martin Fowler, "Gateway" (2021)', url: "https://martinfowler.com/articles/gateway-pattern.html" }
+  ],
+  wisdom: "Code that talks to an external system (a database, a payment provider, GitHub) does it through one object that encapsulates that access, so the rest of the code depends on your interface, not on the foreign one. When the external system changes, fails or is replaced, there is one place to change, one place that knows its errors, and one place to fake in tests.",
+  split: "Three claims, because the practice makes three separate promises and each can break on its own. (1) The boundary: code that handles requests never calls the external library directly; it binds to the external library's API on one side and to the integration point's classes on the other. (2) The shape inside the boundary: each external resource (on RealWorld, each stored entity) has exactly one dedicated handler, so two handlers never drift apart on the same resource; it binds to the resource types and the handler classes. (3) The failure contract: when the external system answers with nothing or with an error, the request answers with an explicit status code instead of an unhandled error; it binds to the external API's calls that can fail. The cut falls at the promises, never at a folder: a claim about which folder may call the library breaks the day the code moves, and says nothing about the other two promises. On RealWorld the external system is the database, reached through its ORM library.",
+  claims: [
+    {
+      sentence: "Controllers, services and middleware never call the database library directly; only repositories do.",
+      concept: "the database library's API, and the repository classes",
+      intended: {
+        bindsTo: ["the MikroORM EntityManager and EntityRepository APIs", "classes that extend EntityRepository"],
+        mustFail: ["ArticleService", "ProfileService", "UserService", "TagService", "AuthMiddleware"],
+        mustPass: ["ArticleController", "UserController", "ProfileController", "TagController", "UserRepository"]
+      }
+    },
+    {
+      sentence: "Each stored entity has exactly one dedicated repository.",
+      concept: "the stored entity classes, and the repository classes",
+      intended: {
+        bindsTo: ["classes decorated as MikroORM entities", "classes that extend EntityRepository"],
+        mustFail: ["Article", "Comment", "Tag"],
+        mustPass: ["User"]
+      }
+    },
+    {
+      sentence: "Every database lookup that fails when it finds nothing states the status code the request answers with.",
+      concept: "the database library's find-or-fail lookups",
+      intended: {
+        bindsTo: ["calls to findOneOrFail"],
+        mustFail: [
+          "ArticleService.findAll",
+          "ArticleService.findOne",
+          "ArticleService.addComment",
+          "ArticleService.deleteComment",
+          "ArticleService.favorite",
+          "ArticleService.unFavorite",
+          "ArticleService.findComments",
+          "ArticleService.update",
+          "ProfileService.findOne",
+          "ProfileService.findProfile",
+          "ProfileService.follow",
+          "ProfileService.unFollow",
+          "UserService.update",
+          "UserService.findByEmail"
+        ],
+        mustPass: ["AuthMiddleware.use"]
+      }
+    }
+  ]
+};
+
+// ../define/src/library/entries/least-privilege.ts
+init_esm_shims();
+var leastPrivilege = {
+  id: "least-privilege",
+  practice: "Least privilege: every change is made only by someone allowed to make it",
+  otherNames: [
+    "principle of least privilege",
+    "access control",
+    "authorization",
+    "deny by default",
+    "broken access control",
+    "insecure direct object reference",
+    "IDOR",
+    "broken object level authorization",
+    "BOLA",
+    "ownership check",
+    "authentication required"
+  ],
+  quality: { characteristic: "Security", subcharacteristic: "Integrity" },
+  sources: [
+    {
+      title: 'Saltzer and Schroeder, "The Protection of Information in Computer Systems" (1975), design principle (f): least privilege',
+      url: "https://web.mit.edu/Saltzer/www/publications/protection/Basic.html"
+    },
+    {
+      title: "OWASP ASVS 5.0, V8 Authorization: 8.2.1 function-level and 8.2.2 data-specific access",
+      url: "https://github.com/OWASP/ASVS/blob/master/5.0/en/0x17-V8-Authorization.md"
+    }
+  ],
+  wisdom: "Every program and every user operates with the least set of privileges necessary for the job. In a web service that means two checks: an operation is reachable only by a caller allowed to use that operation at all (function level), and it acts only on records that caller is allowed to touch (data level). Missing the second is the classic insecure direct object reference: any signed-in user can change anyone's record by changing an id in the request.",
+  split: `One claim per level, and one per kind of owned record, because each is enforced in a different place and each can be missing while the others hold. (1) Function level: every request that changes stored data requires a signed-in user, with signing up as the one named exception. It binds to the request handlers that write, and to the step that establishes the signed-in user. (2) and (3) Data level, per owned record: on RealWorld, articles and comments each have an author, so each gets its own claim that only its author may change or delete it. They bind to the operations that change that record and to the record's author. The cut falls at the record type, not at the route: one claim per route would miss the next route that changes the same record, and one claim for "all records" would hide which record lost its check.`,
+  claims: [
+    {
+      sentence: "Every request that changes stored data requires a signed-in user, except signing up.",
+      concept: "the request handlers that change stored data, and the sign-in check",
+      intended: {
+        bindsTo: ["controller handlers whose calls reach a database write", "AuthMiddleware"],
+        mustFail: ["UserController.delete"],
+        mustPass: [
+          "ArticleController.create",
+          "ArticleController.update",
+          "ArticleController.delete",
+          "ArticleController.createComment",
+          "ArticleController.deleteComment",
+          "ArticleController.favorite",
+          "ArticleController.unFavorite",
+          "UserController.update",
+          "ProfileController.follow",
+          "ProfileController.unFollow",
+          "UserController.create"
+        ]
+      }
+    },
+    {
+      sentence: "Only an article's author may change or delete that article.",
+      concept: "the operations that change an article, and the article's author",
+      intended: {
+        bindsTo: ["ArticleService.update", "ArticleService.delete", "Article.author"],
+        mustFail: ["ArticleService.update", "ArticleService.delete"],
+        mustPass: [],
+        planted: [{ branch: "planted/article-author-check", mustPass: ["ArticleService.update", "ArticleService.delete"] }]
+      }
+    },
+    {
+      sentence: "Only a comment's author may delete that comment.",
+      concept: "the operation that deletes a comment, and the comment's author",
+      intended: {
+        bindsTo: ["ArticleService.deleteComment", "Comment.author"],
+        mustFail: ["ArticleService.deleteComment"],
+        mustPass: [],
+        planted: [{ branch: "planted/comment-author-check", mustPass: ["ArticleService.deleteComment"] }]
+      }
+    }
+  ]
+};
+
+// ../define/src/library/entries.ts
+var PRACTICE_ENTRIES = [oneIntegrationPoint, leastPrivilege];
+
+// ../define/src/library/search.ts
+init_esm_shims();
+var IGNORED = /* @__PURE__ */ new Set(["how", "the", "and", "for", "one", "can", "what", "does", "define", "definition", "definitions", "write", "should", "with", "that", "this", "our", "your", "code"]);
+function words(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 3 && !IGNORED.has(w));
+}
+function hits(queryWords, text) {
+  const own = words(text);
+  return queryWords.filter((q) => own.some((w) => w.startsWith(q))).length;
+}
+function searchPractices(entries, query) {
+  const q = [...new Set(words(query))];
+  const scored = entries.map((entry) => ({
+    entry,
+    score: 3 * hits(q, [entry.practice, ...entry.otherNames].join(" ")) + 2 * hits(q, `${entry.quality.characteristic} ${entry.quality.subcharacteristic}`) + hits(q, [entry.wisdom, entry.split, ...entry.claims.map((c) => c.sentence)].join(" "))
+  }));
+  const best = Math.max(0, ...scored.map((s) => s.score));
+  return scored.filter((s) => s.score > 0 && 2 * s.score >= best).sort((a, b) => b.score - a.score).map((s) => s.entry);
+}
+
+// ../define/src/library/render.ts
+init_esm_shims();
+
+// ../define/src/library/entry.ts
+init_esm_shims();
+var EXAMPLE_PROJECT = {
+  name: "RealWorld",
+  spec: "https://github.com/gothinkster/realworld",
+  repo: "mikro-orm/nestjs-realworld-example-app",
+  commit: "e723ffb798f7c7c6cad0037b0ca25d05b93db8ef"
+};
+var QUALITY_MODEL_SOURCE = {
+  title: "ISO/IEC 25010:2023 product quality model, as listed by the arc42 quality model",
+  url: "https://quality.arc42.org/standards/iso-25010"
+};
+
+// ../define/src/library/render.ts
+function recordLine(claim) {
+  const r = claim.record;
+  if (r === void 0) return "not yet run through the product";
+  if (r.kind === "failing") return `the product cannot admit or evaluate it yet (${r.issue})`;
+  return `admitted as ${r.definitionId} v${r.version}, ${r.rung}`;
+}
+function renderPractice(entry) {
+  const out2 = [
+    `## ${entry.practice}`,
+    `Also known as: ${entry.otherNames.join(", ")}.`,
+    `Quality (ISO/IEC 25010:2023): ${entry.quality.characteristic} / ${entry.quality.subcharacteristic}.`,
+    "",
+    entry.wisdom,
+    "",
+    `How to split it into definitions, shown on ${EXAMPLE_PROJECT.name} (${EXAMPLE_PROJECT.repo} at ${EXAMPLE_PROJECT.commit.slice(0, 8)}):`,
+    entry.split,
+    "",
+    "Enter each sentence on its own (`define` with `nlIntent`), rewritten for your own code's concepts:"
+  ];
+  entry.claims.forEach((claim, i) => {
+    out2.push(`${i + 1}. "${claim.sentence}"`);
+    out2.push(`   binds to: ${claim.concept}. On ${EXAMPLE_PROJECT.name}: ${recordLine(claim)}.`);
+  });
+  out2.push("", "Sources:");
+  for (const s of [...entry.sources, QUALITY_MODEL_SOURCE]) out2.push(`- ${s.title}: ${s.url}`);
+  return out2.join("\n");
+}
+function renderPracticeSearch(query, matches, all) {
+  if (matches.length === 0) {
+    return [
+      `show: no practice entry matches "${query}". The entries are:`,
+      ...all.map((e) => `- ${e.practice} (search: ${e.otherNames.slice(0, 3).join(", ")})`)
+    ].join("\n");
+  }
+  return [
+    `show: ${matches.length} practice entr${matches.length === 1 ? "y" : "ies"} for "${query}". Each states a practice as definitions on concepts (classes, methods, routes), never on files or folders, so they follow the code when it moves.`,
+    ...matches.map(renderPractice)
+  ].join("\n\n");
+}
+
+// ../define/src/tool/show.ts
 var input3 = external_exports.object({
-  definitionId: external_exports.string().min(1).optional(),
+  definitionId: external_exports.string().uuid().optional(),
   repo: external_exports.string().min(1).optional(),
   status: external_exports.enum(["active", "contested", "abandoned", "superseded"]).optional(),
   // F6d discovery (ruling 2026-08-02). Seeded/defaulted definitions are deliberately NOT pushed
@@ -30999,7 +31229,10 @@ var input3 = external_exports.object({
   // (`locationPrefix`). Dashboard-mode filters; meaningless beside `definitionId`.
   versionStatus: external_exports.enum(["defaulted", "ratified", "corrected"]).optional(),
   provenance: external_exports.enum(["authored", "mined", "witness-derived"]).optional(),
-  locationPrefix: external_exports.string().min(1).optional()
+  locationPrefix: external_exports.string().min(1).optional(),
+  // The practice library (direction/define/language.md §9.6): a search over product content, never
+  // over this tenant's definitions, so it is an arm of its own and takes no other field beside it.
+  practice: external_exports.string().min(1).optional()
 });
 var statusBody = external_exports.object({
   definitions: external_exports.array(external_exports.object({
@@ -31088,18 +31321,25 @@ var showBody = external_exports.discriminatedUnion("ok", [
 ]);
 var showTool = {
   name: "show",
-  description: "Show this tenant's definitions. With `definitionId`: ONE definition as a coherent object \u2014 every version with its status and provenance, the approval stamp, subject bindings, standing violations, live suppressions, and banked witnesses. Without: the corpus dashboard (admitted definitions, the open drift backlog, corpus size + evaluation staleness), optionally filtered by `repo`, epistemic `status`, `versionStatus` (use `defaulted` to see the un-affirmed definitions), `provenance`, or `locationPrefix` (e.g. `app/src/billing/`).",
+  description: 'Show this tenant\'s definitions. With `definitionId`: ONE definition as a coherent object \u2014 every version with its status and provenance, the approval stamp, subject bindings, standing violations, live suppressions, and banked witnesses. Without: the corpus dashboard (admitted definitions, the open drift backlog, corpus size + evaluation staleness), optionally filtered by `repo`, epistemic `status`, `versionStatus` (use `defaulted` to see the un-affirmed definitions), `provenance`, or `locationPrefix` (e.g. `app/src/billing/`). With `practice` (words, e.g. "one integration point for an external API" or "least privilege"): the practice library \u2014 how to state a coding best practice as definitions on your code\'s concepts, with the plain sentences to enter through `define`.',
   capability: "define",
   inputSchema: input3.shape,
   async handler(raw, ctx) {
     const args2 = input3.parse(raw);
+    if (args2.practice !== void 0) {
+      const { practice, ...rest } = args2;
+      if (Object.values(rest).some((v) => v !== void 0)) {
+        return { text: "show: `practice` searches the practice library and takes no other field beside it \u2014 search the library, or read this tenant's definitions, not both." };
+      }
+      return { text: renderPracticeSearch(practice, searchPractices(PRACTICE_ENTRIES, practice), PRACTICE_ENTRIES) };
+    }
     if (args2.definitionId !== void 0) {
       const raw2 = await ctx.gateway.invoke("define-show", { definitionId: args2.definitionId });
       const object2 = readBody(showBody, raw2, "show", "define-show");
       if (!object2.ok) return { text: object2.text };
       return { text: renderObject(args2.definitionId, object2.value) };
     }
-    const { definitionId: _omit, ...filters } = args2;
+    const { definitionId: _omit, practice: _practice, ...filters } = args2;
     const result = await ctx.gateway.invoke("define-status", filters);
     const status = readBody(statusBody, result, "show", "define-status");
     if (!status.ok) return { text: status.text };
@@ -48433,7 +48673,7 @@ var workReadTools = createWorkReadToolProviders({ capability: "work" });
 var bundledProviders = [src_default2, src_default, tension_default, ...defineTools, ...decisionTools, ...captureTools, ...buildTools, secureTool, ...workTools, ...workReadTools];
 
 // package.json
-var version2 = "0.4.32";
+var version2 = "0.4.34";
 
 // src/server.ts
 var SERVER_VERSION = version2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@subseam/mcp",
-  "version": "0.4.32",
+  "version": "0.4.34",
   "private": false,
   "type": "module",
   "bin": {