@unbrained/pm-cli 2026.8.25 → 2026.8.27

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