@plune-ai/cli 0.33.0 → 0.34.1

package/dist/mcp-tools.cjs

@@ -0,0 +1,932 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/mcp-tools/index.ts
+var mcp_tools_exports = {};
+__export(mcp_tools_exports, {
+  BATCH_MAX: () => BATCH_MAX,
+  CONFIRM_TTL_MS: () => CONFIRM_TTL_MS,
+  MAX_VISIBLE_TOOLS: () => MAX_VISIBLE_TOOLS,
+  PLUNE_TOOLS: () => PLUNE_TOOLS,
+  PLUNE_TOOL_NAMES: () => PLUNE_TOOL_NAMES,
+  PluneApiError: () => PluneApiError,
+  PluneNetworkError: () => PluneNetworkError,
+  createPluneToolExecutor: () => createPluneToolExecutor,
+  defaultVisibleTools: () => defaultVisibleTools,
+  isPluneToolName: () => isPluneToolName,
+  pluneTool: () => pluneTool
+});
+module.exports = __toCommonJS(mcp_tools_exports);
+
+// src/mcp-tools/contract.ts
+var import_zod2 = require("zod");
+
+// src/mcp-tools/schemas.ts
+var import_zod = require("zod");
+var BATCH_MAX = 100;
+var isHttp = (s) => {
+  try {
+    const u = new URL(s);
+    return u.protocol === "http:" || u.protocol === "https:";
+  } catch {
+    return false;
+  }
+};
+var httpLink = (what, max) => import_zod.z.string().trim().min(1, `${what} is empty`).max(max).refine(isHttp, `${what} must be an http or https address`);
+var id = (what) => import_zod.z.string().min(1).describe(what);
+var dryRun = import_zod.z.boolean().optional().describe("true: answer what would be sent, and send nothing");
+var MISSION_STATES = ["draft", "active", "done"];
+var MISSION_DOCUMENTATION = ["unknown", "provided", "none"];
+var MISSION_LINK_KINDS = ["url", "openapi", "repo", "ticket"];
+var missionName = import_zod.z.string().trim().min(1, "a mission needs a name").max(200);
+var missionSummary = import_zod.z.string().trim().max(2e3).describe("What the product is, in 3-5 sentences");
+var missionUrl = httpLink("url", 2048).nullable().describe("Where the product runs; null takes it off");
+var missionFields = {
+  name: missionName,
+  summary: missionSummary.optional(),
+  url: missionUrl.optional(),
+  state: import_zod.z.enum(MISSION_STATES).optional(),
+  documentation: import_zod.z.enum(MISSION_DOCUMENTATION).optional().describe("Is there documentation: provided (it is among the sources), none, or unknown")
+};
+var sourceTitle = import_zod.z.string().trim().min(1).max(200);
+var sourceVersion = import_zod.z.string().trim().min(1).max(200).describe("A commit, a tag, a revision, an ETag");
+var linkSource = import_zod.z.strictObject({
+  missionId: id("The mission"),
+  kind: import_zod.z.enum(MISSION_LINK_KINDS),
+  ref: httpLink("ref", 2048).describe("The link"),
+  title: sourceTitle.optional(),
+  version: sourceVersion.optional(),
+  dry_run: dryRun
+});
+var fileSource = import_zod.z.strictObject({
+  missionId: id("The mission"),
+  kind: import_zod.z.literal("file"),
+  name: import_zod.z.string().trim().min(1).max(200).regex(/\.(txt|md|markdown|json)$/i, "a source file is .txt, .md, .markdown or .json").describe("The file name; its extension sets the type"),
+  text: import_zod.z.string().max(1048576).describe("The whole text of the file, UTF-8, at most 1 MiB"),
+  title: sourceTitle.optional(),
+  version: sourceVersion.optional(),
+  dry_run: dryRun
+});
+var ACCESS_KINDS = ["openapi", "repo", "staging", "har"];
+var questionText = import_zod.z.string().trim().min(1).max(2e3);
+var questionInput = import_zod.z.strictObject({
+  template: import_zod.z.enum(["plain", "access"]).describe("plain: a question with up to three options; access: ask for an API description, the code, a staging host or a HAR file"),
+  text: questionText,
+  missionId: import_zod.z.string().min(1).optional(),
+  options: import_zod.z.array(import_zod.z.string().trim().min(1).max(200)).min(1).max(3).refine((o) => new Set(o).size === o.length, { message: "no two options are the same" }).optional().describe("plain only: what the person may pick from"),
+  access: import_zod.z.array(import_zod.z.enum(ACCESS_KINDS)).min(1).max(ACCESS_KINDS.length).refine((a) => new Set(a).size === a.length, { message: "an access kind is named once" }).optional().describe("access only: what you ask to be given"),
+  dry_run: dryRun
+});
+var STRATEGY_SOURCE_KINDS = ["mission-source", "doc-section", "screen", "endpoint", "requirement", "url"];
+var TEST_LEVELS = ["component", "component-integration", "system", "system-integration", "acceptance"];
+var QUALITY_CHARACTERISTICS = [
+  "functional-suitability",
+  "performance-efficiency",
+  "compatibility",
+  "interaction-capability",
+  "reliability",
+  "security",
+  "maintainability",
+  "flexibility",
+  "safety"
+];
+var TEST_TECHNIQUES = [
+  "equivalence-partitioning",
+  "boundary-value",
+  "decision-table",
+  "state-transition",
+  "statement",
+  "branch",
+  "error-guessing",
+  "exploratory",
+  "checklist"
+];
+var RISK_SCALE = ["low", "medium", "high"];
+var itemFields = {
+  text: import_zod.z.string().trim().min(1).max(1e3).describe("Markdown"),
+  source: import_zod.z.strictObject({ kind: import_zod.z.enum(STRATEGY_SOURCE_KINDS), ref: import_zod.z.string().trim().min(1).max(300) }).optional().describe("Where it was read"),
+  assumption: import_zod.z.literal(true).optional().describe("You assumed it: a person confirms"),
+  waitingOn: import_zod.z.string().min(1).optional().describe("The id of an open question of this mission it waits for")
+};
+var strategyItem = import_zod.z.strictObject(itemFields);
+var items = import_zod.z.array(strategyItem).min(1).max(25);
+var unique = (values) => import_zod.z.array(import_zod.z.enum(values)).min(1).refine((a) => new Set(a).size === a.length, { message: "named once" });
+var linkIds = import_zod.z.array(import_zod.z.string().min(1)).max(50).refine((a) => new Set(a).size === a.length, { message: "an id is named once" });
+var share = import_zod.z.number().int().min(0).max(100);
+var strategyContent = import_zod.z.strictObject({
+  objectives: items,
+  scope: import_zod.z.strictObject({ in: items, out: items.describe("What is deliberately not tested, and why") }),
+  approach: items,
+  profile: import_zod.z.strictObject({
+    levels: unique(TEST_LEVELS),
+    characteristics: unique(QUALITY_CHARACTERISTICS),
+    techniques: unique(TEST_TECHNIQUES),
+    split: import_zod.z.strictObject({ api: share, ui: share, manual: share }).refine((s) => s.api + s.ui + s.manual === 100, { message: "the split of api, ui and manual adds up to 100" }),
+    notes: items
+  }),
+  risks: import_zod.z.array(
+    import_zod.z.strictObject({
+      ...itemFields,
+      likelihood: import_zod.z.enum(RISK_SCALE),
+      impact: import_zod.z.enum(RISK_SCALE),
+      caseIds: linkIds.optional(),
+      requirementIds: linkIds.optional()
+    })
+  ).min(1).max(50),
+  entryCriteria: items,
+  exitCriteria: items
+});
+var SOURCE_REF_KINDS = ["url", "openapi-operation", "requirement", "pasted-text"];
+var proposedCase = import_zod.z.strictObject({
+  title: import_zod.z.string().trim().min(1).max(300),
+  steps: import_zod.z.array(import_zod.z.string().trim().min(1).max(400)).min(1).max(20),
+  expected: import_zod.z.string().trim().min(1).max(2e3),
+  execution: import_zod.z.enum(["auto", "manual"]).optional().describe("auto: can be automated; manual (default): stays with a person"),
+  technique: import_zod.z.string().min(1).max(32).optional(),
+  priority: import_zod.z.string().min(1).optional(),
+  source: import_zod.z.strictObject({ kind: import_zod.z.enum(SOURCE_REF_KINDS), value: import_zod.z.string().min(1).max(100) }).optional().describe("What you read to design it"),
+  rationale: import_zod.z.string().min(1).max(400).optional().describe("Why the case is worth having")
+});
+var API_METHODS = ["GET", "PUT", "POST", "DELETE", "OPTIONS", "HEAD", "PATCH", "TRACE"];
+var proposedEndpoint = import_zod.z.strictObject({
+  method: import_zod.z.enum(API_METHODS),
+  path: import_zod.z.string().min(1).max(512).regex(/^\/[^?#\s]*$/, "a path template starts with / and has no query").describe("A template: /users/{id}, never /users/42"),
+  source: import_zod.z.enum(["spec", "code", "traffic"]),
+  trust: import_zod.z.enum(["confirmed", "derived"]).optional(),
+  summary: import_zod.z.string().trim().min(1).max(500).optional(),
+  auth: import_zod.z.array(import_zod.z.string().trim().min(1).max(100)).max(10).optional(),
+  environment: import_zod.z.string().trim().min(1).max(100).optional(),
+  seenAt: import_zod.z.string().optional().describe("ISO 8601 date and time with an offset")
+});
+var REVIEW_STATES = ["pending", "changes_requested", "approved", "rejected"];
+var REVIEW_KINDS = ["result", "proposal", "discovered", "endpoint", "strategy", "report", "memory_rule"];
+var REJECTION_CATEGORIES = ["duplicate", "incorrect", "out-of-scope", "low-value", "not-testable", "other"];
+var entity = import_zod.z.looseObject({ id: import_zod.z.string().optional() });
+var plannedRequest = import_zod.z.object({
+  method: import_zod.z.string(),
+  path: import_zod.z.string(),
+  query: import_zod.z.record(import_zod.z.string(), import_zod.z.string()).optional(),
+  body: import_zod.z.unknown().optional()
+});
+var writeOutput = import_zod.z.object({
+  dryRun: import_zod.z.boolean(),
+  request: plannedRequest.optional(),
+  result: entity.optional()
+});
+var batchOutput = import_zod.z.object({
+  dryRun: import_zod.z.boolean(),
+  requested: import_zod.z.number().int(),
+  applied: import_zod.z.number().int(),
+  requests: import_zod.z.array(plannedRequest).optional(),
+  results: import_zod.z.array(
+    import_zod.z.object({
+      ok: import_zod.z.boolean(),
+      status: import_zod.z.number().int().optional(),
+      id: import_zod.z.string().optional(),
+      error: import_zod.z.string().optional(),
+      code: import_zod.z.string().optional()
+    })
+  ).optional(),
+  report: import_zod.z.looseObject({}).optional()
+});
+var bulkPreview = import_zod.z.looseObject({
+  total: import_zod.z.number().int(),
+  confirm: import_zod.z.string(),
+  expiresInSeconds: import_zod.z.number().int()
+});
+
+// src/mcp-tools/contract.ts
+var MAX_VISIBLE_TOOLS = 20;
+var define = (tool) => tool;
+var listPage = {
+  limit: import_zod2.z.number().int().min(1).max(BATCH_MAX).optional(),
+  cursor: import_zod2.z.string().min(1).optional().describe("nextCursor of the previous page")
+};
+var missionId = id("The mission id");
+var PLUNE_TOOLS = [
+  define({
+    name: "plune_project_context",
+    title: "Project context",
+    description: "Start here: learn the project you are working in with one call \u2014 its projects, the suite tree, how many test cases it has, its testing missions, and how much waits in the review queue.",
+    input: import_zod2.z.strictObject({}),
+    output: import_zod2.z.object({
+      projectId: import_zod2.z.string().nullable(),
+      projects: import_zod2.z.array(entity),
+      suites: import_zod2.z.array(entity),
+      cases: import_zod2.z.object({ total: import_zod2.z.number().int() }),
+      missions: import_zod2.z.array(entity),
+      reviewQueue: import_zod2.z.object({ pending: import_zod2.z.number().int(), more: import_zod2.z.boolean() })
+    }),
+    write: false,
+    visibility: "core",
+    endpoints: ["GET /v1/projects", "GET /v1/suites", "GET /v1/test-cases", "GET /v1/missions", "GET /v1/review-items"]
+  }),
+  define({
+    name: "plune_get",
+    title: "Read one object",
+    description: "Read one test case, run or review queue entry in full when you already hold its id \u2014 steps, state, history fields and everything the platform keeps on it.",
+    input: import_zod2.z.strictObject({ kind: import_zod2.z.enum(["test-case", "run", "review-item"]), id: id("Its id") }),
+    output: import_zod2.z.object({ kind: import_zod2.z.string(), item: entity }),
+    write: false,
+    visibility: "core",
+    endpoints: ["GET /v1/test-cases/:id", "GET /v1/runs/:id", "GET /v1/review-items/:id"]
+  }),
+  define({
+    name: "plune_cases_search",
+    title: "Find test cases",
+    description: "Find test cases of the project by filter \u2014 suite, state, tag, priority, text and the other filters of the case list \u2014 one page at a time, with the total and how many match.",
+    input: import_zod2.z.strictObject({
+      filters: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.union([import_zod2.z.string(), import_zod2.z.array(import_zod2.z.string())])).optional().describe('Query filters of GET /v1/test-cases: a list is OR inside one key, keys are AND-ed (e.g. {"suiteId": "s1", "tag": ["smoke"]})'),
+      ...listPage
+    }),
+    output: import_zod2.z.object({
+      testCases: import_zod2.z.array(entity),
+      total: import_zod2.z.number().int().optional(),
+      matching: import_zod2.z.number().int().optional(),
+      nextCursor: import_zod2.z.string().nullable()
+    }),
+    write: false,
+    visibility: "core",
+    endpoints: ["GET /v1/test-cases?filters"]
+  }),
+  define({
+    name: "plune_review_list",
+    title: "Read the review queue",
+    description: "See what waits for a decision in the review queue \u2014 proposed cases, discovered tests, endpoints, strategies, reports \u2014 narrowed by state and kind, newest first, one page at a time.",
+    input: import_zod2.z.strictObject({
+      state: import_zod2.z.enum(REVIEW_STATES).optional(),
+      kinds: import_zod2.z.array(import_zod2.z.enum(REVIEW_KINDS)).min(1).optional().describe("Questions are read with the question tool"),
+      ...listPage
+    }),
+    output: import_zod2.z.object({ items: import_zod2.z.array(entity), nextCursor: import_zod2.z.string().nullable() }),
+    write: false,
+    visibility: "core",
+    endpoints: ["GET /v1/review-items"]
+  }),
+  define({
+    name: "plune_review_decide",
+    title: "Decide queue entries",
+    description: "Approve or reject up to 100 review queue entries in one decision. The first call changes nothing and returns a preview with a confirm value; repeat the same call with confirm to apply it.",
+    input: import_zod2.z.strictObject({
+      itemIds: import_zod2.z.array(import_zod2.z.string().min(1)).min(1).max(BATCH_MAX).refine((a) => new Set(a).size === a.length, { message: "an id is named once" }),
+      verdict: import_zod2.z.enum(["approved", "rejected"]),
+      rejectionCategory: import_zod2.z.enum(REJECTION_CATEGORIES).optional().describe("Required to reject"),
+      note: import_zod2.z.string().trim().min(1).max(2e3).optional().describe("Why \u2014 required to reject"),
+      confirm: import_zod2.z.string().min(1).optional().describe("The confirm value of the preview")
+    }),
+    output: import_zod2.z.object({
+      requested: import_zod2.z.number().int(),
+      applied: import_zod2.z.number().int(),
+      preview: bulkPreview.optional(),
+      report: import_zod2.z.looseObject({}).optional()
+    }),
+    write: true,
+    visibility: "core",
+    endpoints: ["POST /v1/review-items/decisions"]
+  }),
+  define({
+    name: "plune_case_propose",
+    title: "Propose test cases",
+    description: "Propose up to 100 new test cases for a person to review: they land in the review queue as proposals and become cases only when someone approves them. Nothing is created silently.",
+    input: import_zod2.z.strictObject({
+      target: import_zod2.z.string().trim().min(1).max(2048).describe("What the cases test: the product address, or the mission name"),
+      cases: import_zod2.z.array(proposedCase).min(1).max(BATCH_MAX),
+      dry_run: dryRun
+    }),
+    output: batchOutput,
+    write: true,
+    visibility: "core",
+    endpoints: ["POST /v1/ingest/cairn"]
+  }),
+  define({
+    name: "plune_mission_create",
+    title: "Create a mission",
+    description: "Create a testing mission for a product: its name, a short description of what the product is, where it runs, and whether documentation exists. It starts as a draft you fill in.",
+    input: import_zod2.z.strictObject({ ...missionFields, dry_run: dryRun }),
+    output: writeOutput,
+    write: true,
+    visibility: "core",
+    endpoints: ["POST /v1/missions"]
+  }),
+  define({
+    name: "plune_mission_get",
+    title: "Read a mission",
+    description: "Read a testing mission with everything it holds \u2014 its brief, state, documentation answer and every source attached to it \u2014 before planning or continuing the work on it.",
+    input: import_zod2.z.strictObject({ missionId }),
+    output: import_zod2.z.object({ mission: entity }),
+    write: false,
+    visibility: "core",
+    endpoints: ["GET /v1/missions/:id"]
+  }),
+  define({
+    name: "plune_mission_update",
+    title: "Update a mission",
+    description: "Change a testing mission: rename it, rewrite the brief, set or remove the address, answer whether documentation exists, or move it between draft, active and done.",
+    input: import_zod2.z.strictObject({
+      missionId,
+      name: missionFields.name.optional(),
+      summary: missionFields.summary,
+      url: missionFields.url,
+      state: missionFields.state,
+      documentation: missionFields.documentation,
+      dry_run: dryRun
+    }).refine((b) => ["name", "summary", "url", "state", "documentation"].some((k) => b[k] !== void 0), {
+      message: "nothing to change"
+    }),
+    output: writeOutput,
+    write: true,
+    visibility: "core",
+    endpoints: ["PATCH /v1/missions/:id"]
+  }),
+  define({
+    name: "plune_source_add",
+    title: "Add a source to a mission",
+    description: "Attach something to read to a mission: a link (page, OpenAPI document, repository, ticket) or the text of a file of the project \u2014 Markdown, plain text or JSON, up to 1 MiB.",
+    input: import_zod2.z.strictObject({
+      missionId,
+      kind: import_zod2.z.enum([...MISSION_LINK_KINDS, "file"]),
+      ref: import_zod2.z.string().optional().describe("The link, for url, openapi, repo and ticket"),
+      name: import_zod2.z.string().optional().describe("The file name, for file (.md, .markdown, .txt, .json)"),
+      text: import_zod2.z.string().optional().describe("The file text, for file"),
+      title: import_zod2.z.string().optional(),
+      version: import_zod2.z.string().optional(),
+      dry_run: dryRun
+    }).superRefine((b, ctx) => {
+      if (b.kind === "file" && (b.name === void 0 || b.text === void 0))
+        ctx.addIssue({ code: "custom", message: "a file source carries name and text" });
+      if (b.kind !== "file" && b.ref === void 0) ctx.addIssue({ code: "custom", message: "a link source carries ref" });
+    }),
+    output: writeOutput,
+    write: true,
+    visibility: "core",
+    endpoints: ["POST /v1/missions/:id/sources", "POST /v1/missions/:id/files"]
+  }),
+  define({
+    name: "plune_question_ask",
+    title: "Ask a person",
+    description: "Ask a person what you do not know instead of guessing: a plain question with up to three options, or a request for access to an API description, the code, staging or a HAR file.",
+    input: questionInput.superRefine((b, ctx) => {
+      if (b.template === "plain" && b.access !== void 0) ctx.addIssue({ code: "custom", message: "access belongs to an access question" });
+      if (b.template === "access" && b.options !== void 0) ctx.addIssue({ code: "custom", message: "options belong to a plain question" });
+      if (b.template === "access" && b.access === void 0) ctx.addIssue({ code: "custom", message: "an access question names the access" });
+    }),
+    output: writeOutput,
+    write: true,
+    visibility: "core",
+    endpoints: ["POST /v1/review-items/questions"]
+  }),
+  define({
+    name: "plune_question_list",
+    title: "Read questions and answers",
+    description: "Check the questions asked to people and the answers they gave \u2014 all of them or one mission's, waiting or answered \u2014 so the work continues from what a person actually said.",
+    input: import_zod2.z.strictObject({ missionId: import_zod2.z.string().min(1).optional(), state: import_zod2.z.enum(REVIEW_STATES).optional(), ...listPage }),
+    output: import_zod2.z.object({ questions: import_zod2.z.array(entity), nextCursor: import_zod2.z.string().nullable() }),
+    write: false,
+    visibility: "core",
+    endpoints: ["GET /v1/review-items?kind=question"]
+  }),
+  define({
+    name: "plune_strategy_propose",
+    title: "Propose a test strategy",
+    description: "Propose a test strategy for a mission in ISTQB sections \u2014 objectives, scope in and out, approach, levels and techniques, risks, entry and exit criteria \u2014 for a person to accept.",
+    input: import_zod2.z.strictObject({ missionId, content: strategyContent, dry_run: dryRun }),
+    output: writeOutput,
+    write: true,
+    visibility: "core",
+    endpoints: ["POST /v1/missions/:id/strategy"]
+  }),
+  define({
+    name: "plune_report_request",
+    title: "Request the mission report",
+    description: "Ask the platform to build the completion report of a mission from its own data and queue it for a person to approve; it needs an accepted strategy first.",
+    input: import_zod2.z.strictObject({ missionId, dry_run: dryRun }),
+    output: writeOutput,
+    write: true,
+    visibility: "core",
+    endpoints: ["POST /v1/missions/:id/report"]
+  }),
+  define({
+    name: "plune_discover_tools",
+    title: "Find more tools",
+    description: "Look for a capability that is not in your tool list \u2014 editing cases, writing results, starting runs, cataloguing API endpoints, a raw API call \u2014 and switch the ones you need on for this session.",
+    input: import_zod2.z.strictObject({
+      query: import_zod2.z.string().trim().min(1).max(200).optional().describe('Words of the task, e.g. "write results"'),
+      names: import_zod2.z.array(import_zod2.z.string().min(1)).min(1).max(MAX_VISIBLE_TOOLS).optional().describe("Tools to switch on")
+    }),
+    output: import_zod2.z.object({
+      revealed: import_zod2.z.array(import_zod2.z.string()),
+      available: import_zod2.z.array(import_zod2.z.object({ name: import_zod2.z.string(), title: import_zod2.z.string(), description: import_zod2.z.string(), write: import_zod2.z.boolean() })),
+      visible: import_zod2.z.array(import_zod2.z.string())
+    }),
+    write: false,
+    visibility: "core",
+    endpoints: ["LOCAL /discover"]
+  }),
+  define({
+    name: "plune_cases_update",
+    title: "Edit test cases",
+    description: "Edit up to 100 existing test cases in one call \u2014 title, steps, expected result, priority, tags, suite \u2014 each applied on its own, with a count of how many were applied.",
+    input: import_zod2.z.strictObject({
+      cases: import_zod2.z.array(import_zod2.z.strictObject({ id: id("The case id"), changes: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown()).describe("Fields of PATCH /v1/test-cases/:id") })).min(1).max(BATCH_MAX),
+      dry_run: dryRun
+    }),
+    output: batchOutput,
+    write: true,
+    visibility: "discoverable",
+    endpoints: ["PATCH /v1/test-cases/:id"]
+  }),
+  define({
+    name: "plune_run_create",
+    title: "Start a run",
+    description: "Start a test run on the platform to record results into \u2014 named, with its environment and the cases it covers \u2014 using the body of POST /v1/runs (schemaVersion 2).",
+    input: import_zod2.z.strictObject({ run: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown()).describe("The body of POST /v1/runs"), dry_run: dryRun }),
+    output: writeOutput,
+    write: true,
+    visibility: "discoverable",
+    endpoints: ["POST /v1/runs"]
+  }),
+  define({
+    name: "plune_results_write",
+    title: "Write results into a run",
+    description: "Record up to 100 test results into an open run in one request \u2014 passed, failed, skipped, with their keys and evidence \u2014 and learn how many the platform accepted.",
+    input: import_zod2.z.strictObject({
+      runId: id("The run id"),
+      results: import_zod2.z.array(import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown())).min(1).max(BATCH_MAX).describe("Results as POST /v1/runs/:id/results takes them"),
+      combination: import_zod2.z.number().int().min(0).optional(),
+      configuration: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.string()).optional(),
+      dry_run: dryRun
+    }),
+    output: batchOutput,
+    write: true,
+    visibility: "discoverable",
+    endpoints: ["POST /v1/runs/:id/results"]
+  }),
+  define({
+    name: "plune_endpoint_propose",
+    title: "Propose API endpoints",
+    description: "Propose up to 100 API endpoints you found in a spec, the code or traffic for the project's API catalog; each waits in the review queue until a person approves it.",
+    input: import_zod2.z.strictObject({ endpoints: import_zod2.z.array(proposedEndpoint).min(1).max(BATCH_MAX), dry_run: dryRun }),
+    output: batchOutput,
+    write: true,
+    visibility: "discoverable",
+    endpoints: ["POST /v1/review-items/endpoints"]
+  }),
+  define({
+    name: "plune_api_request",
+    title: "Call the REST API directly",
+    description: "Reach any Plune REST endpoint under /v1 that no other tool covers. Every guard still holds: a deletion is previewed first and needs confirm, and the platform refuses an agent what it refuses over HTTP.",
+    input: import_zod2.z.strictObject({
+      method: import_zod2.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+      path: import_zod2.z.string().min(1).max(2048).describe("A path under /v1, e.g. /v1/suites"),
+      query: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.string()).optional(),
+      body: import_zod2.z.unknown().optional(),
+      confirm: import_zod2.z.string().min(1).optional().describe("The confirm value of a preview"),
+      dry_run: dryRun
+    }),
+    output: import_zod2.z.object({
+      status: import_zod2.z.number().int().optional(),
+      body: import_zod2.z.unknown().optional(),
+      dryRun: import_zod2.z.boolean().optional(),
+      request: plannedRequest.optional(),
+      preview: import_zod2.z.looseObject({ method: import_zod2.z.string(), path: import_zod2.z.string(), confirm: import_zod2.z.string(), expiresInSeconds: import_zod2.z.number().int() }).optional()
+    }),
+    write: true,
+    visibility: "discoverable",
+    endpoints: ["ANY /v1/*"]
+  })
+];
+var PLUNE_TOOL_NAMES = PLUNE_TOOLS.map((t) => t.name);
+var BY_NAME = new Map(PLUNE_TOOLS.map((t) => [t.name, t]));
+function pluneTool(name) {
+  const tool = BY_NAME.get(name);
+  if (tool === void 0) throw new Error(`unknown tool: ${name}`);
+  return tool;
+}
+function isPluneToolName(name) {
+  return BY_NAME.has(name);
+}
+function defaultVisibleTools(scope) {
+  return PLUNE_TOOLS.filter((t) => t.visibility === "core" && !(scope === "read" && t.write)).map((t) => t.name);
+}
+
+// src/mcp-tools/execute.ts
+var import_node_crypto = require("crypto");
+
+// src/mcp-tools/client.ts
+var PluneApiError = class extends Error {
+  constructor(status, body) {
+    const error = bodyField(body, "error");
+    super(error ?? `HTTP ${status}`);
+    this.status = status;
+    this.body = body;
+    this.name = "PluneApiError";
+  }
+  status;
+  body;
+  get code() {
+    return bodyField(this.body, "code");
+  }
+};
+var PluneNetworkError = class extends Error {
+  constructor(apiUrl) {
+    super(`could not reach Plune at ${apiUrl}`);
+    this.apiUrl = apiUrl;
+    this.name = "PluneNetworkError";
+  }
+  apiUrl;
+};
+function bodyField(body, key) {
+  if (body === null || typeof body !== "object") return void 0;
+  const value = body[key];
+  return typeof value === "string" ? value : void 0;
+}
+function apiBase(apiUrl) {
+  return apiUrl.replace(/\/+$/, "");
+}
+function buildUrl(apiUrl, req) {
+  const url = new URL(apiBase(apiUrl) + req.path);
+  for (const [key, value] of Object.entries(req.query ?? {})) {
+    for (const v of typeof value === "string" ? [value] : value) url.searchParams.append(key, v);
+  }
+  return url;
+}
+function createPluneApi(opts) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const headers = {
+    authorization: `Bearer ${opts.token}`,
+    accept: "application/json",
+    "x-plune-session": opts.sessionId,
+    ...opts.projectId === void 0 ? {} : { "x-plune-project": opts.projectId },
+    ...opts.userAgent === void 0 ? {} : { "user-agent": opts.userAgent }
+  };
+  return async function request(req) {
+    const url = buildUrl(opts.apiUrl, req);
+    let res;
+    try {
+      res = await doFetch(url.toString(), {
+        method: req.method,
+        headers: req.body === void 0 ? headers : { ...headers, "content-type": "application/json" },
+        ...req.body === void 0 ? {} : { body: JSON.stringify(req.body) },
+        // Host pinning (#1283): a redirect elsewhere would carry the token there.
+        redirect: "manual"
+      });
+    } catch {
+      throw new PluneNetworkError(apiBase(opts.apiUrl));
+    }
+    const text = await res.text();
+    let body = text;
+    if (text !== "") {
+      try {
+        body = JSON.parse(text);
+      } catch {
+      }
+    } else {
+      body = void 0;
+    }
+    if (res.status < 200 || res.status >= 300) throw new PluneApiError(res.status, body);
+    return { status: res.status, body };
+  };
+}
+
+// src/mcp-tools/execute.ts
+var CONFIRM_TTL_MS = 5 * 60 * 1e3;
+var READ_ONLY_REFUSAL = "read-only token";
+var readScopeMessage = (what) => `This token has the read scope, so ${what}. Use a token with the write scope (Plune \u2192 Account \u2192 API tokens) and restart the server.`;
+var fail = (code, message, extra = {}) => ({
+  ok: false,
+  error: { code, message, ...extra }
+});
+function errorOf(err) {
+  if (err instanceof PluneApiError) {
+    if (err.status === 401)
+      return { status: 401, code: "token_rejected", message: `Plune rejected the token (401): ${err.message}. Run \`plune login\` or set PLUNE_TOKEN to a live token.` };
+    if (err.status === 403 && err.message === READ_ONLY_REFUSAL)
+      return { status: 403, code: "read_only_token", message: `Plune refused (403): ${readScopeMessage("it cannot write")}` };
+    const code = err.code ?? `http_${err.status}`;
+    return { status: err.status, code, message: `Plune refused (${err.status} ${code}): ${err.message}`, details: err.body };
+  }
+  if (err instanceof PluneNetworkError) return { code: "network", message: `${err.message}. Check PLUNE_API_URL and the network.` };
+  throw err;
+}
+var zodMessage = (error) => error.issues.map((i) => `${i.path.join(".") || "(input)"}: ${i.message}`).join("; ");
+var path = (template, ...ids) => {
+  let i = 0;
+  return template.replace(/:[a-z]+/gi, () => encodeURIComponent(ids[i++] ?? ""));
+};
+var withoutUndefined = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0));
+var asRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
+var asArray = (v) => Array.isArray(v) ? v : [];
+var cursorOf = (v) => typeof v === "string" ? v : null;
+function isDeletion(req) {
+  if (req.method === "DELETE") return true;
+  if (asRecord(asRecord(req.body)["action"])["kind"] === "delete") return true;
+  return /\/(bulk-delete|purge|empty)$/.test(req.path);
+}
+var rawWrites = (method, p) => method !== "GET" && !(method === "POST" && p === "/v1/test-cases/resolve");
+function safePath(apiUrl, raw) {
+  if (!/^\/v1\/[^\\\s]*$/.test(raw) || raw.startsWith("//") || raw.includes("?") || raw.includes("#")) return void 0;
+  if (raw.split("/").some((s) => s === "." || s === ".." || /^%2e/i.test(s))) return void 0;
+  const base = new URL(apiUrl);
+  const url = new URL(raw, base);
+  return url.origin === base.origin && url.pathname.startsWith("/v1/") ? raw : void 0;
+}
+function createPluneToolExecutor(opts) {
+  const sessionId = opts.sessionId ?? (0, import_node_crypto.randomUUID)();
+  const now = opts.now ?? Date.now;
+  const request = createPluneApi({ ...opts, sessionId });
+  let scope = opts.scope;
+  const revealed = /* @__PURE__ */ new Set();
+  const confirms = /* @__PURE__ */ new Map();
+  let proposals = 0;
+  const visibleTools = () => {
+    const core = defaultVisibleTools(scope);
+    const extra = [...revealed].filter((n) => !(scope === "read" && pluneTool(n).write) && !core.includes(n));
+    return [...core, ...extra];
+  };
+  async function call(req) {
+    try {
+      return await request(req);
+    } catch (err) {
+      if (err instanceof PluneApiError && err.status === 403 && err.message === READ_ONLY_REFUSAL) scope = "read";
+      throw err;
+    }
+  }
+  const planned = (req) => withoutUndefined({ method: req.method, path: req.path, query: req.query, body: req.body });
+  async function write(req, dry) {
+    if (dry === true) return { dryRun: true, request: planned(req) };
+    const res = await call(req);
+    return { dryRun: false, result: asRecord(res.body) };
+  }
+  async function batch(reqs, dry, idOf) {
+    if (dry === true) return { dryRun: true, requested: reqs.length, applied: 0, requests: reqs.map(planned) };
+    const results = [];
+    for (const [i, req] of reqs.entries()) {
+      try {
+        const res = await call(req);
+        results.push(withoutUndefined({ ok: true, status: res.status, id: idOf(res.body, i) }));
+      } catch (err) {
+        const e = errorOf(err);
+        if (e.code === "token_rejected" || e.code === "read_only_token" || e.code === "network") throw err;
+        results.push(withoutUndefined({ ok: false, status: e.status, error: e.message, code: e.code }));
+      }
+    }
+    return { dryRun: false, requested: reqs.length, applied: results.filter((r) => r["ok"] === true).length, results };
+  }
+  const fingerprint = (req) => JSON.stringify([req.method, req.path, req.query ?? {}, req.body ?? null]);
+  const str = (v) => v;
+  const handlers = {
+    async plune_project_context() {
+      const [projects, suites, cases, missions, queue] = await Promise.all([
+        call({ method: "GET", path: "/v1/projects" }),
+        call({ method: "GET", path: "/v1/suites" }),
+        call({ method: "GET", path: "/v1/test-cases", query: { limit: "1", stability: "0" } }),
+        call({ method: "GET", path: "/v1/missions" }),
+        call({ method: "GET", path: "/v1/review-items", query: { state: "pending", limit: "100" } })
+      ]);
+      const projectList = asArray(asRecord(projects.body)["projects"]);
+      const only = projectList.length === 1 ? asRecord(projectList[0])["id"] : void 0;
+      const projectId = opts.projectId ?? (typeof only === "string" ? only : null);
+      const total = asRecord(cases.body)["total"];
+      return {
+        projectId,
+        projects: projectList,
+        suites: asArray(asRecord(suites.body)["suites"]),
+        cases: { total: typeof total === "number" ? total : 0 },
+        missions: asArray(asRecord(missions.body)["missions"]),
+        reviewQueue: { pending: asArray(asRecord(queue.body)["items"]).length, more: cursorOf(asRecord(queue.body)["nextCursor"]) !== null }
+      };
+    },
+    async plune_get(i) {
+      const route = { "test-case": "/v1/test-cases/:id", run: "/v1/runs/:id", "review-item": "/v1/review-items/:id" }[str(i["kind"])];
+      const res = await call({ method: "GET", path: path(route, str(i["id"])) });
+      return { kind: str(i["kind"]), item: asRecord(res.body) };
+    },
+    async plune_cases_search(i) {
+      const query = withoutUndefined({
+        ...i["filters"],
+        limit: i["limit"] === void 0 ? void 0 : String(i["limit"]),
+        cursor: i["cursor"],
+        stability: "0"
+      });
+      const body = asRecord((await call({ method: "GET", path: "/v1/test-cases", query })).body);
+      return withoutUndefined({
+        testCases: asArray(body["testCases"]),
+        total: typeof body["total"] === "number" ? body["total"] : void 0,
+        matching: typeof body["matching"] === "number" ? body["matching"] : void 0,
+        nextCursor: cursorOf(body["nextCursor"])
+      });
+    },
+    async plune_review_list(i) {
+      const kinds = i["kinds"];
+      const query = withoutUndefined({
+        state: i["state"],
+        kind: kinds?.join(","),
+        limit: i["limit"] === void 0 ? void 0 : String(i["limit"]),
+        cursor: i["cursor"]
+      });
+      const body = asRecord((await call({ method: "GET", path: "/v1/review-items", query })).body);
+      return { items: asArray(body["items"]), nextCursor: cursorOf(body["nextCursor"]) };
+    },
+    async plune_review_decide(i) {
+      const itemIds = i["itemIds"];
+      const res = await call({
+        method: "POST",
+        path: "/v1/review-items/decisions",
+        ...i["confirm"] === void 0 ? {} : { query: { confirm: str(i["confirm"]) } },
+        body: withoutUndefined({ itemIds, state: i["verdict"], rejectionCategory: i["rejectionCategory"], note: i["note"] })
+      });
+      const body = asRecord(res.body);
+      if (body["preview"] !== void 0) return { requested: itemIds.length, applied: 0, preview: asRecord(body["preview"]) };
+      const applied = body["applied"];
+      return { requested: itemIds.length, applied: typeof applied === "number" ? applied : 0, report: body };
+    },
+    async plune_case_propose(i) {
+      const cases = i["cases"].map((c) => {
+        const steps = c["steps"];
+        const stableId = (0, import_node_crypto.createHash)("sha256").update([c["title"], ...steps, c["expected"]].join("\n")).digest("hex").slice(0, 32);
+        return withoutUndefined({ stableId, execution: "manual", ...c });
+      });
+      proposals += 1;
+      const req = {
+        method: "POST",
+        path: "/v1/ingest/cairn",
+        body: { schemaVersion: 1, run: { runId: `mcp-${sessionId}-${proposals}`, mode: "design", target: str(i["target"]) }, cases }
+      };
+      if (i["dry_run"] === true) return { dryRun: true, requested: cases.length, applied: 0, requests: [planned(req)] };
+      const summary = asRecord((await call(req)).body);
+      const proposed = summary["proposed"];
+      return { dryRun: false, requested: cases.length, applied: typeof proposed === "number" ? proposed : 0, report: summary };
+    },
+    async plune_mission_create(i) {
+      const { dry_run, ...body } = i;
+      return write({ method: "POST", path: "/v1/missions", body: withoutUndefined(body) }, dry_run);
+    },
+    async plune_mission_get(i) {
+      const res = await call({ method: "GET", path: path("/v1/missions/:id", str(i["missionId"])) });
+      return { mission: asRecord(res.body) };
+    },
+    async plune_mission_update(i) {
+      const { dry_run, missionId: missionId2, ...body } = i;
+      return write({ method: "PATCH", path: path("/v1/missions/:id", str(missionId2)), body: withoutUndefined(body) }, dry_run);
+    },
+    async plune_source_add(i) {
+      const parsed = (i["kind"] === "file" ? fileSource : linkSource).safeParse(withoutUndefined(i));
+      if (!parsed.success) return fail("invalid_input", `The input does not fit: ${zodMessage(parsed.error)}`);
+      const { dry_run, missionId: missionId2, kind, ...rest } = parsed.data;
+      const req = kind === "file" ? { method: "POST", path: path("/v1/missions/:id/files", str(missionId2)), body: withoutUndefined(rest) } : { method: "POST", path: path("/v1/missions/:id/sources", str(missionId2)), body: withoutUndefined({ kind, ...rest }) };
+      return write(req, dry_run);
+    },
+    async plune_question_ask(i) {
+      const { dry_run, ...body } = i;
+      return write({ method: "POST", path: "/v1/review-items/questions", body: withoutUndefined(body) }, dry_run);
+    },
+    async plune_question_list(i) {
+      const query = withoutUndefined({
+        kind: "question",
+        state: i["state"],
+        limit: i["limit"] === void 0 ? void 0 : String(i["limit"]),
+        cursor: i["cursor"]
+      });
+      const body = asRecord((await call({ method: "GET", path: "/v1/review-items", query })).body);
+      const missionId2 = i["missionId"];
+      const questions = asArray(body["items"]).filter(
+        (item) => missionId2 === void 0 || asRecord(asRecord(item)["question"])["missionId"] === missionId2
+      );
+      return { questions, nextCursor: cursorOf(body["nextCursor"]) };
+    },
+    async plune_strategy_propose(i) {
+      return write({ method: "POST", path: path("/v1/missions/:id/strategy", str(i["missionId"])), body: i["content"] }, i["dry_run"]);
+    },
+    async plune_report_request(i) {
+      return write({ method: "POST", path: path("/v1/missions/:id/report", str(i["missionId"])), body: {} }, i["dry_run"]);
+    },
+    async plune_discover_tools(i) {
+      const names = i["names"] ?? [];
+      const unknown = names.filter((n) => !isPluneToolName(n));
+      if (unknown.length > 0) return fail("invalid_input", `No such tool: ${unknown.join(", ")}. Call this tool without names to see what there is.`);
+      const refused = names.filter((n) => scope === "read" && pluneTool(n).write);
+      if (refused.length > 0) return fail("read_only_token", readScopeMessage(`${refused.join(", ")} cannot be switched on`));
+      for (const n of names) revealed.add(n);
+      const words = (i["query"] ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+      const visible = visibleTools();
+      const available = PLUNE_TOOLS.filter((t) => !visible.includes(t.name) && !(scope === "read" && t.write)).filter((t) => words.every((w) => `${t.name} ${t.title} ${t.description}`.toLowerCase().includes(w))).map((t) => ({ name: t.name, title: t.title, description: t.description, write: t.write }));
+      return { revealed: names, available, visible };
+    },
+    async plune_cases_update(i) {
+      const cases = i["cases"];
+      return batch(
+        cases.map((c) => ({ method: "PATCH", path: path("/v1/test-cases/:id", c.id), body: c.changes })),
+        i["dry_run"],
+        (_b, n) => cases[n]?.id
+      );
+    },
+    async plune_run_create(i) {
+      return write({ method: "POST", path: "/v1/runs", body: i["run"] }, i["dry_run"]);
+    },
+    async plune_results_write(i) {
+      const results = i["results"];
+      const req = {
+        method: "POST",
+        path: path("/v1/runs/:id/results", str(i["runId"])),
+        body: withoutUndefined({ results, combination: i["combination"], configuration: i["configuration"] })
+      };
+      if (i["dry_run"] === true) return { dryRun: true, requested: results.length, applied: 0, requests: [planned(req)] };
+      const report = asRecord((await call(req)).body);
+      const accepted = asRecord(report["counts"])["accepted"];
+      return { dryRun: false, requested: results.length, applied: typeof accepted === "number" ? accepted : 0, report };
+    },
+    async plune_endpoint_propose(i) {
+      return batch(
+        i["endpoints"].map((e) => ({ method: "POST", path: "/v1/review-items/endpoints", body: withoutUndefined(e) })),
+        i["dry_run"],
+        (b) => asRecord(b)["id"]
+      );
+    },
+    async plune_api_request(i) {
+      const method = str(i["method"]);
+      const p = safePath(opts.apiUrl, str(i["path"]));
+      if (p === void 0) return fail("invalid_input", `path must be a path under /v1 on ${new URL(opts.apiUrl).origin}, e.g. /v1/suites \u2014 no host, no dot segments, no query (use query)`);
+      const query = i["query"];
+      const req = withoutUndefined({ method, path: p, query, body: i["body"] });
+      if (i["dry_run"] === true) return { dryRun: true, request: planned(req) };
+      const confirm = i["confirm"];
+      if (isDeletion(req)) {
+        const t = now();
+        for (const [k, v] of confirms) if (v.expires <= t) confirms.delete(k);
+        if (confirm === void 0) {
+          const value = (0, import_node_crypto.randomBytes)(24).toString("base64url");
+          confirms.set(value, { fingerprint: fingerprint(req), expires: t + CONFIRM_TTL_MS });
+          return {
+            preview: {
+              action: "delete",
+              method,
+              path: p,
+              confirm: value,
+              expiresInSeconds: CONFIRM_TTL_MS / 1e3,
+              note: "Nothing was sent. Repeat the same call with confirm to send it. The platform refuses an agent any deletion (agent_cannot_delete, bulk_delete_needs_person): a person deletes from the dashboard."
+            }
+          };
+        }
+        const held = confirms.get(confirm);
+        confirms.delete(confirm);
+        if (held === void 0 || held.fingerprint !== fingerprint(req))
+          return fail("confirm_invalid", "confirm is unknown, expired, used, or for another request \u2014 repeat the call without it to get a new preview");
+      } else if (confirm !== void 0) {
+        req.query = { ...query, confirm };
+      }
+      const res = await call(req);
+      return { status: res.status, body: res.body };
+    }
+  };
+  return {
+    sessionId,
+    scope: () => scope,
+    visibleTools,
+    async execute(name, input) {
+      const handler = isPluneToolName(name) ? handlers[name] : void 0;
+      if (handler === void 0) return fail("unknown_tool", `No such tool: ${name}.`);
+      const tool = pluneTool(name);
+      const parsed = tool.input.safeParse(input ?? {});
+      if (!parsed.success) return fail("invalid_input", `The input does not fit: ${zodMessage(parsed.error)}`);
+      const args = parsed.data;
+      const writes = name === "plune_api_request" ? rawWrites(str(args["method"]), str(args["path"])) : tool.write;
+      if (writes && scope === "read" && args["dry_run"] !== true) return fail("read_only_token", readScopeMessage(`${name} is refused before any request`));
+      try {
+        const out = await handler(args);
+        return "ok" in out && typeof out["ok"] === "boolean" && ("error" in out || "data" in out) ? out : { ok: true, data: out };
+      } catch (err) {
+        return { ok: false, error: errorOf(err) };
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BATCH_MAX,
+  CONFIRM_TTL_MS,
+  MAX_VISIBLE_TOOLS,
+  PLUNE_TOOLS,
+  PLUNE_TOOL_NAMES,
+  PluneApiError,
+  PluneNetworkError,
+  createPluneToolExecutor,
+  defaultVisibleTools,
+  isPluneToolName,
+  pluneTool
+});