@unbrained/pm-cli 2026.6.5 → 2026.6.7

package/dist/mcp/server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bca7578e-84fd-5024-bf68-3518ff6f4192")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="79898dcc-efb2-588b-9a84-bda479483130")}catch(e){}}();
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { activateExtensions, loadExtensions, runActiveCommandHandler, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, } from "../core/extensions/index.js";
@@ -8,12 +8,15 @@ import { pathExists } from "../core/fs/fs-utils.js";
 import { projectMutationResult } from "../core/output/mutation-projection.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { decodeHtmlEntitiesInOptions } from "../core/shared/html-entity-decode.js";
+import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
 import { asRecordClone } from "../core/shared/primitives.js";
+import { createSerialQueue } from "../core/shared/serial-queue.js";
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { normalizeListOptions, normalizeUpdateOptions } from "../cli/registration-helpers.js";
 import { UPDATE_COMMANDER_STRING_OPTION_CONTRACTS } from "../sdk/cli-contracts/commander-mutation-options.js";
-import { runActivity, runAggregate, runAppend, runClaim, runClose, runCloseMany, runComments, runContracts, runContext, runCreate, runConfig, runDelete, runDeps, runDocs, runExtension, runFiles, runFilesDiscover, runGc, runGet, runHealth, runHistory, runHistoryRedact, runHistoryRepair, runInit, runLearnings, runList, runNotes, runPlan, runRelease, runSchemaAddStatus, runSchemaAddType, runSchemaList, runSchemaRemoveStatus, runSchemaRemoveType, runSchemaShow, runSearch, runStats, runTest, runTestAll, runUpdate, runUpdateMany, runUpgrade, runValidate, } from "../cli/commands/index.js";
+import { PM_TOOL_ACTIONS } from "../sdk/cli-contracts/enum-contracts.js";
+import { runActivity, runAggregate, runAppend, runClaim, runClose, runCloseMany, runComments, runContracts, runContext, runCreate, runCopy, runConfig, runDelete, runDeps, runDocs, runExtension, runFiles, runFilesDiscover, runGc, runGet, runHealth, runHistory, runHistoryCompact, runHistoryRedact, runHistoryRepair, runInit, runLearnings, runList, runNotes, runPlan, runRelease, runSchemaAddStatus, runSchemaAddType, runSchemaList, runSchemaRemoveStatus, runSchemaRemoveType, runSchemaShow, runSearch, runStats, runTelemetry, runTest, runTestAll, runUpdate, runUpdateMany, runUpgrade, runValidate, } from "../cli/commands/index.js";
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 function resolvePmPackageRoot() {
     return fileURLToPath(new URL("../..", import.meta.url));
@@ -43,6 +46,11 @@ const idSchema = {
     type: "string",
     description: "pm item id, for example pm-abc1.",
 };
+// pm-fd8n: derive the pm_run action enumeration from the canonical
+// PM_TOOL_ACTIONS contract instead of a hand-maintained prose list, so the
+// MCP-facing description can never drift from the actual supported actions.
+const PM_RUN_ACTION_DESCRIPTION = `Operation name (one of): ${PM_TOOL_ACTIONS.join(", ")}. ` +
+    "Package-owned actions (for example calendar/templates/guide/dedupe-audit/normalize/reindex/comments-audit/completion/test-runs-list/test-runs-status/test-runs-logs/test-runs-stop/test-runs-resume) are available dynamically when installed.";
 function objectSchema(properties, required = []) {
     return {
         ...TOOL_SCHEMA_BASE,
@@ -60,7 +68,7 @@ const TOOLS = [
         inputSchema: objectSchema({
             action: {
                 type: "string",
-                description: "Operation name: init, context, list, get, search, create, update, delete, claim, release, close, close-many, comments, notes, learnings, files, files-discover, docs, deps, test, test-all, validate, health, contracts, config, activity, aggregate, extension, extension-reload, package, package-install, package-catalog, install, upgrade, history, schema, stats, append, update-many, gc. Package-owned actions (for example calendar/templates/guide/dedupe-audit/normalize/reindex/comments-audit/completion/test-runs-list/test-runs-status/test-runs-logs/test-runs-stop/test-runs-resume) are available dynamically when installed.",
+                description: PM_RUN_ACTION_DESCRIPTION,
             },
             id: idSchema,
             query: { type: "string", description: "Search query for action=search." },
@@ -139,6 +147,16 @@ const TOOLS = [
             options: { type: "object", description: "Create options. title and description are required." },
         }, ["options"]),
     },
+    {
+        name: "pm_copy",
+        description: "Copy an existing pm item into a new id while resetting lifecycle fields. " +
+            "Output is compact by default (changed_fields replaced with changed_field_count); pass fullChangedFields=true for the full changed_fields array.",
+        inputSchema: objectSchema({
+            id: idSchema,
+            fullChangedFields: { type: "boolean", description: "Return full changed_fields instead of changed_field_count." },
+            options: { type: "object", description: "Copy options such as title override, author, and message." },
+        }, ["id"]),
+    },
     {
         name: "pm_update",
         description: "Update pm item metadata/body/dependencies/log seeds natively. " +
@@ -161,14 +179,14 @@ const TOOLS = [
     },
     {
         name: "pm_close",
-        description: "Close a pm item with a reason and optional close validation. " +
+        description: "Close a pm item with optional close reason and optional close validation (reason requirement follows governance settings). " +
             "Output is compact by default (changed_fields replaced with changed_field_count); pass fullChangedFields=true for the full changed_fields array.",
         inputSchema: objectSchema({
             id: idSchema,
-            reason: { type: "string" },
+            reason: { type: "string", description: "Close reason text when provided or required by governance settings." },
             fullChangedFields: { type: "boolean", description: "Return full changed_fields instead of changed_field_count." },
             options: { type: "object" },
-        }, ["id", "reason"]),
+        }, ["id"]),
     },
     {
         name: "pm_comments",
@@ -187,6 +205,21 @@ const TOOLS = [
         description: "List, add, or remove linked docs for a pm item.",
         inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, ["id"]),
     },
+    {
+        name: "pm_notes",
+        description: "List or add structured notes on a pm item. Use options.add to append a note; omit it to list existing notes.",
+        inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, ["id"]),
+    },
+    {
+        name: "pm_learnings",
+        description: "List or add learnings on a pm item. Use options.add to capture a learning/insight; omit it to list existing learnings.",
+        inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, ["id"]),
+    },
+    {
+        name: "pm_deps",
+        description: "List, add, or remove dependencies for a pm item. Use options.add to declare a dependency and options.remove to drop one; omit both to list current dependencies.",
+        inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, ["id"]),
+    },
     {
         name: "pm_test",
         description: "List, add, remove, or run linked tests for a pm item.",
@@ -218,6 +251,62 @@ const TOOLS = [
         }),
     },
 ];
+// pm-qxwu: TOOL_SCHEMA_BASE keeps additionalProperties:true so legitimate
+// passthrough keeps working, which means a typo'd top-level arg (e.g.
+// "fullChangedField" missing the trailing "s") is silently swallowed and the
+// agent gets default behavior with no signal. We precompute the declared
+// top-level property keys for each tool and, on every tools/call, warn (without
+// rejecting) when an unexpected top-level key appears. The warning is surfaced
+// to stderr and additively in structuredContent.warnings.
+const TOOL_DECLARED_KEYS = new Map(TOOLS.map((tool) => {
+    const schema = tool.inputSchema;
+    const properties = schema.properties ?? {};
+    return [tool.name, Object.keys(properties)];
+}));
+function nearestDeclaredKey(unexpected, declared) {
+    // Cheap did-you-mean: budget grows with key length but stays small so we only
+    // suggest genuine near-misses (a single typo / transposition for short keys).
+    const limit = Math.max(1, Math.min(3, Math.floor(unexpected.length / 4) + 1));
+    let best;
+    for (const candidate of declared) {
+        const distance = levenshteinDistanceWithinLimit(unexpected, candidate, limit);
+        if (distance === null) {
+            continue;
+        }
+        if (best === undefined || distance < best.distance) {
+            best = { key: candidate, distance };
+        }
+    }
+    return best?.key;
+}
+// pm_run is the explicit catch-all passthrough tool: extension/package actions
+// accept arbitrary top-level keys (see extensionOptionsFromArgs), so unexpected
+// keys there are by-design rather than typos and must not be flagged.
+const UNEXPECTED_KEY_WARNING_EXEMPT_TOOLS = new Set(["pm_run"]);
+function detectUnexpectedTopLevelKeys(toolName, args) {
+    if (typeof args !== "object" || args === null || Array.isArray(args)) {
+        return [];
+    }
+    if (UNEXPECTED_KEY_WARNING_EXEMPT_TOOLS.has(toolName)) {
+        return [];
+    }
+    const declared = TOOL_DECLARED_KEYS.get(toolName);
+    if (declared === undefined) {
+        return [];
+    }
+    const declaredSet = new Set(declared);
+    const warnings = [];
+    for (const key of Object.keys(args)) {
+        if (declaredSet.has(key)) {
+            continue;
+        }
+        const suggestion = nearestDeclaredKey(key, declared);
+        warnings.push(suggestion !== undefined
+            ? `Unexpected top-level argument "${key}" for ${toolName} (did you mean "${suggestion}"?). It was passed through unchanged; declared arguments are: ${declared.join(", ")}.`
+            : `Unexpected top-level argument "${key}" for ${toolName}. It was passed through unchanged; declared arguments are: ${declared.join(", ")}.`);
+    }
+    return warnings;
+}
 function readString(args, key) {
     const value = args[key];
     return typeof value === "string" && value.trim().length > 0 ? value : undefined;
@@ -562,6 +651,16 @@ async function runAction(args) {
             const { changedFields, runnerOptions } = withMutationCompaction(args, options);
             return projectMutationResult(await runCreate(runnerOptions, global), { changedFields });
         }
+        case "copy": {
+            const { changedFields, runnerOptions } = withMutationCompaction(args, options);
+            const copyOptions = {
+                ...runnerOptions,
+                ...(runnerOptions.title === undefined && typeof args.title === "string" ? { title: args.title } : {}),
+                ...(runnerOptions.message === undefined && typeof args.message === "string" ? { message: args.message } : {}),
+                ...(runnerOptions.author === undefined && typeof args.author === "string" ? { author: args.author } : {}),
+            };
+            return projectMutationResult(await runCopy(id ?? readRequiredString(copyOptions, "id"), copyOptions, global), { changedFields });
+        }
         case "update": {
             const { changedFields, runnerOptions } = withMutationCompaction(args, options);
             return projectMutationResult(await runUpdate(id ?? readRequiredString(runnerOptions, "id"), runnerOptions, global), { changedFields });
@@ -572,7 +671,11 @@ async function runAction(args) {
             return runRelease(id ?? readRequiredString(options, "id"), force, global, options);
         case "close": {
             const { changedFields, runnerOptions } = withMutationCompaction(args, options);
-            return projectMutationResult(await runClose(id ?? readRequiredString(runnerOptions, "id"), readRequiredString(args, "reason"), runnerOptions, global), { changedFields });
+            const closeReason = readString(args, "reason") ??
+                readString(args, "text") ??
+                readString(runnerOptions, "reason") ??
+                readString(runnerOptions, "text");
+            return projectMutationResult(await runClose(id ?? readRequiredString(runnerOptions, "id"), closeReason, runnerOptions, global), { changedFields });
         }
         case "comments": {
             const commentOptions = { ...options };
@@ -598,6 +701,15 @@ async function runAction(args) {
             return runTest(id ?? readRequiredString(options, "id"), options, global);
         case "test-all":
             return runTestAll(options, global);
+        case "telemetry":
+            return runTelemetry({
+                subcommand: readString(args, "subcommand") ?? readString(options, "subcommand"),
+                limit: typeof args.limit === "number" && Number.isFinite(args.limit)
+                    ? args.limit
+                    : typeof options.limit === "number" && Number.isFinite(options.limit)
+                        ? options.limit
+                        : readString(args, "limit") ?? readString(options, "limit"),
+            }, global);
         case "validate":
             return runValidate(options, global);
         case "health":
@@ -641,6 +753,8 @@ async function runAction(args) {
             return runHistoryRedact(id ?? readRequiredString(options, "id"), options, global);
         case "history-repair":
             return runHistoryRepair(id ?? readRequiredString(options, "id"), options, global);
+        case "history-compact":
+            return runHistoryCompact(id ?? readRequiredString(options, "id"), options, global);
         case "plan": {
             const subcommand = readRequiredString(options, "subcommand");
             const planRecord = options;
@@ -729,7 +843,7 @@ async function runAction(args) {
             }, global);
         }
         case "stats":
-            return runStats(global);
+            return runStats(global, { storage: options.storage === true });
         case "append": {
             const { changedFields, runnerOptions } = withMutationCompaction(args, options);
             return projectMutationResult(await runAppend(id ?? readRequiredString(runnerOptions, "id"), runnerOptions, global), { changedFields });
@@ -762,6 +876,7 @@ const HANDLERS = {
     pm_list: (args) => runAction({ ...args, action: "list" }),
     pm_get: (args) => runAction({ ...args, action: "get" }),
     pm_create: (args) => runAction({ ...args, action: "create" }),
+    pm_copy: (args) => runAction({ ...args, action: "copy" }),
     pm_update: (args) => runAction({ ...args, action: "update" }),
     pm_claim: (args) => runAction({ ...args, action: "claim" }),
     pm_release: (args) => runAction({ ...args, action: "release" }),
@@ -769,13 +884,19 @@ const HANDLERS = {
     pm_comments: (args) => runAction({ ...args, action: "comments" }),
     pm_files: (args) => runAction({ ...args, action: "files" }),
     pm_docs: (args) => runAction({ ...args, action: "docs" }),
+    pm_notes: (args) => runAction({ ...args, action: "notes" }),
+    pm_learnings: (args) => runAction({ ...args, action: "learnings" }),
+    pm_deps: (args) => runAction({ ...args, action: "deps" }),
     pm_test: (args) => runAction({ ...args, action: "test" }),
     pm_validate: (args) => runAction({ ...args, action: "validate" }),
     pm_health: (args) => runAction({ ...args, action: "health" }),
     pm_contracts: (args) => runAction({ ...args, action: "contracts" }),
     pm_plan: (args) => runAction({ ...args, action: "plan" }),
 };
-function resultContent(result) {
+function resultContent(result, warnings) {
+    // pm-qxwu: warnings is additive — existing fields (content, structuredContent.result)
+    // are never removed or renamed. The warnings array only appears when non-empty.
+    const structuredContent = warnings !== undefined && warnings.length > 0 ? { result, warnings } : { result };
     return {
         content: [
             {
@@ -783,7 +904,7 @@ function resultContent(result) {
                 text: JSON.stringify(result, null, 2),
             },
         ],
-        structuredContent: { result },
+        structuredContent,
     };
 }
 function errorContent(error) {
@@ -811,10 +932,10 @@ export async function handleRequest(request) {
             serverInfo: { name: "pm-mcp", version: "1.0.0" },
             instructions: "You have access to native pm CLI tools for git-based project management. " +
                 "Use pm_context or pm_search before creating new work. " +
-                "Prefer narrow tools (pm_context, pm_list, pm_get, pm_search, pm_create, pm_update, pm_claim, pm_release, pm_close, pm_comments, pm_files, pm_docs, pm_test, pm_validate, pm_health, pm_contracts, pm_plan) over pm_run when they cover the operation. " +
+                "Prefer narrow tools (pm_context, pm_list, pm_get, pm_search, pm_create, pm_copy, pm_update, pm_claim, pm_release, pm_close, pm_comments, pm_files, pm_docs, pm_notes, pm_learnings, pm_deps, pm_test, pm_validate, pm_health, pm_contracts, pm_plan) over pm_run when they cover the operation. " +
                 "Use pm_plan for agent harness Plan workflows: it provides Codex/Claude/Cursor-style planning with durable steps, dependencies, decisions, discoveries, validation, and materialization. " +
-                "Use pm_run with an explicit action for package-owned operations (calendar/templates/guide/dedupe-audit/normalize/reindex/comments-audit/completion/test-runs-list/test-runs-status/test-runs-logs/test-runs-stop/test-runs-resume), plus activity, aggregate, history, stats, append, notes, learnings, test-all, and gc. " +
-                "Use history-redact for audited history-stream redaction workflows, and history-repair to re-anchor a drifted history chain so pm health/validate report ok. " +
+                "Use pm_run with an explicit action for package-owned operations (calendar/templates/guide/dedupe-audit/normalize/reindex/comments-audit/completion/test-runs-list/test-runs-status/test-runs-logs/test-runs-stop/test-runs-resume), plus activity, aggregate, history, stats, append, test-all, and gc. " +
+                "Use history-redact for audited history-stream redaction workflows, history-repair to re-anchor a drifted history chain, and history-compact to checkpoint/prune long history streams while preserving replay integrity. " +
                 "Set author to 'claude-code-agent' on all mutations. " +
                 "Do not pass path during real repository tracking — only pass path for sandbox or test runs.",
         };
@@ -836,8 +957,14 @@ export async function handleRequest(request) {
         // affected; decoding at the MCP boundary normalizes the agent path while
         // leaving normal text untouched.
         const args = decodeHtmlEntitiesInOptions(asRecordClone(params.arguments));
+        // pm-qxwu: non-breaking detection of typo'd / unexpected top-level keys.
+        // additionalProperties stays true so passthrough still works; we only warn.
+        const warnings = detectUnexpectedTopLevelKeys(name, args);
+        for (const warning of warnings) {
+            console.error(`[pm-mcp] ${warning}`);
+        }
         const result = await withCwd(args.cwd, () => handler(args));
-        return resultContent(result);
+        return resultContent(result, warnings);
     }
     throw new PmCliError(`Unsupported MCP method: ${request.method ?? "(missing)"}`, 64);
 }
@@ -849,40 +976,58 @@ function writeError(id, error) {
     const message = error instanceof Error ? error.message : String(error);
     process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } })}\n`);
 }
+// pm-3puw: parse one JSON-RPC line, dispatch it, and write the response. Kept
+// as a standalone async unit so the stdio loop can enqueue it onto a serial
+// queue (process lines in arrival order) and tests can drive it directly.
+export async function processRpcLine(line) {
+    if (line.trim().length === 0) {
+        return;
+    }
+    let request;
+    try {
+        request = JSON.parse(line);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeError(null, new PmCliError(`Parse error: ${message}`, -32700));
+        return;
+    }
+    if (typeof request !== "object" || request === null || Array.isArray(request)) {
+        writeError(null, new PmCliError("Invalid JSON-RPC request: expected an object", -32600));
+        return;
+    }
+    const shouldRespond = Object.prototype.hasOwnProperty.call(request, "id");
+    try {
+        const result = await handleRequest(request);
+        if (shouldRespond && result !== undefined) {
+            writeResponse(request.id, result);
+        }
+    }
+    catch (error) {
+        if (!shouldRespond) {
+            return;
+        }
+        if (request.method === "tools/call") {
+            writeResponse(request.id, errorContent(error));
+        }
+        else {
+            writeError(request.id, error);
+        }
+    }
+}
 export function startMcpServer() {
     const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+    // pm-3puw: serialize line handling so pipelined requests are processed in
+    // arrival order. The previous fire-and-forget handler ran requests
+    // concurrently, so a client that pipelined two mutations on the same item
+    // (without awaiting the first response) hit a lock conflict on the second.
+    const queue = createSerialQueue();
     rl.on("line", (line) => {
-        void (async () => {
-            if (line.trim().length === 0) {
-                return;
-            }
-            let request;
-            try {
-                request = JSON.parse(line);
-            }
-            catch (error) {
-                writeError(null, error);
-                return;
-            }
-            try {
-                const result = await handleRequest(request);
-                if (result !== undefined) {
-                    writeResponse(request.id, result);
-                }
-            }
-            catch (error) {
-                if (request.method === "tools/call") {
-                    writeResponse(request.id, errorContent(error));
-                }
-                else {
-                    writeError(request.id, error);
-                }
-            }
-        })();
+        void queue.enqueue(() => processRpcLine(line));
     });
 }
 if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
     startMcpServer();
 }
 //# sourceMappingURL=server.js.map
-//# debugId=bca7578e-84fd-5024-bf68-3518ff6f4192
+//# debugId=79898dcc-efb2-588b-9a84-bda479483130