@unbrained/pm-cli 2026.6.12 → 2026.6.16

package/dist/cli/register-mutation.js

@@ -1,6 +1,7 @@
 
-!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]="07f90455-c9f8-5cb9-86fe-be98e72908cb")}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]="77fb8735-3d70-59c2-86f3-3e6462688b5d")}catch(e){}}();
 import { Option } from "commander";
+import { resolveBodyFileContent } from "../core/io/body-file.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { isPureSnakeCaseAlias } from "../core/shared/option-alias-visibility.js";
@@ -32,7 +33,7 @@ function addHiddenOption(command, flags, description, repeatable) {
  * supplied but does not parse to a finite integer (rather than silently dropping
  * it). Returns `undefined` only when the flag was genuinely not provided.
  */
-function parseSchemaOrderOption(raw) {
+export function parseSchemaOrderOption(raw) {
     if (raw === undefined || raw === null) {
         return undefined;
     }
@@ -54,7 +55,104 @@ function parseSchemaOrderOption(raw) {
     }
     throw new PmCliError("--order must be a finite integer.", EXIT_CODE.USAGE);
 }
-function registerCommanderOptionContracts(command, contracts) {
+/**
+ * Build a commander argParser that coerces a flag value into a positive
+ * (1-based) integer, throwing a usage error when the supplied value is not a
+ * whole number >= 1. Used by `pm comments --edit/--delete <index>` so an
+ * invalid index fails fast with a clear message instead of silently coercing.
+ */
+export function parsePositiveIntOption(flag) {
+    return (value) => {
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed) || parsed < 1) {
+            throw new PmCliError(`${flag} must be a positive integer (1-based index).`, EXIT_CODE.USAGE);
+        }
+        return parsed;
+    };
+}
+// Bulk content-field selection filters (GH-242) shared by update-many and
+// close-many. Each pair mirrors the list-family presence/absence flags but uses
+// the `--filter-` prefix so they live in the bulk-selection namespace. The
+// governance-missing filters (GH-236) reuse the same `--filter-<gov>-missing`
+// spelling as the list family.
+function registerBulkContentAndGovernanceFilters(command, action) {
+    command
+        .option("--filter-has-notes", `Select only items that have notes before ${action}`)
+        .option("--filter-no-notes", `Select only items that have no notes before ${action}`)
+        .option("--filter-has-learnings", `Select only items that have learnings before ${action}`)
+        .option("--filter-no-learnings", `Select only items that have no learnings before ${action}`)
+        .option("--filter-has-files", `Select only items that have linked files before ${action}`)
+        .option("--filter-no-files", `Select only items that have no linked files before ${action}`)
+        .option("--filter-has-docs", `Select only items that have linked docs before ${action}`)
+        .option("--filter-no-docs", `Select only items that have no linked docs before ${action}`)
+        .option("--filter-has-tests", `Select only items that have linked tests before ${action}`)
+        .option("--filter-no-tests", `Select only items that have no linked tests before ${action}`)
+        .option("--filter-has-comments", `Select only items that have comments before ${action}`)
+        .option("--filter-no-comments", `Select only items that have no comments before ${action}`)
+        .option("--filter-has-deps", `Select only items that have dependencies before ${action}`)
+        .option("--filter-no-deps", `Select only items that have no dependencies before ${action}`)
+        .option("--filter-has-body", `Select only items that have a non-empty body before ${action}`)
+        .option("--filter-empty-body", `Select only items with an empty body before ${action}`)
+        .option("--filter-has-linked-command", `Select only items whose linked tests carry a runnable command before ${action}`)
+        .option("--filter-no-linked-command", `Select only items whose linked tests carry no runnable command before ${action}`)
+        .option("--filter-reviewer-missing", `Select only items missing reviewer before ${action}`)
+        .option("--filter-risk-missing", `Select only items missing risk before ${action}`)
+        .option("--filter-confidence-missing", `Select only items missing confidence before ${action}`)
+        .option("--filter-sprint-missing", `Select only items missing sprint before ${action}`)
+        .option("--filter-release-missing", `Select only items missing release before ${action}`);
+}
+// Map the bulk content/governance `--filter-*` commander options into the
+// ListOptions content/governance fields runList consumes. Shared by update-many
+// and close-many.
+// [hasCommanderKey, noCommanderKey, --filter-has flag, --filter-no flag]
+const BULK_CONTENT_FILTER_CONFLICTS = [
+    ["filterHasNotes", "filterNoNotes", "--filter-has-notes", "--filter-no-notes"],
+    ["filterHasLearnings", "filterNoLearnings", "--filter-has-learnings", "--filter-no-learnings"],
+    ["filterHasFiles", "filterNoFiles", "--filter-has-files", "--filter-no-files"],
+    ["filterHasDocs", "filterNoDocs", "--filter-has-docs", "--filter-no-docs"],
+    ["filterHasTests", "filterNoTests", "--filter-has-tests", "--filter-no-tests"],
+    ["filterHasComments", "filterNoComments", "--filter-has-comments", "--filter-no-comments"],
+    ["filterHasDeps", "filterNoDeps", "--filter-has-deps", "--filter-no-deps"],
+    ["filterHasBody", "filterEmptyBody", "--filter-has-body", "--filter-empty-body"],
+    ["filterHasLinkedCommand", "filterNoLinkedCommand", "--filter-has-linked-command", "--filter-no-linked-command"],
+];
+function mapBulkContentAndGovernanceFilters(options) {
+    const presence = (key) => (options[key] === true ? true : undefined);
+    // Catch a both-present-and-absent bulk request here so the error names the
+    // bulk --filter-* flags the user actually typed, rather than the downstream
+    // list-level --has-/--no- flags resolveContentFieldFilters would report.
+    for (const [hasKey, noKey, hasFlag, noFlag] of BULK_CONTENT_FILTER_CONFLICTS) {
+        if (options[hasKey] === true && options[noKey] === true) {
+            throw new PmCliError(`Cannot combine ${hasFlag} with ${noFlag} for the same field.`, EXIT_CODE.USAGE);
+        }
+    }
+    return {
+        filterReviewerMissing: presence("filterReviewerMissing"),
+        filterRiskMissing: presence("filterRiskMissing"),
+        filterConfidenceMissing: presence("filterConfidenceMissing"),
+        filterSprintMissing: presence("filterSprintMissing"),
+        filterReleaseMissing: presence("filterReleaseMissing"),
+        hasNotes: presence("filterHasNotes"),
+        hasLearnings: presence("filterHasLearnings"),
+        hasFiles: presence("filterHasFiles"),
+        hasDocs: presence("filterHasDocs"),
+        hasTests: presence("filterHasTests"),
+        hasComments: presence("filterHasComments"),
+        hasDeps: presence("filterHasDeps"),
+        hasBody: presence("filterHasBody"),
+        hasLinkedCommand: presence("filterHasLinkedCommand"),
+        noNotes: presence("filterNoNotes"),
+        noLearnings: presence("filterNoLearnings"),
+        noFiles: presence("filterNoFiles"),
+        noDocs: presence("filterNoDocs"),
+        noTests: presence("filterNoTests"),
+        noComments: presence("filterNoComments"),
+        noDeps: presence("filterNoDeps"),
+        emptyBody: presence("filterEmptyBody"),
+        noLinkedCommand: presence("filterNoLinkedCommand"),
+    };
+}
+export function registerCommanderOptionContracts(command, contracts) {
     for (const contract of contracts) {
         if (contract.required) {
             command.requiredOption(contract.option, contract.description);
@@ -81,6 +179,39 @@ function registerCommanderOptionContracts(command, contracts) {
         }
     }
 }
+/**
+ * Map raw `update-many --filter-*` commander options into the ListOptions shape
+ * runList consumes. Extracted from registerMutationCommands so its many
+ * string/boolean coercions do not inflate that function's cyclomatic complexity.
+ */
+function buildUpdateManyListOptions(options) {
+    const readString = (key) => typeof options[key] === "string" ? options[key] : undefined;
+    return {
+        type: readString("filterType"),
+        tag: readString("filterTag"),
+        priority: readString("filterPriority"),
+        deadlineBefore: readString("filterDeadlineBefore"),
+        deadlineAfter: readString("filterDeadlineAfter"),
+        updatedAfter: readString("filterUpdatedAfter"),
+        updatedBefore: readString("filterUpdatedBefore"),
+        createdAfter: readString("filterCreatedAfter"),
+        createdBefore: readString("filterCreatedBefore"),
+        ids: readString("ids"),
+        assignee: readString("filterAssignee"),
+        assigneeFilter: readString("filterAssigneeFilter") ?? readString("filterAssignee_filter"),
+        parent: readString("filterParent"),
+        sprint: readString("filterSprint"),
+        release: readString("filterRelease"),
+        filterAcMissing: options.filterAcMissing === true ? true : undefined,
+        filterEstimatesMissing: options.filterEstimatesMissing === true || options.filterEstimateMissing === true ? true : undefined,
+        filterResolutionMissing: options.filterResolutionMissing === true ? true : undefined,
+        filterMetadataMissing: options.filterMetadataMissing === true ? true : undefined,
+        ...mapBulkContentAndGovernanceFilters(options),
+        limit: readString("limit"),
+        offset: readString("offset"),
+        includeBody: true,
+    };
+}
 export function registerMutationCommands(program) {
     const createCommand = program
         .command("create")
@@ -89,6 +220,7 @@ export function registerMutationCommands(program) {
         .description("Create a new project management item.");
     registerCommanderOptionContracts(createCommand, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS);
     createCommand
+        .option("--body-file <path>", "Load the item markdown body from a file (mutually exclusive with --body)")
         .option("--clear-deps", "Clear dependency entries")
         .option("--clear-comments", "Clear comments")
         .option("--clear-notes", "Clear notes")
@@ -112,7 +244,15 @@ export function registerMutationCommands(program) {
             positionalTitle = secondTitle;
         }
         else if (typeof typeOrTitle === "string" && typeOrTitle.length > 0) {
-            positionalTitle = typeOrTitle;
+            // Honor `pm create <type> --title ...` by treating the lone positional as
+            // type when an explicit --title is already present.
+            const explicitTitleProvided = typeof options.title === "string" && options.title.trim().length > 0;
+            if (explicitTitleProvided && options.type === undefined) {
+                positionalType = typeOrTitle;
+            }
+            else {
+                positionalTitle = typeOrTitle;
+            }
         }
         // pm-edge #1 (2026-05-28): when the sole positional matches a known
         // item type AND no --title was supplied, refuse early instead of
@@ -145,6 +285,12 @@ export function registerMutationCommands(program) {
         if (typeof positionalTitle === "string" && positionalTitle.length > 0 && options.title === undefined) {
             options.title = positionalTitle;
         }
+        // GH-214: resolve --body-file into the existing body field before
+        // normalization so the rest of create is unchanged. CLI-only input alias.
+        if (typeof options.bodyFile === "string") {
+            options.body = await resolveBodyFileContent(options.bodyFile, options.body !== undefined ? String(options.body) : undefined);
+            delete options.bodyFile;
+        }
         const normalized = normalizeCreateOptions(options, { requireType: false });
         const { runCreate } = await import("./commands/create.js");
         const result = await runCreate(normalized, globalOptions);
@@ -176,12 +322,28 @@ export function registerMutationCommands(program) {
             printError(`profile:command=copy took_ms=${Date.now() - startedAt}`);
         }
     });
+    program
+        .command("focus")
+        .argument("[id]", "Item id to focus (omit to show current focus)")
+        .option("--clear", "Clear the focused item")
+        .description("Set/clear/show the session focused item that new items default --parent to.")
+        .action(async (id, options, command) => {
+        const globalOptions = getGlobalOptions(command);
+        const startedAt = Date.now();
+        const { runFocus } = await import("./commands/focus.js");
+        const result = await runFocus(id, { clear: options.clear === true }, globalOptions);
+        printResult(result, globalOptions);
+        if (globalOptions.profile) {
+            printError(`profile:command=focus took_ms=${Date.now() - startedAt}`);
+        }
+    });
     const updateCommand = program
         .command("update")
         .argument("<id>", "Item id")
         .description("Update item fields and metadata.");
     registerCommanderOptionContracts(updateCommand, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS);
     updateCommand
+        .option("--body-file <path>", "Load the item markdown body from a file (mutually exclusive with --body)")
         .option("--replace-deps", "Atomically replace dependency entries with the provided --dep values")
         .option("--replace-tests", "Atomically replace linked test entries with the provided --test values")
         .option("--clear-deps", "Clear dependency entries")
@@ -203,6 +365,12 @@ export function registerMutationCommands(program) {
         .action(async (id, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        // GH-214: resolve --body-file into the existing body field before
+        // normalization so the rest of update is unchanged. CLI-only input alias.
+        if (typeof options.bodyFile === "string") {
+            options.body = await resolveBodyFileContent(options.bodyFile, options.body !== undefined ? String(options.body) : undefined);
+            delete options.bodyFile;
+        }
         const { runUpdate } = await import("./commands/update.js");
         const result = await runUpdate(id, normalizeUpdateOptions(options), globalOptions);
         await invalidateSearchCachesForMutation(globalOptions, result);
@@ -229,6 +397,12 @@ export function registerMutationCommands(program) {
         .option("--filter-parent <value>", "Filter by parent item ID before applying updates")
         .option("--filter-sprint <value>", "Filter by sprint before applying updates")
         .option("--filter-release <value>", "Filter by release before applying updates")
+        .option("--filter-ac-missing", "Select only items missing acceptance_criteria (bulk backfill)")
+        .option("--filter-estimates-missing", "Select only items missing estimated_minutes (bulk backfill)")
+        .option("--filter-resolution-missing", "Select only terminal items missing resolution (bulk backfill)")
+        .option("--filter-metadata-missing", "Select only items missing any tracked metadata (AC, estimate, or resolution)");
+    registerBulkContentAndGovernanceFilters(updateManyCommand, "applying updates");
+    updateManyCommand
         .option("--ids <value>", "Restrict to an explicit comma-separated ID allowlist (intersected with other filters)")
         .option("--limit <n>", "Limit matched item count before apply/preview")
         .option("--offset <n>", "Skip first n matched rows before apply/preview")
@@ -329,6 +503,7 @@ export function registerMutationCommands(program) {
         ["--customer_impact <value>", "Alias for --customer-impact"],
         ["--allow_audit_update", "Alias for --allow-audit-update"],
         ["--allow_audit_dep_update", "Alias for --allow-audit-dep-update"],
+        ["--filter-estimate-missing", "Alias for --filter-estimates-missing"],
     ]) {
         addHiddenOption(updateManyCommand, flags, description, false);
     }
@@ -347,30 +522,7 @@ export function registerMutationCommands(program) {
         const { runUpdateMany } = await import("./commands/update-many.js");
         const result = await runUpdateMany({
             status: typeof options.filterStatus === "string" ? options.filterStatus : undefined,
-            list: {
-                type: typeof options.filterType === "string" ? options.filterType : undefined,
-                tag: typeof options.filterTag === "string" ? options.filterTag : undefined,
-                priority: typeof options.filterPriority === "string" ? options.filterPriority : undefined,
-                deadlineBefore: typeof options.filterDeadlineBefore === "string" ? options.filterDeadlineBefore : undefined,
-                deadlineAfter: typeof options.filterDeadlineAfter === "string" ? options.filterDeadlineAfter : undefined,
-                updatedAfter: typeof options.filterUpdatedAfter === "string" ? options.filterUpdatedAfter : undefined,
-                updatedBefore: typeof options.filterUpdatedBefore === "string" ? options.filterUpdatedBefore : undefined,
-                createdAfter: typeof options.filterCreatedAfter === "string" ? options.filterCreatedAfter : undefined,
-                createdBefore: typeof options.filterCreatedBefore === "string" ? options.filterCreatedBefore : undefined,
-                ids: typeof options.ids === "string" ? options.ids : undefined,
-                assignee: typeof options.filterAssignee === "string" ? options.filterAssignee : undefined,
-                assigneeFilter: typeof options.filterAssigneeFilter === "string"
-                    ? options.filterAssigneeFilter
-                    : typeof options.filterAssignee_filter === "string"
-                        ? options.filterAssignee_filter
-                        : undefined,
-                parent: typeof options.filterParent === "string" ? options.filterParent : undefined,
-                sprint: typeof options.filterSprint === "string" ? options.filterSprint : undefined,
-                release: typeof options.filterRelease === "string" ? options.filterRelease : undefined,
-                limit: typeof options.limit === "string" ? options.limit : undefined,
-                offset: typeof options.offset === "string" ? options.offset : undefined,
-                includeBody: true,
-            },
+            list: buildUpdateManyListOptions(options),
             update: normalizeUpdateOptions(extractUpdateManyMutationOptionSource(options)),
             dryRun: options.dryRun === true ? true : undefined,
             rollback: typeof options.rollback === "string" ? options.rollback : undefined,
@@ -386,11 +538,11 @@ export function registerMutationCommands(program) {
         .command("close")
         .argument("<id>", "Item id")
         .argument("[text]", "Close reason text (alias: --reason)")
-        .option("--reason <value>", "Close reason text (alias for positional <text>)")
+        .option("-r, --reason <value>", "Close reason text (alias for positional <text>)")
         .option("--close-reason <value>", "Close reason text (alias for positional <text>)")
-        .option("--duplicate-of <id>", "Close as a duplicate of the canonical item id and auto-fill duplicate closure metadata")
+        .option("-d, --duplicate-of <id>", "Close as a duplicate of the canonical item id and auto-fill duplicate closure metadata")
         .option("--author <value>", "Mutation author")
-        .option("--message <value>", "History message")
+        .option("-m, --message <value>", "History message")
         .option("--validate-close [mode]", 'Validate closure metadata before close: "off", "warn", or "strict" (default: settings governance preset)')
         .option("--resolution <value>", "Set the closure resolution summary inline (same field --validate-close strict checks; previously required a prior pm update)")
         .option("--expected-result <value>", "Set the expected-result note inline (closure validation field)")
@@ -458,7 +610,9 @@ export function registerMutationCommands(program) {
         .option("--filter-assignee-filter <value>", "Filter assignee presence: assigned|unassigned before closing")
         .option("--filter-parent <value>", "Filter by parent item ID before closing")
         .option("--filter-sprint <value>", "Filter by sprint before closing")
-        .option("--filter-release <value>", "Filter by release before closing")
+        .option("--filter-release <value>", "Filter by release before closing");
+    registerBulkContentAndGovernanceFilters(closeManyCommand, "closing");
+    closeManyCommand
         .option("--ids <value>", "Restrict to an explicit comma-separated ID allowlist (intersected with other filters)")
         .option("--limit <n>", "Limit matched item count before apply/preview")
         .option("--offset <n>", "Skip first n matched rows before apply/preview")
@@ -508,6 +662,7 @@ export function registerMutationCommands(program) {
                 parent: typeof options.filterParent === "string" ? options.filterParent : undefined,
                 sprint: typeof options.filterSprint === "string" ? options.filterSprint : undefined,
                 release: typeof options.filterRelease === "string" ? options.filterRelease : undefined,
+                ...mapBulkContentAndGovernanceFilters(options),
                 limit: typeof options.limit === "string" ? options.limit : undefined,
                 offset: typeof options.offset === "string" ? options.offset : undefined,
             },
@@ -943,12 +1098,16 @@ export function registerMutationCommands(program) {
                 ],
             });
         }
-        const aliases = typeof options.alias === "string"
+        const aliases = 
+        /* c8 ignore next -- --alias is registered with commander `collect`, so it is always an array here; the string arm is a defensive guard for non-CLI (programmatic) callers */
+        typeof options.alias === "string"
             ? [options.alias]
             : Array.isArray(options.alias)
                 ? options.alias
                 : undefined;
-        const roles = typeof options.role === "string"
+        const roles = 
+        /* c8 ignore next -- --role is registered with commander `collect`, so it is always an array here; the string arm is a defensive guard for non-CLI (programmatic) callers */
+        typeof options.role === "string"
             ? [options.role]
             : Array.isArray(options.role)
                 ? options.role
@@ -1041,15 +1200,19 @@ export function registerMutationCommands(program) {
         .option("--add <text>", "Add one comment entry (plain text fallback, text=<value>, markdown pairs, or - for stdin; CSV-like key fragments are preserved as plain text unless text is explicit)")
         .option("--stdin", "Read comment text from stdin (supports multiline markdown)")
         .option("--file <path>", "Read comment text from file (supports multiline markdown)")
+        .option("--edit <index>", "Replace the comment at 1-based <index> (replacement text from positional [text], --add, --stdin, or --file)", parsePositiveIntOption("--edit"))
+        .option("--delete <index>", "Delete the comment at 1-based <index>", parsePositiveIntOption("--delete"))
         .option("--limit <n>", "Return only latest n comments")
         .option("--author [value]", "Comment author (optional; falls back to PM_AUTHOR/settings)")
         .option("--message <value>", "History message")
-        .option("--allow-audit-comment", "Allow non-owner append-only comment audits without requiring --force")
+        .option("--allow-audit-comment", "Allow non-owner append-only comment audits (add/edit/delete) without requiring --force")
         .option("--force", "Force ownership override")
-        .description("List or add comments for an item.")
+        .description("List, add, edit, or delete comments for an item.")
         .action(async (id, text, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        const editIndex = typeof options.edit === "number" ? options.edit : undefined;
+        const deleteIndex = typeof options.delete === "number" ? options.delete : undefined;
         const addFromOption = typeof options.add === "string" ? options.add : undefined;
         const addFromPositional = typeof text === "string" ? text : undefined;
         const readFromStdin = options.stdin === true;
@@ -1070,13 +1233,16 @@ export function registerMutationCommands(program) {
             add,
             stdin: readFromStdin,
             file: readFromFile,
+            edit: editIndex,
+            delete: deleteIndex,
             limit: typeof options.limit === "string" ? options.limit : undefined,
             author: typeof options.author === "string" ? options.author : undefined,
             message: typeof options.message === "string" ? options.message : undefined,
             allowAuditComment: Boolean(options.allowAuditComment),
             force: Boolean(options.force),
         }, globalOptions);
-        if (typeof add === "string" || readFromStdin || readFromFile !== undefined) {
+        const isMutation = typeof add === "string" || readFromStdin || readFromFile !== undefined || editIndex !== undefined || deleteIndex !== undefined;
+        if (isMutation) {
             await invalidateSearchCachesForMutation(globalOptions, result);
         }
         printResult(result, globalOptions);
@@ -1297,10 +1463,14 @@ export function registerMutationCommands(program) {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
         const { runDeps } = await import("./commands/deps.js");
+        // --format and --collapse carry commander defaults ("tree"/"none"), so
+        // they are always strings by the time the action runs; --maxDepth has no
+        // default and may be unset. Use `as string` rather than String(...) so an
+        // omitted option stays undefined instead of becoming the literal "undefined".
         const result = await runDeps(id, {
-            format: typeof options.format === "string" ? options.format : undefined,
+            format: options.format,
             maxDepth: typeof options.maxDepth === "string" ? options.maxDepth : undefined,
-            collapse: typeof options.collapse === "string" ? options.collapse : undefined,
+            collapse: options.collapse,
             summary: options.summary === true,
         }, globalOptions);
         printResult(result, globalOptions);
@@ -1310,4 +1480,4 @@ export function registerMutationCommands(program) {
     });
 }
 //# sourceMappingURL=register-mutation.js.map
-//# debugId=07f90455-c9f8-5cb9-86fe-be98e72908cb
+//# debugId=77fb8735-3d70-59c2-86f3-3e6462688b5d