@unbrained/pm-cli 2026.5.11 → 2026.5.14

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/guide-topics.js

@@ -128,27 +128,29 @@ const GUIDE_TOPICS = [
     },
     {
         id: "extensions",
-        aliases: ["plugins", "extension-authoring"],
-        title: "Extensions",
-        summary: "Install, author, and diagnose extensions with deterministic lifecycle controls.",
-        intent: "Use this for extension management, capability registration, and runtime diagnostics.",
+        aliases: ["plugins", "extension-authoring", "packages", "package-authoring"],
+        title: "Packages and Extensions",
+        summary: "Install, author, and diagnose packages/extensions with deterministic lifecycle controls.",
+        intent: "Use this for package management, extension capability registration, and runtime diagnostics.",
         commands: [
-            "pm extension explore --project",
-            "pm extension install <target> --project",
-            "pm extension manage --detail summary",
-            "pm extension doctor --detail deep",
-            "pm extension activate <target> --project",
-            "pm extension deactivate <target> --project",
+            "pm install <target> --project",
+            "pm upgrade --dry-run",
+            "pm package explore --project",
+            "pm package manage --detail summary",
+            "pm package doctor --detail deep",
+            "pm package activate <target> --project",
+            "pm package deactivate <target> --project",
         ],
         workflows: [
             {
                 name: "Lifecycle Triage",
                 goal: "Diagnose extension state before forceful lifecycle actions.",
-                prompt: "You are debugging extension behavior. Inspect managed state first, then run doctor diagnostics, then apply install/adopt/activate actions.",
+                prompt: "You are debugging package behavior. Inspect managed state first, then run doctor diagnostics, then apply install/adopt/activate actions.",
                 commands: [
-                    "pm extension explore --project",
-                    "pm extension manage --detail summary",
-                    "pm extension doctor --detail deep",
+                    "pm package explore --project",
+                    "pm package manage --detail summary",
+                    "pm package doctor --detail deep",
+                    "pm upgrade --packages-only --dry-run",
                 ],
             },
         ],
@@ -196,8 +198,8 @@ const GUIDE_TOPICS = [
         id: "harnesses",
         aliases: ["compatibility", "agent-compatibility"],
         title: "Agent Harness Compatibility",
-        summary: "Cross-harness compatibility guidance for skill discovery, prompts, and docs routing.",
-        intent: "Use this when adapting pm skills/docs usage for Pi, OpenClaw, Claude Code, Codex CLI, OpenCode, Amp, Droid, Hermes, or Gemini CLI.",
+        summary: "Cross-harness compatibility guidance for docs routing.",
+        intent: "Use this when adapting pm docs and SDK contracts for an external automation harness.",
         commands: ["pm guide skills", "pm guide commands", "pm contracts --runtime-only --availability-only"],
         workflows: [
             {

package/dist/cli/guide-topics.js.map

@@ -1 +1 @@
-{"version":3,"file":"guide-topics.js","sourceRoot":"/","sources":["cli/guide-topics.ts"],"names":[],"mappings":"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","sourcesContent":["export interface GuideDocReference {\n  path: string;\n  purpose: string;\n  optional?: boolean;\n}\n\nexport interface GuideWorkflowTemplate {\n  name: string;\n  goal: string;\n  prompt: string;\n  commands: string[];\n}\n\nexport interface GuideTopicDefinition {\n  id: string;\n  aliases: string[];\n  title: string;\n  summary: string;\n  intent: string;\n  commands: string[];\n  workflows: GuideWorkflowTemplate[];\n  docs: GuideDocReference[];\n  related: string[];\n}\n\nfunction normalizeTopicToken(value: string): string {\n  return value.trim().toLowerCase().replaceAll(\"_\", \"-\");\n}\n\nconst GUIDE_TOPICS: GuideTopicDefinition[] = [\n  {\n    id: \"quickstart\",\n    aliases: [\"start\", \"getting-started\", \"bootstrap\"],\n    title: \"Quickstart\",\n    summary: \"Initialize a tracker and run the shortest safe plan -> execute -> close loop.\",\n    intent: \"Use this when a human or agent needs to start productive work quickly with minimal context load.\",\n    commands: [\n      \"pm init\",\n      \"pm context --limit 10\",\n      \"pm list-open --limit 20\",\n      \"pm create --create-mode progressive --title \\\"...\\\" --description \\\"...\\\" --type Task\",\n      \"pm claim <ID>\",\n      \"pm update <ID> --status in_progress\",\n      \"pm close <ID> \\\"<reason with evidence>\\\" --validate-close warn\",\n    ],\n    workflows: [\n      {\n        name: \"Start Session Safely\",\n        goal: \"Bootstrap without mutating unrelated state.\",\n        prompt:\n          \"You are bootstrapping pm work. Use a token-efficient context snapshot first, then select one open item, claim it, and only then mutate.\",\n        commands: [\"pm context --limit 10\", \"pm list-open --limit 20\", \"pm claim <ID>\"],\n      },\n    ],\n    docs: [\n      { path: \"README.md\", purpose: \"High-level project and install entrypoint.\" },\n      { path: \"docs/QUICKSTART.md\", purpose: \"Short setup and first-command walkthrough.\" },\n      { path: \"docs/COMMANDS.md\", purpose: \"Task-oriented command recipes.\" },\n    ],\n    related: [\"commands\", \"workflows\", \"release\"],\n  },\n  {\n    id: \"commands\",\n    aliases: [\"cli\", \"operations\", \"reference\"],\n    title: \"CLI Command Routing\",\n    summary: \"Find the right command family quickly and use command-scoped help/contracts output.\",\n    intent: \"Use this when selecting command paths, flags, and output formats for implementation or automation.\",\n    commands: [\n      \"pm --help\",\n      \"pm <command> --help\",\n      \"pm <command> --help --explain\",\n      \"pm contracts --command <command> --flags-only\",\n      \"pm contracts --command <command> --availability-only --runtime-only\",\n      \"pm completion <bash|zsh|fish>\",\n    ],\n    workflows: [\n      {\n        name: \"Flag Discovery\",\n        goal: \"Resolve command flags deterministically before mutations.\",\n        prompt:\n          \"You are preparing to run a command. Use help and contracts surfaces to verify required/optional flags before execution.\",\n        commands: [\"pm <command> --help --explain\", \"pm contracts --command <command> --flags-only\"],\n      },\n    ],\n    docs: [\n      { path: \"docs/COMMANDS.md\", purpose: \"Command grouping and examples.\" },\n      { path: \"docs/CONFIGURATION.md\", purpose: \"Project/global settings and policy controls.\" },\n      { path: \"docs/TESTING.md\", purpose: \"Linked-test orchestration and safety guidance.\" },\n    ],\n    related: [\"quickstart\", \"workflows\", \"sdk\", \"extensions\"],\n  },\n  {\n    id: \"workflows\",\n    aliases: [\"developer\", \"maintainer\", \"agent\"],\n    title: \"Developer and Agent Workflows\",\n    summary: \"Apply canonical claim -> execute -> verify -> close workflows with append-only evidence.\",\n    intent: \"Use this for day-to-day coding-agent execution loops and handoff-safe updates.\",\n    commands: [\n      \"pm claim <ID>\",\n      \"pm update <ID> --status in_progress\",\n      \"pm files <ID> --add ...\",\n      \"pm test <ID> --add ...\",\n      \"pm comments <ID> \\\"...\\\"\",\n      \"pm validate --check-resolution --check-history-drift\",\n      \"pm release <ID>\",\n    ],\n    workflows: [\n      {\n        name: \"Execution Loop\",\n        goal: \"Keep code, tests, and tracker evidence synchronized.\",\n        prompt:\n          \"You are implementing a scoped change. Claim first, link files/tests/docs as you go, append evidence comments, and close only after validation.\",\n        commands: [\n          \"pm claim <ID>\",\n          \"pm update <ID> --status in_progress\",\n          \"pm files <ID> --add path=<file>,scope=project\",\n          \"pm test <ID> --run --progress\",\n          \"pm close <ID> \\\"<evidence>\\\" --validate-close warn\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"AGENTS.md\", purpose: \"Repository operating rules and required workflow.\" },\n      { path: \"docs/AGENT_GUIDE.md\", purpose: \"Agent-oriented usage and context strategy.\" },\n      { path: \"docs/TESTING.md\", purpose: \"Sandbox-safe test execution rules.\" },\n    ],\n    related: [\"quickstart\", \"commands\", \"skills\"],\n  },\n  {\n    id: \"sdk\",\n    aliases: [\"api\", \"typescript-sdk\"],\n    title: \"SDK and Integrations\",\n    summary: \"Use the published SDK surface for extension authoring and contract-safe integrations.\",\n    intent: \"Use this when building or reviewing programmatic integrations against @unbrained/pm-cli/sdk.\",\n    commands: [\n      \"pm contracts --schema-only\",\n      \"pm contracts --command extension --flags-only\",\n      \"pm contracts --runtime-only --availability-only\",\n    ],\n    workflows: [\n      {\n        name: \"Integration Contract Check\",\n        goal: \"Confirm action schemas and runtime availability before coding.\",\n        prompt:\n          \"You are wiring an integration. Capture schema + runtime availability first, then map your adapter payload fields to contract keys.\",\n        commands: [\n          \"pm contracts --schema-only\",\n          \"pm contracts --availability-only --runtime-only\",\n          \"pm contracts --command <command> --flags-only\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"docs/SDK.md\", purpose: \"Public SDK exports and extension authoring references.\" },\n      { path: \"docs/ARCHITECTURE.md\", purpose: \"Core runtime composition and extension load flow.\" },\n    ],\n    related: [\"extensions\", \"commands\"],\n  },\n  {\n    id: \"extensions\",\n    aliases: [\"plugins\", \"extension-authoring\"],\n    title: \"Extensions\",\n    summary: \"Install, author, and diagnose extensions with deterministic lifecycle controls.\",\n    intent: \"Use this for extension management, capability registration, and runtime diagnostics.\",\n    commands: [\n      \"pm extension explore --project\",\n      \"pm extension install <target> --project\",\n      \"pm extension manage --detail summary\",\n      \"pm extension doctor --detail deep\",\n      \"pm extension activate <target> --project\",\n      \"pm extension deactivate <target> --project\",\n    ],\n    workflows: [\n      {\n        name: \"Lifecycle Triage\",\n        goal: \"Diagnose extension state before forceful lifecycle actions.\",\n        prompt:\n          \"You are debugging extension behavior. Inspect managed state first, then run doctor diagnostics, then apply install/adopt/activate actions.\",\n        commands: [\n          \"pm extension explore --project\",\n          \"pm extension manage --detail summary\",\n          \"pm extension doctor --detail deep\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"docs/EXTENSIONS.md\", purpose: \"Capability model and lifecycle command usage.\" },\n      {\n        path: \"docs/examples/starter-extension/README.md\",\n        purpose: \"Starter extension scaffold and local development path.\",\n      },\n      { path: \"docs/SDK.md\", purpose: \"SDK contracts used by extension implementations.\" },\n    ],\n    related: [\"sdk\", \"commands\", \"skills\"],\n  },\n  {\n    id: \"skills\",\n    aliases: [\"agent-skills\", \"agentskills\"],\n    title: \"Agent Skills\",\n    summary: \"Skill bundles for developer, user, extensions, and sdk workflows aligned to the current CLI.\",\n    intent: \"Use this when an agent needs reproducible prompts/workflows with strict compatibility metadata.\",\n    commands: [\n      \"pm guide skills --depth deep\",\n      \"pm contracts --command guide --flags-only\",\n      \"pm validate --check-command-references\",\n    ],\n    workflows: [\n      {\n        name: \"Skill Selection\",\n        goal: \"Pick the narrowest compatible skill first to minimize context usage.\",\n        prompt:\n          \"Select a pm skill based on the task intent, then execute only the workflow section needed for the current change.\",\n        commands: [\"pm guide skills\", \"pm guide skills --depth deep\"],\n      },\n    ],\n    docs: [\n      { path: \"docs/AGENT_GUIDE.md\", purpose: \"Agent-first usage and context model.\" },\n      { path: \"docs/README.md\", purpose: \"Documentation routing with progressive disclosure.\" },\n      { path: \".agents/skills/README.md\", purpose: \"Agent skills index and routing overview.\" },\n      { path: \".agents/skills/pm-developer/SKILL.md\", purpose: \"Developer-oriented pm skill workflow.\" },\n      { path: \".agents/skills/pm-user/SKILL.md\", purpose: \"User/operator pm skill workflow.\" },\n      { path: \".agents/skills/pm-extensions/SKILL.md\", purpose: \"Extension-focused pm skill workflow.\" },\n      { path: \".agents/skills/pm-sdk/SKILL.md\", purpose: \"SDK integration pm skill workflow.\" },\n    ],\n    related: [\"workflows\", \"harnesses\", \"commands\"],\n  },\n  {\n    id: \"harnesses\",\n    aliases: [\"compatibility\", \"agent-compatibility\"],\n    title: \"Agent Harness Compatibility\",\n    summary: \"Cross-harness compatibility guidance for skill discovery, prompts, and docs routing.\",\n    intent: \"Use this when adapting pm skills/docs usage for Pi, OpenClaw, Claude Code, Codex CLI, OpenCode, Amp, Droid, Hermes, or Gemini CLI.\",\n    commands: [\"pm guide skills\", \"pm guide commands\", \"pm contracts --runtime-only --availability-only\"],\n    workflows: [\n      {\n        name: \"Harness Mapping\",\n        goal: \"Route each harness to the same canonical skill/docs sources.\",\n        prompt:\n          \"Map harness-specific entrypoints to the same pm guide topics and .agents/skills workflows without adding runtime harness-specific code.\",\n        commands: [\"pm guide harnesses --depth standard\", \"pm guide skills --depth deep\"],\n      },\n    ],\n    docs: [\n      { path: \"docs/AGENT_GUIDE.md\", purpose: \"Agent context and output-mode conventions.\" },\n      { path: \"docs/README.md\", purpose: \"Single-source documentation routing entrypoint.\" },\n      { path: \".agents/skills/HARNESS_COMPATIBILITY.md\", purpose: \"Harness compatibility matrix and usage notes.\" },\n    ],\n    related: [\"skills\", \"workflows\"],\n  },\n  {\n    id: \"release\",\n    aliases: [\"gates\", \"ship\", \"release-readiness\"],\n    title: \"Release and Staleness Gates\",\n    summary: \"Run release gates and docs/skills freshness checks before publishing.\",\n    intent: \"Use this when validating release readiness and preventing docs/skills drift.\",\n    commands: [\n      \"pnpm build\",\n      \"pnpm test:coverage\",\n      \"pnpm quality:static\",\n      \"node scripts/release/run-gates.mjs --telemetry-mode best-effort\",\n      \"pnpm security:scan\",\n    ],\n    workflows: [\n      {\n        name: \"Pre-Release Gate Sweep\",\n        goal: \"Ensure code, docs, and skills are all green before publish.\",\n        prompt:\n          \"Run release gates in deterministic order and treat docs/skills freshness failures as release blockers.\",\n        commands: [\n          \"pnpm build\",\n          \"pnpm test:coverage\",\n          \"node scripts/release/run-gates.mjs --telemetry-mode best-effort\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"docs/RELEASING.md\", purpose: \"Release flow and safety checks.\" },\n      { path: \"CHANGELOG.md\", purpose: \"Versioned release history and unreleased notes.\" },\n      { path: \"scripts/release/run-gates.mjs\", purpose: \"Source of truth for release gate ordering.\" },\n    ],\n    related: [\"commands\", \"skills\", \"workflows\"],\n  },\n];\n\nconst TOPIC_BY_TOKEN = new Map<string, GuideTopicDefinition>();\nfor (const topic of GUIDE_TOPICS) {\n  TOPIC_BY_TOKEN.set(topic.id, topic);\n  for (const alias of topic.aliases) {\n    TOPIC_BY_TOKEN.set(alias, topic);\n  }\n}\n\nexport function listGuideTopics(): GuideTopicDefinition[] {\n  return GUIDE_TOPICS.map((topic) => ({\n    ...topic,\n    aliases: [...topic.aliases],\n    commands: [...topic.commands],\n    workflows: topic.workflows.map((workflow) => ({\n      ...workflow,\n      commands: [...workflow.commands],\n    })),\n    docs: topic.docs.map((doc) => ({ ...doc })),\n    related: [...topic.related],\n  }));\n}\n\nexport function listGuideTopicIds(): string[] {\n  return GUIDE_TOPICS.map((topic) => topic.id);\n}\n\nexport function resolveGuideTopic(rawTopic: string | undefined): GuideTopicDefinition | null {\n  if (!rawTopic) {\n    return null;\n  }\n  const normalized = normalizeTopicToken(rawTopic);\n  if (!normalized) {\n    return null;\n  }\n  return TOPIC_BY_TOKEN.get(normalized) ?? null;\n}\n\n"]}
+{"version":3,"file":"guide-topics.js","sourceRoot":"/","sources":["cli/guide-topics.ts"],"names":[],"mappings":"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","sourcesContent":["export interface GuideDocReference {\n  path: string;\n  purpose: string;\n  optional?: boolean;\n}\n\nexport interface GuideWorkflowTemplate {\n  name: string;\n  goal: string;\n  prompt: string;\n  commands: string[];\n}\n\nexport interface GuideTopicDefinition {\n  id: string;\n  aliases: string[];\n  title: string;\n  summary: string;\n  intent: string;\n  commands: string[];\n  workflows: GuideWorkflowTemplate[];\n  docs: GuideDocReference[];\n  related: string[];\n}\n\nfunction normalizeTopicToken(value: string): string {\n  return value.trim().toLowerCase().replaceAll(\"_\", \"-\");\n}\n\nconst GUIDE_TOPICS: GuideTopicDefinition[] = [\n  {\n    id: \"quickstart\",\n    aliases: [\"start\", \"getting-started\", \"bootstrap\"],\n    title: \"Quickstart\",\n    summary: \"Initialize a tracker and run the shortest safe plan -> execute -> close loop.\",\n    intent: \"Use this when a human or agent needs to start productive work quickly with minimal context load.\",\n    commands: [\n      \"pm init\",\n      \"pm context --limit 10\",\n      \"pm list-open --limit 20\",\n      \"pm create --create-mode progressive --title \\\"...\\\" --description \\\"...\\\" --type Task\",\n      \"pm claim <ID>\",\n      \"pm update <ID> --status in_progress\",\n      \"pm close <ID> \\\"<reason with evidence>\\\" --validate-close warn\",\n    ],\n    workflows: [\n      {\n        name: \"Start Session Safely\",\n        goal: \"Bootstrap without mutating unrelated state.\",\n        prompt:\n          \"You are bootstrapping pm work. Use a token-efficient context snapshot first, then select one open item, claim it, and only then mutate.\",\n        commands: [\"pm context --limit 10\", \"pm list-open --limit 20\", \"pm claim <ID>\"],\n      },\n    ],\n    docs: [\n      { path: \"README.md\", purpose: \"High-level project and install entrypoint.\" },\n      { path: \"docs/QUICKSTART.md\", purpose: \"Short setup and first-command walkthrough.\" },\n      { path: \"docs/COMMANDS.md\", purpose: \"Task-oriented command recipes.\" },\n    ],\n    related: [\"commands\", \"workflows\", \"release\"],\n  },\n  {\n    id: \"commands\",\n    aliases: [\"cli\", \"operations\", \"reference\"],\n    title: \"CLI Command Routing\",\n    summary: \"Find the right command family quickly and use command-scoped help/contracts output.\",\n    intent: \"Use this when selecting command paths, flags, and output formats for implementation or automation.\",\n    commands: [\n      \"pm --help\",\n      \"pm <command> --help\",\n      \"pm <command> --help --explain\",\n      \"pm contracts --command <command> --flags-only\",\n      \"pm contracts --command <command> --availability-only --runtime-only\",\n      \"pm completion <bash|zsh|fish>\",\n    ],\n    workflows: [\n      {\n        name: \"Flag Discovery\",\n        goal: \"Resolve command flags deterministically before mutations.\",\n        prompt:\n          \"You are preparing to run a command. Use help and contracts surfaces to verify required/optional flags before execution.\",\n        commands: [\"pm <command> --help --explain\", \"pm contracts --command <command> --flags-only\"],\n      },\n    ],\n    docs: [\n      { path: \"docs/COMMANDS.md\", purpose: \"Command grouping and examples.\" },\n      { path: \"docs/CONFIGURATION.md\", purpose: \"Project/global settings and policy controls.\" },\n      { path: \"docs/TESTING.md\", purpose: \"Linked-test orchestration and safety guidance.\" },\n    ],\n    related: [\"quickstart\", \"workflows\", \"sdk\", \"extensions\"],\n  },\n  {\n    id: \"workflows\",\n    aliases: [\"developer\", \"maintainer\", \"agent\"],\n    title: \"Developer and Agent Workflows\",\n    summary: \"Apply canonical claim -> execute -> verify -> close workflows with append-only evidence.\",\n    intent: \"Use this for day-to-day coding-agent execution loops and handoff-safe updates.\",\n    commands: [\n      \"pm claim <ID>\",\n      \"pm update <ID> --status in_progress\",\n      \"pm files <ID> --add ...\",\n      \"pm test <ID> --add ...\",\n      \"pm comments <ID> \\\"...\\\"\",\n      \"pm validate --check-resolution --check-history-drift\",\n      \"pm release <ID>\",\n    ],\n    workflows: [\n      {\n        name: \"Execution Loop\",\n        goal: \"Keep code, tests, and tracker evidence synchronized.\",\n        prompt:\n          \"You are implementing a scoped change. Claim first, link files/tests/docs as you go, append evidence comments, and close only after validation.\",\n        commands: [\n          \"pm claim <ID>\",\n          \"pm update <ID> --status in_progress\",\n          \"pm files <ID> --add path=<file>,scope=project\",\n          \"pm test <ID> --run --progress\",\n          \"pm close <ID> \\\"<evidence>\\\" --validate-close warn\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"AGENTS.md\", purpose: \"Repository operating rules and required workflow.\" },\n      { path: \"docs/AGENT_GUIDE.md\", purpose: \"Agent-oriented usage and context strategy.\" },\n      { path: \"docs/TESTING.md\", purpose: \"Sandbox-safe test execution rules.\" },\n    ],\n    related: [\"quickstart\", \"commands\", \"skills\"],\n  },\n  {\n    id: \"sdk\",\n    aliases: [\"api\", \"typescript-sdk\"],\n    title: \"SDK and Integrations\",\n    summary: \"Use the published SDK surface for extension authoring and contract-safe integrations.\",\n    intent: \"Use this when building or reviewing programmatic integrations against @unbrained/pm-cli/sdk.\",\n    commands: [\n      \"pm contracts --schema-only\",\n      \"pm contracts --command extension --flags-only\",\n      \"pm contracts --runtime-only --availability-only\",\n    ],\n    workflows: [\n      {\n        name: \"Integration Contract Check\",\n        goal: \"Confirm action schemas and runtime availability before coding.\",\n        prompt:\n          \"You are wiring an integration. Capture schema + runtime availability first, then map your adapter payload fields to contract keys.\",\n        commands: [\n          \"pm contracts --schema-only\",\n          \"pm contracts --availability-only --runtime-only\",\n          \"pm contracts --command <command> --flags-only\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"docs/SDK.md\", purpose: \"Public SDK exports and extension authoring references.\" },\n      { path: \"docs/ARCHITECTURE.md\", purpose: \"Core runtime composition and extension load flow.\" },\n    ],\n    related: [\"extensions\", \"commands\"],\n  },\n  {\n    id: \"extensions\",\n    aliases: [\"plugins\", \"extension-authoring\", \"packages\", \"package-authoring\"],\n    title: \"Packages and Extensions\",\n    summary: \"Install, author, and diagnose packages/extensions with deterministic lifecycle controls.\",\n    intent: \"Use this for package management, extension capability registration, and runtime diagnostics.\",\n    commands: [\n      \"pm install <target> --project\",\n      \"pm upgrade --dry-run\",\n      \"pm package explore --project\",\n      \"pm package manage --detail summary\",\n      \"pm package doctor --detail deep\",\n      \"pm package activate <target> --project\",\n      \"pm package deactivate <target> --project\",\n    ],\n    workflows: [\n      {\n        name: \"Lifecycle Triage\",\n        goal: \"Diagnose extension state before forceful lifecycle actions.\",\n        prompt:\n          \"You are debugging package behavior. Inspect managed state first, then run doctor diagnostics, then apply install/adopt/activate actions.\",\n        commands: [\n          \"pm package explore --project\",\n          \"pm package manage --detail summary\",\n          \"pm package doctor --detail deep\",\n          \"pm upgrade --packages-only --dry-run\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"docs/EXTENSIONS.md\", purpose: \"Capability model and lifecycle command usage.\" },\n      {\n        path: \"docs/examples/starter-extension/README.md\",\n        purpose: \"Starter extension scaffold and local development path.\",\n      },\n      { path: \"docs/SDK.md\", purpose: \"SDK contracts used by extension implementations.\" },\n    ],\n    related: [\"sdk\", \"commands\", \"skills\"],\n  },\n  {\n    id: \"skills\",\n    aliases: [\"agent-skills\", \"agentskills\"],\n    title: \"Agent Skills\",\n    summary: \"Skill bundles for developer, user, extensions, and sdk workflows aligned to the current CLI.\",\n    intent: \"Use this when an agent needs reproducible prompts/workflows with strict compatibility metadata.\",\n    commands: [\n      \"pm guide skills --depth deep\",\n      \"pm contracts --command guide --flags-only\",\n      \"pm validate --check-command-references\",\n    ],\n    workflows: [\n      {\n        name: \"Skill Selection\",\n        goal: \"Pick the narrowest compatible skill first to minimize context usage.\",\n        prompt:\n          \"Select a pm skill based on the task intent, then execute only the workflow section needed for the current change.\",\n        commands: [\"pm guide skills\", \"pm guide skills --depth deep\"],\n      },\n    ],\n    docs: [\n      { path: \"docs/AGENT_GUIDE.md\", purpose: \"Agent-first usage and context model.\" },\n      { path: \"docs/README.md\", purpose: \"Documentation routing with progressive disclosure.\" },\n      { path: \".agents/skills/README.md\", purpose: \"Agent skills index and routing overview.\" },\n      { path: \".agents/skills/pm-developer/SKILL.md\", purpose: \"Developer-oriented pm skill workflow.\" },\n      { path: \".agents/skills/pm-user/SKILL.md\", purpose: \"User/operator pm skill workflow.\" },\n      { path: \".agents/skills/pm-extensions/SKILL.md\", purpose: \"Extension-focused pm skill workflow.\" },\n      { path: \".agents/skills/pm-sdk/SKILL.md\", purpose: \"SDK integration pm skill workflow.\" },\n    ],\n    related: [\"workflows\", \"harnesses\", \"commands\"],\n  },\n  {\n    id: \"harnesses\",\n    aliases: [\"compatibility\", \"agent-compatibility\"],\n    title: \"Agent Harness Compatibility\",\n    summary: \"Cross-harness compatibility guidance for docs routing.\",\n    intent: \"Use this when adapting pm docs and SDK contracts for an external automation harness.\",\n    commands: [\"pm guide skills\", \"pm guide commands\", \"pm contracts --runtime-only --availability-only\"],\n    workflows: [\n      {\n        name: \"Harness Mapping\",\n        goal: \"Route each harness to the same canonical skill/docs sources.\",\n        prompt:\n          \"Map harness-specific entrypoints to the same pm guide topics and .agents/skills workflows without adding runtime harness-specific code.\",\n        commands: [\"pm guide harnesses --depth standard\", \"pm guide skills --depth deep\"],\n      },\n    ],\n    docs: [\n      { path: \"docs/AGENT_GUIDE.md\", purpose: \"Agent context and output-mode conventions.\" },\n      { path: \"docs/README.md\", purpose: \"Single-source documentation routing entrypoint.\" },\n      { path: \".agents/skills/HARNESS_COMPATIBILITY.md\", purpose: \"Harness compatibility matrix and usage notes.\" },\n    ],\n    related: [\"skills\", \"workflows\"],\n  },\n  {\n    id: \"release\",\n    aliases: [\"gates\", \"ship\", \"release-readiness\"],\n    title: \"Release and Staleness Gates\",\n    summary: \"Run release gates and docs/skills freshness checks before publishing.\",\n    intent: \"Use this when validating release readiness and preventing docs/skills drift.\",\n    commands: [\n      \"pnpm build\",\n      \"pnpm test:coverage\",\n      \"pnpm quality:static\",\n      \"node scripts/release/run-gates.mjs --telemetry-mode best-effort\",\n      \"pnpm security:scan\",\n    ],\n    workflows: [\n      {\n        name: \"Pre-Release Gate Sweep\",\n        goal: \"Ensure code, docs, and skills are all green before publish.\",\n        prompt:\n          \"Run release gates in deterministic order and treat docs/skills freshness failures as release blockers.\",\n        commands: [\n          \"pnpm build\",\n          \"pnpm test:coverage\",\n          \"node scripts/release/run-gates.mjs --telemetry-mode best-effort\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"docs/RELEASING.md\", purpose: \"Release flow and safety checks.\" },\n      { path: \"CHANGELOG.md\", purpose: \"Versioned release history and unreleased notes.\" },\n      { path: \"scripts/release/run-gates.mjs\", purpose: \"Source of truth for release gate ordering.\" },\n    ],\n    related: [\"commands\", \"skills\", \"workflows\"],\n  },\n];\n\nconst TOPIC_BY_TOKEN = new Map<string, GuideTopicDefinition>();\nfor (const topic of GUIDE_TOPICS) {\n  TOPIC_BY_TOKEN.set(topic.id, topic);\n  for (const alias of topic.aliases) {\n    TOPIC_BY_TOKEN.set(alias, topic);\n  }\n}\n\nexport function listGuideTopics(): GuideTopicDefinition[] {\n  return GUIDE_TOPICS.map((topic) => ({\n    ...topic,\n    aliases: [...topic.aliases],\n    commands: [...topic.commands],\n    workflows: topic.workflows.map((workflow) => ({\n      ...workflow,\n      commands: [...workflow.commands],\n    })),\n    docs: topic.docs.map((doc) => ({ ...doc })),\n    related: [...topic.related],\n  }));\n}\n\nexport function listGuideTopicIds(): string[] {\n  return GUIDE_TOPICS.map((topic) => topic.id);\n}\n\nexport function resolveGuideTopic(rawTopic: string | undefined): GuideTopicDefinition | null {\n  if (!rawTopic) {\n    return null;\n  }\n  const normalized = normalizeTopicToken(rawTopic);\n  if (!normalized) {\n    return null;\n  }\n  return TOPIC_BY_TOKEN.get(normalized) ?? null;\n}\n"]}