pipebrain-mcp 0.35.0 → 0.36.0

package/dist/main.js

@@ -15101,6 +15101,9 @@ var issueRefSchema = external_exports.string().min(1, { message: "issue referenc
 var requirementRefSchema = external_exports.string().min(1, {
   message: "requirement reference must not be empty \u2014 use a display id (`DWB-R4`) or uuid"
 });
+var conventionRefSchema = external_exports.string().min(1, {
+  message: "convention reference must not be empty \u2014 use a display id (`CONV-3`) or uuid"
+});
 var decisionRefSchema = external_exports.string().min(1, {
   message: "decision reference must not be empty \u2014 use a display id (`DWB-D7`) or uuid"
 });
@@ -15167,6 +15170,36 @@ function parseDeliverableDisplayId(value) {
   return { key: match[1], number: Number(match[2]), platform: match[3] };
 }
 
+// ../../libs/domain/dist/project-scope.js
+var CODE_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
+  "cjs",
+  "css",
+  "go",
+  "java",
+  "js",
+  "jsx",
+  "mjs",
+  "py",
+  "rb",
+  "rs",
+  "sh",
+  "sql",
+  "ts",
+  "tsx"
+]);
+var DOCUMENT_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
+  "html",
+  "json",
+  "md",
+  "toml",
+  "yaml",
+  "yml"
+]);
+var SOURCE_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ...CODE_FILE_EXTENSIONS,
+  ...DOCUMENT_FILE_EXTENSIONS
+]);
+
 // ../../libs/domain/dist/entities.js
 var organizationSchema = external_exports.object({
   id: uuidSchema,
@@ -15376,6 +15409,42 @@ var requirementApprovalSchema = external_exports.object({
   approvedBy: uuidSchema,
   createdAt: external_exports.iso.datetime({ offset: true })
 });
+var conventionSchema = external_exports.object({
+  id: uuidSchema,
+  displayId: external_exports.string().min(1),
+  orgId: uuidSchema,
+  number: positiveIntSchema,
+  approvedRevisionId: uuidSchema.nullable(),
+  lifecycle: requirementLifecycleSchema,
+  supersededById: uuidSchema.nullable(),
+  supersededAt: external_exports.iso.datetime({ offset: true }).nullable(),
+  createdBy: uuidSchema.nullable(),
+  createdAt: external_exports.iso.datetime({ offset: true }),
+  updatedAt: external_exports.iso.datetime({ offset: true }),
+  deletedAt: external_exports.iso.datetime({ offset: true }).nullable()
+});
+var conventionRevisionSchema = external_exports.object({
+  id: uuidSchema,
+  orgId: uuidSchema,
+  conventionId: uuidSchema,
+  revisionNumber: positiveIntSchema,
+  title: external_exports.string().min(1),
+  body: markdownSchema,
+  note: external_exports.string().nullable(),
+  createdBy: uuidSchema.nullable(),
+  viaTokenId: uuidSchema.nullable(),
+  createdAt: external_exports.iso.datetime({ offset: true })
+});
+var conventionApprovalSchema = external_exports.object({
+  id: uuidSchema,
+  orgId: uuidSchema,
+  conventionId: uuidSchema,
+  revisionId: uuidSchema,
+  approvedBy: uuidSchema,
+  viaTokenId: uuidSchema.nullable(),
+  supersededId: uuidSchema.nullable(),
+  createdAt: external_exports.iso.datetime({ offset: true })
+});
 var issueRequirementLinkSchema = external_exports.object({
   id: uuidSchema,
   orgId: uuidSchema,
@@ -15821,6 +15890,25 @@ var approveRequirementInputSchema = external_exports.strictObject({
   // → requirement_revisions.revision_number, an `integer` column (PIPE-149).
   revision: int4Schema.optional()
 });
+var createConventionInputSchema = external_exports.strictObject({
+  title: external_exports.string().min(1, { message: "convention title must not be empty" }),
+  body: markdownSchema,
+  note: external_exports.string().optional(),
+  outlivesAnyProject: external_exports.literal(true, {
+    message: "set outlivesAnyProject: true to assert this statement outlives any single project \u2014 if it stops being true when one project ends it is a cross-cutting requirement on that project, not a convention"
+  })
+});
+var updateConventionInputSchema = external_exports.strictObject({
+  convention: conventionRefSchema,
+  title: external_exports.string().min(1, { message: "convention title must not be empty" }).optional(),
+  body: markdownSchema.optional(),
+  note: external_exports.string().min(1, { message: "note must not be empty \u2014 omit it if there is nothing to record" }).optional()
+}).refine((v) => v.title !== void 0 || v.body !== void 0, {
+  message: "empty edit: supply at least one of `title` or `body`"
+});
+var listConventionsFilterSchema = external_exports.strictObject({
+  text: external_exports.string().optional()
+});
 var createDecisionInputSchema = external_exports.strictObject({
   project: projectRefSchema,
   title: external_exports.string().min(1, { message: "decision title must not be empty" }),
@@ -15899,9 +15987,10 @@ var createOrgInputSchema = external_exports.strictObject({
 });
 var updateOrgInputSchema = external_exports.strictObject({
   name: external_exports.string().min(1, { message: "organization name must not be empty" }).optional(),
-  slug: orgSlugSchema.optional()
-}).refine((v) => v.name !== void 0 || v.slug !== void 0, {
-  message: "empty edit: supply at least one of `name` or `slug`"
+  slug: orgSlugSchema.optional(),
+  conventionWarningThreshold: int4Schema.nullable().optional()
+}).refine((v) => v.name !== void 0 || v.slug !== void 0 || v.conventionWarningThreshold !== void 0, {
+  message: "empty edit: supply at least one of `name`, `slug`, or `conventionWarningThreshold`"
 });
 var createInvitationInputSchema = external_exports.strictObject({
   email: emailSchema,
@@ -16401,6 +16490,33 @@ var ApiClient = class _ApiClient {
       body: revision === void 0 ? {} : { revision }
     });
   }
+  // --- organization conventions (PIPE-193) -----------------------------------
+  //
+  // FOUR methods, and the absence of a fifth is the design: there is deliberately NO
+  // `approveConvention` here, and there must not be one. Approving is a signed-in
+  // person's act in the browser (AC-1) — the API refuses the route to a bearer caller —
+  // and this client is what the agent surface calls, so a method for it would only ever
+  // be a door an agent walks into a 403 through. The web app posts that route directly.
+  /**
+   * The whole list, superseded conventions included, with the delivered count and the
+   * threshold that warns about it. NOT `requestList`: the response is a named object
+   * rather than an `{ items }` envelope, because the count and the threshold are answers
+   * to the same question the list is and belong in the same read.
+   */
+  listConventions(filter = {}) {
+    return this.request("GET", "/api/v1/conventions", { query: filter });
+  }
+  getConvention(ref) {
+    return this.request("GET", `/api/v1/conventions/${enc(ref)}`);
+  }
+  createConvention(input) {
+    return this.request("POST", "/api/v1/conventions", { body: input });
+  }
+  updateConvention(ref, fields) {
+    return this.request("PATCH", `/api/v1/conventions/${enc(ref)}`, {
+      body: fields
+    });
+  }
   // --- decision records (PIPE-84) --------------------------------------------
   //
   // Five routes, no DELETE: PIPE-73 made four record kinds deletable and this epic
@@ -17118,7 +17234,7 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
       // one description loaded into EVERY session by `anthropic/alwaysLoad`. The clauses
       // that went were the ones arguing for the rule rather than stating it; what a caller
       // needs to predict a refusal all stayed.
-      description: "Everything a session needs before it starts work, in ONE read \u2014 assembled by the API and returned verbatim, with the BINDING GUIDANCE appended after it: the product doctrine and this organization\u2019s own writing rules, in full. This is the one call that returns them; every other read only names it. CALL IT FIRST, before you write anything. Addressed by `issue` OR by `project`, never both and never neither: an issue names its own project, so the pair is refused rather than resolved for you (\xA77). Given an ISSUE: that issue\u2019s full detail \u2014 the same payload `get_issue` returns \u2014 PLUS the BODY TEXT of every requirement it links, at the revision the link is pinned at. That text is the round trip this removes: `get_issue` names which documents bind the work and at which revision, never what they SAY. Comments come CAPPED at the newest `commentLimit`, with `commentCount` \u2014 the issue\u2019s TRUE total \u2014 beside them; read the issue directly for the rest. Given a PROJECT: `available`, the work a session could START right now. It EXCLUDES finished and abandoned work (`done`, `killed`), work another person has claimed, and anything blocked \u2014 the status guard would refuse to start that. Your OWN claims stay, and so does unscheduled work carrying no milestone. `available` comes CAPPED at `availableLimit` rows, with `availableCount` \u2014 the project\u2019s TRUE total of startable work \u2014 beside it. The item form carries no `available`; the project form carries no item. BOTH forms also carry the project half: the release currently being worked (the active milestone) and the project\u2019s cross-cutting requirements WITH their text \u2014 they bind every epic automatically. READ-ONLY \u2014 this claims nothing, moves nothing and writes nothing.",
+      description: "Everything a session needs before it starts work, in ONE read \u2014 assembled by the API and returned verbatim, with the BINDING GUIDANCE appended after it: the product doctrine and this organization\u2019s own writing rules, in full. This is the one call that returns them; every other read only names it. CALL IT FIRST, before you write anything. Addressed by `issue` OR by `project`, never both and never neither: an issue names its own project, so the pair is refused rather than resolved for you (\xA77). Given an ISSUE: that issue\u2019s full detail \u2014 the same payload `get_issue` returns \u2014 PLUS the BODY TEXT of every requirement it links, at the revision the link is pinned at. That text is the round trip this removes: `get_issue` names which documents bind the work and at which revision, never what they SAY. Comments come CAPPED at the newest `commentLimit`, with `commentCount` \u2014 the issue\u2019s TRUE total \u2014 beside them; read the issue directly for the rest. Given a PROJECT: `available`, the work a session could START right now. It EXCLUDES finished and abandoned work (`done`, `killed`), work another person has claimed, and anything blocked \u2014 the status guard would refuse to start that. Your OWN claims stay, and so does unscheduled work carrying no milestone. `available` comes CAPPED at `availableLimit` rows, with `availableCount` \u2014 the project\u2019s TRUE total of startable work \u2014 beside it. The item form carries no `available`; the project form carries no item. BOTH forms also carry the project half: the release currently being worked (the active milestone) and the project\u2019s cross-cutting requirements WITH their text \u2014 they bind every epic automatically \u2014 and this organization\u2019s approved conventions in full, standing guidance that binds work in EVERY project here, not just this one. READ-ONLY \u2014 this claims nothing, moves nothing and writes nothing.",
       // The WHOLE domain schema rather than its `.shape`: the exactly-one-of rule is a
       // refinement on the OBJECT, and a raw shape drops it — the SDK validates against
       // what it is handed, so the shape alone would quietly accept both arguments and
@@ -17234,7 +17350,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, 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: 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", {
@@ -17367,6 +17483,29 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
     description: "Approve (pin) a requirement\u2019s latest revision, or a specified `revision`, recording it in approvals history and advancing the approved revision that downstream links and reads build against (\xA75, \xA77).",
     inputSchema: approveRequirementInputSchema.shape
   }, (args) => run(() => client2.approveRequirement(args.requirement, args.revision)));
+  server2.registerTool("list_conventions", {
+    description: "List this organization\u2019s conventions \u2014 standing guidance that binds work in EVERY project here, unlike a requirement, which binds one project. Returns display id (`CONV-{n}`), title, the standing text, lifecycle (draft/approved/amended), latest + approved revision numbers, and whether it has been superseded and by which convention. Optional `text` matches over title and body. Retired conventions are INCLUDED and marked, so you can see what the organization used to require rather than proposing it again. Only APPROVED, unretired conventions are actually delivered to agents \u2014 every `get_issue` and `get_work_context` read carries them.",
+    inputSchema: listConventionsFilterSchema.shape
+  }, (args) => run(() => client2.listConventions(args), GUIDANCE_POINTER));
+  server2.registerTool("get_convention", {
+    description: "Get one convention by display id (`CONV-{n}`) or uuid: the standing text at the approved revision, its full revision history with who wrote each and when, its approval history, and \u2014 when it has been retired \u2014 which convention replaced it. A convention that was never approved is readable here and is delivered to nobody.",
+    inputSchema: { convention: conventionRefSchema }
+  }, (args) => run(() => client2.getConvention(args.convention), GUIDANCE_POINTER));
+  server2.registerTool("create_convention", {
+    description: "Write a convention: organization-wide standing guidance, with no project attached. THE GOVERNING TEST \u2014 if it stops being true when this project ends it is a cross-cutting requirement; if it would still be true on the next project it is a convention. You must assert that test by passing `outlivesAnyProject: true`; the write is refused without it. A statement naming one specific project \u2014 its key, a display id built on it, a repository path, or a database object \u2014 is also refused (422 `convention_names_project_scope`), and the message says to file it as a cross-cutting requirement on that project instead. IT BINDS NOBODY UNTIL IT IS APPROVED, and approval is NOT available on this surface: it requires a signed-in person in the browser, so there is no tool for it here and asking for one is asking for a tool that deliberately does not exist. A new convention starts as a draft; write it, then ask a person to review and approve it. Writing guidance for this tool lives in the product doctrine, which `get_work_context` returns \u2014 see \u201CSearch before you create\u201D and \u201CLink by key; never paste another record\u2019s text\u201D.",
+    inputSchema: createConventionInputSchema.shape
+  }, (args) => run(() => client2.createConvention(args)));
+  server2.registerTool("update_convention", {
+    description: "Amend a convention: `title` and/or `body` APPEND a new revision \u2014 nothing is ever edited in place \u2014 and optional `note` records why. Supplying neither is an empty edit (400); a note alone amends nothing. The same project-scope refusal applies as on create, over the amended text. THE AMENDMENT BINDS NOBODY UNTIL IT IS ITSELF APPROVED: until then agents keep receiving the approved revision, so amending is not a way to change what is being delivered \u2014 a signed-in person approving the new revision is.",
+    // Inline shape (updateConventionInputSchema is a refine, so it has no `.shape`);
+    // the empty-edit rule is enforced by the API, not by this shape.
+    inputSchema: {
+      convention: conventionRefSchema,
+      title: external_exports.string().min(1).optional(),
+      body: markdownSchema.optional(),
+      note: external_exports.string().min(1).optional()
+    }
+  }, ({ convention, ...fields }) => run(() => client2.updateConvention(convention, fields)));
   server2.registerTool("create_decision", {
     description: "Record ONE decision as a project-scoped decision record (`KEY-D{n}`): `title` names the decision and `body` says what was decided and why. A new record starts `proposed`; moving it to `accepted` IS the acceptance \u2014 there is no separate approval step. Returns the created record. Title and body can be corrected only while the record is `proposed`; from `accepted` onward it is frozen, and the way to change a decision is to write a NEW record and `supersede_decision` the old one \u2014 which leaves the original readable and says where the current decision went. Nothing on any surface deletes one. Writing guidance for this tool lives in the product doctrine, which `get_work_context` returns \u2014 see \u201CA decision record is written once\u201D and \u201CSearch before you create\u201D.",
     inputSchema: createDecisionInputSchema.shape
@@ -17577,7 +17716,7 @@ function loadMcpConfig() {
 }
 
 // src/version.ts
-var VERSION = "0.35.0";
+var VERSION = "0.36.0";
 
 // src/main.ts
 var config2 = loadMcpConfig();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pipebrain-mcp",
-  "version": "0.35.0",
+  "version": "0.36.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",