@unbrained/pm-cli 2026.7.17 → 2026.7.18

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="6ef4aa9a-1dd1-5723-a17e-ddc2fc40213e")}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]="eceb55d4-5d10-5d1f-b060-4ea493f70d9d")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 import path from "node:path";
 import { createEmptyExtensionCommandRegistry, createEmptyExtensionHookRegistry, createEmptyExtensionParserRegistry, createEmptyExtensionPreflightRegistry, createEmptyExtensionRegistrationRegistry, createEmptyExtensionRendererRegistry, createEmptyExtensionServiceRegistry, } from "../core/extensions/extension-registries.js";
@@ -19,8 +19,6 @@ import { createSerialQueue } from "../core/shared/serial-queue.js";
 import { resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.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 "./cli-contracts/commander-mutation-options.js";
 import { clearWorkspaceContractsCache, memoizeWorkspaceExtensionRegistrations, } from "./workspace-contracts-cache.js";
 export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";
 import { runActivity, runAggregate, runAppend, runClaim, runClaimNext, runClose, runCloseMany, runComments, runContext, runCopy, runCreate, runDelete, runFocus, runGet, runHistory, runLearnings, runNext, runNotes, runPlan, runRestore, runRelease, runUpdate, runUpdateMany, runUpgrade, } from "../cli/commands/index.js";
@@ -33,9 +31,10 @@ import { runInit } from "./init.js";
 import { runProfileApply, runProfileLint, runProfileList, runProfileShow, } from "./profile.js";
 import { runHistoryRedact, } from "./history-redact.js";
 import { runMcpHistoryCompactAction, runMcpHistoryRepairAction, } from "./history-mcp.js";
-import { isRuntimeRecord as isRecord, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, } from "./runtime-input.js";
+import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, readRuntimeStringArray as readStringArray, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction, } from "./runtime-input.js";
 import { runDeps } from "./dependencies.js";
 import { runDocs } from "./docs.js";
+import { runGraph, } from "./graph/run.js";
 import { runFiles, runFilesDiscover } from "./files.js";
 import { runContracts, } from "../cli/commands/contracts.js";
 import { runList } from "./query/list.js";
@@ -172,6 +171,10 @@ export class PmClient {
     deps(id, options = {}) {
         return this.runTyped("deps", { id, options });
     }
+    /** Run bounded workspace graph traversal, analytics, or governance-audit queries. */
+    graph(subcommand, ids = {}, options = {}) {
+        return this.runTyped("graph", { subcommand, ...ids, options });
+    }
     /** Append markdown/body text to an item through the mutation pipeline. */
     append(id, body, options = {}) {
         return this.runTyped("append", {
@@ -638,6 +641,10 @@ export function docs(id, options = {}, clientOptions = {}) {
 export function deps(id, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).deps(id, options);
 }
+/** Run bounded workspace graph queries without constructing a reusable client. */
+export function graph(subcommand, ids = {}, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).graph(subcommand, ids, options);
+}
 /** Append markdown/body text to an item without constructing a reusable client. */
 export function append(id, body, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).append(id, body, options);
@@ -941,230 +948,6 @@ export function readRequiredString(args, key) {
     }
     return value;
 }
-function globalOptions(args) {
-    return {
-        json: true,
-        quiet: true,
-        path: readString(args, "path"),
-        noExtensions: args.noExtensions === true || args.no_extensions === true,
-        noPager: true,
-    };
-}
-const ARRAY_TO_CSV_FIELDS = new Set([
-    "tags",
-    "blockedBy",
-    "blocked_by",
-    "skills",
-    "fields",
-]);
-const SCALAR_TO_ARRAY_FIELDS = new Set([
-    "comment",
-    "note",
-    "learning",
-    "reminder",
-    "event",
-    "dep",
-    "depRemove",
-    "dep_remove",
-    "file",
-    "doc",
-    "test",
-    "unset",
-    "addGlob",
-    "add_glob",
-    "migrate",
-    "envSet",
-    "env_set",
-    "envClear",
-    "env_clear",
-]);
-// Actions where the linked-resource fields `add` and `remove` are string[] arrays.
-// For other actions (comments/notes/learnings) `add` and `remove` are scalar strings
-// and must NOT be auto-promoted.
-const ARRAY_ADD_REMOVE_ACTIONS = new Set([
-    "files",
-    "files-discover",
-    "docs",
-    "test",
-    "test-all",
-]);
-const LIFECYCLE_AUTHOR_ALIAS_ACTIONS = new Set([
-    "claim",
-    "release",
-    "start-task",
-    "pause-task",
-    "close-task",
-]);
-function normalizeMcpOptionsArrays(options, action) {
-    const result = {};
-    const promoteAddRemove = action !== undefined && ARRAY_ADD_REMOVE_ACTIONS.has(action);
-    const preserveStandaloneNote = action === "files" || action === "files-discover" || action === "docs";
-    for (const [key, value] of Object.entries(options)) {
-        if (Array.isArray(value) && ARRAY_TO_CSV_FIELDS.has(key)) {
-            result[key] = value.join(",");
-            continue;
-        }
-        if (key === "note" && preserveStandaloneNote) {
-            result[key] = value;
-            continue;
-        }
-        if (typeof value === "string" && SCALAR_TO_ARRAY_FIELDS.has(key)) {
-            result[key] = [value];
-            continue;
-        }
-        if (typeof value === "string" &&
-            promoteAddRemove &&
-            (key === "add" || key === "remove")) {
-            result[key] = [value];
-            continue;
-        }
-        result[key] = value;
-    }
-    return result;
-}
-function optionsWithAuthor(args, action) {
-    const baseOptions = asRecordClone(args.options);
-    const hoistedTopLevel = {};
-    const hoistKey = (key) => {
-        if (baseOptions[key] !== undefined || args[key] === undefined) {
-            return;
-        }
-        hoistedTopLevel[key] = args[key];
-    };
-    if (action === "list") {
-        hoistKey("status");
-        hoistKey("type");
-        hoistKey("tag");
-        hoistKey("priority");
-        hoistKey("limit");
-        hoistKey("offset");
-    }
-    else if (action === "search") {
-        hoistKey("mode");
-        hoistKey("status");
-        hoistKey("type");
-        hoistKey("tag");
-        hoistKey("priority");
-        hoistKey("limit");
-    }
-    else if (action === "create") {
-        hoistKey("title");
-        hoistKey("type");
-        hoistKey("status");
-        hoistKey("description");
-        hoistKey("body");
-        hoistKey("priority");
-        hoistKey("tags");
-        hoistKey("parent");
-        hoistKey("createMode");
-        hoistKey("create_mode");
-        hoistKey("allowMissingParent");
-    }
-    else if (action === "close") {
-        hoistKey("duplicateOf");
-    }
-    else if (action === "append") {
-        // pm-7u9j: the narrow pm_append tool declares `body` top-level; runAppend
-        // reads it from options, so hoist unless options.body already wins.
-        // (pm_schema/pm_config top-level args are consumed directly by runAction's
-        // schema/config cases, which read args before options — no hoist needed.)
-        hoistKey("body");
-    }
-    const options = normalizeMcpOptionsArrays({ ...hoistedTopLevel, ...baseOptions }, action);
-    const author = readString(args, "author");
-    const authorFromAssignee = action !== undefined && LIFECYCLE_AUTHOR_ALIAS_ACTIONS.has(action)
-        ? (readString(args, "assignee") ?? readString(options, "assignee"))
-        : undefined;
-    if (author && options.author === undefined) {
-        return { ...options, author };
-    }
-    if (authorFromAssignee && options.author === undefined) {
-        return { ...options, author: authorFromAssignee };
-    }
-    return options;
-}
-// GH-170 (pm-pfnx): the narrow pm_files/pm_docs tools spell the CLI --note flag
-// as `addNote` (the shared `note` parameter is the array-typed create/update
-// note seed). Translate it onto the runner's `note` option; an explicit
-// options.note (pm_run callers) wins.
-function withAddNoteOption(options) {
-    if (options.addNote === undefined) {
-        return options;
-    }
-    const next = { ...options };
-    if (next.note === undefined && typeof next.addNote === "string") {
-        next.note = next.addNote;
-    }
-    delete next.addNote;
-    return next;
-}
-function withFilesDiscoveryOptions(options) {
-    const next = { ...options };
-    if (next.discoveryNote !== undefined &&
-        next.note === undefined &&
-        typeof next.discoveryNote === "string") {
-        next.note = next.discoveryNote;
-    }
-    delete next.discover;
-    delete next.discoveryNote;
-    return next;
-}
-function normalizeActionName(value) {
-    const chunks = [];
-    let lastWasSeparator = true;
-    for (const character of value.trim().toLowerCase()) {
-        const isAlphaNumeric = (character >= "a" && character <= "z") ||
-            (character >= "0" && character <= "9");
-        if (isAlphaNumeric) {
-            chunks.push(character);
-            lastWasSeparator = false;
-            continue;
-        }
-        if (!lastWasSeparator) {
-            chunks.push("-");
-            lastWasSeparator = true;
-        }
-    }
-    if (chunks.at(-1) === "-") {
-        chunks.pop();
-    }
-    return chunks.join("");
-}
-function normalizeCommandPath(value) {
-    return value.trim().toLowerCase().split(/\s+/).filter(Boolean).join(" ");
-}
-function readStringArray(value) {
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    return value
-        .map((entry) => String(entry))
-        .filter((entry) => entry.length > 0);
-}
-function extensionOptionsFromArgs(args, options) {
-    const reserved = new Set([
-        "action",
-        "args",
-        "author",
-        "cwd",
-        "fullChangedFields",
-        "id",
-        "options",
-        "path",
-        "query",
-        "reason",
-        "target",
-    ]);
-    const passthrough = {};
-    for (const [key, value] of Object.entries(args)) {
-        if (!reserved.has(key)) {
-            passthrough[key] = value;
-        }
-    }
-    const normalizedOptions = { ...passthrough, ...options };
-    delete normalizedOptions.args;
-    return normalizedOptions;
-}
 // pm-bl6m / pm-zumn: every native MCP action runs inside an activation cycle that
 // mutates the process-global active extension registries (set globals -> run -> clear
 // globals in a finally). The stdio transport already processes JSON-RPC lines
@@ -1337,148 +1120,6 @@ async function withCwd(cwd, run) {
         process.chdir(previous);
     }
 }
-/** Mutation tools (create/update/close/append/update-many) return a verbose `changed_fields` array. On the agent path we drop it to a `changed_field_count` by default for token efficiency, restoring the full array only when the caller explicitly passes the MCP-level fullChangedFields=true control. Mutation options are forwarded unchanged so runtime fields named `full` remain valid user data. */
-function withMutationCompaction(args, options) {
-    return {
-        changedFields: args.fullChangedFields === true ? "full" : "compact",
-        idOnly: args.idOnly === true,
-        runnerOptions: { ...options },
-    };
-}
-function mutationListOptions(options) {
-    return {
-        type: readScalarString(options, "filterType"),
-        tag: readScalarString(options, "filterTag"),
-        priority: readScalarString(options, "filterPriority"),
-        deadlineBefore: readScalarString(options, "filterDeadlineBefore"),
-        deadlineAfter: readScalarString(options, "filterDeadlineAfter"),
-        updatedAfter: readScalarString(options, "filterUpdatedAfter"),
-        updatedBefore: readScalarString(options, "filterUpdatedBefore"),
-        createdAfter: readScalarString(options, "filterCreatedAfter"),
-        createdBefore: readScalarString(options, "filterCreatedBefore"),
-        ids: readScalarStringAllowBlank(options, "ids"),
-        assignee: readScalarString(options, "filterAssignee"),
-        assigneeFilter: readScalarString(options, "filterAssigneeFilter") ??
-            readScalarString(options, "filterAssignee_filter"),
-        parent: readScalarString(options, "filterParent"),
-        sprint: readScalarString(options, "filterSprint"),
-        release: readScalarString(options, "filterRelease"),
-        limit: readScalarString(options, "limit"),
-        offset: readScalarString(options, "offset"),
-    };
-}
-function closeManyOptionsFromFlat(options) {
-    return {
-        status: readString(options, "filterStatus"),
-        list: isRecord(options.list)
-            ? normalizeListOptions(options.list)
-            : mutationListOptions(options),
-        reason: readString(options, "reason"),
-        resolution: readString(options, "resolution"),
-        expectedResult: readString(options, "expectedResult") ??
-            readString(options, "expected_result") ??
-            readString(options, "expected"),
-        actualResult: readString(options, "actualResult") ??
-            readString(options, "actual_result") ??
-            readString(options, "actual"),
-        validateClose: readString(options, "validateClose") ??
-            readString(options, "validate_close"),
-        author: readString(options, "author"),
-        message: readString(options, "message"),
-        force: options.force === true ? true : undefined,
-        dryRun: options.dryRun === true || options.dry_run === true ? true : undefined,
-        rollback: readString(options, "rollback"),
-        checkpoint: options.checkpoint === false ||
-            options.noCheckpoint === true ||
-            options.no_checkpoint === true
-            ? false
-            : undefined,
-    };
-}
-const UPDATE_MANY_FLAT_CONTROL_KEYS = new Set([
-    "filterStatus",
-    "filterType",
-    "filterTag",
-    "filterPriority",
-    "filterDeadlineBefore",
-    "filterDeadlineAfter",
-    "filterUpdatedAfter",
-    "filterUpdatedBefore",
-    "filterCreatedAfter",
-    "filterCreatedBefore",
-    "filterAssignee",
-    "filterAssigneeFilter",
-    "filterAssignee_filter",
-    "filterParent",
-    "filterSprint",
-    "filterRelease",
-    "ids",
-    "list",
-    "update",
-    "limit",
-    "offset",
-    "dryRun",
-    "dry_run",
-    "rollback",
-    "checkpoint",
-    "noCheckpoint",
-    "no_checkpoint",
-]);
-function updateManyUpdateOptionsFromFlat(options) {
-    const update = {};
-    for (const [key, value] of Object.entries(options)) {
-        if (UPDATE_MANY_FLAT_CONTROL_KEYS.has(key)) {
-            continue;
-        }
-        update[key] = value;
-    }
-    return normalizeMcpUpdateOptions(update);
-}
-function normalizeMcpUpdateOptions(options) {
-    const normalizedInput = normalizeMcpOptionsArrays(options, "update-many");
-    for (const contract of UPDATE_COMMANDER_STRING_OPTION_CONTRACTS) {
-        for (const key of contract.keys) {
-            const value = normalizedInput[key];
-            if (typeof value === "number" && Number.isFinite(value)) {
-                normalizedInput[key] = String(value);
-            }
-        }
-    }
-    return normalizeUpdateOptions(normalizedInput);
-}
-function updateManyOptionsFromFlat(options) {
-    if (isRecord(options.list) || isRecord(options.update)) {
-        const updateSource = isRecord(options.update)
-            ? options.update
-            : updateManyUpdateOptionsFromFlat(options);
-        return {
-            status: readScalarString(options, "filterStatus"),
-            list: isRecord(options.list)
-                ? normalizeListOptions(options.list)
-                : mutationListOptions(options),
-            update: normalizeMcpUpdateOptions(updateSource),
-            dryRun: options.dryRun === true || options.dry_run === true ? true : undefined,
-            rollback: readString(options, "rollback"),
-            checkpoint: options.checkpoint === false ||
-                options.noCheckpoint === true ||
-                options.no_checkpoint === true
-                ? false
-                : undefined,
-        };
-    }
-    return {
-        status: readScalarString(options, "filterStatus"),
-        list: mutationListOptions(options),
-        update: updateManyUpdateOptionsFromFlat(options),
-        dryRun: options.dryRun === true || options.dry_run === true ? true : undefined,
-        rollback: readString(options, "rollback"),
-        checkpoint: options.checkpoint === false ||
-            options.noCheckpoint === true ||
-            options.no_checkpoint === true
-            ? false
-            : undefined,
-    };
-}
 const WORKSPACE_CONTRACTS_CACHE_PRESERVING_ACTIONS = new Set([
     "activity",
     "aggregate",
@@ -1487,6 +1128,7 @@ const WORKSPACE_CONTRACTS_CACHE_PRESERVING_ACTIONS = new Set([
     "deps",
     "files-discover",
     "get",
+    "graph",
     "health",
     "history",
     "list",
@@ -2044,6 +1686,11 @@ async function runMcpCloseTaskAction(ctx) {
         release: releaseResult,
     };
 }
+/** Dispatch the graph action merging flat MCP parameters onto runner options. */
+function runMcpGraphAction(ctx) {
+    const merged = { ...ctx.args, ...ctx.options };
+    return runGraph(readRequiredString(merged, "subcommand"), readString(merged, "id") ?? ctx.id, readString(merged, "target"), graphOptionsFromFlat(merged), ctx.global);
+}
 const SDK_ACTION_HANDLERS = {
     init: (ctx) => runInit(readString(ctx.args, "prefix"), ctx.global, ctx.options),
     context: (ctx) => runContext(ctx.options, ctx.global),
@@ -2086,6 +1733,7 @@ const SDK_ACTION_HANDLERS = {
     upgrade: (ctx) => runUpgrade(readMcpTarget(ctx), ctx.options, ctx.global),
     delete: (ctx) => runDelete(requireMcpItemId(ctx), ctx.options, ctx.global),
     deps: (ctx) => runDeps(requireMcpItemId(ctx), ctx.options, ctx.global),
+    graph: runMcpGraphAction,
     "files-discover": (ctx) => runFilesDiscover(requireMcpItemId(ctx), ctx.options, ctx.global),
     history: (ctx) => runHistory(requireMcpItemId(ctx), ctx.options, ctx.global),
     "history-redact": (ctx) => runHistoryRedact(requireMcpItemId(ctx), ctx.options, ctx.global),
@@ -2161,4 +1809,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=6ef4aa9a-1dd1-5723-a17e-ddc2fc40213e
+//# debugId=eceb55d4-5d10-5d1f-b060-4ea493f70d9d