@unbrained/pm-cli 2026.5.10 → 2026.5.12

package/dist/cli/commands/upgrade.d.ts

@@ -0,0 +1,63 @@
+import { type ExtensionScope, type ManagedExtensionSource } from "./extension.js";
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+export interface UpgradeCommandOptions {
+    dryRun?: boolean;
+    cliOnly?: boolean;
+    packagesOnly?: boolean;
+    project?: boolean;
+    local?: boolean;
+    global?: boolean;
+    repair?: boolean;
+    tag?: string;
+    packageName?: string;
+    commandRunner?: UpgradeCommandRunner;
+}
+export interface UpgradeCommandRunnerResult {
+    stdout: string;
+    stderr: string;
+}
+export type UpgradeCommandRunner = (command: string, args: string[], options?: {
+    cwd?: string;
+}) => Promise<UpgradeCommandRunnerResult>;
+export interface UpgradeCliResult {
+    requested: boolean;
+    status: "planned" | "updated" | "failed" | "skipped";
+    package: string;
+    target: string;
+    command: string[];
+    before_version?: string;
+    after_version?: string;
+    repair: boolean;
+    reason?: string;
+    error?: string;
+}
+export interface UpgradePackageResult {
+    name: string;
+    directory: string;
+    scope: ExtensionScope;
+    source: ManagedExtensionSource;
+    status: "planned" | "updated" | "failed" | "skipped";
+    command: string[];
+    previous_version: string;
+    installed_version?: string;
+    reason?: string;
+    error?: string;
+}
+export interface UpgradeResult {
+    ok: boolean;
+    action: "upgrade";
+    dry_run: boolean;
+    scope: ExtensionScope;
+    target?: string;
+    cli: UpgradeCliResult;
+    packages: UpgradePackageResult[];
+    summary: {
+        requested_cli: boolean;
+        requested_packages: boolean;
+        planned: number;
+        updated: number;
+        skipped: number;
+        failed: number;
+    };
+}
+export declare function runUpgrade(target: string | undefined, options: UpgradeCommandOptions, global: GlobalOptions): Promise<UpgradeResult>;

package/dist/cli/commands/upgrade.js

@@ -0,0 +1,260 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { readManagedExtensionState, runExtension, } from "./extension.js";
+import { resolveExtensionRoots } from "../../core/extensions/loader.js";
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { resolvePmRoot } from "../../core/store/paths.js";
+const execFileAsync = promisify(execFile);
+const DEFAULT_CLI_PACKAGE = "@unbrained/pm-cli";
+const DEFAULT_TAG = "latest";
+function resolveScope(options) {
+    const projectLike = options.project === true || options.local === true;
+    const global = options.global === true;
+    if (projectLike && global) {
+        throw new PmCliError('Options "--project/--local" and "--global" are mutually exclusive.', EXIT_CODE.USAGE);
+    }
+    return global ? "global" : "project";
+}
+function normalizeTarget(value) {
+    return value.trim().toLowerCase();
+}
+function packageRecordMatchesTarget(record, target) {
+    const normalizedTarget = normalizeTarget(target);
+    const values = [
+        record.name,
+        record.directory,
+        record.source.input,
+        record.source.location,
+        record.source.package,
+        record.source.repository,
+        record.source.owner && record.source.repo ? `${record.source.owner}/${record.source.repo}` : undefined,
+    ];
+    return values.some((value) => typeof value === "string" && normalizeTarget(value) === normalizedTarget);
+}
+function resolveRoots(scope, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    const roots = resolveExtensionRoots(pmRoot, process.cwd());
+    return {
+        selected_root: scope === "global" ? roots.global : roots.project,
+    };
+}
+async function defaultCommandRunner(command, args, options) {
+    try {
+        const result = await execFileAsync(command, args, {
+            cwd: options?.cwd,
+            encoding: "utf8",
+        });
+        return {
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+        };
+    }
+    catch (error) {
+        const stderr = typeof error === "object" && error !== null && "stderr" in error
+            ? String(error.stderr ?? "")
+            : "";
+        const message = stderr.trim().length > 0 ? stderr.trim() : error instanceof Error ? error.message : String(error);
+        throw new PmCliError(`Command failed: ${command} ${args.join(" ")}\n${message}`, EXIT_CODE.GENERIC_FAILURE);
+    }
+}
+async function readCurrentVersion() {
+    const packageJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..", "package.json");
+    try {
+        const parsed = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveTag(options) {
+    return typeof options.tag === "string" && options.tag.trim().length > 0 ? options.tag.trim() : DEFAULT_TAG;
+}
+function resolveCliPackage(options) {
+    return typeof options.packageName === "string" && options.packageName.trim().length > 0
+        ? options.packageName.trim()
+        : DEFAULT_CLI_PACKAGE;
+}
+async function upgradeCli(options, dryRun) {
+    const runner = options.commandRunner ?? defaultCommandRunner;
+    const packageName = resolveCliPackage(options);
+    const tag = resolveTag(options);
+    const target = `${packageName}@${tag}`;
+    const command = ["npm", "install", "-g", target];
+    if (options.repair === true) {
+        command.push("--force");
+    }
+    const beforeVersion = await readCurrentVersion();
+    const planned = {
+        requested: true,
+        status: "planned",
+        package: packageName,
+        target,
+        command,
+        before_version: beforeVersion,
+        repair: options.repair === true,
+    };
+    if (dryRun) {
+        return planned;
+    }
+    try {
+        await runner(command[0], command.slice(1));
+        const verified = await runner("pm", ["--version"]);
+        return {
+            ...planned,
+            status: "updated",
+            after_version: verified.stdout.trim() || undefined,
+        };
+    }
+    catch (error) {
+        return {
+            ...planned,
+            status: "failed",
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function isLocalNpmSpec(spec) {
+    return path.isAbsolute(spec) || spec.startsWith(".") || spec.startsWith("..") || spec.startsWith("file:");
+}
+function resolvePackageInstallSource(source, tag) {
+    if (source.kind === "npm") {
+        const rawSpec = source.input.startsWith("npm:") ? source.input.slice("npm:".length).trim() : source.input.trim();
+        if (!isLocalNpmSpec(rawSpec) && source.package && source.package.trim().length > 0) {
+            return `npm:${source.package.trim()}@${tag}`;
+        }
+        return source.input.startsWith("npm:") ? source.input : `npm:${source.input}`;
+    }
+    return source.input;
+}
+async function resolveRunnablePackageSource(source, tag) {
+    const installSource = resolvePackageInstallSource(source, tag);
+    if (source.kind !== "local") {
+        return installSource;
+    }
+    if (await pathExists(installSource)) {
+        return installSource;
+    }
+    if (await pathExists(source.location)) {
+        return source.location;
+    }
+    return installSource;
+}
+function packageCommandFor(source, installSource, scope, ref) {
+    const command = ["pm", "install", installSource, scope === "global" ? "--global" : "--project"];
+    if (source.kind === "github" && ref && ref.trim().length > 0) {
+        command.push("--ref", ref.trim());
+    }
+    return command;
+}
+async function readManagedRecords(scope, global) {
+    const roots = resolveRoots(scope, global);
+    const managedState = await readManagedExtensionState(roots.selected_root);
+    return managedState.state.entries.filter((entry) => entry.scope === scope);
+}
+async function refreshManagedRecord(scope, global, record) {
+    const records = await readManagedRecords(scope, global);
+    return records.find((candidate) => packageRecordMatchesTarget(candidate, record.name)) ??
+        records.find((candidate) => normalizeTarget(candidate.directory) === normalizeTarget(record.directory));
+}
+async function upgradePackageRecord(record, options, global, scope, dryRun) {
+    const tag = resolveTag(options);
+    const installSource = await resolveRunnablePackageSource(record.source, tag);
+    const command = packageCommandFor(record.source, installSource, scope, record.source.ref);
+    const planned = {
+        name: record.name,
+        directory: record.directory,
+        scope,
+        source: record.source,
+        status: "planned",
+        command,
+        previous_version: record.manifest_version,
+    };
+    if (dryRun) {
+        return planned;
+    }
+    try {
+        await runExtension(installSource, {
+            install: true,
+            project: scope === "project",
+            global: scope === "global",
+            ref: record.source.kind === "github" ? record.source.ref : undefined,
+        }, global);
+        const refreshed = await refreshManagedRecord(scope, global, record);
+        return {
+            ...planned,
+            status: "updated",
+            installed_version: refreshed?.manifest_version,
+        };
+    }
+    catch (error) {
+        return {
+            ...planned,
+            status: "failed",
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function summarize(cli, packages, includeCli, includePackages) {
+    const statuses = [includeCli ? cli.status : undefined, ...packages.map((entry) => entry.status)].filter((value) => typeof value === "string");
+    return {
+        requested_cli: includeCli,
+        requested_packages: includePackages,
+        planned: statuses.filter((status) => status === "planned").length,
+        updated: statuses.filter((status) => status === "updated").length,
+        skipped: statuses.filter((status) => status === "skipped").length,
+        failed: statuses.filter((status) => status === "failed").length,
+    };
+}
+export async function runUpgrade(target, options, global) {
+    if (options.cliOnly === true && options.packagesOnly === true) {
+        throw new PmCliError('Options "--cli-only" and "--packages-only" are mutually exclusive.', EXIT_CODE.USAGE);
+    }
+    const scope = resolveScope(options);
+    const dryRun = options.dryRun === true;
+    const normalizedTarget = typeof target === "string" && target.trim().length > 0 ? target.trim() : undefined;
+    if (options.cliOnly === true && normalizedTarget) {
+        throw new PmCliError('A package target cannot be used with "--cli-only".', EXIT_CODE.USAGE);
+    }
+    const includeCli = options.packagesOnly === true || normalizedTarget ? false : true;
+    const includePackages = options.cliOnly === true ? false : true;
+    const cli = includeCli
+        ? await upgradeCli(options, dryRun)
+        : {
+            requested: false,
+            status: "skipped",
+            package: resolveCliPackage(options),
+            target: `${resolveCliPackage(options)}@${resolveTag(options)}`,
+            command: ["npm", "install", "-g", `${resolveCliPackage(options)}@${resolveTag(options)}`],
+            repair: options.repair === true,
+            reason: "not_requested",
+        };
+    let packageRecords = includePackages ? await readManagedRecords(scope, global) : [];
+    if (normalizedTarget) {
+        packageRecords = packageRecords.filter((entry) => packageRecordMatchesTarget(entry, normalizedTarget));
+        if (packageRecords.length === 0) {
+            throw new PmCliError(`Managed package "${normalizedTarget}" was not found in ${scope} scope.`, EXIT_CODE.NOT_FOUND);
+        }
+    }
+    const packages = [];
+    for (const record of packageRecords) {
+        packages.push(await upgradePackageRecord(record, options, global, scope, dryRun));
+    }
+    const summary = summarize(cli, packages, includeCli, includePackages);
+    return {
+        ok: summary.failed === 0,
+        action: "upgrade",
+        dry_run: dryRun,
+        scope,
+        target: normalizedTarget,
+        cli,
+        packages,
+        summary,
+    };
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/cli/commands/upgrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.js","sourceRoot":"/","sources":["cli/commands/upgrade.ts"],"names":[],"mappings":"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","sourcesContent":["import { execFile } from \"node:child_process\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { promisify } from \"node:util\";\nimport {\n  readManagedExtensionState,\n  runExtension,\n  type ExtensionScope,\n  type ManagedExtensionRecord,\n  type ManagedExtensionSource,\n} from \"./extension.js\";\nimport { resolveExtensionRoots } from \"../../core/extensions/loader.js\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { resolvePmRoot } from \"../../core/store/paths.js\";\n\nconst execFileAsync = promisify(execFile);\nconst DEFAULT_CLI_PACKAGE = \"@unbrained/pm-cli\";\nconst DEFAULT_TAG = \"latest\";\n\nexport interface UpgradeCommandOptions {\n  dryRun?: boolean;\n  cliOnly?: boolean;\n  packagesOnly?: boolean;\n  project?: boolean;\n  local?: boolean;\n  global?: boolean;\n  repair?: boolean;\n  tag?: string;\n  packageName?: string;\n  commandRunner?: UpgradeCommandRunner;\n}\n\nexport interface UpgradeCommandRunnerResult {\n  stdout: string;\n  stderr: string;\n}\n\nexport type UpgradeCommandRunner = (\n  command: string,\n  args: string[],\n  options?: { cwd?: string },\n) => Promise<UpgradeCommandRunnerResult>;\n\nexport interface UpgradeCliResult {\n  requested: boolean;\n  status: \"planned\" | \"updated\" | \"failed\" | \"skipped\";\n  package: string;\n  target: string;\n  command: string[];\n  before_version?: string;\n  after_version?: string;\n  repair: boolean;\n  reason?: string;\n  error?: string;\n}\n\nexport interface UpgradePackageResult {\n  name: string;\n  directory: string;\n  scope: ExtensionScope;\n  source: ManagedExtensionSource;\n  status: \"planned\" | \"updated\" | \"failed\" | \"skipped\";\n  command: string[];\n  previous_version: string;\n  installed_version?: string;\n  reason?: string;\n  error?: string;\n}\n\nexport interface UpgradeResult {\n  ok: boolean;\n  action: \"upgrade\";\n  dry_run: boolean;\n  scope: ExtensionScope;\n  target?: string;\n  cli: UpgradeCliResult;\n  packages: UpgradePackageResult[];\n  summary: {\n    requested_cli: boolean;\n    requested_packages: boolean;\n    planned: number;\n    updated: number;\n    skipped: number;\n    failed: number;\n  };\n}\n\nfunction resolveScope(options: UpgradeCommandOptions): ExtensionScope {\n  const projectLike = options.project === true || options.local === true;\n  const global = options.global === true;\n  if (projectLike && global) {\n    throw new PmCliError('Options \"--project/--local\" and \"--global\" are mutually exclusive.', EXIT_CODE.USAGE);\n  }\n  return global ? \"global\" : \"project\";\n}\n\nfunction normalizeTarget(value: string): string {\n  return value.trim().toLowerCase();\n}\n\nfunction packageRecordMatchesTarget(record: ManagedExtensionRecord, target: string): boolean {\n  const normalizedTarget = normalizeTarget(target);\n  const values = [\n    record.name,\n    record.directory,\n    record.source.input,\n    record.source.location,\n    record.source.package,\n    record.source.repository,\n    record.source.owner && record.source.repo ? `${record.source.owner}/${record.source.repo}` : undefined,\n  ];\n  return values.some((value) => typeof value === \"string\" && normalizeTarget(value) === normalizedTarget);\n}\n\nfunction resolveRoots(scope: ExtensionScope, global: GlobalOptions): {\n  selected_root: string;\n} {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  const roots = resolveExtensionRoots(pmRoot, process.cwd());\n  return {\n    selected_root: scope === \"global\" ? roots.global : roots.project,\n  };\n}\n\nasync function defaultCommandRunner(\n  command: string,\n  args: string[],\n  options?: { cwd?: string },\n): Promise<UpgradeCommandRunnerResult> {\n  try {\n    const result = await execFileAsync(command, args, {\n      cwd: options?.cwd,\n      encoding: \"utf8\",\n    });\n    return {\n      stdout: result.stdout ?? \"\",\n      stderr: result.stderr ?? \"\",\n    };\n  } catch (error: unknown) {\n    const stderr = typeof error === \"object\" && error !== null && \"stderr\" in error\n      ? String((error as { stderr?: unknown }).stderr ?? \"\")\n      : \"\";\n    const message = stderr.trim().length > 0 ? stderr.trim() : error instanceof Error ? error.message : String(error);\n    throw new PmCliError(`Command failed: ${command} ${args.join(\" \")}\\n${message}`, EXIT_CODE.GENERIC_FAILURE);\n  }\n}\n\nasync function readCurrentVersion(): Promise<string | undefined> {\n  const packageJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), \"../../..\", \"package.json\");\n  try {\n    const parsed = JSON.parse(await fs.readFile(packageJsonPath, \"utf8\")) as { version?: unknown };\n    return typeof parsed.version === \"string\" ? parsed.version : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction resolveTag(options: UpgradeCommandOptions): string {\n  return typeof options.tag === \"string\" && options.tag.trim().length > 0 ? options.tag.trim() : DEFAULT_TAG;\n}\n\nfunction resolveCliPackage(options: UpgradeCommandOptions): string {\n  return typeof options.packageName === \"string\" && options.packageName.trim().length > 0\n    ? options.packageName.trim()\n    : DEFAULT_CLI_PACKAGE;\n}\n\nasync function upgradeCli(options: UpgradeCommandOptions, dryRun: boolean): Promise<UpgradeCliResult> {\n  const runner = options.commandRunner ?? defaultCommandRunner;\n  const packageName = resolveCliPackage(options);\n  const tag = resolveTag(options);\n  const target = `${packageName}@${tag}`;\n  const command = [\"npm\", \"install\", \"-g\", target];\n  if (options.repair === true) {\n    command.push(\"--force\");\n  }\n  const beforeVersion = await readCurrentVersion();\n  const planned: UpgradeCliResult = {\n    requested: true,\n    status: \"planned\",\n    package: packageName,\n    target,\n    command,\n    before_version: beforeVersion,\n    repair: options.repair === true,\n  };\n  if (dryRun) {\n    return planned;\n  }\n  try {\n    await runner(command[0]!, command.slice(1));\n    const verified = await runner(\"pm\", [\"--version\"]);\n    return {\n      ...planned,\n      status: \"updated\",\n      after_version: verified.stdout.trim() || undefined,\n    };\n  } catch (error: unknown) {\n    return {\n      ...planned,\n      status: \"failed\",\n      error: error instanceof Error ? error.message : String(error),\n    };\n  }\n}\n\nfunction isLocalNpmSpec(spec: string): boolean {\n  return path.isAbsolute(spec) || spec.startsWith(\".\") || spec.startsWith(\"..\") || spec.startsWith(\"file:\");\n}\n\nfunction resolvePackageInstallSource(source: ManagedExtensionSource, tag: string): string {\n  if (source.kind === \"npm\") {\n    const rawSpec = source.input.startsWith(\"npm:\") ? source.input.slice(\"npm:\".length).trim() : source.input.trim();\n    if (!isLocalNpmSpec(rawSpec) && source.package && source.package.trim().length > 0) {\n      return `npm:${source.package.trim()}@${tag}`;\n    }\n    return source.input.startsWith(\"npm:\") ? source.input : `npm:${source.input}`;\n  }\n  return source.input;\n}\n\nasync function resolveRunnablePackageSource(source: ManagedExtensionSource, tag: string): Promise<string> {\n  const installSource = resolvePackageInstallSource(source, tag);\n  if (source.kind !== \"local\") {\n    return installSource;\n  }\n  if (await pathExists(installSource)) {\n    return installSource;\n  }\n  if (await pathExists(source.location)) {\n    return source.location;\n  }\n  return installSource;\n}\n\nfunction packageCommandFor(source: ManagedExtensionSource, installSource: string, scope: ExtensionScope, ref?: string): string[] {\n  const command = [\"pm\", \"install\", installSource, scope === \"global\" ? \"--global\" : \"--project\"];\n  if (source.kind === \"github\" && ref && ref.trim().length > 0) {\n    command.push(\"--ref\", ref.trim());\n  }\n  return command;\n}\n\nasync function readManagedRecords(scope: ExtensionScope, global: GlobalOptions): Promise<ManagedExtensionRecord[]> {\n  const roots = resolveRoots(scope, global);\n  const managedState = await readManagedExtensionState(roots.selected_root);\n  return managedState.state.entries.filter((entry) => entry.scope === scope);\n}\n\nasync function refreshManagedRecord(\n  scope: ExtensionScope,\n  global: GlobalOptions,\n  record: ManagedExtensionRecord,\n): Promise<ManagedExtensionRecord | undefined> {\n  const records = await readManagedRecords(scope, global);\n  return records.find((candidate) => packageRecordMatchesTarget(candidate, record.name)) ??\n    records.find((candidate) => normalizeTarget(candidate.directory) === normalizeTarget(record.directory));\n}\n\nasync function upgradePackageRecord(\n  record: ManagedExtensionRecord,\n  options: UpgradeCommandOptions,\n  global: GlobalOptions,\n  scope: ExtensionScope,\n  dryRun: boolean,\n): Promise<UpgradePackageResult> {\n  const tag = resolveTag(options);\n  const installSource = await resolveRunnablePackageSource(record.source, tag);\n  const command = packageCommandFor(record.source, installSource, scope, record.source.ref);\n  const planned: UpgradePackageResult = {\n    name: record.name,\n    directory: record.directory,\n    scope,\n    source: record.source,\n    status: \"planned\",\n    command,\n    previous_version: record.manifest_version,\n  };\n  if (dryRun) {\n    return planned;\n  }\n  try {\n    await runExtension(\n      installSource,\n      {\n        install: true,\n        project: scope === \"project\",\n        global: scope === \"global\",\n        ref: record.source.kind === \"github\" ? record.source.ref : undefined,\n      },\n      global,\n    );\n    const refreshed = await refreshManagedRecord(scope, global, record);\n    return {\n      ...planned,\n      status: \"updated\",\n      installed_version: refreshed?.manifest_version,\n    };\n  } catch (error: unknown) {\n    return {\n      ...planned,\n      status: \"failed\",\n      error: error instanceof Error ? error.message : String(error),\n    };\n  }\n}\n\nfunction summarize(\n  cli: UpgradeCliResult,\n  packages: UpgradePackageResult[],\n  includeCli: boolean,\n  includePackages: boolean,\n): UpgradeResult[\"summary\"] {\n  const statuses = [includeCli ? cli.status : undefined, ...packages.map((entry) => entry.status)].filter(\n    (value): value is UpgradeCliResult[\"status\"] => typeof value === \"string\",\n  );\n  return {\n    requested_cli: includeCli,\n    requested_packages: includePackages,\n    planned: statuses.filter((status) => status === \"planned\").length,\n    updated: statuses.filter((status) => status === \"updated\").length,\n    skipped: statuses.filter((status) => status === \"skipped\").length,\n    failed: statuses.filter((status) => status === \"failed\").length,\n  };\n}\n\nexport async function runUpgrade(\n  target: string | undefined,\n  options: UpgradeCommandOptions,\n  global: GlobalOptions,\n): Promise<UpgradeResult> {\n  if (options.cliOnly === true && options.packagesOnly === true) {\n    throw new PmCliError('Options \"--cli-only\" and \"--packages-only\" are mutually exclusive.', EXIT_CODE.USAGE);\n  }\n\n  const scope = resolveScope(options);\n  const dryRun = options.dryRun === true;\n  const normalizedTarget = typeof target === \"string\" && target.trim().length > 0 ? target.trim() : undefined;\n  if (options.cliOnly === true && normalizedTarget) {\n    throw new PmCliError('A package target cannot be used with \"--cli-only\".', EXIT_CODE.USAGE);\n  }\n  const includeCli = options.packagesOnly === true || normalizedTarget ? false : true;\n  const includePackages = options.cliOnly === true ? false : true;\n  const cli = includeCli\n    ? await upgradeCli(options, dryRun)\n    : {\n        requested: false,\n        status: \"skipped\",\n        package: resolveCliPackage(options),\n        target: `${resolveCliPackage(options)}@${resolveTag(options)}`,\n        command: [\"npm\", \"install\", \"-g\", `${resolveCliPackage(options)}@${resolveTag(options)}`],\n        repair: options.repair === true,\n        reason: \"not_requested\",\n      } as UpgradeCliResult;\n\n  let packageRecords = includePackages ? await readManagedRecords(scope, global) : [];\n  if (normalizedTarget) {\n    packageRecords = packageRecords.filter((entry) => packageRecordMatchesTarget(entry, normalizedTarget));\n    if (packageRecords.length === 0) {\n      throw new PmCliError(`Managed package \"${normalizedTarget}\" was not found in ${scope} scope.`, EXIT_CODE.NOT_FOUND);\n    }\n  }\n\n  const packages: UpgradePackageResult[] = [];\n  for (const record of packageRecords) {\n    packages.push(await upgradePackageRecord(record, options, global, scope, dryRun));\n  }\n\n  const summary = summarize(cli, packages, includeCli, includePackages);\n  return {\n    ok: summary.failed === 0,\n    action: \"upgrade\",\n    dry_run: dryRun,\n    scope,\n    target: normalizedTarget,\n    cli,\n    packages,\n    summary,\n  };\n}\n"]}

package/dist/cli/error-guidance.d.ts

@@ -1,4 +1,4 @@
-import type { PmCliErrorContext } from "../core/shared/errors.js";
+import type { PmCliErrorContext, PmCliErrorRecoveryPayload } from "../core/shared/errors.js";
 interface GuidanceMessage {
     code: string;
     type: string;
@@ -8,6 +8,7 @@ interface GuidanceMessage {
     why?: string;
     examples?: string[];
     nextSteps?: string[];
+    recovery?: PmCliErrorRecoveryPayload;
 }
 export interface JsonErrorEnvelope {
     type: string;
@@ -19,6 +20,7 @@ export interface JsonErrorEnvelope {
     why?: string;
     examples?: string[];
     next_steps?: string[];
+    recovery?: PmCliErrorRecoveryPayload;
 }
 export interface ErrorClassification {
     type: string;
@@ -29,10 +31,16 @@ export interface ErrorClassification {
     why?: string;
     examples?: string[];
     next_steps?: string[];
+    recovery?: PmCliErrorRecoveryPayload;
 }
 export interface CommanderGuidanceContext {
     unknownCommandExamples?: string[];
     unknownCommandNextSteps?: string[];
+    attemptedCommand?: string;
+    normalizedInvocationArgs?: string[];
+    providedOptionFlags?: string[];
+    unknownOptionSuggestions?: string[];
+    suggestedRetryCommand?: string;
 }
 export declare function renderGuidanceMessage(message: GuidanceMessage): string;
 export declare function formatPmCliErrorForDisplay(rawMessage: string, context?: PmCliErrorContext): string;

package/dist/cli/error-guidance.js

@@ -1,3 +1,4 @@
+import { renderPmCommand } from "./argv-utils.js";
 function errorType(code) {
     return `urn:pm-cli:error:${code}`;
 }
@@ -13,6 +14,60 @@ function renderList(title, entries) {
     }
     return [title, ...entries.map((entry) => `  - ${entry}`)];
 }
+function normalizeRecoveryPayload(payload) {
+    if (!payload || typeof payload !== "object") {
+        return undefined;
+    }
+    const normalized = {};
+    if (typeof payload.attempted_command === "string" && payload.attempted_command.trim().length > 0) {
+        normalized.attempted_command = payload.attempted_command.trim();
+    }
+    if (Array.isArray(payload.normalized_args)) {
+        const args = payload.normalized_args.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+        if (args.length > 0) {
+            normalized.normalized_args = args;
+        }
+    }
+    if (Array.isArray(payload.provided_fields)) {
+        const fields = payload.provided_fields.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+        if (fields.length > 0) {
+            normalized.provided_fields = fields;
+        }
+    }
+    if (Array.isArray(payload.missing)) {
+        const missing = payload.missing.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+        if (missing.length > 0) {
+            normalized.missing = missing;
+        }
+    }
+    if (typeof payload.suggested_retry === "string" && payload.suggested_retry.trim().length > 0) {
+        normalized.suggested_retry = payload.suggested_retry.trim();
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+function renderRecoveryBundle(recovery) {
+    const normalized = normalizeRecoveryPayload(recovery);
+    if (!normalized) {
+        return [];
+    }
+    const lines = ["Recovery bundle:"];
+    if (normalized.attempted_command) {
+        lines.push(`  attempted_command: ${normalized.attempted_command}`);
+    }
+    if (normalized.normalized_args && normalized.normalized_args.length > 0) {
+        lines.push(`  normalized_args: ${normalized.normalized_args.join(" ")}`);
+    }
+    if (normalized.provided_fields && normalized.provided_fields.length > 0) {
+        lines.push(`  provided_fields: ${normalized.provided_fields.join(", ")}`);
+    }
+    if (normalized.missing && normalized.missing.length > 0) {
+        lines.push(`  missing: ${normalized.missing.join(", ")}`);
+    }
+    if (normalized.suggested_retry) {
+        lines.push(`  suggested_retry: ${normalized.suggested_retry}`);
+    }
+    return lines;
+}
 export function renderGuidanceMessage(message) {
     const lines = [
         `Error: ${message.title}`,
@@ -35,6 +90,11 @@ export function renderGuidanceMessage(message) {
         lines.push("");
         lines.push(...renderList("Next steps:", message.nextSteps));
     }
+    const recoveryLines = renderRecoveryBundle(message.recovery);
+    if (recoveryLines.length > 0) {
+        lines.push("");
+        lines.push(...recoveryLines);
+    }
     return lines.join("\n");
 }
 function guidanceToJsonEnvelope(message, exitCode) {
@@ -55,6 +115,9 @@ function guidanceToJsonEnvelope(message, exitCode) {
     if (message.nextSteps && message.nextSteps.length > 0) {
         payload.next_steps = message.nextSteps;
     }
+    if (message.recovery) {
+        payload.recovery = message.recovery;
+    }
     return payload;
 }
 function guidanceToClassification(message) {
@@ -74,6 +137,9 @@ function guidanceToClassification(message) {
     if (message.nextSteps && message.nextSteps.length > 0) {
         payload.next_steps = message.nextSteps;
     }
+    if (message.recovery) {
+        payload.recovery = message.recovery;
+    }
     return payload;
 }
 function normalizeMessage(message) {
@@ -106,6 +172,7 @@ function applyPmCliErrorContext(guidance, rawMessage, context) {
     const examples = normalizeContextList(context.examples) ?? guidance.examples;
     const nextSteps = normalizeContextList(context.nextSteps) ?? guidance.nextSteps;
     const fallbackTitle = guidance.code === "command_failed" && context.code ? buildFallbackTitleFromMessage(normalizedRawMessage) : undefined;
+    const recovery = normalizeRecoveryPayload(context.recovery) ?? guidance.recovery;
     return {
         ...guidance,
         code,
@@ -116,6 +183,7 @@ function applyPmCliErrorContext(guidance, rawMessage, context) {
         why: typeof context.why === "string" && context.why.trim().length > 0 ? context.why.trim() : guidance.why,
         examples,
         nextSteps,
+        recovery,
     };
 }
 function buildPmCliErrorGuidance(rawMessage, context) {
@@ -267,12 +335,65 @@ function commandExampleForRequiredOption(commandName, optionFlag, allowedTypes)
     }
     return [`pm ${commandName ?? "<command>"} --help`];
 }
+function normalizeRequiredOptionLabel(rawValue) {
+    const normalized = rawValue.trim();
+    const firstLongFlag = normalized.match(/--[A-Za-z0-9][A-Za-z0-9_-]*/)?.[0];
+    return firstLongFlag ?? normalized;
+}
+function renderPmCommandFromArgs(argv) {
+    if (!Array.isArray(argv) || argv.length === 0) {
+        return undefined;
+    }
+    return renderPmCommand(argv);
+}
+function normalizeOptionFlags(values) {
+    if (!Array.isArray(values)) {
+        return undefined;
+    }
+    const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0);
+    return normalized.length > 0 ? normalized : undefined;
+}
+function buildCommanderRecoveryPayload(context, overrides = {}) {
+    const providedFields = normalizeOptionFlags(context?.providedOptionFlags);
+    const normalizedArgs = Array.isArray(context?.normalizedInvocationArgs) && context?.normalizedInvocationArgs.length > 0
+        ? context.normalizedInvocationArgs
+        : undefined;
+    const attemptedCommand = typeof context?.attemptedCommand === "string" ? context.attemptedCommand : renderPmCommandFromArgs(normalizedArgs);
+    const retryCommand = typeof context?.suggestedRetryCommand === "string" ? context.suggestedRetryCommand : undefined;
+    return normalizeRecoveryPayload({
+        attempted_command: attemptedCommand,
+        normalized_args: normalizedArgs,
+        provided_fields: providedFields,
+        suggested_retry: retryCommand,
+        ...overrides,
+    });
+}
+function appendIfMissing(entries, value) {
+    if (!value || entries.includes(value)) {
+        return entries;
+    }
+    return [...entries, value];
+}
 function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context) {
     const message = normalizeMessage(rawMessage);
     const requiredOption = message.match(/required option '([^']+)' not specified/);
     if (requiredOption) {
-        const optionFlag = requiredOption[1];
+        const optionFlag = normalizeRequiredOptionLabel(requiredOption[1]);
         const isType = optionFlag.startsWith("--type");
+        const retryCommand = context?.suggestedRetryCommand;
+        const providedFlags = normalizeOptionFlags(context?.providedOptionFlags);
+        const missing = [optionFlag];
+        const examples = commandExampleForRequiredOption(commandName, optionFlag, allowedTypes);
+        const examplesWithRetry = retryCommand ? appendIfMissing(examples, retryCommand) : examples;
+        const nextStepsBase = isType
+            ? [`Allowed type values: ${allowedTypes}`, `Run "pm ${commandName ?? "create"} --help --type <value>" for type-aware policy details.`]
+            : [`Run "pm ${commandName ?? "<command>"} --help" for required option guidance.`];
+        const nextStepsWithRetry = retryCommand
+            ? appendIfMissing(nextStepsBase, `Replay with preserved arguments: ${retryCommand}`)
+            : nextStepsBase;
+        const nextSteps = providedFlags && providedFlags.length > 0
+            ? appendIfMissing(nextStepsWithRetry, `Already provided options: ${providedFlags.join(", ")}`)
+            : nextStepsWithRetry;
         return makeGuidanceMessage({
             code: "missing_required_option",
             title: `Missing required option ${optionFlag}`,
@@ -281,10 +402,9 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
             why: isType
                 ? "--type selects item contract and policy routing, including required/disabled option rules."
                 : "Required flags define mandatory command intent and prevent ambiguous execution.",
-            examples: commandExampleForRequiredOption(commandName, optionFlag, allowedTypes),
-            nextSteps: isType
-                ? [`Allowed type values: ${allowedTypes}`, `Run "pm ${commandName ?? "create"} --help --type <value>" for type-aware policy details.`]
-                : [`Run "pm ${commandName ?? "<command>"} --help" for required option guidance.`],
+            examples: examplesWithRetry,
+            nextSteps,
+            recovery: buildCommanderRecoveryPayload(context, { missing }),
         });
     }
     const missingArgument = message.match(/missing required argument '([^']+)'/);
@@ -297,11 +417,14 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
             required: `Provide ${argumentName} in the expected command position.`,
             why: "Positional arguments identify the target entity or action context for the command.",
             examples: [`pm ${commandName ?? "<command>"} --help`],
+            recovery: buildCommanderRecoveryPayload(context, { missing: [argumentName] }),
         });
     }
     const unknownOption = message.match(/unknown option '([^']+)'/);
     if (unknownOption) {
         const optionName = unknownOption[1];
+        const suggestions = normalizeOptionFlags(context?.unknownOptionSuggestions);
+        const retryCommand = context?.suggestedRetryCommand;
         if (commandName === "update" && (optionName === "--file" || optionName === "--doc")) {
             return makeGuidanceMessage({
                 code: "unsupported_update_option",
@@ -314,15 +437,31 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
                     'pm docs pm-a1b2 --add "path=README.md,scope=project,note=user-facing contract"',
                 ],
                 nextSteps: ['Run "pm files --help" and "pm docs --help" for add/remove payload formats.'],
+                recovery: buildCommanderRecoveryPayload(context, {
+                    missing: suggestions,
+                }),
             });
         }
+        const nextSteps = [
+            "Run command help to confirm the exact option contracts for this command path.",
+            ...(suggestions && suggestions.length > 0 ? [`Nearest supported options: ${suggestions.join(", ")}`] : []),
+            ...(retryCommand ? [`Replay with suggested correction: ${retryCommand}`] : []),
+        ];
+        const examples = [
+            ...(retryCommand ? [retryCommand] : []),
+            `pm ${commandName ?? "<command>"} --help`,
+        ];
         return makeGuidanceMessage({
             code: "unknown_option",
             title: `Unknown option ${optionName}`,
             happened: `Commander does not recognize option ${optionName} for this command path.`,
             required: "Use supported options only, or move option to the correct subcommand.",
             why: "Option contracts are command-specific and intentionally validated.",
-            examples: [`pm ${commandName ?? "<command>"} --help`],
+            examples,
+            nextSteps,
+            recovery: buildCommanderRecoveryPayload(context, {
+                missing: suggestions,
+            }),
         });
     }
     const unknownCommand = message.match(/unknown command '([^']+)'/);
@@ -338,6 +477,7 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
             why: "Command registry includes core commands plus active extension command handlers.",
             examples: runtimeExamples ?? ["pm --help"],
             nextSteps: runtimeNextSteps ?? ["Verify spelling and active extensions, then rerun."],
+            recovery: buildCommanderRecoveryPayload(context),
         });
     }
     return makeGuidanceMessage({
@@ -347,6 +487,7 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
         required: "Use the command with valid arguments and options.",
         why: "Commander validates CLI contracts before execution.",
         examples: ["pm --help", `pm ${commandName ?? "<command>"} --help`],
+        recovery: buildCommanderRecoveryPayload(context),
     });
 }
 export function formatPmCliErrorForDisplay(rawMessage, context) {