@unbrained/pm-cli 2026.8.17 → 2026.8.19

package/dist/cli/register-list-query.js

@@ -1,10 +1,11 @@
 
-!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]="0bcbdc33-3145-54cc-b4b6-10df50aef57a")}catch(e){}}();
-import { EXIT_CODE, PmCliError, renderRowsAsCsv, renderRowsAsTable, } from "../sdk/runtime-primitives.js";
+!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]="d3206ea9-3bf7-5e23-8b95-2a9078942b6f")}catch(e){}}();
+import { EXIT_CODE, PmCliError, readSettings, renderRowsAsCsv, renderRowsAsTable, resolvePmRoot, } from "../sdk/runtime-primitives.js";
+import { renderPmCommandAliasMigrationHint, resolvePmCommandAlias, } from "../sdk/cli-contracts.js";
 import { EVAL_QUERY_SET_SCHEMA_ID } from "../sdk/eval.js";
 import { applyContextIntentProjection } from "../sdk/context-intent-contracts.js";
-import { serializeNdjsonRows } from "../sdk/output.js";
-import { listMutationEvents, subscribeMutationEvents, } from "../sdk/mutation-events.js";
+import { serializeNdjsonRows, serializeNdjsonStream, } from "../sdk/output.js";
+import { listMutationEvents, subscribeMutationEventBatches, subscribeMutationEvents, } from "../sdk/mutation-events.js";
 import { runActivity } from "./commands/activity.js";
 import { runAggregate } from "./commands/aggregate.js";
 import { renderContextMarkdown, runContext, resolveContextOutputFormat, } from "./commands/context.js";
@@ -103,6 +104,14 @@ function registerContentAndGovernanceFilters(command) {
         .option("--filter-sprint-missing", "Show only items missing sprint")
         .option("--filter-release-missing", "Show only items missing release");
 }
+const CANONICAL_LIST_STATUS_VARIANTS = {
+    draft: { name: "list-draft", dependencyBlocked: false },
+    open: { name: "list-open", dependencyBlocked: false },
+    in_progress: { name: "list-in-progress", dependencyBlocked: false },
+    blocked: { name: "list-blocked", dependencyBlocked: true },
+    closed: { name: "list-closed", dependencyBlocked: false },
+    canceled: { name: "list-canceled", dependencyBlocked: false },
+};
 /** Resolve and validate the mutually exclusive list rendering modes. */
 function resolveRegisteredListOutputContext(options, globalOptions) {
     const streamMode = options.stream === true;
@@ -146,39 +155,63 @@ function renderRegisteredListResult(commandName, result, output) {
     }
 }
 async function runRegisteredListCommand(params) {
-    const globalOptions = getGlobalOptions(params.actionCommand);
+    const parsedGlobalOptions = getGlobalOptions(params.actionCommand);
+    const globalOptions = params.aliasContract
+        ? { ...parsedGlobalOptions, command: params.aliasContract.canonical }
+        : parsedGlobalOptions;
     const startedAt = Date.now();
-    if (params.options.all === true) {
-        throw new PmCliError("List --all was ambiguous and is no longer an alias for --no-truncate. Use `pm list --status all --no-truncate` for every status, or `pm list-all --no-truncate` for the dedicated all-status command.", EXIT_CODE.USAGE, {
-            code: "ambiguous_list_all",
-            examples: [
-                "pm list --status all --no-truncate",
-                "pm list-all --no-truncate",
-            ],
-        });
+    if (params.aliasContract?.lifecycle === "deprecated") {
+        const deprecationHints = await readSettings(resolvePmRoot(process.cwd(), globalOptions.path)).then((settings) => settings.ux.deprecation_hints);
+        if (deprecationHints) {
+            printError(renderPmCommandAliasMigrationHint(params.aliasContract));
+        }
     }
     const intentOptions = applyContextIntentProjection("list", params.options);
     const listOptions = normalizeListOptions(intentOptions);
-    applyDefaultListProjection(listOptions, params.name);
-    if (params.excludeTerminal)
-        listOptions.excludeTerminal = true;
-    if (params.name === "list" && listOptions.status === undefined) {
-        listOptions.status = "all";
+    let effectiveName = params.name;
+    let effectiveStatus = params.status;
+    let effectiveDependencyBlocked = params.dependencyBlocked === true;
+    let effectiveExcludeTerminal = params.excludeTerminal === true;
+    const requestedStatus = listOptions.status?.trim().toLowerCase();
+    const requestedVariant = params.name === "list" && requestedStatus !== undefined
+        ? CANONICAL_LIST_STATUS_VARIANTS[requestedStatus]
+        : undefined;
+    if (params.name === "list") {
+        if (params.options.all === true || requestedStatus === "all") {
+            effectiveName = "list-all";
+            effectiveExcludeTerminal = false;
+            listOptions.status = undefined;
+        }
+        else if (requestedStatus !== undefined && requestedVariant !== undefined) {
+            effectiveName = requestedVariant.name;
+            effectiveStatus = requestedStatus;
+            effectiveDependencyBlocked = requestedVariant.dependencyBlocked;
+            effectiveExcludeTerminal = false;
+            listOptions.status = undefined;
+        }
     }
-    listOptions.dependencyBlocked = params.dependencyBlocked;
+    applyDefaultListProjection(listOptions, effectiveName);
+    if (effectiveExcludeTerminal)
+        listOptions.excludeTerminal = true;
+    listOptions.dependencyBlocked = effectiveDependencyBlocked;
     const output = resolveRegisteredListOutputContext(intentOptions, globalOptions);
-    const result = await runList(params.dependencyBlocked ? undefined : params.status, listOptions, globalOptions);
-    renderRegisteredListResult(params.name, result, output);
+    const result = await runList(effectiveDependencyBlocked ? undefined : effectiveStatus, listOptions, globalOptions);
+    renderRegisteredListResult("list", result, output);
     if (globalOptions.profile) {
-        printError(`profile:command=${params.name} took_ms=${Date.now() - startedAt}`);
+        printError(`profile:command=list took_ms=${Date.now() - startedAt}`);
     }
 }
 function registerListCommand(program, descriptor) {
-    const { name, description, status, excludeTerminal, allowStatusFilter, dependencyBlocked, } = descriptor;
-    const command = program.command(name).description(description);
+    const { name, description, status, excludeTerminal, allowStatusFilter, dependencyBlocked, aliasContract, } = descriptor;
+    const command = program
+        .command(name, { hidden: aliasContract?.hidden === true })
+        .description(description);
     if (allowStatusFilter) {
         command.option("--status <value>", "Filter by status (repeatable or comma-separated; matches any; all selects every status)", collect);
     }
+    if (name === "list") {
+        command.option("--all", "Include every lifecycle status");
+    }
     command
         .option("--for <intent>", "Apply a declared context intent projection")
         .option("--token-budget <n>", "Override the selected intent's maximum estimated output tokens")
@@ -228,6 +261,7 @@ function registerListCommand(program, descriptor) {
             dependencyBlocked,
             options,
             actionCommand,
+            aliasContract,
         });
     });
     // Hidden pure snake_case underscore-duplicate alias (kept parse-functional).
@@ -235,7 +269,6 @@ function registerListCommand(program, descriptor) {
     addHiddenOption(command, "--assignee_filter <value>", "Alias for --assignee-filter");
     addHiddenOption(command, "--tree_depth <n>", "Alias for --tree-depth");
     addHiddenOption(command, "--token_budget <n>", "Alias for --token-budget");
-    addHiddenOption(command, "--all", "Removed ambiguous alias; emits migration guidance");
     // Singular alias so `--filter-estimate-missing` works (matches update-many spelling).
     addHiddenOption(command, "--filter-estimate-missing", "Alias for --filter-estimates-missing");
 }
@@ -301,9 +334,12 @@ async function runNextAction(options, actionCommand) {
 async function runSearchAction(keywords, options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
-    const intentOptions = applyContextIntentProjection("search", options);
+    const query = normalizeSearchKeywordsInput(keywords);
+    const intentOptions = applyContextIntentProjection("search", options, [
+        query,
+    ]);
     const searchOptions = normalizeSearchOptions(intentOptions);
-    const result = await runSearch(normalizeSearchKeywordsInput(keywords), {
+    const result = await runSearch(query, {
         ...searchOptions,
         mode: typeof searchOptions.mode === "string" &&
             searchOptions.mode.trim().length > 0
@@ -349,7 +385,7 @@ async function runEvalAction(options, command) {
 async function runGetAction(id, options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
-    const intentOptions = applyContextIntentProjection("get", options);
+    const intentOptions = applyContextIntentProjection("get", options, [id]);
     const result = await runGet(id, globalOptions, {
         depth: typeof intentOptions.depth === "string" ? intentOptions.depth : undefined,
         fields: typeof intentOptions.fields === "string"
@@ -411,6 +447,13 @@ function buildMutationEventOptions(options, pmRoot) {
     const harness = readRepeatableStringOption(options, "harness");
     const agentInstance = readRepeatableStringOption(options, "agentInstance");
     const provenanceFilter = readRepeatableStringOption(options, "provenanceFilter");
+    const rawCursorMode = typeof options.cursorMode === "string" ? options.cursorMode : undefined;
+    if (rawCursorMode !== undefined &&
+        rawCursorMode !== "batch" &&
+        rawCursorMode !== "row") {
+        throw new PmCliError("Events --cursor-mode must be batch or row.", EXIT_CODE.USAGE, { code: "invalid_event_cursor_mode" });
+    }
+    const cursorMode = rawCursorMode;
     return {
         pmRoot,
         since: typeof options.since === "string" ? options.since : undefined,
@@ -426,42 +469,76 @@ function buildMutationEventOptions(options, pmRoot) {
         ...(harness === undefined ? {} : { harness }),
         ...(agentInstance === undefined ? {} : { agentInstance }),
         ...(provenanceFilter === undefined ? {} : { provenanceFilter }),
+        cursorMode,
     };
 }
-async function runEventsAction(options, command) {
-    const globalOptions = getGlobalOptions(command);
-    const startedAt = Date.now();
-    const eventOptions = buildMutationEventOptions(options, globalOptions.path);
-    if (options.follow === true) {
-        if (options.provenanceSummary === true) {
-            throw new PmCliError("Events --provenance-summary is bounded to one page and cannot be combined with --follow.", EXIT_CODE.USAGE);
-        }
-        const intervalMs = typeof options.intervalMs === "string"
-            ? Number(options.intervalMs)
-            : undefined;
+/** Follows mutation events using either compatibility row cursors or the default batch-boundary trailer contract. */
+async function followMutationEvents(eventOptions, options, quiet) {
+    if (options.provenanceSummary === true) {
+        throw new PmCliError("Events --provenance-summary is bounded to one page and cannot be combined with --follow.", EXIT_CODE.USAGE);
+    }
+    const intervalMs = typeof options.intervalMs === "string"
+        ? Number(options.intervalMs)
+        : undefined;
+    if (eventOptions.cursorMode === "row") {
         for await (const event of subscribeMutationEvents({
             ...eventOptions,
             intervalMs,
         })) {
-            if (!globalOptions.quiet) {
+            if (!quiet) {
                 writeStdout(`${JSON.stringify(event)}\n`);
             }
         }
         return;
     }
+    for await (const page of subscribeMutationEventBatches({
+        ...eventOptions,
+        intervalMs,
+    })) {
+        if (!quiet) {
+            writeStdout(`${serializeNdjsonStream(page.events, {
+                count: page.count,
+                has_more: page.has_more,
+                next_cursor: page.next_cursor ?? null,
+                source: page.source,
+                heartbeat: page.count === 0,
+            })}\n`);
+        }
+    }
+}
+/** Serializes one bounded mutation-event page using its declared row or batch cursor mode. */
+function renderMutationEventPage(page) {
+    if (page.cursor_mode === "row") {
+        return serializeNdjsonRows(page.events);
+    }
+    return serializeNdjsonStream(page.events, {
+        count: page.count,
+        has_more: page.has_more,
+        next_cursor: page.next_cursor ?? null,
+        source: page.source,
+        ...(page.provenance_summary === undefined
+            ? {}
+            : { provenance_summary: page.provenance_summary }),
+    });
+}
+async function runEventsAction(options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const eventOptions = buildMutationEventOptions(options, globalOptions.path);
+    if (options.follow === true) {
+        await followMutationEvents(eventOptions, options, globalOptions.quiet === true);
+        return;
+    }
     const page = await listMutationEvents(eventOptions);
     setActiveCommandResult(page);
-    const rendered = serializeNdjsonRows([
-        ...page.events,
-        ...(page.provenance_summary === undefined
-            ? []
-            : [
-                {
-                    type: "provenance_summary",
-                    provenance_summary: page.provenance_summary,
-                },
-            ]),
-    ]);
+    if (globalOptions.json) {
+        printResult(page, globalOptions);
+        if (globalOptions.profile) {
+            printError(`profile:command=events took_ms=${Date.now() - startedAt}`);
+        }
+        return;
+    }
+    const rendered = renderMutationEventPage(page);
     if (!globalOptions.quiet && rendered.length > 0) {
         writeStdout(`${rendered}\n`);
     }
@@ -530,7 +607,7 @@ export function registerListQueryCommands(program, options) {
     const listCommandDescriptors = [
         {
             name: "list",
-            description: "List items across every lifecycle status with optional filters.",
+            description: "List active items with optional lifecycle-status and project filters.",
             excludeTerminal: true,
             allowStatusFilter: true,
         },
@@ -579,7 +656,13 @@ export function registerListQueryCommands(program, options) {
     ];
     for (const descriptor of listCommandDescriptors) {
         if (shouldRegister(descriptor.name)) {
-            registerListCommand(program, descriptor);
+            const aliasContract = resolvePmCommandAlias(descriptor.name);
+            registerListCommand(program, {
+                ...descriptor,
+                ...(aliasContract?.registration === "commander"
+                    ? { aliasContract }
+                    : {}),
+            });
         }
     }
     if (shouldRegister("aggregate")) {
@@ -775,6 +858,7 @@ export function registerListQueryCommands(program, options) {
             .option("--author <value>", "Filter by mutation author (repeatable or comma-separated)", collect)
             .option("--item <value>", "Filter by item or workspace stream id (repeatable or comma-separated)", collect)
             .option("--limit <n>", "Return at most 1,000 events (default: 100)")
+            .option("--cursor-mode <mode>", "Cursor framing: batch emits one terminal trailer (default); row preserves one cursor per event")
             .option("--full", "Include each complete authoritative history entry")
             .option("--provenance", "Include patch-free author, harness, instance, and extensible provenance")
             .option("--provenance-summary", "Include bounded provenance completeness counts")
@@ -838,4 +922,4 @@ export const _testOnlyRegisterListQuery = {
     parseListFormat,
 };
 //# sourceMappingURL=register-list-query.js.map
-//# debugId=0bcbdc33-3145-54cc-b4b6-10df50aef57a
+//# debugId=d3206ea9-3bf7-5e23-8b95-2a9078942b6f

package/dist/cli/register-mutation.js

@@ -1,5 +1,5 @@
 
-!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]="7feb0fe0-386c-56dc-afe1-e7b4ce1bc95a")}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]="07f3212f-c6d3-534e-8273-fae43a8fca18")}catch(e){}}();
 import { resolveBodyFileContent, EXIT_CODE, splitCommaList, PmCliError, createUnknownSubcommandError, } from "../sdk/runtime-primitives.js";
 import { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, } from "../sdk/cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES, PLAN_STEP_LINK_KIND_VALUES, } from "../types/index.js";
@@ -1233,7 +1233,7 @@ async function runDepsAction(id, options, command) {
 export function registerMutationCommands(program, registrationOptions = {}) {
     const createCommand = program
         .command("create")
-        .argument("[typeOrTitle]", 'Item title, or item type when a title follows (e.g. `pm create task "Fix bug"`)')
+        .argument("[type-or-title]", 'Item title, or item type when a title follows (e.g. `pm create task "Fix bug"`)')
         .argument("[title]", "Item title when the first argument is an item type")
         .description("Create a new project management item.");
     registerCommanderOptionContracts(createCommand, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS);
@@ -1530,10 +1530,10 @@ export function registerMutationCommands(program, registrationOptions = {}) {
     const planCommand = program
         .command("plan")
         .description("Agent-optimized Plan item workflow: create, manage steps, link dependencies, approve, and materialize.")
-        .argument("[subcommand]", "Plan subcommand: create|show|add-step|update-step|complete-step|block-step|reorder-step|remove-step|link|unlink|decision|discovery|validation|resume|approve|materialize")
+        .argument("[subcommand]", "Required; Plan subcommand: create|show|add-step|update-step|complete-step|block-step|reorder-step|remove-step|link|unlink|decision|discovery|validation|resume|approve|materialize")
         .argument("[id]", "Plan id (required for non-create subcommands); for create this may be the positional title")
-        .argument("[stepRef]", "Step reference: stable id (plan-step-001) or order integer")
-        .argument("[reorderTo]", "New order integer for reorder-step")
+        .argument("[step]", "Step reference: stable id (plan-step-001) or order integer")
+        .argument("[new-order]", "New order integer for reorder-step")
         .option("--title <value>", "Plan title")
         .option("--description <value>", "Plan description")
         .option("--scope <value>", "Short scope statement of the target change or investigation")
@@ -1740,7 +1740,7 @@ export function registerMutationCommands(program, registrationOptions = {}) {
         .action(runMergeAction);
     const schemaCommand = program
         .command("schema")
-        .argument("[subcommand]", "Schema subcommand: list, show, show-status, add/remove type/status/field, rename-type, rename-field, remap-status, or a custom item type name shorthand")
+        .argument("[subcommand]", "Required; Schema subcommand: list, show, show-status, add/remove type/status/field, rename-type, rename-field, remap-status, or a custom item type name shorthand")
         .argument("[name]", "Definition name, or source name for rename/remap migrations")
         .option("--description <text>", "Human description for the custom item type, status, or field")
         .option("--default-status <status>", "Default status hint recorded for the custom item type")
@@ -1770,7 +1770,7 @@ export function registerMutationCommands(program, registrationOptions = {}) {
     schemaCommand.action(runSchemaAction);
     const profileCommand = program
         .command("profile")
-        .argument("[subcommand]", "Profile subcommand: list, show, apply, or lint")
+        .argument("[subcommand]", "Required; Profile subcommand: list, show, apply, or lint")
         .argument("[name]", "Profile name for show/apply/lint: agile, ops, or research")
         .option("--dry-run", "Preview the apply diff without writing any files (apply)")
         .option("--author <value>", "Mutation author")
@@ -1840,4 +1840,4 @@ export function registerMutationCommands(program, registrationOptions = {}) {
         .action(runDepsAction);
 }
 //# sourceMappingURL=register-mutation.js.map
-//# debugId=7feb0fe0-386c-56dc-afe1-e7b4ce1bc95a
+//# debugId=07f3212f-c6d3-534e-8273-fae43a8fca18

package/dist/cli/register-operations.js

@@ -1,9 +1,9 @@
 
-!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]="dec5fb7d-416f-5da6-bd97-c05c25dbf769")}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]="975321a1-0375-5829-a012-f23e32e9c6bf")}catch(e){}}();
 import { resolveRuntimeStatusRegistry, setActiveCommandResult, EXIT_CODE, PmCliError, createUnknownSubcommandError, resolveAuthor, resolvePmRoot, readSettings, } from "../sdk/runtime-primitives.js";
 import { resolveStartTaskInProgressStatus } from "../sdk/start-task-status.js";
 import { parseStatsAnalyticsJson } from "./stats-analytics-json.js";
-import { createWorkspaceSnapshot, deleteWorkspaceSnapshot, inspectWorkspaceSnapshot, listWorkspaceSnapshots, planWorkspaceSnapshotRestore, restoreWorkspaceSnapshotWithRecovery, } from "../sdk/workspace-snapshot.js";
+import { createWorkspaceSnapshot, deleteWorkspaceSnapshot, inspectWorkspaceSnapshot, listWorkspaceSnapshots, planWorkspaceSnapshotRestore, restoreWorkspaceSnapshotWithRecovery, WORKSPACE_SNAPSHOT_ACTIONS, } from "../sdk/workspace-snapshot.js";
 import { runClaim, runClaimNext, runRelease } from "./commands/claim.js";
 import { runClose } from "./commands/close.js";
 import { runContracts } from "./commands/contracts.js";
@@ -380,11 +380,11 @@ async function runWorkspaceSnapshotAction(action, target, options, command) {
     const globalOptions = getGlobalOptions(command);
     const pmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
     const normalizedAction = action.trim().toLowerCase();
-    if (!["create", "list", "inspect", "restore", "delete"].includes(normalizedAction)) {
+    if (!WORKSPACE_SNAPSHOT_ACTIONS.some((entry) => entry === normalizedAction)) {
         throw createUnknownSubcommandError({
             command_path: "workspace snapshot",
             token: action,
-            allowed: ["create", "list", "inspect", "restore", "delete"],
+            allowed: WORKSPACE_SNAPSHOT_ACTIONS,
             display_name: "workspace snapshot",
             token_kind: "action",
             examples: [
@@ -606,7 +606,7 @@ export function registerOperationCommands(program) {
     });
     program
         .command("telemetry")
-        .argument("[namespaceOrSubcommand]", "Telemetry subcommand: status, flush, stats, clear (default: status)")
+        .argument("[namespace-or-subcommand]", "Telemetry subcommand: status, flush, stats, clear (default: status)")
         .argument("[subcommand]", "Compatibility alias target for local-analytics: status, flush, stats, clear")
         .option("--limit <n>", "Maximum command groups returned by telemetry stats")
         .description("Inspect and manage local telemetry queue/runtime state.")
@@ -873,4 +873,4 @@ function registerSchedulingShortcutCommands(program) {
     });
 }
 //# sourceMappingURL=register-operations.js.map
-//# debugId=dec5fb7d-416f-5da6-bd97-c05c25dbf769
+//# debugId=975321a1-0375-5829-a012-f23e32e9c6bf