@unbrained/pm-cli 2026.3.9

package/dist/cli/main.js

@@ -0,0 +1,1494 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { runAppend, runActivity, runClaim, runClose, runComments, runCompletion, runConfig, runCreate, runDelete, runDocs, runFiles, runGet, runGc, runHealth, runHistory, runInit, runInstall, runList, runSearch, runReindex, runRestore, runRelease, runStats, runTest, runTestAll, runUpdate, } from "./commands/index.js";
+import { activateExtensions, clearActiveExtensionHooks, createEmptyExtensionCommandRegistry, createEmptyExtensionHookRegistry, createEmptyExtensionRendererRegistry, loadExtensions, runActiveCommandHandler, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandContext, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionRenderers, } from "../core/extensions/index.js";
+import { pathExists } from "../core/fs/fs-utils.js";
+import { refreshSearchArtifactsForMutation } from "../core/search/cache.js";
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
+import { printError, printResult } from "../core/output/output.js";
+import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+import { readSettings } from "../core/store/settings.js";
+import { getEnabledBuiltInExtensions } from "../core/extensions/builtins.js";
+import { parseLooseCommandOptions } from "./extension-command-options.js";
+function collect(value, previous) {
+    const next = previous ?? [];
+    next.push(value);
+    return next;
+}
+function getGlobalOptions(command) {
+    const opts = command.optsWithGlobals();
+    return {
+        json: Boolean(opts.json),
+        quiet: Boolean(opts.quiet),
+        path: typeof opts.path === "string" ? opts.path : undefined,
+        noExtensions: opts.extensions === false,
+        profile: Boolean(opts.profile),
+    };
+}
+function getCommandPath(command) {
+    const parts = [];
+    let current = command;
+    while (current?.parent) {
+        parts.unshift(current.name());
+        current = current.parent;
+    }
+    return parts.join(" ");
+}
+function normalizeExtensionCommandPath(commandPath) {
+    return commandPath
+        .trim()
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((part) => part.length > 0)
+        .join(" ");
+}
+function toNonEmptyFlagString(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function formatDynamicExtensionFlagHelpLine(definition) {
+    const longName = toNonEmptyFlagString(definition.long);
+    if (!longName || !longName.startsWith("--") || longName.length < 3) {
+        return null;
+    }
+    const shortName = toNonEmptyFlagString(definition.short);
+    const shortPrefix = shortName && shortName.startsWith("-") && !shortName.startsWith("--") ? `${shortName}, ` : "";
+    const valueName = toNonEmptyFlagString(definition.value_name);
+    const valueSuffix = valueName ? ` <${valueName}>` : "";
+    const description = toNonEmptyFlagString(definition.description) ?? "Extension-provided option.";
+    return `${shortPrefix}${longName}${valueSuffix}  ${description}`;
+}
+function buildDynamicExtensionFlagHelp(definitions) {
+    const lines = [
+        ...new Set(definitions
+            .map(formatDynamicExtensionFlagHelpLine)
+            .filter((line) => line !== null)),
+    ].sort((left, right) => left.localeCompare(right));
+    if (lines.length === 0) {
+        return null;
+    }
+    return `\nExtension-provided flags:\n  ${lines.join("\n  ")}`;
+}
+function collectDynamicExtensionFlagHelpByCommand(registrations) {
+    const grouped = new Map();
+    for (const registration of registrations) {
+        const commandPath = normalizeExtensionCommandPath(registration.target_command);
+        if (commandPath.length === 0) {
+            continue;
+        }
+        const existing = grouped.get(commandPath) ?? [];
+        existing.push(...registration.flags);
+        grouped.set(commandPath, existing);
+    }
+    const entries = [...grouped.entries()].sort(([left], [right]) => left.localeCompare(right));
+    const helpByCommand = new Map();
+    for (const [commandPath, definitions] of entries) {
+        const helpText = buildDynamicExtensionFlagHelp(definitions);
+        if (!helpText) {
+            continue;
+        }
+        helpByCommand.set(commandPath, helpText);
+    }
+    return helpByCommand;
+}
+function findDirectChildCommand(parent, name) {
+    return parent.commands.find((entry) => entry.name() === name) ?? null;
+}
+function findCommandByPath(root, pathParts) {
+    let current = root;
+    for (const part of pathParts) {
+        const next = findDirectChildCommand(current, part);
+        if (!next) {
+            return null;
+        }
+        current = next;
+    }
+    return current;
+}
+function ensureCommandPath(root, pathParts) {
+    if (pathParts.length === 0) {
+        return null;
+    }
+    let current = root;
+    for (let index = 0; index < pathParts.length; index += 1) {
+        const part = pathParts[index];
+        const existing = findDirectChildCommand(current, part);
+        if (existing) {
+            current = existing;
+            continue;
+        }
+        const created = current.command(part);
+        if (index < pathParts.length - 1) {
+            created.description("Extension-provided command group.");
+        }
+        else {
+            created.description("Extension-provided command path.");
+        }
+        current = created;
+    }
+    return current;
+}
+function parseBootstrapPathToken(token, next) {
+    if (token === "--path") {
+        if (typeof next === "string" && next.length > 0) {
+            return {
+                consumed: 2,
+                pathValue: next,
+            };
+        }
+        return {
+            consumed: 1,
+        };
+    }
+    if (!token.startsWith("--path=")) {
+        return null;
+    }
+    const value = token.slice("--path=".length);
+    if (value.length > 0) {
+        return {
+            consumed: 1,
+            pathValue: value,
+        };
+    }
+    return {
+        consumed: 1,
+    };
+}
+function parseBootstrapGlobalOptions(argv) {
+    let pathValue;
+    let noExtensions = false;
+    let index = 0;
+    while (index < argv.length) {
+        const token = argv[index];
+        if (token === "--") {
+            break;
+        }
+        if (token === "--no-extensions") {
+            noExtensions = true;
+            index += 1;
+            continue;
+        }
+        const parsedPath = parseBootstrapPathToken(token, argv[index + 1]);
+        if (parsedPath) {
+            if (parsedPath.pathValue !== undefined) {
+                pathValue = parsedPath.pathValue;
+            }
+            index += parsedPath.consumed;
+            continue;
+        }
+        index += 1;
+    }
+    return {
+        path: pathValue,
+        noExtensions,
+    };
+}
+let activeExtensionHookContext = null;
+function formatHookWarnings(warnings) {
+    return warnings.join(",");
+}
+function toNonEmptyString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function resolveMigrationId(definition, fallbackIndex) {
+    const explicit = toNonEmptyString(definition.id);
+    if (explicit) {
+        return explicit;
+    }
+    return `migration-${String(fallbackIndex + 1).padStart(3, "0")}`;
+}
+function resolveNormalizedMigrationStatus(definition) {
+    const normalized = toNonEmptyString(definition.status)?.toLowerCase();
+    return normalized ?? "pending";
+}
+function isMandatoryMigrationDefinition(definition) {
+    return definition.mandatory === true;
+}
+function compareMandatoryMigrationBlockers(left, right) {
+    const byLayer = left.layer.localeCompare(right.layer);
+    if (byLayer !== 0) {
+        return byLayer;
+    }
+    const byName = left.name.localeCompare(right.name);
+    if (byName !== 0) {
+        return byName;
+    }
+    return left.id.localeCompare(right.id);
+}
+function collectMandatoryMigrationBlockers(migrations) {
+    const blockers = [];
+    migrations.forEach((entry, index) => {
+        if (!isMandatoryMigrationDefinition(entry.definition)) {
+            return;
+        }
+        const status = resolveNormalizedMigrationStatus(entry.definition);
+        if (status === "applied") {
+            return;
+        }
+        blockers.push({
+            layer: entry.layer,
+            name: entry.name,
+            id: resolveMigrationId(entry.definition, index),
+            status,
+        });
+    });
+    blockers.sort(compareMandatoryMigrationBlockers);
+    return blockers;
+}
+function hasMutatingListValues(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+function decideWriteGate(commandPath, options) {
+    const forceRequested = options.force === true;
+    switch (commandPath) {
+        case "create":
+        case "beads import":
+        case "todos import":
+            return {
+                isMutation: true,
+                forceCapable: false,
+                forceRequested: false,
+            };
+        case "restore":
+        case "update":
+        case "close":
+        case "delete":
+        case "append":
+        case "claim":
+        case "release":
+            return {
+                isMutation: true,
+                forceCapable: true,
+                forceRequested,
+            };
+        case "comments":
+            return {
+                isMutation: typeof options.add === "string",
+                forceCapable: true,
+                forceRequested,
+            };
+        case "files":
+        case "docs":
+        case "test":
+            return {
+                isMutation: hasMutatingListValues(options.add) || hasMutatingListValues(options.remove),
+                forceCapable: true,
+                forceRequested,
+            };
+        default:
+            return {
+                isMutation: false,
+                forceCapable: false,
+                forceRequested: false,
+            };
+    }
+}
+function enforceMandatoryMigrationWriteGate(commandPath, options, blockers) {
+    if (blockers.length === 0) {
+        return;
+    }
+    const decision = decideWriteGate(commandPath, options);
+    if (!decision.isMutation) {
+        return;
+    }
+    if (decision.forceCapable && decision.forceRequested) {
+        return;
+    }
+    const codes = blockers.map((entry) => `extension_migration_blocking:${entry.layer}:${entry.name}:${entry.id}:${entry.status}`);
+    const forceGuidance = decision.forceCapable
+        ? "Re-run this command with --force to bypass."
+        : "This command path does not support --force bypass.";
+    throw new PmCliError(`Write command "${commandPath}" blocked by unresolved mandatory extension migrations (${codes.join(",")}). ${forceGuidance}`, EXIT_CODE.CONFLICT);
+}
+function describeUnknownError(error) {
+    if (error instanceof PmCliError) {
+        return error.message;
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return "Unknown failure";
+}
+function collectMutationItemIds(result) {
+    if (!result || typeof result !== "object") {
+        return [];
+    }
+    const record = result;
+    const ids = new Set();
+    const pushId = (value) => {
+        if (typeof value !== "string") {
+            return;
+        }
+        const normalized = value.trim();
+        if (normalized.length === 0) {
+            return;
+        }
+        ids.add(normalized);
+    };
+    pushId(record.id);
+    const item = record.item;
+    if (item && typeof item === "object") {
+        pushId(item.id);
+    }
+    const explicitIds = record.ids;
+    if (Array.isArray(explicitIds)) {
+        for (const candidate of explicitIds) {
+            pushId(candidate);
+        }
+    }
+    const items = record.items;
+    if (Array.isArray(items)) {
+        for (const candidate of items) {
+            if (!candidate || typeof candidate !== "object") {
+                continue;
+            }
+            pushId(candidate.id);
+        }
+    }
+    return [...ids].sort((left, right) => left.localeCompare(right));
+}
+async function invalidateSearchCachesForMutation(globalOptions, result) {
+    const pmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
+    const refreshResult = await refreshSearchArtifactsForMutation(pmRoot, collectMutationItemIds(result));
+    if (globalOptions.profile && refreshResult.warnings.length > 0) {
+        printError(`profile:search_refresh_warnings=${formatHookWarnings(refreshResult.warnings)}`);
+    }
+}
+async function runAndClearAfterCommandHooks(outcome) {
+    const runtime = activeExtensionHookContext;
+    activeExtensionHookContext = null;
+    clearActiveExtensionHooks();
+    if (!runtime) {
+        return;
+    }
+    const hookWarnings = await runAfterCommandHooks(runtime.hooks, {
+        command: runtime.commandName,
+        args: runtime.commandArgs,
+        pm_root: runtime.pmRoot,
+        ok: outcome.ok,
+        error: outcome.error,
+    });
+    if (runtime.profileEnabled && hookWarnings.length > 0) {
+        printError(`profile:extensions hook_warnings=${formatHookWarnings(hookWarnings)}`);
+    }
+}
+async function maybeLoadRuntimeExtensions(command) {
+    const globalOptions = getGlobalOptions(command);
+    if (globalOptions.noExtensions) {
+        return null;
+    }
+    const pmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
+    const settingsPath = getSettingsPath(pmRoot);
+    if (!(await pathExists(settingsPath))) {
+        return null;
+    }
+    try {
+        const settings = await readSettings(pmRoot);
+        const loadResult = await loadExtensions({
+            pmRoot,
+            settings,
+            cwd: process.cwd(),
+            noExtensions: globalOptions.noExtensions,
+        });
+        const loadedWithBuiltins = [...getEnabledBuiltInExtensions(settings), ...loadResult.loaded];
+        const activationResult = await activateExtensions({
+            ...loadResult,
+            loaded: loadedWithBuiltins,
+        });
+        if (globalOptions.profile) {
+            printError(`profile:extensions loaded=${loadedWithBuiltins.length} failed=${loadResult.failed.length} warnings=${loadResult.warnings.length} activation_failed=${activationResult.failed.length} hook_counts=before:${activationResult.hook_counts.before_command}|after:${activationResult.hook_counts.after_command}|write:${activationResult.hook_counts.on_write}|read:${activationResult.hook_counts.on_read}|index:${activationResult.hook_counts.on_index} command_overrides=${activationResult.command_override_count} command_handlers=${activationResult.command_handler_count} renderer_overrides=${activationResult.renderer_override_count}`);
+            if (activationResult.warnings.length > 0) {
+                printError(`profile:extensions activation_warnings=${formatHookWarnings(activationResult.warnings)}`);
+            }
+        }
+        const migrationBlockers = collectMandatoryMigrationBlockers(activationResult.registrations.migrations);
+        return {
+            hooks: activationResult.hooks,
+            commands: activationResult.commands,
+            renderers: activationResult.renderers,
+            pmRoot,
+            migrationBlockers,
+        };
+    }
+    catch (error) {
+        if (globalOptions.profile) {
+            const message = error instanceof Error ? error.message : String(error);
+            printError(`profile:extensions load_error=${message}`);
+        }
+        return {
+            hooks: createEmptyExtensionHookRegistry(),
+            commands: createEmptyExtensionCommandRegistry(),
+            renderers: createEmptyExtensionRendererRegistry(),
+            pmRoot,
+            migrationBlockers: [],
+        };
+    }
+}
+async function runRequiredExtensionCommand(command, options, globalOptions) {
+    const commandPath = getCommandPath(command);
+    const commandArgs = command.args.map(String);
+    const pmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
+    setActiveCommandContext({
+        command: commandPath,
+        args: commandArgs,
+        options: { ...options },
+        global: { ...globalOptions },
+        pm_root: pmRoot,
+    });
+    const extensionCommandResult = await runActiveCommandHandler({
+        command: commandPath,
+        args: commandArgs,
+        options,
+        global: globalOptions,
+        pm_root: pmRoot,
+    });
+    if (globalOptions.profile && extensionCommandResult.warnings.length > 0) {
+        printError(`profile:extensions command_handler_warnings=${formatHookWarnings(extensionCommandResult.warnings)}`);
+    }
+    if (!extensionCommandResult.handled) {
+        if (extensionCommandResult.warnings.length > 0) {
+            const warningCode = extensionCommandResult.warnings[0];
+            throw new PmCliError(`Command "${commandPath}" failed in extension handler (${warningCode}).`, EXIT_CODE.GENERIC_FAILURE);
+        }
+        throw new PmCliError(`Command "${commandPath}" is provided by extensions and is not currently available.`, EXIT_CODE.NOT_FOUND);
+    }
+    return extensionCommandResult.result;
+}
+async function registerDynamicExtensionCommandPaths(rootProgram) {
+    const bootstrapGlobalOptions = parseBootstrapGlobalOptions(process.argv.slice(2));
+    if (bootstrapGlobalOptions.noExtensions) {
+        return;
+    }
+    const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobalOptions.path);
+    const settingsPath = getSettingsPath(pmRoot);
+    if (!(await pathExists(settingsPath))) {
+        return;
+    }
+    let settings;
+    try {
+        settings = await readSettings(pmRoot);
+    }
+    catch {
+        return;
+    }
+    let commandHandlers;
+    let commandFlagHelp;
+    try {
+        const loadResult = await loadExtensions({
+            pmRoot,
+            settings,
+            cwd: process.cwd(),
+            noExtensions: false,
+        });
+        const loadedWithBuiltins = [...getEnabledBuiltInExtensions(settings), ...loadResult.loaded];
+        const activationResult = await activateExtensions({
+            ...loadResult,
+            loaded: loadedWithBuiltins,
+        });
+        commandHandlers = [...new Set(activationResult.commands.handlers.map((entry) => normalizeExtensionCommandPath(entry.command)))]
+            .filter((entry) => entry.length > 0)
+            .sort((left, right) => left.localeCompare(right));
+        commandFlagHelp = collectDynamicExtensionFlagHelpByCommand(activationResult.registrations.flags);
+    }
+    catch {
+        return;
+    }
+    for (const commandPath of commandHandlers) {
+        const pathParts = commandPath.split(" ").filter((part) => part.length > 0);
+        if (pathParts.length === 0) {
+            continue;
+        }
+        if (findCommandByPath(rootProgram, pathParts)) {
+            continue;
+        }
+        const dynamicCommand = ensureCommandPath(rootProgram, pathParts);
+        if (!dynamicCommand) {
+            continue;
+        }
+        const flagHelp = commandFlagHelp.get(commandPath);
+        if (flagHelp) {
+            dynamicCommand.addHelpText("after", flagHelp);
+        }
+        dynamicCommand
+            .allowUnknownOption(true)
+            .allowExcessArguments(true)
+            .action(async (_options, command) => {
+            const globalOptions = getGlobalOptions(command);
+            const startedAt = Date.now();
+            const looseOptions = parseLooseCommandOptions(command.args.map(String));
+            const result = await runRequiredExtensionCommand(command, looseOptions, globalOptions);
+            printResult(result, globalOptions);
+            if (globalOptions.profile) {
+                printError(`profile:command=${commandPath} took_ms=${Date.now() - startedAt}`);
+            }
+        });
+    }
+}
+function normalizeCreateOptions(commandOptions) {
+    const estimatedMinutes = (typeof commandOptions.estimate === "string" ? commandOptions.estimate : undefined) ??
+        (typeof commandOptions.estimatedMinutes === "string" ? commandOptions.estimatedMinutes : undefined) ??
+        (typeof commandOptions.estimated_minutes === "string" ? commandOptions.estimated_minutes : undefined);
+    if (estimatedMinutes === undefined) {
+        throw new PmCliError("Missing required option --estimate/--estimated-minutes/--estimated_minutes", EXIT_CODE.USAGE);
+    }
+    const requiredString = (key, display) => {
+        const value = commandOptions[key];
+        if (typeof value !== "string") {
+            throw new PmCliError(`Missing required option ${display}`, EXIT_CODE.USAGE);
+        }
+        return value;
+    };
+    const requiredRepeatable = (key, display) => {
+        const value = commandOptions[key];
+        if (!Array.isArray(value) || value.length === 0) {
+            throw new PmCliError(`Missing required option ${display} (use 'none' for explicit empty)`, EXIT_CODE.USAGE);
+        }
+        return value;
+    };
+    return {
+        title: requiredString("title", "--title"),
+        description: requiredString("description", "--description"),
+        type: requiredString("type", "--type"),
+        status: requiredString("status", "--status"),
+        priority: requiredString("priority", "--priority"),
+        tags: requiredString("tags", "--tags"),
+        body: requiredString("body", "--body"),
+        deadline: requiredString("deadline", "--deadline"),
+        estimatedMinutes,
+        acceptanceCriteria: (typeof commandOptions.acceptanceCriteria === "string" ? commandOptions.acceptanceCriteria : undefined) ??
+            (typeof commandOptions.acceptance_criteria === "string" ? commandOptions.acceptance_criteria : undefined) ??
+            requiredString("ac", "--acceptance-criteria/--ac"),
+        definitionOfReady: (typeof commandOptions.definitionOfReady === "string" ? commandOptions.definitionOfReady : undefined) ??
+            (typeof commandOptions.definition_of_ready === "string" ? commandOptions.definition_of_ready : undefined),
+        order: typeof commandOptions.order === "string" ? commandOptions.order : undefined,
+        rank: typeof commandOptions.rank === "string" ? commandOptions.rank : undefined,
+        goal: typeof commandOptions.goal === "string" ? commandOptions.goal : undefined,
+        objective: typeof commandOptions.objective === "string" ? commandOptions.objective : undefined,
+        value: typeof commandOptions.value === "string" ? commandOptions.value : undefined,
+        impact: typeof commandOptions.impact === "string" ? commandOptions.impact : undefined,
+        outcome: typeof commandOptions.outcome === "string" ? commandOptions.outcome : undefined,
+        whyNow: (typeof commandOptions.whyNow === "string" ? commandOptions.whyNow : undefined) ??
+            (typeof commandOptions.why_now === "string" ? commandOptions.why_now : undefined),
+        author: requiredString("author", "--author"),
+        message: requiredString("message", "--message"),
+        assignee: requiredString("assignee", "--assignee"),
+        parent: typeof commandOptions.parent === "string" ? commandOptions.parent : undefined,
+        reviewer: typeof commandOptions.reviewer === "string" ? commandOptions.reviewer : undefined,
+        risk: typeof commandOptions.risk === "string" ? commandOptions.risk : undefined,
+        confidence: typeof commandOptions.confidence === "string" ? commandOptions.confidence : undefined,
+        sprint: typeof commandOptions.sprint === "string" ? commandOptions.sprint : undefined,
+        release: typeof commandOptions.release === "string" ? commandOptions.release : undefined,
+        blockedBy: (typeof commandOptions.blockedBy === "string" ? commandOptions.blockedBy : undefined) ??
+            (typeof commandOptions.blocked_by === "string" ? commandOptions.blocked_by : undefined),
+        blockedReason: (typeof commandOptions.blockedReason === "string" ? commandOptions.blockedReason : undefined) ??
+            (typeof commandOptions.blocked_reason === "string" ? commandOptions.blocked_reason : undefined),
+        unblockNote: (typeof commandOptions.unblockNote === "string" ? commandOptions.unblockNote : undefined) ??
+            (typeof commandOptions.unblock_note === "string" ? commandOptions.unblock_note : undefined),
+        reporter: typeof commandOptions.reporter === "string" ? commandOptions.reporter : undefined,
+        severity: typeof commandOptions.severity === "string" ? commandOptions.severity : undefined,
+        environment: typeof commandOptions.environment === "string" ? commandOptions.environment : undefined,
+        reproSteps: (typeof commandOptions.reproSteps === "string" ? commandOptions.reproSteps : undefined) ??
+            (typeof commandOptions.repro_steps === "string" ? commandOptions.repro_steps : undefined),
+        resolution: typeof commandOptions.resolution === "string" ? commandOptions.resolution : undefined,
+        expectedResult: (typeof commandOptions.expectedResult === "string" ? commandOptions.expectedResult : undefined) ??
+            (typeof commandOptions.expected_result === "string" ? commandOptions.expected_result : undefined),
+        actualResult: (typeof commandOptions.actualResult === "string" ? commandOptions.actualResult : undefined) ??
+            (typeof commandOptions.actual_result === "string" ? commandOptions.actual_result : undefined),
+        affectedVersion: (typeof commandOptions.affectedVersion === "string" ? commandOptions.affectedVersion : undefined) ??
+            (typeof commandOptions.affected_version === "string" ? commandOptions.affected_version : undefined),
+        fixedVersion: (typeof commandOptions.fixedVersion === "string" ? commandOptions.fixedVersion : undefined) ??
+            (typeof commandOptions.fixed_version === "string" ? commandOptions.fixed_version : undefined),
+        component: typeof commandOptions.component === "string" ? commandOptions.component : undefined,
+        regression: typeof commandOptions.regression === "string" ? commandOptions.regression : undefined,
+        customerImpact: (typeof commandOptions.customerImpact === "string" ? commandOptions.customerImpact : undefined) ??
+            (typeof commandOptions.customer_impact === "string" ? commandOptions.customer_impact : undefined),
+        dep: requiredRepeatable("dep", "--dep"),
+        comment: requiredRepeatable("comment", "--comment"),
+        note: requiredRepeatable("note", "--note"),
+        learning: requiredRepeatable("learning", "--learning"),
+        file: requiredRepeatable("file", "--file"),
+        test: requiredRepeatable("test", "--test"),
+        doc: requiredRepeatable("doc", "--doc"),
+    };
+}
+function normalizeUpdateOptions(commandOptions) {
+    const estimatedMinutes = (typeof commandOptions.estimate === "string" ? commandOptions.estimate : undefined) ??
+        (typeof commandOptions.estimatedMinutes === "string" ? commandOptions.estimatedMinutes : undefined) ??
+        (typeof commandOptions.estimated_minutes === "string" ? commandOptions.estimated_minutes : undefined);
+    return {
+        description: typeof commandOptions.description === "string" ? commandOptions.description : undefined,
+        status: typeof commandOptions.status === "string" ? commandOptions.status : undefined,
+        priority: typeof commandOptions.priority === "string" ? commandOptions.priority : undefined,
+        type: typeof commandOptions.type === "string" ? commandOptions.type : undefined,
+        tags: typeof commandOptions.tags === "string" ? commandOptions.tags : undefined,
+        deadline: typeof commandOptions.deadline === "string" ? commandOptions.deadline : undefined,
+        estimatedMinutes,
+        acceptanceCriteria: (typeof commandOptions.acceptanceCriteria === "string" ? commandOptions.acceptanceCriteria : undefined) ??
+            (typeof commandOptions.acceptance_criteria === "string" ? commandOptions.acceptance_criteria : undefined) ??
+            (typeof commandOptions.ac === "string" ? commandOptions.ac : undefined),
+        definitionOfReady: (typeof commandOptions.definitionOfReady === "string" ? commandOptions.definitionOfReady : undefined) ??
+            (typeof commandOptions.definition_of_ready === "string" ? commandOptions.definition_of_ready : undefined),
+        order: typeof commandOptions.order === "string" ? commandOptions.order : undefined,
+        rank: typeof commandOptions.rank === "string" ? commandOptions.rank : undefined,
+        goal: typeof commandOptions.goal === "string" ? commandOptions.goal : undefined,
+        objective: typeof commandOptions.objective === "string" ? commandOptions.objective : undefined,
+        value: typeof commandOptions.value === "string" ? commandOptions.value : undefined,
+        impact: typeof commandOptions.impact === "string" ? commandOptions.impact : undefined,
+        outcome: typeof commandOptions.outcome === "string" ? commandOptions.outcome : undefined,
+        whyNow: (typeof commandOptions.whyNow === "string" ? commandOptions.whyNow : undefined) ??
+            (typeof commandOptions.why_now === "string" ? commandOptions.why_now : undefined),
+        author: typeof commandOptions.author === "string" ? commandOptions.author : undefined,
+        message: typeof commandOptions.message === "string" ? commandOptions.message : undefined,
+        force: Boolean(commandOptions.force),
+        assignee: typeof commandOptions.assignee === "string" ? commandOptions.assignee : undefined,
+        parent: typeof commandOptions.parent === "string" ? commandOptions.parent : undefined,
+        reviewer: typeof commandOptions.reviewer === "string" ? commandOptions.reviewer : undefined,
+        risk: typeof commandOptions.risk === "string" ? commandOptions.risk : undefined,
+        confidence: typeof commandOptions.confidence === "string" ? commandOptions.confidence : undefined,
+        sprint: typeof commandOptions.sprint === "string" ? commandOptions.sprint : undefined,
+        release: typeof commandOptions.release === "string" ? commandOptions.release : undefined,
+        blockedBy: (typeof commandOptions.blockedBy === "string" ? commandOptions.blockedBy : undefined) ??
+            (typeof commandOptions.blocked_by === "string" ? commandOptions.blocked_by : undefined),
+        blockedReason: (typeof commandOptions.blockedReason === "string" ? commandOptions.blockedReason : undefined) ??
+            (typeof commandOptions.blocked_reason === "string" ? commandOptions.blocked_reason : undefined),
+        unblockNote: (typeof commandOptions.unblockNote === "string" ? commandOptions.unblockNote : undefined) ??
+            (typeof commandOptions.unblock_note === "string" ? commandOptions.unblock_note : undefined),
+        reporter: typeof commandOptions.reporter === "string" ? commandOptions.reporter : undefined,
+        severity: typeof commandOptions.severity === "string" ? commandOptions.severity : undefined,
+        environment: typeof commandOptions.environment === "string" ? commandOptions.environment : undefined,
+        reproSteps: (typeof commandOptions.reproSteps === "string" ? commandOptions.reproSteps : undefined) ??
+            (typeof commandOptions.repro_steps === "string" ? commandOptions.repro_steps : undefined),
+        resolution: typeof commandOptions.resolution === "string" ? commandOptions.resolution : undefined,
+        expectedResult: (typeof commandOptions.expectedResult === "string" ? commandOptions.expectedResult : undefined) ??
+            (typeof commandOptions.expected_result === "string" ? commandOptions.expected_result : undefined),
+        actualResult: (typeof commandOptions.actualResult === "string" ? commandOptions.actualResult : undefined) ??
+            (typeof commandOptions.actual_result === "string" ? commandOptions.actual_result : undefined),
+        affectedVersion: (typeof commandOptions.affectedVersion === "string" ? commandOptions.affectedVersion : undefined) ??
+            (typeof commandOptions.affected_version === "string" ? commandOptions.affected_version : undefined),
+        fixedVersion: (typeof commandOptions.fixedVersion === "string" ? commandOptions.fixedVersion : undefined) ??
+            (typeof commandOptions.fixed_version === "string" ? commandOptions.fixed_version : undefined),
+        component: typeof commandOptions.component === "string" ? commandOptions.component : undefined,
+        regression: typeof commandOptions.regression === "string" ? commandOptions.regression : undefined,
+        customerImpact: (typeof commandOptions.customerImpact === "string" ? commandOptions.customerImpact : undefined) ??
+            (typeof commandOptions.customer_impact === "string" ? commandOptions.customer_impact : undefined),
+    };
+}
+function normalizeListOptions(options) {
+    return {
+        type: typeof options.type === "string" ? options.type : undefined,
+        tag: typeof options.tag === "string" ? options.tag : undefined,
+        priority: typeof options.priority === "string" ? options.priority : undefined,
+        deadlineBefore: typeof options.deadlineBefore === "string" ? options.deadlineBefore : undefined,
+        deadlineAfter: typeof options.deadlineAfter === "string" ? options.deadlineAfter : undefined,
+        assignee: typeof options.assignee === "string" ? options.assignee : undefined,
+        sprint: typeof options.sprint === "string" ? options.sprint : undefined,
+        release: typeof options.release === "string" ? options.release : undefined,
+        limit: typeof options.limit === "string" ? options.limit : undefined,
+    };
+}
+function normalizeSearchOptions(options) {
+    return {
+        mode: typeof options.mode === "string" ? options.mode : undefined,
+        includeLinked: options.includeLinked === true ? true : undefined,
+        type: typeof options.type === "string" ? options.type : undefined,
+        tag: typeof options.tag === "string" ? options.tag : undefined,
+        priority: typeof options.priority === "string" ? options.priority : undefined,
+        deadlineBefore: typeof options.deadlineBefore === "string" ? options.deadlineBefore : undefined,
+        deadlineAfter: typeof options.deadlineAfter === "string" ? options.deadlineAfter : undefined,
+        limit: typeof options.limit === "string" ? options.limit : undefined,
+    };
+}
+function resolveCliVersion() {
+    try {
+        const currentFilePath = fileURLToPath(import.meta.url);
+        const packageJsonPath = path.resolve(path.dirname(currentFilePath), "../../package.json");
+        const raw = fs.readFileSync(packageJsonPath, "utf8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.version === "string" ? parsed.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const program = new Command();
+program
+    .name("pm")
+    .description("Agent-friendly, git-native project management CLI.")
+    .version(resolveCliVersion())
+    .showHelpAfterError()
+    .allowExcessArguments(false)
+    .allowUnknownOption(false)
+    .option("--json", "Output JSON instead of TOON")
+    .option("--quiet", "Suppress stdout output")
+    .option("--path <dir>", "Override PM path for this command")
+    .option("--no-extensions", "Disable extension loading")
+    .option("--profile", "Print deterministic timing diagnostics")
+    .exitOverride();
+program.hook("preAction", async (_thisCommand, actionCommand) => {
+    activeExtensionHookContext = null;
+    clearActiveExtensionHooks();
+    const runtimeExtensions = await maybeLoadRuntimeExtensions(actionCommand);
+    if (!runtimeExtensions) {
+        return;
+    }
+    const globalOptions = getGlobalOptions(actionCommand);
+    const commandPath = getCommandPath(actionCommand);
+    const commandArgs = actionCommand.args.map(String);
+    activeExtensionHookContext = {
+        hooks: runtimeExtensions.hooks,
+        commandName: commandPath,
+        commandArgs,
+        pmRoot: runtimeExtensions.pmRoot,
+        profileEnabled: Boolean(globalOptions.profile),
+        migrationBlockers: runtimeExtensions.migrationBlockers,
+    };
+    setActiveExtensionHooks(runtimeExtensions.hooks);
+    setActiveExtensionCommands(runtimeExtensions.commands);
+    setActiveExtensionRenderers(runtimeExtensions.renderers);
+    const commandOptions = actionCommand.optsWithGlobals();
+    setActiveCommandContext({
+        command: commandPath,
+        args: commandArgs,
+        options: { ...commandOptions },
+        global: { ...globalOptions },
+        pm_root: runtimeExtensions.pmRoot,
+    });
+    const hookWarnings = await runBeforeCommandHooks(runtimeExtensions.hooks, {
+        command: commandPath,
+        args: commandArgs,
+        pm_root: runtimeExtensions.pmRoot,
+    });
+    if (globalOptions.profile && hookWarnings.length > 0) {
+        printError(`profile:extensions hook_warnings=${formatHookWarnings(hookWarnings)}`);
+    }
+    enforceMandatoryMigrationWriteGate(commandPath, actionCommand.optsWithGlobals(), runtimeExtensions.migrationBlockers);
+});
+program.hook("postAction", async () => {
+    await runAndClearAfterCommandHooks({ ok: true });
+});
+program
+    .command("init")
+    .argument("[prefix]", "Optional id prefix")
+    .description("Initialize .agents/pm storage and settings.")
+    .action(async (prefix, _options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runInit(prefix, globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=init took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("config")
+    .argument("<scope>", "Config scope: project|global")
+    .argument("<action>", "Config action: get|set")
+    .argument("<key>", "Config key: definition-of-done")
+    .option("--criterion <text>", "Definition-of-Done criterion (repeatable for set)", collect)
+    .description("Read or update deterministic pm settings.")
+    .action(async (scope, action, key, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const criteria = Array.isArray(options.criterion) ? options.criterion : [];
+    const result = await runConfig(scope, action, key, {
+        criterion: criteria,
+    }, globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=config took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("install")
+    .argument("<target>", "Install target: pi")
+    .option("--project", "Install Pi extension into resolved project root .pi/extensions (derived from --path, default)")
+    .option("--global", "Install Pi extension into global PI_CODING_AGENT_DIR or ~/.pi/agent")
+    .description("Install supported integrations (currently: pi).")
+    .action(async (target, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runInstall(target, {
+        project: options.project === true,
+        global: options.global === true,
+    }, globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=install took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("create")
+    .description("Create a new item with deterministic front matter and history entry.")
+    .requiredOption("--title, -t <value>", "Item title")
+    .requiredOption("--description, -d <value>", "Item description (allow empty string)")
+    .requiredOption("--type <value>", "Item type: Epic|Feature|Task|Chore|Issue")
+    .requiredOption("--status, -s <value>", "Item status")
+    .requiredOption("--priority, -p <value>", "Priority 0..4")
+    .requiredOption("--tags <value>", "Comma-separated tags, or 'none'")
+    .requiredOption("--body, -b <value>", "Item markdown body (allow empty string)")
+    .requiredOption("--deadline <value>", "ISO deadline, relative +6h/+1d/+2w, or none")
+    .option("--estimate, --estimated-minutes <value>", "Estimated minutes, or none")
+    .option("--estimated_minutes <value>", "Alias for --estimated-minutes")
+    .option("--acceptance-criteria <value>", "Acceptance criteria (allow empty string)")
+    .option("--acceptance_criteria <value>", "Alias for --acceptance-criteria")
+    .option("--ac <value>", "Alias for --acceptance-criteria")
+    .option("--definition-of-ready <value>", "Definition of ready (allow empty string, or none)")
+    .option("--definition_of_ready <value>", "Alias for --definition-of-ready")
+    .option("--order <value>", "Planning order/rank integer, or none")
+    .option("--rank <value>", "Alias for --order")
+    .option("--goal <value>", "Goal identifier, or none")
+    .option("--objective <value>", "Objective identifier, or none")
+    .option("--value <value>", "Business value summary, or none")
+    .option("--impact <value>", "Business impact summary, or none")
+    .option("--outcome <value>", "Expected outcome summary, or none")
+    .option("--why-now <value>", "Why-now rationale, or none")
+    .option("--why_now <value>", "Alias for --why-now")
+    .requiredOption("--author <value>", "Mutation author, or none")
+    .requiredOption("--message <value>", "History message (allow empty string)")
+    .requiredOption("--assignee <value>", "Item assignee, or none")
+    .option("--parent <value>", "Parent item ID, or none")
+    .option("--reviewer <value>", "Reviewer, or none")
+    .option("--risk <value>", "Risk level: low|med|medium|high|critical, or none (med persists as medium)")
+    .option("--confidence <value>", "Confidence level: 0..100|low|med|medium|high, or none (med persists as medium)")
+    .option("--sprint <value>", "Sprint identifier, or none")
+    .option("--release <value>", "Release identifier, or none")
+    .option("--blocked-by <value>", "Blocked-by item ID or reason, or none")
+    .option("--blocked_by <value>", "Alias for --blocked-by")
+    .option("--blocked-reason <value>", "Blocked reason, or none")
+    .option("--blocked_reason <value>", "Alias for --blocked-reason")
+    .option("--unblock-note <value>", "Unblock rationale note, or none")
+    .option("--unblock_note <value>", "Alias for --unblock-note")
+    .option("--reporter <value>", "Issue reporter, or none")
+    .option("--severity <value>", "Issue severity: low|med|medium|high|critical, or none (med persists as medium)")
+    .option("--environment <value>", "Issue environment context, or none")
+    .option("--repro-steps <value>", "Issue reproduction steps, or none")
+    .option("--repro_steps <value>", "Alias for --repro-steps")
+    .option("--resolution <value>", "Issue resolution summary, or none")
+    .option("--expected-result <value>", "Issue expected behavior, or none")
+    .option("--expected_result <value>", "Alias for --expected-result")
+    .option("--actual-result <value>", "Issue observed behavior, or none")
+    .option("--actual_result <value>", "Alias for --actual-result")
+    .option("--affected-version <value>", "Affected version identifier, or none")
+    .option("--affected_version <value>", "Alias for --affected-version")
+    .option("--fixed-version <value>", "Fixed version identifier, or none")
+    .option("--fixed_version <value>", "Alias for --fixed-version")
+    .option("--component <value>", "Issue component ownership, or none")
+    .option("--regression <value>", "Regression marker: true|false|1|0, or none")
+    .option("--customer-impact <value>", "Customer impact summary, or none")
+    .option("--customer_impact <value>", "Alias for --customer-impact")
+    .option("--dep <value>", "Seed dependency entry (required; use none for empty)", collect)
+    .option("--comment <value>", "Seed comment entry (required; use none for empty)", collect)
+    .option("--note <value>", "Seed note entry (required; use none for empty)", collect)
+    .option("--learning <value>", "Seed learning entry (required; use none for empty)", collect)
+    .option("--file <value>", "Seed linked file entry (required; use none for empty)", collect)
+    .option("--test <value>", "Seed linked test entry (required; use none for empty)", collect)
+    .option("--doc <value>", "Seed linked doc entry (required; use none for empty)", collect)
+    .action(async (options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const normalized = normalizeCreateOptions(options);
+    const result = await runCreate(normalized, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=create took_ms=${Date.now() - startedAt}`);
+    }
+});
+function registerListCommand(name, description, status, excludeTerminal) {
+    program
+        .command(name)
+        .description(description)
+        .option("--type <value>", "Filter by item type")
+        .option("--tag <value>", "Filter by tag")
+        .option("--priority <value>", "Filter by priority")
+        .option("--deadline-before <value>", "Filter by deadline upper bound")
+        .option("--deadline-after <value>", "Filter by deadline lower bound")
+        .option("--assignee <value>", "Filter by assignee (use 'none' for unassigned)")
+        .option("--sprint <value>", "Filter by sprint")
+        .option("--release <value>", "Filter by release")
+        .option("--limit <n>", "Limit returned item count")
+        .action(async (options, command) => {
+        const globalOptions = getGlobalOptions(command);
+        const startedAt = Date.now();
+        const listOptions = normalizeListOptions(options);
+        if (excludeTerminal)
+            listOptions.excludeTerminal = true;
+        const result = await runList(status, listOptions, globalOptions);
+        printResult(result, globalOptions);
+        if (globalOptions.profile) {
+            printError(`profile:command=${name} took_ms=${Date.now() - startedAt}`);
+        }
+    });
+}
+registerListCommand("list", "List active items (excludes closed/canceled) with optional filters.", undefined, true);
+registerListCommand("list-all", "List all items with optional filters.");
+registerListCommand("list-draft", "List draft items with optional filters.", "draft");
+registerListCommand("list-open", "List open items with optional filters.", "open");
+registerListCommand("list-in-progress", "List in-progress items with optional filters.", "in_progress");
+registerListCommand("list-blocked", "List blocked items with optional filters.", "blocked");
+registerListCommand("list-closed", "List closed items with optional filters.", "closed");
+registerListCommand("list-canceled", "List canceled items with optional filters.", "canceled");
+program
+    .command("beads")
+    .description("Built-in Beads extension commands.")
+    .command("import")
+    .description("Import Beads JSONL records as PM items.")
+    .option("--file <path>", "Path to Beads JSONL file", ".beads/issues.jsonl")
+    .option("--author <value>", "Mutation author")
+    .option("--message <value>", "History message for import entries")
+    .action(async (options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runRequiredExtensionCommand(command, options, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=beads import took_ms=${Date.now() - startedAt}`);
+    }
+});
+const todosCommand = program.command("todos").description("Built-in todos extension commands.");
+todosCommand
+    .command("import")
+    .description("Import todos markdown files as PM items.")
+    .option("--folder <path>", "Path to todos markdown folder", ".pi/todos")
+    .option("--author <value>", "Mutation author")
+    .option("--message <value>", "History message for import entries")
+    .action(async (options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runRequiredExtensionCommand(command, options, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=todos import took_ms=${Date.now() - startedAt}`);
+    }
+});
+todosCommand
+    .command("export")
+    .description("Export PM items to todos markdown files.")
+    .option("--folder <path>", "Path to todos markdown folder", ".pi/todos")
+    .action(async (options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runRequiredExtensionCommand(command, options, globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=todos export took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("search")
+    .argument("<keywords>", "Keyword query string")
+    .description("Search items across keyword and optional semantic/hybrid modes.")
+    .option("--mode <value>", "Search mode: keyword|semantic|hybrid (default: hybrid when semantic config is available, else keyword)")
+    .option("--include-linked", "Include readable linked docs/files/tests content in keyword and hybrid lexical scoring")
+    .option("--type <value>", "Filter by item type")
+    .option("--tag <value>", "Filter by tag")
+    .option("--priority <value>", "Filter by priority")
+    .option("--deadline-before <value>", "Filter by deadline upper bound")
+    .option("--deadline-after <value>", "Filter by deadline lower bound")
+    .option("--limit <n>", "Limit returned item count")
+    .action(async (keywords, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runSearch(keywords, normalizeSearchOptions(options), globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=search took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("reindex")
+    .description("Rebuild deterministic search artifacts for keyword, semantic, and hybrid modes.")
+    .option("--mode <value>", "Reindex mode: keyword|semantic|hybrid", "keyword")
+    .action(async (options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runReindex({
+        mode: typeof options.mode === "string" ? options.mode : undefined,
+    }, globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=reindex took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("get")
+    .argument("<id>", "Item id")
+    .description("Get item details by id.")
+    .action(async (id, _options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runGet(id, globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=get took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("history")
+    .argument("<id>", "Item id")
+    .option("--limit <n>", "Return only the latest n history entries")
+    .description("Show append-only history entries for an item.")
+    .action(async (id, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runHistory(id, {
+        limit: typeof options.limit === "string" ? options.limit : undefined,
+    }, globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=history took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("activity")
+    .option("--limit <n>", "Return only the latest n activity entries")
+    .description("Show recent activity across all item history streams.")
+    .action(async (options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runActivity({
+        limit: typeof options.limit === "string" ? options.limit : undefined,
+    }, globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=activity took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("restore")
+    .argument("<id>", "Item id")
+    .argument("<target>", "Restore target timestamp or version number")
+    .option("--author <value>", "Mutation author")
+    .option("--message <value>", "History message")
+    .option("--force", "Force ownership/lock override")
+    .description("Restore an item to a previous timestamp or version.")
+    .action(async (id, target, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runRestore(id, target, {
+        author: typeof options.author === "string" ? options.author : undefined,
+        message: typeof options.message === "string" ? options.message : undefined,
+        force: Boolean(options.force),
+    }, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=restore took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("update")
+    .argument("<id>", "Item id")
+    .description("Update item front-matter fields.")
+    .option("--title, -t <value>", "Set title")
+    .option("--description, -d <value>", "Set description")
+    .option("--status, -s <value>", "Set status (use close command for closed)")
+    .option("--priority, -p <value>", "Set priority")
+    .option("--type <value>", "Set type")
+    .option("--tags <value>", "Set comma-separated tags")
+    .option("--deadline <value>", "Set deadline (or none)")
+    .option("--estimate, --estimated-minutes <value>", "Set estimated minutes (or none)")
+    .option("--estimated_minutes <value>", "Alias for --estimated-minutes")
+    .option("--acceptance-criteria <value>", "Set acceptance criteria (or none)")
+    .option("--acceptance_criteria <value>", "Alias for --acceptance-criteria")
+    .option("--ac <value>", "Alias for --acceptance-criteria")
+    .option("--definition-of-ready <value>", "Set definition of ready (or none)")
+    .option("--definition_of_ready <value>", "Alias for --definition-of-ready")
+    .option("--order <value>", "Set planning order/rank integer (or none)")
+    .option("--rank <value>", "Alias for --order")
+    .option("--goal <value>", "Set goal identifier (or none)")
+    .option("--objective <value>", "Set objective identifier (or none)")
+    .option("--value <value>", "Set business value summary (or none)")
+    .option("--impact <value>", "Set business impact summary (or none)")
+    .option("--outcome <value>", "Set expected outcome summary (or none)")
+    .option("--why-now <value>", "Set why-now rationale (or none)")
+    .option("--why_now <value>", "Alias for --why-now")
+    .option("--author <value>", "Mutation author")
+    .option("--message <value>", "Mutation message")
+    .option("--assignee <value>", "Set assignee (or none)")
+    .option("--parent <value>", "Set parent item ID (or none)")
+    .option("--reviewer <value>", "Set reviewer (or none)")
+    .option("--risk <value>", "Set risk level: low|med|medium|high|critical (or none; med persists as medium)")
+    .option("--confidence <value>", "Set confidence level: 0..100|low|med|medium|high (or none; med persists as medium)")
+    .option("--sprint <value>", "Set sprint identifier (or none)")
+    .option("--release <value>", "Set release identifier (or none)")
+    .option("--blocked-by <value>", "Set blocked-by item ID or reason (or none)")
+    .option("--blocked_by <value>", "Alias for --blocked-by")
+    .option("--blocked-reason <value>", "Set blocked reason (or none)")
+    .option("--blocked_reason <value>", "Alias for --blocked-reason")
+    .option("--unblock-note <value>", "Set unblock rationale note (or none)")
+    .option("--unblock_note <value>", "Alias for --unblock-note")
+    .option("--reporter <value>", "Set issue reporter (or none)")
+    .option("--severity <value>", "Set issue severity: low|med|medium|high|critical (or none; med persists as medium)")
+    .option("--environment <value>", "Set issue environment context (or none)")
+    .option("--repro-steps <value>", "Set issue reproduction steps (or none)")
+    .option("--repro_steps <value>", "Alias for --repro-steps")
+    .option("--resolution <value>", "Set issue resolution summary (or none)")
+    .option("--expected-result <value>", "Set issue expected behavior (or none)")
+    .option("--expected_result <value>", "Alias for --expected-result")
+    .option("--actual-result <value>", "Set issue observed behavior (or none)")
+    .option("--actual_result <value>", "Alias for --actual-result")
+    .option("--affected-version <value>", "Set affected version identifier (or none)")
+    .option("--affected_version <value>", "Alias for --affected-version")
+    .option("--fixed-version <value>", "Set fixed version identifier (or none)")
+    .option("--fixed_version <value>", "Alias for --fixed-version")
+    .option("--component <value>", "Set issue component ownership (or none)")
+    .option("--regression <value>", "Set regression marker: true|false|1|0 (or none)")
+    .option("--customer-impact <value>", "Set customer impact summary (or none)")
+    .option("--customer_impact <value>", "Alias for --customer-impact")
+    .option("--force", "Force ownership override")
+    .action(async (id, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runUpdate(id, normalizeUpdateOptions(options), globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=update took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("close")
+    .argument("<id>", "Item id")
+    .argument("<text>", "Close reason text")
+    .option("--author <value>", "Mutation author")
+    .option("--message <value>", "History message")
+    .option("--force", "Force ownership override")
+    .description("Close an item with required reason text.")
+    .action(async (id, text, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runClose(id, text, {
+        author: typeof options.author === "string" ? options.author : undefined,
+        message: typeof options.message === "string" ? options.message : undefined,
+        force: Boolean(options.force),
+    }, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=close took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("delete")
+    .argument("<id>", "Item id")
+    .option("--author <value>", "Mutation author")
+    .option("--message <value>", "History message")
+    .option("--force", "Force ownership override")
+    .description("Delete an item and append a delete history entry.")
+    .action(async (id, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runDelete(id, {
+        author: typeof options.author === "string" ? options.author : undefined,
+        message: typeof options.message === "string" ? options.message : undefined,
+        force: Boolean(options.force),
+    }, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=delete took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("append")
+    .argument("<id>", "Item id")
+    .requiredOption("--body <value>", "Text to append to body")
+    .option("--author <value>", "Mutation author")
+    .option("--message <value>", "Mutation message")
+    .option("--force", "Force ownership override")
+    .description("Append text to an item body.")
+    .action(async (id, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runAppend(id, {
+        body: typeof options.body === "string" ? options.body : "",
+        author: typeof options.author === "string" ? options.author : undefined,
+        message: typeof options.message === "string" ? options.message : undefined,
+        force: Boolean(options.force),
+    }, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=append took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("comments")
+    .argument("<id>", "Item id")
+    .option("--add <text>", "Add one comment entry")
+    .option("--limit <n>", "Return only latest n comments")
+    .option("--author <value>", "Comment author")
+    .option("--message <value>", "History message")
+    .option("--force", "Force ownership override")
+    .description("List or append comments for an item.")
+    .action(async (id, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runComments(id, {
+        add: typeof options.add === "string" ? options.add : undefined,
+        limit: typeof options.limit === "string" ? options.limit : undefined,
+        author: typeof options.author === "string" ? options.author : undefined,
+        message: typeof options.message === "string" ? options.message : undefined,
+        force: Boolean(options.force),
+    }, globalOptions);
+    if (typeof options.add === "string") {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=comments took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("files")
+    .argument("<id>", "Item id")
+    .option("--add <value>", "Add linked file entry", collect)
+    .option("--remove <value>", "Remove linked file by path", collect)
+    .option("--author <value>", "Mutation author")
+    .option("--message <value>", "History message")
+    .option("--force", "Force ownership override")
+    .description("List/add/remove linked files.")
+    .action(async (id, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const addValues = Array.isArray(options.add) ? options.add : [];
+    const removeValues = Array.isArray(options.remove) ? options.remove : [];
+    const result = await runFiles(id, {
+        add: addValues,
+        remove: removeValues,
+        author: typeof options.author === "string" ? options.author : undefined,
+        message: typeof options.message === "string" ? options.message : undefined,
+        force: Boolean(options.force),
+    }, globalOptions);
+    if (addValues.length > 0 || removeValues.length > 0) {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=files took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("docs")
+    .argument("<id>", "Item id")
+    .option("--add <value>", "Add linked doc entry", collect)
+    .option("--remove <value>", "Remove linked doc by path", collect)
+    .option("--author <value>", "Mutation author")
+    .option("--message <value>", "History message")
+    .option("--force", "Force ownership override")
+    .description("List/add/remove linked docs.")
+    .action(async (id, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const addValues = Array.isArray(options.add) ? options.add : [];
+    const removeValues = Array.isArray(options.remove) ? options.remove : [];
+    const result = await runDocs(id, {
+        add: addValues,
+        remove: removeValues,
+        author: typeof options.author === "string" ? options.author : undefined,
+        message: typeof options.message === "string" ? options.message : undefined,
+        force: Boolean(options.force),
+    }, globalOptions);
+    if (addValues.length > 0 || removeValues.length > 0) {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=docs took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("test")
+    .argument("<id>", "Item id")
+    .option("--add <value>", "Add linked test entry", collect)
+    .option("--remove <value>", "Remove linked test entry by command/path", collect)
+    .option("--run", "Run linked test commands")
+    .option("--timeout <seconds>", "Default run timeout in seconds")
+    .option("--author <value>", "Mutation author")
+    .option("--message <value>", "History message")
+    .option("--force", "Force ownership override")
+    .description("List/add/remove linked tests and optionally run them.")
+    .action(async (id, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const addValues = Array.isArray(options.add) ? options.add : [];
+    const removeValues = Array.isArray(options.remove) ? options.remove : [];
+    const result = await runTest(id, {
+        add: addValues,
+        remove: removeValues,
+        run: Boolean(options.run),
+        timeout: typeof options.timeout === "string" ? options.timeout : undefined,
+        author: typeof options.author === "string" ? options.author : undefined,
+        message: typeof options.message === "string" ? options.message : undefined,
+        force: Boolean(options.force),
+    }, globalOptions);
+    if (addValues.length > 0 || removeValues.length > 0) {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=test took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("test-all")
+    .description("Run linked test commands across many items.")
+    .option("--status <value>", "Filter items by status before running tests")
+    .option("--timeout <seconds>", "Default run timeout in seconds")
+    .action(async (options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runTestAll({
+        status: typeof options.status === "string" ? options.status : undefined,
+        timeout: typeof options.timeout === "string" ? options.timeout : undefined,
+    }, globalOptions);
+    printResult(result, globalOptions);
+    if (result.failed > 0) {
+        process.exitCode = EXIT_CODE.DEPENDENCY_FAILED;
+    }
+    if (globalOptions.profile) {
+        printError(`profile:command=test-all took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("stats")
+    .description("Show deterministic tracker statistics summary.")
+    .action(async (_options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runStats(globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=stats took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("health")
+    .description("Show deterministic tracker health checks summary.")
+    .action(async (_options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runHealth(globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=health took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("gc")
+    .description("Collect optional cache artifacts and report deterministic summary.")
+    .action(async (_options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runGc(globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=gc took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("claim")
+    .argument("<id>", "Item id")
+    .option("--author <value>", "Mutation author")
+    .option("--message <value>", "History message")
+    .option("--force", "Force claim override")
+    .description("Claim ownership of an item.")
+    .action(async (id, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runClaim(id, Boolean(options.force), globalOptions, {
+        author: typeof options.author === "string" ? options.author : undefined,
+        message: typeof options.message === "string" ? options.message : undefined,
+    });
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=claim took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("release")
+    .argument("<id>", "Item id")
+    .option("--author <value>", "Mutation author")
+    .option("--message <value>", "History message")
+    .option("--force", "Force release override")
+    .description("Release ownership of an item.")
+    .action(async (id, options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const result = await runRelease(id, Boolean(options.force), globalOptions, {
+        author: typeof options.author === "string" ? options.author : undefined,
+        message: typeof options.message === "string" ? options.message : undefined,
+    });
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=release took_ms=${Date.now() - startedAt}`);
+    }
+});
+program
+    .command("completion")
+    .argument("<shell>", "Shell type: bash, zsh, or fish")
+    .description("Generate shell completion script for pm.")
+    .action((shell, _options, command) => {
+    const globalOptions = getGlobalOptions(command);
+    const result = runCompletion(shell);
+    if (globalOptions.json) {
+        printResult(result, globalOptions);
+    }
+    else if (!globalOptions.quiet) {
+        process.stdout.write(`${result.script}\n`);
+    }
+    if (globalOptions.profile) {
+        printError(`profile:command=completion took_ms=0`);
+    }
+});
+async function main() {
+    try {
+        await registerDynamicExtensionCommandPaths(program);
+        await program.parseAsync(process.argv);
+    }
+    catch (error) {
+        await runAndClearAfterCommandHooks({
+            ok: false,
+            error: describeUnknownError(error),
+        });
+        if (error instanceof PmCliError) {
+            printError(error.message);
+            process.exit(error.exitCode);
+        }
+        if (typeof error === "object" && error !== null && "code" in error) {
+            const code = error.code;
+            if (code === "commander.helpDisplayed") {
+                process.exit(EXIT_CODE.SUCCESS);
+            }
+            if (code === "commander.version") {
+                process.exit(EXIT_CODE.SUCCESS);
+            }
+            if (code?.startsWith("commander.")) {
+                const message = error.message ?? "Invalid command usage";
+                printError(message.replace(/\(outputHelp\)/g, "").trim());
+                process.exit(EXIT_CODE.USAGE);
+            }
+        }
+        const message = describeUnknownError(error);
+        printError(message);
+        process.exit(EXIT_CODE.GENERIC_FAILURE);
+    }
+}
+void main();
+//# sourceMappingURL=main.js.map