@unbrained/pm-cli 2026.8.26 → 2026.8.28

package/dist/cli/register-annotations.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="79bf0b3f-ad63-5d9f-9911-d5a142214ac1")}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]="775518a4-ff3e-5a54-8fbd-b2c4863e23db")}catch(e){}}();
 import { EXIT_CODE, PmCliError, } from "../sdk/runtime-primitives.js";
 import { renderPmCommand } from "../sdk/command-line.js";
 import { runComments } from "./commands/comments.js";
@@ -11,6 +11,7 @@ function assertNoTransposedAnnotationAction(collection, id, text, options) {
         return;
     }
     const suppliedText = readOptionString(options, "add") ??
+        readOptionString(options, "text") ??
         readOptionString(options, "note") ??
         readOptionString(options, "body") ??
         readOptionString(options, "comment");
@@ -25,12 +26,7 @@ function assertNoTransposedAnnotationAction(collection, id, text, options) {
     else
         retryArgs.push("--add", "-");
     const suggestedRetry = renderPmCommand(retryArgs);
-    const stdinRetry = renderPmCommand([
-        collection,
-        text.trim(),
-        "--add",
-        "-",
-    ]);
+    const stdinRetry = renderPmCommand([collection, text.trim(), "--add", "-"]);
     throw new PmCliError(`The positional token "add" was parsed as the item id, while "${text.trim()}" was parsed as annotation text. ${collection} does not use an add subcommand.`, EXIT_CODE.USAGE, {
         code: "annotation_transposed_subcommand",
         reason: "noun_verb_object_transposition",
@@ -47,12 +43,26 @@ function assertNoTransposedAnnotationAction(collection, id, text, options) {
         },
     });
 }
+function resolveAnnotationTextAliases(label, options, aliases) {
+    const supplied = aliases.flatMap((alias) => {
+        const value = readOptionString(options, alias);
+        return value === undefined ? [] : [{ alias, value }];
+    });
+    const distinctValues = [...new Set(supplied.map(({ value }) => value))];
+    if (distinctValues.length > 1) {
+        throw new PmCliError(`Specify ${label} text with one alias or the same value across aliases: ${supplied.map(({ alias }) => `--${alias}`).join(", ")}`, EXIT_CODE.USAGE, { code: "annotation_alias_conflict" });
+    }
+    return supplied[0]?.value;
+}
 function resolveCommentSources(text, options) {
     const editIndex = typeof options.edit === "number" ? options.edit : undefined;
     const deleteIndex = typeof options.delete === "number" ? options.delete : undefined;
-    const addFromOption = readOptionString(options, "add") ??
-        readOptionString(options, "body") ??
-        readOptionString(options, "comment");
+    const addFromOption = resolveAnnotationTextAliases("comment", options, [
+        "add",
+        "text",
+        "body",
+        "comment",
+    ]);
     const addFromPositional = typeof text === "string" ? text : undefined;
     const readFromStdin = options.stdin === true;
     const readFromFile = readOptionString(options, "file");
@@ -83,20 +93,33 @@ function resolveCommentSources(text, options) {
             deleteIndex !== undefined,
     };
 }
-function resolveSingleTextSource(label, positional, options) {
-    const canonicalAdd = readOptionString(options, "add");
-    const aliasAdd = label === "note" ? readOptionString(options, "note") : undefined;
-    if (canonicalAdd !== undefined &&
-        aliasAdd !== undefined &&
-        canonicalAdd !== aliasAdd) {
-        throw new PmCliError("Specify note text with either --add or --note, not conflicting values for both aliases", EXIT_CODE.USAGE, { code: "annotation_alias_conflict" });
-    }
-    const addFromOption = canonicalAdd ?? aliasAdd;
+/** Resolves every mutation-bearing source for notes and learnings once. */
+function resolveSingleAnnotationSources(label, positional, options) {
+    const addFromOption = resolveAnnotationTextAliases(label, options, label === "note" ? ["add", "text", "note"] : ["add", "text"]);
     const addFromPositional = typeof positional === "string" ? positional : undefined;
     if (addFromOption !== undefined && addFromPositional !== undefined) {
         throw new PmCliError(`Specify ${label} text either as positional [text] or with --add, not both`, EXIT_CODE.USAGE);
     }
-    return addFromOption ?? addFromPositional;
+    const add = addFromOption ?? addFromPositional;
+    const addJson = label === "note" ? readOptionString(options, "addJson") : undefined;
+    const readFromStdin = options.stdin === true;
+    const readFromFile = readOptionString(options, "file");
+    const editIndex = typeof options.edit === "number" ? options.edit : undefined;
+    const deleteIndex = typeof options.delete === "number" ? options.delete : undefined;
+    return {
+        add,
+        addJson,
+        readFromStdin,
+        readFromFile,
+        editIndex,
+        deleteIndex,
+        isMutation: typeof add === "string" ||
+            addJson !== undefined ||
+            readFromStdin ||
+            readFromFile !== undefined ||
+            editIndex !== undefined ||
+            deleteIndex !== undefined,
+    };
 }
 async function runCommentsAction(id, text, options, command) {
     const globalOptions = getGlobalOptions(command);
@@ -111,12 +134,13 @@ async function runCommentsAction(id, text, options, command) {
         delete: sources.deleteIndex,
         limit: readOptionString(options, "limit"),
         fullHistory: options.fullHistory === true,
+        ifAbsent: options.ifAbsent === true,
         author: readOptionString(options, "author"),
         message: readOptionString(options, "message"),
         ownershipAppendBypass: options.ownershipAppendBypass === true,
         force: Boolean(options.force),
     }, globalOptions);
-    if (sources.isMutation) {
+    if (sources.isMutation && result.changed !== false) {
         await invalidateSearchCachesForMutation(globalOptions, result);
     }
     printAnnotationResult("comments", result, globalOptions, startedAt);
@@ -125,30 +149,26 @@ async function runNotesAction(id, text, options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
     assertNoTransposedAnnotationAction("notes", id, text, options);
-    const add = resolveSingleTextSource("note", text, options);
+    const sources = resolveSingleAnnotationSources("note", text, options);
     const result = await runNotes(id, {
-        add,
-        addJson: readOptionString(options, "addJson"),
-        stdin: options.stdin === true,
-        file: readOptionString(options, "file"),
-        edit: typeof options.edit === "number" ? options.edit : undefined,
-        delete: typeof options.delete === "number" ? options.delete : undefined,
+        add: sources.add,
+        addJson: sources.addJson,
+        stdin: sources.readFromStdin,
+        file: sources.readFromFile,
+        edit: sources.editIndex,
+        delete: sources.deleteIndex,
         limit: readOptionString(options, "limit"),
         since: readOptionString(options, "since"),
         eventType: readOptionString(options, "eventType"),
         includeMeta: options.includeMeta === true,
         fullHistory: options.fullHistory === true,
+        ifAbsent: options.ifAbsent === true,
         author: readOptionString(options, "author"),
         message: readOptionString(options, "message"),
         ownershipAppendBypass: options.ownershipAppendBypass === true,
         force: Boolean(options.force),
     }, globalOptions);
-    if (typeof add === "string" ||
-        typeof options.addJson === "string" ||
-        options.stdin === true ||
-        typeof options.file === "string" ||
-        typeof options.edit === "number" ||
-        typeof options.delete === "number") {
+    if (sources.isMutation && result.changed !== false) {
         await invalidateSearchCachesForMutation(globalOptions, result);
     }
     printAnnotationResult("notes", result, globalOptions, startedAt);
@@ -157,25 +177,22 @@ async function runLearningsAction(id, text, options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
     assertNoTransposedAnnotationAction("learnings", id, text, options);
-    const add = resolveSingleTextSource("learning", text, options);
+    const sources = resolveSingleAnnotationSources("learning", text, options);
     const result = await runLearnings(id, {
-        add,
-        stdin: options.stdin === true,
-        file: readOptionString(options, "file"),
-        edit: typeof options.edit === "number" ? options.edit : undefined,
-        delete: typeof options.delete === "number" ? options.delete : undefined,
+        add: sources.add,
+        stdin: sources.readFromStdin,
+        file: sources.readFromFile,
+        edit: sources.editIndex,
+        delete: sources.deleteIndex,
         limit: readOptionString(options, "limit"),
         fullHistory: options.fullHistory === true,
+        ifAbsent: options.ifAbsent === true,
         author: readOptionString(options, "author"),
         message: readOptionString(options, "message"),
         ownershipAppendBypass: options.ownershipAppendBypass === true,
         force: Boolean(options.force),
     }, globalOptions);
-    if (typeof add === "string" ||
-        options.stdin === true ||
-        typeof options.file === "string" ||
-        typeof options.edit === "number" ||
-        typeof options.delete === "number") {
+    if (sources.isMutation && result.changed !== false) {
         await invalidateSearchCachesForMutation(globalOptions, result);
     }
     printAnnotationResult("learnings", result, globalOptions, startedAt);
@@ -192,27 +209,29 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .command("comments")
         .argument("<id>", "Item id")
         .argument("[text]", "Optional comment text shorthand (equivalent to --add)")
-        .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("--add <text>", "Append comment text; use text=<value> for structured input or - for stdin")
         .option("--stdin", "Read comment text from stdin (supports multiline markdown)")
         .option("--file <path>", "Read comment text from a file or stdin (-)")
-        .option("--edit <index>", "Replace the comment at 1-based <index> (replacement text from positional [text], --add, --stdin, or --file)", parsePositiveInteger("--edit"))
+        .option("--edit <index>", "Replace one comment using positional text, --add, --stdin, or --file", parsePositiveInteger("--edit"))
         .option("--delete <index>", "Delete the comment at 1-based <index>", parsePositiveInteger("--delete"))
         .option("--limit <n>", "Return only latest n comments")
-        .option("--full-history", "Return the complete post-mutation comment history instead of a bounded receipt")
-        .option("--author [value]", "Comment author (optional; falls back to PM_AUTHOR/settings)")
+        .option("--full-history", "Return complete comment history instead of a bounded mutation receipt")
+        .option("--if-absent", "Append only when resolved author and text are absent")
+        .option("--author [value]", "Comment author; defaults to PM_AUTHOR or settings")
         .option("--message <value>", "History message")
         .option("--force", "Force ownership override")
         .description("List, add, edit, or delete comments for an item.")
         .action(runCommentsAction);
     addHiddenOption(commentsCommand, "--body <text>", "Alias for --add", false);
+    addHiddenOption(commentsCommand, "--text <text>", "Alias for --add", false);
     addHiddenOption(commentsCommand, "--comment <text>", "Alias for --add", false);
-    program
+    const notesCommand = program
         .command("notes")
         .argument("<id>", "Item id")
-        .argument("[text]", "Optional note text shorthand (equivalent to --add; use - for stdin)")
+        .argument("[text]", "Optional note text shorthand for --add")
         .option("--add <text>", "Add a text note (- reads stdin)")
         .option("--note <text>", "Alias for --add")
-        .option("--add-json <json>", "Append a merge-safe JSON event")
+        .option("--add-json <json>", "Append a JSON event")
         .option("--stdin", "Read note text from stdin")
         .option("--file <path>", "Read note from file or stdin (-)")
         .option("--edit <index>", "Replace a 1-based note using the selected text input", parsePositiveInteger("--edit"))
@@ -221,28 +240,32 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .option("--since <timestamp>", "Filter JSON events from this ISO time")
         .option("--event-type <value>", "Filter JSON events by top-level type")
         .option("--include-meta", "Include count and truncation metadata")
-        .option("--full-history", "Return the complete post-mutation note history instead of a bounded receipt")
+        .option("--full-history", "Return complete note history instead of a bounded receipt")
+        .option("--if-absent", "Append only when resolved author and text are absent")
         .option("--author [value]", "Author; defaults to PM_AUTHOR/settings")
         .option("--message <value>", "History message")
         .option("--force", "Force ownership override")
         .description("Manage merge-safe text notes and JSON context events.")
         .action(runNotesAction);
-    program
+    addHiddenOption(notesCommand, "--text <text>", "Alias for --add", false);
+    const learningsCommand = program
         .command("learnings")
         .argument("<id>", "Item id")
-        .argument("[text]", "Optional learning text shorthand (equivalent to --add; use - for stdin)")
-        .option("--add <text>", "Add one learning 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 learning text from stdin (supports multiline markdown)")
+        .argument("[text]", "Optional learning text shorthand for --add")
+        .option("--add <text>", "Append learning text; use text=<value> or - for stdin")
+        .option("--stdin", "Read learning text from stdin")
         .option("--file <path>", "Read learning text from a file or stdin (-)")
-        .option("--edit <index>", "Replace the learning at 1-based <index> (replacement text from positional [text], --add, --stdin, or --file)", parsePositiveInteger("--edit"))
+        .option("--edit <index>", "Replace one learning using positional text, --add, --stdin, or --file", parsePositiveInteger("--edit"))
         .option("--delete <index>", "Delete the learning at 1-based <index>", parsePositiveInteger("--delete"))
         .option("--limit <n>", "Return only latest n learnings")
-        .option("--full-history", "Return the complete post-mutation learning history instead of a bounded receipt")
+        .option("--full-history", "Return complete learning history instead of a bounded receipt")
+        .option("--if-absent", "Append only when resolved author and text are absent")
         .option("--author [value]", "Learning author (optional; falls back to PM_AUTHOR/settings)")
         .option("--message <value>", "History message")
         .option("--force", "Force ownership override")
         .description("List, add, edit, or delete learnings for an item.")
         .action(runLearningsAction);
+    addHiddenOption(learningsCommand, "--text <text>", "Alias for --add", false);
 }
 //# sourceMappingURL=register-annotations.js.map
-//# debugId=79bf0b3f-ad63-5d9f-9911-d5a142214ac1
+//# debugId=775518a4-ff3e-5a54-8fbd-b2c4863e23db

package/dist/cli/register-setup.js

@@ -1,8 +1,9 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2a7939ad-52a6-5d9c-b7cf-2bc59a6b3d32")}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]="feb682f9-344c-569e-bbab-861fe20f08f1")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
-import { EXIT_CODE, PmCliError, } from "../sdk/runtime-primitives.js";
+import { EXIT_CODE, PmCliError, readSettings, resolvePmRoot, } from "../sdk/runtime-primitives.js";
+import { renderPmCommandAliasMigrationHint, resolvePmCommandAlias, } from "../sdk/cli-contracts.js";
 import { collect, getGlobalOptions, printError, printResult, writeStdout, } from "./registration-helpers.js";
 import { runExtension, } from "./commands/extension.js";
 import { SCAFFOLD_CAPABILITIES } from "./commands/extension/scaffold.js";
@@ -10,6 +11,20 @@ import { renderExtensionDescribeMarkdown, } from "./commands/extension/describe.
 import { runConfig } from "./commands/config.js";
 import { runInit, summarizeInitResult } from "./commands/init.js";
 import { runUpgrade } from "./commands/upgrade.js";
+const LIFECYCLE_DEPRECATION_ALIASES = {
+    extension: "extension",
+    package: undefined,
+};
+async function emitDeprecatedAliasHint(alias, command) {
+    if (!alias)
+        return;
+    const aliasContract = resolvePmCommandAlias(alias);
+    const globalOptions = getGlobalOptions(command);
+    const deprecationHints = await readSettings(resolvePmRoot(process.cwd(), globalOptions.path)).then((settings) => settings.ux.deprecation_hints);
+    if (deprecationHints) {
+        printError(renderPmCommandAliasMigrationHint(aliasContract));
+    }
+}
 const EXTENSION_ACTION_OPTION_KEYS = {
     init: "init",
     install: "install",
@@ -181,7 +196,9 @@ function applyExtensionDoctorStrictExit(result, normalizedOptions) {
 async function executeExtensionCommand(target, options, command, forcedAction, vocabulary = "extension") {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
-    const normalizedOptions = normalizeExtensionOptions(options, forcedAction, vocabulary);
+    const effectiveVocabulary = vocabulary === "extension" ? "package" : vocabulary;
+    await emitDeprecatedAliasHint(LIFECYCLE_DEPRECATION_ALIASES[vocabulary], command);
+    const normalizedOptions = normalizeExtensionOptions(options, forcedAction, effectiveVocabulary);
     const outputOption = typeof normalizedOptions.output === "string"
         ? normalizedOptions.output
         : undefined;
@@ -191,7 +208,7 @@ async function executeExtensionCommand(target, options, command, forcedAction, v
     if (normalizedOptions.markdown === true) {
         await emitExtensionMarkdownResult({
             result,
-            vocabulary,
+            vocabulary: effectiveVocabulary,
             outputPath,
             globalOptions,
         });
@@ -225,36 +242,13 @@ function serializeExtensionInstallError(error) {
         exit_code: EXIT_CODE.GENERIC_FAILURE,
     };
 }
-async function executeExtensionInstallCommand(targets, options, command, vocabulary) {
-    const normalizedTargets = await normalizeInstallTargets(targets);
-    if (normalizedTargets === undefined || normalizedTargets.length <= 1) {
-        await executeExtensionCommand(normalizedTargets?.[0], options, command, "install", vocabulary);
-        return;
-    }
-    const globalOptions = getGlobalOptions(command);
-    const startedAt = Date.now();
-    const normalizedOptions = normalizeExtensionOptions(options, "install", vocabulary);
-    validateExtensionMarkdownOptions(normalizedOptions, globalOptions, undefined);
-    const hasForcedGithubSource = [
-        normalizedOptions.gh,
-        normalizedOptions.github,
-    ].some((value) => typeof value === "string" && value.trim().length > 0);
-    if (hasForcedGithubSource) {
-        throw new PmCliError("Multiple install targets cannot be combined with --gh/--github. Install one GitHub source per command, or pass multiple explicit local, bundled, or npm: targets.", EXIT_CODE.USAGE, {
-            code: "multi_target_github_install_ambiguous",
-            required: "Use exactly one positional target with --gh/--github, or omit --gh/--github when installing multiple targets.",
-            examples: [
-                "pm install --gh owner/repo",
-                "pm install npm:pm-guide-shell pm-todos",
-            ],
-        });
-    }
+async function runMultiTargetExtensionInstalls(targets, options, globalOptions) {
     const rows = [];
     const warnings = [];
     let failureExitCode = EXIT_CODE.GENERIC_FAILURE;
-    for (const target of normalizedTargets) {
+    for (const target of targets) {
         try {
-            const result = await runExtension(target, normalizedOptions, globalOptions);
+            const result = await runExtension(target, options, globalOptions);
             const details = extractExtensionInstallDetails(result);
             const targetWarnings = Array.isArray(result.warnings)
                 ? result.warnings
@@ -302,6 +296,35 @@ async function executeExtensionInstallCommand(targets, options, command, vocabul
             });
         }
     }
+    return { rows, warnings, failureExitCode };
+}
+async function executeExtensionInstallCommand(targets, options, command, vocabulary) {
+    const effectiveVocabulary = vocabulary === "extension" ? "package" : vocabulary;
+    await emitDeprecatedAliasHint(LIFECYCLE_DEPRECATION_ALIASES[vocabulary], command);
+    const normalizedTargets = await normalizeInstallTargets(targets);
+    if (normalizedTargets === undefined || normalizedTargets.length <= 1) {
+        await executeExtensionCommand(normalizedTargets?.[0], options, command, "install", effectiveVocabulary);
+        return;
+    }
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const normalizedOptions = normalizeExtensionOptions(options, "install", effectiveVocabulary);
+    validateExtensionMarkdownOptions(normalizedOptions, globalOptions, undefined);
+    const hasForcedGithubSource = [
+        normalizedOptions.gh,
+        normalizedOptions.github,
+    ].some((value) => typeof value === "string" && value.trim().length > 0);
+    if (hasForcedGithubSource) {
+        throw new PmCliError("Multiple install targets cannot be combined with --gh/--github. Install one GitHub source per command, or pass multiple explicit local, bundled, or npm: targets.", EXIT_CODE.USAGE, {
+            code: "multi_target_github_install_ambiguous",
+            required: "Use exactly one positional target with --gh/--github, or omit --gh/--github when installing multiple targets.",
+            examples: [
+                "pm install --gh owner/repo",
+                "pm install npm:pm-guide-shell pm-todos",
+            ],
+        });
+    }
+    const { rows, warnings, failureExitCode } = await runMultiTargetExtensionInstalls(normalizedTargets, normalizedOptions, globalOptions);
     const failedCount = rows.filter((row) => row.ok !== true).length;
     const result = {
         ok: failedCount === 0,
@@ -337,17 +360,41 @@ function addLifecycleScopeOptions(command, vocabulary) {
         ? addPackageScopeOptions(command)
         : addExtensionScopeOptions(command);
 }
+function addUpgradeOptions(command) {
+    return command
+        .option("--dry-run", "Plan CLI/package upgrades without running npm or reinstalling packages")
+        .option("--cli-only", "Upgrade only the pm CLI/SDK npm package")
+        .option("--packages-only", "Upgrade only managed pm packages")
+        .option("--repair", "Force npm global reinstall when upgrading the pm CLI/SDK")
+        .option("--tag <value>", "npm dist-tag/version for CLI and registry package upgrades")
+        .option("--package-name <value>", "Override the CLI package name for self-upgrade testing");
+}
+async function executeUpgradeCommand(target, command, legacyAlias) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    if (legacyAlias) {
+        await emitDeprecatedAliasHint("upgrade", command);
+    }
+    const result = await runUpgrade(target, command.opts(), globalOptions);
+    printResult(result, globalOptions);
+    if (!result.ok) {
+        process.exitCode = EXIT_CODE.GENERIC_FAILURE;
+    }
+    if (globalOptions.profile) {
+        printError(`profile:command=package-upgrade took_ms=${Date.now() - startedAt}`);
+    }
+}
 function registerLifecycleCommand(program, vocabulary) {
     const noun = vocabulary === "package" ? "package" : "extension";
     const plural = vocabulary === "package" ? "packages" : "extensions";
     const commandName = vocabulary;
     const lifecycleCommand = program
-        .command(commandName)
-        .argument("[target]", `${noun[0].toUpperCase()}${noun.slice(1)} source/name or scaffold target path (for --init/--scaffold)`)
+        .command(commandName, { hidden: vocabulary === "extension" })
+        .argument("[target]", `${noun[0].toUpperCase()}${noun.slice(1)} source, name, or scaffold path`)
         .option("--init", `Generate a starter ${noun} scaffold at target path`)
         .option("--scaffold", "Alias for --init")
-        .option("--capability <kind>", `Capability the --init starter targets (${SCAFFOLD_CAPABILITIES.join("|")}; default commands)`, collect)
-        .option("--install", `Install ${noun} from local path, bundled alias, npm: source, wildcard, or GitHub source`)
+        .option("--capability <kind>", "Starter capability for --init (default: commands)", collect)
+        .option("--install", `Install a ${noun} source`)
         .option("--uninstall", `Uninstall an installed ${noun}`)
         .option("--explore", `List discovered ${plural} in selected scope`)
         .option("--list", "Alias for --explore")
@@ -378,8 +425,8 @@ function registerLifecycleCommand(program, vocabulary) {
         .option("--strict-exit", "Return non-zero exit when doctor warnings are present (ok=false)")
         .option("--fail-on-warn", "Alias for --strict-exit (doctor)")
         .description(vocabulary === "package"
-        ? "Manage package lifecycle operations for project or global scope. Backward-compatible with extension packages."
-        : "Manage extension lifecycle operations for project or global scope.")
+        ? "Manage package lifecycle in project or global scope."
+        : "Manage extension lifecycle in project or global scope.")
         .action(async (target, _options, command) => {
         await executeExtensionCommand(target, command.optsWithGlobals(), command, undefined, vocabulary);
     });
@@ -499,6 +546,14 @@ function registerLifecycleCommand(program, vocabulary) {
         .description(`Deactivate a ${noun} in selected scope settings.`), vocabulary).action(async (target, _options, command) => {
         await executeExtensionCommand(target, command.optsWithGlobals(), command, "deactivate", vocabulary);
     });
+    if (vocabulary === "package") {
+        addUpgradeOptions(addPackageScopeOptions(lifecycleCommand
+            .command("upgrade")
+            .argument("[target]", "Optional managed package name/source to upgrade; omit to upgrade pm CLI and all managed packages")
+            .description("Upgrade the pm CLI/SDK and refresh managed installable pm packages."))).action(async (target, _options, command) => {
+            await executeUpgradeCommand(target, command, false);
+        });
+    }
 }
 async function runInitCommandAction(prefix, options, command) {
     const globalOptions = getGlobalOptions(command);
@@ -642,35 +697,21 @@ export function registerSetupCommands(program) {
     registerLifecycleCommand(program, "extension");
     registerLifecycleCommand(program, "package");
     addPackageScopeOptions(program
-        .command("install")
+        .command("install", { hidden: true })
         .argument("[targets...]", "Package source (local path, bundled alias, npm: source, wildcard, or GitHub source)")
         .option("--gh <github-source>", "Install from GitHub shorthand source (owner/repo[/path])")
         .option("--github <github-source>", "Alias for --gh")
         .option("--ref <ref>", "Git ref/branch/tag for GitHub install sources")
         .description("Install a pm package into the project package scope by default.")).action(async (targets, _options, command) => {
+        await emitDeprecatedAliasHint("install", command);
         await executeExtensionInstallCommand(targets, command.optsWithGlobals(), command, "package");
     });
-    addPackageScopeOptions(program
-        .command("upgrade")
+    addUpgradeOptions(addPackageScopeOptions(program
+        .command("upgrade", { hidden: true })
         .argument("[target]", "Optional managed package name/source to upgrade; omit to upgrade pm CLI and all managed packages")
-        .option("--dry-run", "Plan CLI/package upgrades without running npm or reinstalling packages")
-        .option("--cli-only", "Upgrade only the pm CLI/SDK npm package")
-        .option("--packages-only", "Upgrade only managed pm packages")
-        .option("--repair", "Force npm global reinstall when upgrading the pm CLI/SDK")
-        .option("--tag <value>", "npm dist-tag/version for CLI and registry package upgrades")
-        .option("--package-name <value>", "Override the CLI package name for self-upgrade testing")
-        .description("Upgrade the pm CLI/SDK and refresh managed installable pm packages.")).action(async (target, _options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const result = await runUpgrade(target, command.opts(), globalOptions);
-        printResult(result, globalOptions);
-        if (!result.ok) {
-            process.exitCode = EXIT_CODE.GENERIC_FAILURE;
-        }
-        if (globalOptions.profile) {
-            printError(`profile:command=upgrade took_ms=${Date.now() - startedAt}`);
-        }
+        .description("Upgrade the pm CLI/SDK and refresh managed installable pm packages."))).action(async (target, _options, command) => {
+        await executeUpgradeCommand(target, command, true);
     });
 }
 //# sourceMappingURL=register-setup.js.map
-//# debugId=2a7939ad-52a6-5d9c-b7cf-2bc59a6b3d32
+//# debugId=feb682f9-344c-569e-bbab-861fe20f08f1