pipebrain-mcp 0.37.3 → 0.38.0

package/dist/main.js

@@ -15211,6 +15211,24 @@ function parseDeliverableDisplayId(value) {
 }
 
 // ../../libs/domain/dist/project-scope.js
+var SOURCE_TREE_DIRECTORIES = /* @__PURE__ */ new Set([
+  "apps",
+  "components",
+  "db",
+  "dist",
+  "docs",
+  "e2e",
+  "lib",
+  "libs",
+  "migrations",
+  "modules",
+  "node_modules",
+  "packages",
+  "plugins",
+  "routes",
+  "scripts",
+  "src"
+]);
 var CODE_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
   "cjs",
   "css",
@@ -15239,6 +15257,83 @@ var SOURCE_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
   ...CODE_FILE_EXTENSIONS,
   ...DOCUMENT_FILE_EXTENSIONS
 ]);
+var PATH_RE = /(?:\.{0,2}[/\\])?[\w.-]+(?:[/\\][\w.-]*[\w-][\w.-]*)+/g;
+var SEPARATOR_RE = /[/\\]/;
+var ROOTED_RE = /^\.{0,2}[/\\]/;
+function trimTrailingPunctuation(value) {
+  return value.replace(/[.,;:!?)\]]+$/, "");
+}
+function namesAFile(candidate, extensions) {
+  const segments = candidate.split(SEPARATOR_RE);
+  const last = segments[segments.length - 1];
+  const dot = last.lastIndexOf(".");
+  return dot > 0 && extensions.has(last.slice(dot + 1).toLowerCase());
+}
+function namesASourceFile(candidate) {
+  return namesAFile(candidate, SOURCE_FILE_EXTENSIONS);
+}
+function isRepositoryPath(candidate) {
+  if (ROOTED_RE.test(candidate))
+    return true;
+  if (candidate.split(SEPARATOR_RE).some((segment) => SOURCE_TREE_DIRECTORIES.has(segment.toLowerCase()))) {
+    return true;
+  }
+  return namesASourceFile(candidate);
+}
+function findPath(source, accepts) {
+  for (const raw of source.match(PATH_RE) ?? []) {
+    const candidate = trimTrailingPunctuation(raw);
+    if (accepts(candidate))
+      return candidate;
+  }
+  return null;
+}
+function findRepositoryPath(source) {
+  return findPath(source, isRepositoryPath);
+}
+
+// ../../libs/domain/dist/code-shape.js
+var LINK_RE = /\w+:\/\/\S+/g;
+var BARE_URL_RE = /\b[\w-]+(?:\.[\w-]+)*\.[A-Za-z]{2,}\/\S*/g;
+var LINE_SUFFIX_RE = /(?:\.{0,2}[/\\])?[\w.-]+(?:[/\\][\w.-]+)*:\d+/g;
+var LINE_IN_WORDS_RE = /\b(?:at|on|see|near|around|from)\s+lines?\s+\d+\b/i;
+var BACKTICKED_RE = /`[^`]+`/;
+var CALL_RE = /\b[A-Za-z_$][\w$]*[A-Z][\w$]*\(\)/;
+function findLineSuffix(source) {
+  for (const candidate of source.match(LINE_SUFFIX_RE) ?? []) {
+    const token = candidate.slice(0, candidate.lastIndexOf(":"));
+    if (isRepositoryPath(token))
+      return candidate;
+  }
+  return null;
+}
+function findCodeShape(text) {
+  const prose = text.replace(LINK_RE, " ").replace(BARE_URL_RE, " ");
+  const path = findRepositoryPath(prose);
+  if (path !== null)
+    return { kind: "repository_path", match: path };
+  const suffixed = findLineSuffix(prose);
+  if (suffixed !== null)
+    return { kind: "line_number", match: suffixed };
+  const spelled = LINE_IN_WORDS_RE.exec(prose);
+  if (spelled !== null)
+    return { kind: "line_number", match: spelled[0] };
+  const backticked = BACKTICKED_RE.exec(prose);
+  if (backticked !== null)
+    return { kind: "symbol_name", match: backticked[0] };
+  const called = CALL_RE.exec(prose);
+  if (called !== null)
+    return { kind: "symbol_name", match: called[0] };
+  return null;
+}
+var CODE_SHAPE_NAMES = {
+  repository_path: "repository path",
+  line_number: "line number",
+  symbol_name: "symbol name"
+};
+function codeShapeMessage(field, hit) {
+  return `${field} is read by someone without the code open \u2014 take out the ${CODE_SHAPE_NAMES[hit.kind]} \u201C${hit.match}\u201D and say it in plain words`;
+}
 
 // ../../libs/domain/dist/entities.js
 var organizationSchema = external_exports.object({
@@ -15360,6 +15455,22 @@ var issueSchema = external_exports.object({
   milestone: external_exports.string().nullable(),
   title: external_exports.string().min(1),
   body: markdownSchema,
+  // The header (PIPE-373): what this work is, why it matters, and what it touches —
+  // three fields written by `set_issue_header`, never by the authoring tools, and
+  // carried on every surface that renders a display id.
+  //
+  // OPTIONAL RATHER THAN NULLABLE-REQUIRED, because a header is absent far more often
+  // than it is empty: the columns arrived on a table already full of rows, and the wire
+  // mappers drop an undefined field rather than sending an explicit null.
+  summary: external_exports.string().nullable().optional(),
+  why: external_exports.string().nullable().optional(),
+  affectedSurfaces: external_exports.string().nullable().optional(),
+  // DERIVED ON READ, never stored: true when the header was written from a body that
+  // has since changed, and true as well when there is no header at all — one comparison
+  // covers both, so "absent" and "drifted" cannot answer differently. The provenance
+  // hash it is derived from (`header_body_sha`) is internal and never reaches the wire.
+  headerStale: external_exports.boolean().optional(),
+  headerDerivedAt: external_exports.iso.datetime({ offset: true }).nullable().optional(),
   parentId: uuidSchema.nullable(),
   claimedBy: uuidSchema.nullable(),
   source: sourceSchema,
@@ -15376,6 +15487,7 @@ var criterionFiledBugSchema = external_exports.object({
   projectKey: projectKeySchema,
   displayId: external_exports.string().min(1),
   title: external_exports.string().min(1),
+  summary: external_exports.string().nullable().optional(),
   status: issueStatusSchema
 });
 var criterionSchema = external_exports.object({
@@ -15809,7 +15921,19 @@ var criterionInputSchema = external_exports.strictObject({
   message: "`howTo` applies to manual criteria only \u2014 an auto criterion is checked by a machine, so instructions on one have no reader",
   path: ["howTo"]
 });
+var refusedIssueHeaderFields = {
+  summary: external_exports.never({
+    error: "summary cannot be set here \u2014 create or update the issue first, then write its header with set_issue_header"
+  }).optional().describe("Not writable here. The header summary is written by `set_issue_header`."),
+  why: external_exports.never({
+    error: "why cannot be set here \u2014 create or update the issue first, then write its header with set_issue_header"
+  }).optional().describe("Not writable here. The header reason is written by `set_issue_header`."),
+  affectedSurfaces: external_exports.never({
+    error: "affected surfaces cannot be set here \u2014 create or update the issue first, then write its header with set_issue_header"
+  }).optional().describe("Not writable here. The affected surfaces are written by `set_issue_header`.")
+};
 var createIssueInputSchema = external_exports.strictObject({
+  ...refusedIssueHeaderFields,
   project: projectRefSchema,
   type: issueTypeSchema,
   title: external_exports.string().min(1, { message: "issue title must not be empty" }),
@@ -15835,6 +15959,9 @@ var createIssueInputSchema = external_exports.strictObject({
   criterionId: uuidSchema.optional()
 });
 var promoteFeedbackInputSchema = external_exports.strictObject({
+  // Declared here as well as on create/update: this is a standalone strict object that
+  // does NOT spread create's shape, and it funnels into `createIssue` (PIPE-373 AC-1).
+  ...refusedIssueHeaderFields,
   type: external_exports.enum(["epic", "task"]),
   title: external_exports.string().min(1, { message: "issue title must not be empty" }),
   status: issueStatusSchema.optional(),
@@ -15858,6 +15985,7 @@ var decisionLinkChangesSchema = external_exports.strictObject({
   remove: external_exports.array(decisionRefSchema).optional()
 });
 var updateIssueInputSchema = external_exports.strictObject({
+  ...refusedIssueHeaderFields,
   issue: issueRefSchema,
   title: external_exports.string().min(1, { message: "issue title must not be empty" }).optional(),
   body: markdownSchema.optional(),
@@ -15870,6 +15998,23 @@ var updateIssueInputSchema = external_exports.strictObject({
   deliverableLinks: deliverableLinkChangesSchema.optional(),
   decisionLinks: decisionLinkChangesSchema.optional()
 });
+var ISSUE_SUMMARY_MAX = 350;
+function inPlainWords(schema, field) {
+  return schema.refine((value) => findCodeShape(value) === null, {
+    error: (iss) => {
+      const hit = findCodeShape(String(iss.input));
+      return hit === null ? `${field} must be written in plain words` : codeShapeMessage(field, hit);
+    }
+  });
+}
+var setIssueHeaderInputSchema = external_exports.strictObject({
+  issue: issueRefSchema,
+  summary: inPlainWords(external_exports.string().min(1, { message: "summary must not be empty" }).max(ISSUE_SUMMARY_MAX, {
+    error: (iss) => `summary must be at most ${ISSUE_SUMMARY_MAX} characters \u2014 received ${String(iss.input).length}`
+  }), "summary"),
+  why: inPlainWords(external_exports.string().min(1, { message: "why must not be empty \u2014 say why this matters" }), "why"),
+  affectedSurfaces: inPlainWords(external_exports.string().min(1, { message: "affected surfaces must not be empty" }), "affected surfaces")
+});
 var setStatusInputSchema = external_exports.strictObject({
   issue: issueRefSchema,
   status: issueStatusSchema
@@ -16064,6 +16209,12 @@ var listIssuesFilterSchema = external_exports.strictObject({
   // query string and lets anything else fail HERE, out loud, because a filter the
   // server quietly dropped returns everything and reads like one that matched.
   blocked: external_exports.boolean().optional(),
+  // Header-less or drifted work (PIPE-373 AC-9): `true` is everything whose header is
+  // missing or no longer describes the body it was written from, which is the list
+  // somebody sits down to write headers from. Omitted means both. A real boolean for
+  // the same reason `blocked` is one — a filter the server quietly dropped returns
+  // everything and reads exactly like one that matched everything.
+  needsHeader: external_exports.boolean().optional(),
   // Pagination — server default 200, max 500 (§9); default applied server-side.
   limit: external_exports.number().int().min(1, { message: "limit must be at least 1" }).max(500, { message: "limit must be at most 500" }).optional(),
   offset: external_exports.number().int().nonnegative().optional()
@@ -16549,6 +16700,22 @@ var ApiClient = class _ApiClient {
   addComment(ref, body) {
     return this.request("POST", `/api/v1/issues/${enc(ref)}/comments`, { body: { body } });
   }
+  /**
+   * Writes the structured header onto an issue that already exists (PIPE-373).
+   *
+   * WHOLE VALUE, all three fields required — a stale header is replaced outright,
+   * so there is nothing to merge and nothing to pin. The server stamps a hash of
+   * the body the three texts were derived from at the same time, which is what
+   * later reads compare against to say whether the header still describes the
+   * issue; a partial write would leave that hash vouching for words nobody
+   * rewrote.
+   *
+   * `issue` is dropped from the body because the ref rides the path, the way it
+   * does on every other whole-value write here.
+   */
+  setIssueHeader(ref, input) {
+    return this.request("PUT", `/api/v1/issues/${enc(ref)}/header`, { body: input });
+  }
   /** Records the issue as blocked with a required reason (PIPE-99). */
   setBlocked(ref, reason) {
     return this.request("PUT", `/api/v1/issues/${enc(ref)}/blocked`, {
@@ -17517,7 +17684,7 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
   server2.registerTool(
     "list_issues",
     {
-      description: `List issue summaries (display id, title, type, status, terminal, blocked, priority, milestone, claimer, criteria progress, updated_at) filtered by project, environment, status[], type[], claimedBy (me/unclaimed/uuid), priority[], milestone, text (title+body), parent, and blocked (\xA77). DEFAULT: with no status filter this returns BUILDABLE work only \u2014 ${OPEN_STATUSES.join(", ")}. Terminal work (done, killed) is excluded unless you ask for it by name: pass status explicitly, e.g. status: ["done","killed"] for finished and abandoned work, or list every value to see everything. An explicit status filter is used verbatim and the default is not merged into it. Every row also carries \`terminal\` (PIPE-R15 r4 rule 5). blocked: false returns only work with nothing blocking it, and every issue it returns can be moved to ready without refusal; blocked: true returns only blocked work.`,
+      description: `List issue summaries (display id, title, type, status, terminal, blocked, priority, milestone, claimer, criteria progress, updated_at, and the header \u2014 \`summary\`, \`why\`, \`affectedSurfaces\`, \`headerStale\`, \`headerDerivedAt\` \u2014 so a list says what each issue is about without opening it) filtered by project, environment, status[], type[], claimedBy (me/unclaimed/uuid), priority[], milestone, text (title+body), parent, blocked, and needsHeader (\xA77). DEFAULT: with no status filter this returns BUILDABLE work only \u2014 ${OPEN_STATUSES.join(", ")}. Terminal work (done, killed) is excluded unless you ask for it by name: pass status explicitly, e.g. status: ["done","killed"] for finished and abandoned work, or list every value to see everything. An explicit status filter is used verbatim and the default is not merged into it. Every row also carries \`terminal\` (PIPE-R15 r4 rule 5). blocked: false returns only work with nothing blocking it, and every issue it returns can be moved to ready without refusal; blocked: true returns only blocked work. needsHeader: true returns exactly the issues whose header is missing or no longer describes the body it was derived from \u2014 the set \`set_issue_header\` still has to be called on \u2014 and needsHeader: false returns only those whose header still holds. Each row\u2019s \`headerStale\` is the same expression this filter selects on, so a row cannot disagree with the filter that returned it. The status default above is not lifted for it: name done and killed explicitly when the sweep is meant to reach finished work as well.`,
       inputSchema: listIssuesFilterSchema.shape
     },
     // The default lives HERE, not in the API. PIPE-R15 r4 rule 5 makes the default
@@ -17531,7 +17698,7 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
     (args) => run(() => client2.listIssues(args.status === void 0 ? { ...args, status: [...OPEN_STATUSES] } : args), GUIDANCE_POINTER)
   );
   server2.registerTool("get_issue", {
-    description: "Full issue detail by display id or uuid: body, criteria (states, modes, evidence), explicit requirement links (pinned revision + staleness), the project\u2019s cross-cutting requirements at their latest approved revision, this organization\u2019s approved conventions \u2014 standing guidance that BINDS work in every project here, delivered in full at the revision a person approved \u2014 children, and comments (\xA77). Carries `terminal`: true when the issue is finished (`done`) or deliberately abandoned (`killed`) and is therefore NOT buildable work \u2014 check it before acting on an issue you were handed by key. Reading criterion state: `state_evidence` is required only when a TOKEN sets one, so a `manual` criterion \u2014 settable only from a web session \u2014 carries none by design, and the attribution the server already stores (who set it, and when) IS its record. What this payload tells you about ANOTHER issue goes stale. Reference that issue by key and say what you need from it; never restate its status, its criteria, or whether those criteria passed \u2014 such a sentence is true when written and wrong later, and a terminal issue is never revisited to correct it, so the stale reading is what the next reader inherits.",
+    description: "Full issue detail by display id or uuid: the header \u2014 `summary`, `why`, `affectedSurfaces`, with `headerDerivedAt` and `headerStale`, true when nobody has written a header or the body has moved since one was written, and `set_issue_header` is what writes it \u2014 body, criteria (states, modes, evidence), explicit requirement links (pinned revision + staleness), the project\u2019s cross-cutting requirements at their latest approved revision, this organization\u2019s approved conventions \u2014 standing guidance that BINDS work in every project here, delivered in full at the revision a person approved \u2014 children, and comments (\xA77). Carries `terminal`: true when the issue is finished (`done`) or deliberately abandoned (`killed`) and is therefore NOT buildable work \u2014 check it before acting on an issue you were handed by key. Reading criterion state: `state_evidence` is required only when a TOKEN sets one, so a `manual` criterion \u2014 settable only from a web session \u2014 carries none by design, and the attribution the server already stores (who set it, and when) IS its record. What this payload tells you about ANOTHER issue goes stale. Reference that issue by key and say what you need from it; never restate its status, its criteria, or whether those criteria passed \u2014 such a sentence is true when written and wrong later, and a terminal issue is never revisited to correct it, so the stale reading is what the next reader inherits.",
     inputSchema: { issue: issueRefSchema }
   }, (args) => run(() => client2.getIssue(args.issue), GUIDANCE_POINTER));
   server2.registerTool("create_issue", {
@@ -17557,6 +17724,10 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
     description: "Update any subset of an issue\u2019s title, body, type, priority, milestone, environment, parent (self/cycle rejected), requirement_links (add/remove; adding a link to an unapproved requirement is rejected), deliverable_links (add/remove content-deliverable links, add pins at the current revision), or decision_links (add/remove decision records this work sits under \u2014 `KEY-D{n}`, from `list_decisions`). Changing type to `feedback` is rejected while the issue has criteria (\xA77), since feedback carries none; epic, task and bug interchange freely and the criteria ride along, keeping their AC-{n} numbers and their states. Clearing `milestone` (passing null) is rejected while the issue sits past `triage` \u2014 work already scheduled keeps a milestone (PIPE-R10 rule 9); swap it for a different one, or move the issue back to `triage` first. Writing guidance for this tool lives in the product doctrine, which `get_work_context` returns \u2014 see \u201CLink by key; never paste another record\u2019s text\u201D and \u201CA decision you need is filed as a question, never written into a body\u201D.",
     inputSchema: updateIssueInputSchema.shape
   }, ({ issue: issue2, ...fields }) => run(() => client2.updateIssue(issue2, fields)));
+  server2.registerTool("set_issue_header", {
+    description: "Write an issue\u2019s HEADER \u2014 the three lines an operator reads before deciding anything: `summary` (the change, in one sentence), `why` (the user, business, cost or operational reason rather than the technical one; when nothing is user-visible, the cost of leaving it alone) and `affectedSurfaces` (which parts of the product this touches, and who feels it). All three are REQUIRED and the write is whole-value: the header is replaced entire and never merged, so a partial write cannot leave the stored provenance vouching for lines it did not touch. Returns the full issue detail. WRITE ALL THREE IN PLAIN WORDS: no identifiers, no file paths, no type names, no jargon. Their reader is deciding, not building, and the depth belongs in the body underneath them. A `summary` shaped like code \u2014 a repository path, a line number, a symbol written as a call or in backticks \u2014 is refused (400) naming what was found. `summary` is capped at 350 characters; over it the write is refused naming both the cap and the length received. THE HEADER CAN BE WRITTEN NO OTHER WAY: `summary`, `why` or `affectedSurfaces` passed to `create_issue`, `update_issue` or `promote_feedback` is refused (400) naming the field, rather than silently dropped \u2014 create the issue first, then write its header here. Every read of the issue carries `headerStale`, true when the body has changed since these three lines were derived from it and true when no header was ever written; writing here clears it. Writing guidance for these three lines is stated above; the organization\u2019s own writing rules, which `get_work_context` returns, govern the body beneath them.",
+    inputSchema: setIssueHeaderInputSchema.shape
+  }, ({ issue: issue2, ...fields }) => run(() => client2.setIssueHeader(issue2, fields)));
   server2.registerTool("set_status", {
     description: "Set an issue\u2019s status; the \xA76 guards apply and a guard failure returns the specific reason, naming the rows it refused on (\xA77). The criteria gates read whatever criteria the issue carries, whatever its type: verify needs every auto criterion passed, done needs every criterion passed. ONE guard remains EPIC-ONLY, and the asymmetry is the rule rather than an oversight \u2014 an epic that has stated NO criteria is refused at both gates, because an empty list would clear them having committed to nothing, while a task or a bug carrying none moves through both untouched (most work is stated adequately by its body). `done` additionally requires every child of the issue being closed to be terminal \u2014 an epic, a task and a bug alike \u2014 read from each child\u2019s STATUS and never from its criteria. A BLOCKED issue \u2014 one carrying an explicit mark or waiting on a blocker that is not yet `done`/`killed` \u2014 cannot move to `ready` or `in_progress`, and the refusal names the reason and every unresolved blocker, so clear the mark (`clear_blocked`) or finish, kill or `unlink_blocker` each blocker first; every other target still moves while blocked. An issue with NO milestone cannot move to any status but `triage` and `killed` (PIPE-R10 rule 9) \u2014 set one with `update_issue` first; `killed` is exempt, so work nobody scheduled can still be abandoned.",
     inputSchema: setStatusInputSchema.shape
@@ -17765,7 +17936,13 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
       title: external_exports.string().min(1),
       type: issueTypeSchema,
       status: issueStatusSchema.optional(),
-      body: markdownSchema.optional()
+      body: markdownSchema.optional(),
+      // This tool CREATES an issue, so it is a door the header refusal has to cover
+      // (PIPE-373 AC-1). The fields must be DECLARED here rather than left off: the
+      // SDK rebuilds this raw shape as a non-strict object, so an undeclared key is
+      // STRIPPED rather than refused — the call would succeed, the issue would be
+      // created, and the author's three lines would be dropped with nothing said.
+      ...refusedIssueHeaderFields
     }
   }, ({ deliverable, ...fields }) => run(() => client2.promoteDeliverable(deliverable, fields)));
   server2.registerTool("list_assets", {
@@ -17924,7 +18101,7 @@ function loadMcpConfig() {
 }
 
 // src/version.ts
-var VERSION = "0.37.3";
+var VERSION = "0.38.0";
 
 // src/main.ts
 var config2 = loadMcpConfig();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pipebrain-mcp",
-  "version": "0.37.3",
+  "version": "0.38.0",
   "description": "Pipebrain MCP server for Claude Code and Claude Desktop — issues, requirements, content, assets, and metadata-only secrets over the Pipebrain API.",
   "type": "module",
   "license": "MIT",