@unbrained/pm-cli 2026.5.12 → 2026.5.18

package/dist/cli/commands/extension.js

@@ -1,3 +1,5 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="499323d3-24fc-5cd7-b97a-b27a0971ba12")}catch(e){}}();
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -7,7 +9,8 @@ import { promisify } from "node:util";
 import { activateExtensions, loadExtensions, nextExtensionReloadToken } from "../../core/extensions/index.js";
 import { EXTENSION_CAPABILITY_CONTRACT, KNOWN_EXTENSION_CAPABILITIES, parseLegacyExtensionCapabilityAliasWarning, parseUnknownExtensionCapabilityWarning, resolveExtensionRoots, } from "../../core/extensions/loader.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
-import { collectPackageExtensionDirectories } from "../../core/packages/manifest.js";
+import { PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, } from "../../core/packages/manifest.js";
+import { resolvePmPackageRootFromModule } from "../../core/packages/root.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { nowIso } from "../../core/shared/time.js";
@@ -18,7 +21,7 @@ const DEFAULT_EXTENSION_PRIORITY = 100;
 const MANAGED_EXTENSION_STATE_FILENAME = ".managed-extensions.json";
 const MANAGED_EXTENSION_STATE_VERSION = 1;
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
-const BUNDLED_PACKAGE_ALIASES = {
+const LEGACY_BUNDLED_PACKAGE_ALIASES = {
     beads: {
         package_directory: "pm-beads",
         legacy_extension_directory: "beads",
@@ -35,21 +38,20 @@ function resolvePackageRootCandidates() {
     if (typeof envRoot === "string" && envRoot.trim().length > 0) {
         candidates.push(path.resolve(envRoot.trim()));
     }
-    const moduleRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
-    candidates.push(moduleRoot);
+    candidates.push(resolvePmPackageRootFromModule(import.meta.url, ["../../.."]));
     return [...new Set(candidates)];
 }
 async function resolveBundledExtensionAliasSource(input) {
     const normalized = input.trim().toLowerCase();
-    const alias = BUNDLED_PACKAGE_ALIASES[normalized];
+    const packageRoot = await resolveBundledPackageRoot(normalized);
+    if (packageRoot) {
+        return packageRoot;
+    }
+    const alias = LEGACY_BUNDLED_PACKAGE_ALIASES[normalized];
     if (!alias) {
         return null;
     }
     for (const packageRoot of resolvePackageRootCandidates()) {
-        const packagePath = path.join(packageRoot, "packages", alias.package_directory);
-        if (await pathExists(path.join(packagePath, "package.json"))) {
-            return packagePath;
-        }
         const legacyExtensionPath = path.join(packageRoot, ".agents", "pm", "extensions", alias.legacy_extension_directory);
         if (await pathExists(path.join(legacyExtensionPath, "manifest.json"))) {
             return legacyExtensionPath;
@@ -60,8 +62,67 @@ async function resolveBundledExtensionAliasSource(input) {
 function isBundledPackageInstallAllTarget(input) {
     return BUNDLED_PACKAGE_INSTALL_ALL_TARGETS.has(input.trim().toLowerCase());
 }
-function listBundledPackageAliases() {
-    return Object.keys(BUNDLED_PACKAGE_ALIASES).sort((left, right) => left.localeCompare(right));
+function derivePackageAlias(packageDirectory) {
+    return packageDirectory.replace(/^pm-/i, "").trim().toLowerCase();
+}
+async function collectBundledPackageEntries() {
+    const entriesByAlias = new Map();
+    for (const packageRoot of resolvePackageRootCandidates()) {
+        const packagesRoot = path.join(packageRoot, "packages");
+        if (!(await pathExists(packagesRoot))) {
+            continue;
+        }
+        const entries = await fs.readdir(packagesRoot, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !entry.name.startsWith("pm-")) {
+                continue;
+            }
+            const candidateRoot = path.join(packagesRoot, entry.name);
+            if (!(await pathExists(path.join(candidateRoot, "package.json")))) {
+                continue;
+            }
+            const manifest = await readPmPackageManifest(candidateRoot);
+            const aliases = manifest.aliases && manifest.aliases.length > 0
+                ? manifest.aliases
+                : [derivePackageAlias(entry.name)];
+            for (const alias of aliases) {
+                const normalizedAlias = alias.trim().toLowerCase();
+                if (normalizedAlias.length === 0 || entriesByAlias.has(normalizedAlias)) {
+                    continue;
+                }
+                entriesByAlias.set(normalizedAlias, {
+                    alias: normalizedAlias,
+                    package_directory: entry.name,
+                    package_root: candidateRoot,
+                });
+            }
+        }
+    }
+    for (const [alias, legacy] of Object.entries(LEGACY_BUNDLED_PACKAGE_ALIASES)) {
+        if (entriesByAlias.has(alias)) {
+            continue;
+        }
+        for (const packageRoot of resolvePackageRootCandidates()) {
+            const packagePath = path.join(packageRoot, "packages", legacy.package_directory);
+            if (await pathExists(path.join(packagePath, "package.json"))) {
+                entriesByAlias.set(alias, {
+                    alias,
+                    package_directory: legacy.package_directory,
+                    package_root: packagePath,
+                });
+                break;
+            }
+        }
+    }
+    return [...entriesByAlias.values()].sort((left, right) => left.alias.localeCompare(right.alias));
+}
+async function listBundledPackageAliases() {
+    return (await collectBundledPackageEntries()).map((entry) => entry.alias);
+}
+async function resolveBundledPackageRoot(alias) {
+    const normalized = alias.trim().toLowerCase();
+    const entry = (await collectBundledPackageEntries()).find((candidate) => candidate.alias === normalized);
+    return entry?.package_root ?? null;
 }
 function normalizeStringList(values) {
     return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))].sort((left, right) => left.localeCompare(right));
@@ -291,7 +352,7 @@ function normalizeManagedState(raw) {
             continue;
         }
         const source = entry.source;
-        if ((source.kind !== "local" && source.kind !== "github" && source.kind !== "npm") ||
+        if ((source.kind !== "local" && source.kind !== "github" && source.kind !== "npm" && source.kind !== "builtin") ||
             typeof source.input !== "string" ||
             typeof source.location !== "string") {
             continue;
@@ -309,6 +370,7 @@ function normalizeManagedState(raw) {
                 kind: source.kind,
                 input: source.input,
                 location: source.location,
+                name: typeof source.name === "string" ? source.name : undefined,
                 package: typeof source.package === "string" ? source.package : undefined,
                 version: typeof source.version === "string" ? source.version : undefined,
                 repository: typeof source.repository === "string" ? source.repository : undefined,
@@ -477,6 +539,7 @@ function resolveAction(target, options) {
             options.manage ? "manage" : null,
             options.reload ? "reload" : null,
             options.doctor ? "doctor" : null,
+            options.catalog ? "catalog" : null,
             options.init ? "init" : null,
             options.scaffold ? "init" : null,
             options.adopt ? "adopt" : null,
@@ -491,10 +554,25 @@ function resolveAction(target, options) {
         if (typeof target === "string" && target.trim().toLowerCase() === "reload") {
             return "reload";
         }
+        if (typeof target === "string" && target.trim().toLowerCase() === "catalog") {
+            return "catalog";
+        }
         if (typeof target === "string" && (target.trim().toLowerCase() === "init" || target.trim().toLowerCase() === "scaffold")) {
             return "init";
         }
-        throw new PmCliError("One action flag is required. Use one of: --install, --uninstall, --explore, --manage, --reload, --doctor, --init/--scaffold, --adopt, --adopt-all, --activate, --deactivate.", EXIT_CODE.USAGE);
+        if (typeof target === "string" && target.trim().toLowerCase() === "explore") {
+            return "explore";
+        }
+        if (typeof target === "string" && target.trim().toLowerCase() === "manage") {
+            return "manage";
+        }
+        if (typeof target === "string" && (target.trim().toLowerCase() === "list" || target.trim() === "")) {
+            return "explore";
+        }
+        if (target === undefined) {
+            return "explore";
+        }
+        throw new PmCliError("One action flag is required. Use one of: --install, --uninstall, --explore, --manage, --reload, --doctor, --catalog, --init/--scaffold, --adopt, --adopt-all, --activate, --deactivate. Bare `pm package` and `pm extension` default to --explore.", EXIT_CODE.USAGE);
     }
     if (selected.length > 1) {
         throw new PmCliError("Extension action flags are mutually exclusive.", EXIT_CODE.USAGE);
@@ -509,6 +587,85 @@ function resolveScope(options) {
     }
     return global ? "global" : "project";
 }
+async function buildBundledPackageCatalog(scope, global) {
+    const roots = resolveExtensionRoots(resolvePmRoot(process.cwd(), global.path), process.cwd());
+    const selectedRoot = scope === "global" ? roots.global : roots.project;
+    const managedStateRead = await readManagedExtensionState(selectedRoot);
+    const installedLocations = new Set(managedStateRead.state.entries
+        .filter((entry) => entry.scope === scope)
+        .filter((entry) => entry.source.kind !== "builtin")
+        .map((entry) => path.resolve(entry.source.location)));
+    const installedBuiltinAliases = new Set(managedStateRead.state.entries
+        .filter((entry) => entry.scope === scope && entry.source.kind === "builtin")
+        .flatMap((entry) => [entry.source.name, entry.source.input, entry.source.location])
+        .filter((value) => typeof value === "string" && value.trim().length > 0)
+        .map((value) => value.trim().toLowerCase()));
+    const packages = [];
+    for (const alias of await listBundledPackageAliases()) {
+        const packageRoot = await resolveBundledPackageRoot(alias);
+        const installScopeFlag = scope === "global" ? "--global" : "--project";
+        if (!packageRoot) {
+            packages.push({
+                alias,
+                bundled: true,
+                available: false,
+                installed: false,
+                install_target: alias,
+                install_command: `pm install ${alias} ${installScopeFlag}`,
+            });
+            continue;
+        }
+        const manifest = await readPmPackageManifest(packageRoot);
+        const repository = manifest.catalog?.links?.repository ?? manifest.package_repository_url;
+        const report = manifest.catalog?.links?.report ?? manifest.package_bugs_url;
+        const docs = manifest.catalog?.links?.docs ?? manifest.package_homepage;
+        const npm = manifest.catalog?.links?.npm ??
+            (manifest.package_name && manifest.package_private !== true
+                ? `https://www.npmjs.com/package/${encodeURIComponent(manifest.package_name)}`
+                : undefined);
+        const metadataOnlyResources = Object.fromEntries(PM_PACKAGE_RESOURCE_KINDS
+            .filter((resourceKind) => resourceKind !== "extensions")
+            .map((resourceKind) => [resourceKind, manifest.resources[resourceKind] ?? []])
+            .filter(([, entries]) => Array.isArray(entries) && entries.length > 0));
+        packages.push({
+            alias,
+            bundled: true,
+            available: true,
+            installed: installedBuiltinAliases.has(alias) || installedLocations.has(path.resolve(packageRoot)),
+            install_target: alias,
+            install_command: `pm install ${alias} ${installScopeFlag}`,
+            package_root: packageRoot,
+            package_name: manifest.package_name,
+            package_version: manifest.package_version,
+            description: manifest.catalog?.summary ?? manifest.package_description,
+            keywords: manifest.package_keywords ?? [],
+            resources: manifest.resources,
+            installable_resources: {
+                extensions: manifest.resources.extensions ?? [],
+            },
+            metadata_only_resources: metadataOnlyResources,
+            catalog: {
+                display_name: manifest.catalog?.display_name,
+                category: manifest.catalog?.category,
+                tags: manifest.catalog?.tags ?? manifest.package_keywords ?? [],
+                links: {
+                    docs,
+                    npm,
+                    repository,
+                    report,
+                },
+                media: manifest.catalog?.media,
+            },
+        });
+    }
+    return {
+        total: packages.length,
+        scope,
+        installable_resource_kinds: ["extensions"],
+        metadata_only_resource_kinds: PM_PACKAGE_RESOURCE_KINDS.filter((resourceKind) => resourceKind !== "extensions"),
+        packages,
+    };
+}
 function parseGithubPathSpec(pathSpec, input, refOverride) {
     const segments = pathSpec
         .split("/")
@@ -735,7 +892,7 @@ async function resolvePackageExtensionDirectory(packageRoot, sourceLabel) {
             .sort((left, right) => left.localeCompare(right));
         throw new PmCliError(`Package source "${sourceLabel}" contains multiple extension manifests. Provide an explicit extension path. Candidates: ${choices.join(", ")}`, EXIT_CODE.USAGE);
     }
-    throw new PmCliError(`Unable to locate a pm extension manifest in package source "${sourceLabel}". Add package.json pm.extensions or an extensions/ directory.`, EXIT_CODE.USAGE);
+    throw new PmCliError(`Unable to locate a pm extension manifest in package source "${sourceLabel}". Package installs currently activate only extension resources, so add package.json pm.extensions or an extensions/ directory. Metadata-only resources like pm.docs/pm.examples are catalog metadata and do not activate commands.`, EXIT_CODE.USAGE);
 }
 async function resolveGithubSourceDirectory(cloneDirectory, source) {
     const candidatePaths = [];
@@ -762,11 +919,14 @@ async function resolveGithubSourceDirectory(cloneDirectory, source) {
 }
 async function resolveInstallSource(source) {
     if (source.kind === "local") {
-        if (!(await pathExists(source.absolute_path))) {
+        let localStats;
+        try {
+            localStats = await fs.stat(source.absolute_path);
+        }
+        catch {
             throw new PmCliError(`Local extension source does not exist: "${source.absolute_path}".`, EXIT_CODE.NOT_FOUND);
         }
-        const stats = await fs.stat(source.absolute_path);
-        if (!stats.isDirectory()) {
+        if (!localStats.isDirectory()) {
             throw new PmCliError(`Local extension source must be a directory: "${source.absolute_path}".`, EXIT_CODE.USAGE);
         }
         const directory = await resolvePackageExtensionDirectory(source.absolute_path, source.input);
@@ -966,20 +1126,66 @@ function applyDoctorRuntimeActivationState(extensions, loadResult, activationRes
     const loadedNames = new Set(loadResult.loaded.map((entry) => normalizeExtensionNameForMatch(entry.name)));
     const loadFailedNames = new Set(loadResult.failed.map((entry) => normalizeExtensionNameForMatch(entry.name)));
     const activationFailedNames = new Set(activationResult.failed.map((entry) => normalizeExtensionNameForMatch(entry.name)));
+    const commandPathsByExtension = new Map();
+    const actionPathsByExtension = new Map();
+    const addCommandPath = (extensionName, commandPath) => {
+        const normalizedName = normalizeExtensionNameForMatch(extensionName);
+        const normalizedCommandPath = commandPath.trim();
+        if (normalizedName.length === 0 || normalizedCommandPath.length === 0) {
+            return;
+        }
+        const existing = commandPathsByExtension.get(normalizedName) ?? new Set();
+        existing.add(normalizedCommandPath);
+        commandPathsByExtension.set(normalizedName, existing);
+    };
+    const addActionPath = (extensionName, actionPath) => {
+        const normalizedName = normalizeExtensionNameForMatch(extensionName);
+        const normalizedActionPath = actionPath.trim();
+        if (normalizedName.length === 0 || normalizedActionPath.length === 0) {
+            return;
+        }
+        const existing = actionPathsByExtension.get(normalizedName) ?? new Set();
+        existing.add(normalizedActionPath);
+        actionPathsByExtension.set(normalizedName, existing);
+    };
+    for (const registration of activationResult.registrations.commands) {
+        addCommandPath(registration.name, registration.command);
+        addActionPath(registration.name, registration.action);
+    }
+    for (const handler of activationResult.commands.handlers) {
+        addCommandPath(handler.name, handler.command);
+    }
+    for (const override of activationResult.commands.overrides) {
+        addCommandPath(override.name, override.command);
+    }
+    const sortedPaths = (values) => {
+        if (!values || values.size === 0) {
+            return undefined;
+        }
+        return [...values].sort((left, right) => left.localeCompare(right));
+    };
     return extensions.map((entry) => {
+        const normalizedName = normalizeExtensionNameForMatch(entry.name);
+        const commandPaths = sortedPaths(commandPathsByExtension.get(normalizedName));
+        const actionPaths = sortedPaths(actionPathsByExtension.get(normalizedName));
+        const runtimeMetadata = {
+            ...(commandPaths ? { command_paths: commandPaths } : {}),
+            ...(actionPaths ? { action_paths: actionPaths } : {}),
+        };
         if (!entry.enabled) {
             return {
                 ...entry,
                 runtime_active: false,
                 activation_status: "not_loaded",
+                ...runtimeMetadata,
             };
         }
-        const normalizedName = normalizeExtensionNameForMatch(entry.name);
         if (loadFailedNames.has(normalizedName) || activationFailedNames.has(normalizedName)) {
             return {
                 ...entry,
                 runtime_active: false,
                 activation_status: "failed",
+                ...runtimeMetadata,
             };
         }
         if (loadedNames.has(normalizedName)) {
@@ -987,12 +1193,14 @@ function applyDoctorRuntimeActivationState(extensions, loadResult, activationRes
                 ...entry,
                 runtime_active: true,
                 activation_status: "ok",
+                ...runtimeMetadata,
             };
         }
         return {
             ...entry,
             runtime_active: false,
             activation_status: "not_loaded",
+            ...runtimeMetadata,
         };
     });
 }
@@ -1127,13 +1335,17 @@ function requireTarget(target, action) {
     const normalized = target?.trim();
     if (!normalized) {
         if (action === "init") {
-            throw new PmCliError('Action "init" requires a scaffold target path (for example: pm extension --init ./my-extension or pm extension init ./my-extension).', EXIT_CODE.USAGE);
+            throw new PmCliError('Action "init" requires a scaffold target path (for example: pm package init ./my-package or pm extension init ./my-extension).', EXIT_CODE.USAGE);
         }
         throw new PmCliError(`Action "${action}" requires an extension name or source target argument.`, EXIT_CODE.USAGE);
     }
     return normalized;
 }
-function buildStarterExtensionScaffoldFiles(extensionName, commandName) {
+function lifecycleFlagCommand(options, action) {
+    return options.vocabulary === "package" ? `pm package ${action}` : `pm extension --${action}`;
+}
+function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary) {
+    const packageName = `pm-${extensionName}`;
     const manifest = `${JSON.stringify({
         name: extensionName,
         version: "0.1.0",
@@ -1159,10 +1371,63 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName) {
         "};",
         "",
     ].join("\n");
+    if (vocabulary === "package") {
+        const packageJson = `${JSON.stringify({
+            name: packageName,
+            version: "0.1.0",
+            private: true,
+            type: "module",
+            keywords: ["pm-package"],
+            peerDependencies: {
+                "@unbrained/pm-cli": "*",
+            },
+            pm: {
+                aliases: [extensionName],
+                extensions: [`extensions/${extensionName}`],
+                docs: ["README.md"],
+                examples: ["README.md"],
+                catalog: {
+                    display_name: extensionName,
+                    category: "workflow",
+                    summary: "Starter pm package scaffold.",
+                    tags: ["starter"],
+                },
+            },
+        }, null, 2)}\n`;
+        const packageReadme = [
+            `# ${packageName}`,
+            "",
+            "Generated by `pm package init`.",
+            "",
+            "## Included Files",
+            "- `package.json`: package metadata and `pm` resource manifest.",
+            `- \`extensions/${extensionName}/manifest.json\`: extension metadata and capabilities.`,
+            `- \`extensions/${extensionName}/index.js\`: starter command registration using the \`commands\` capability.`,
+            "",
+            "## Quick Start",
+            "```bash",
+            "pm install --project <package-path>",
+            `pm ${commandName}`,
+            "pm package doctor --project --detail summary",
+            "```",
+            "",
+            "## Notes",
+            "- Keep package metadata in `package.json` and runtime behavior under `extensions/`.",
+            "- Add capabilities to the extension manifest only when the entrypoint uses the matching SDK API.",
+            "- Use `@unbrained/pm-cli/sdk` as the public SDK import for richer package runtimes.",
+            "",
+        ].join("\n");
+        return {
+            "package.json": packageJson,
+            [`extensions/${extensionName}/manifest.json`]: manifest,
+            [`extensions/${extensionName}/index.js`]: entrypoint,
+            "README.md": packageReadme,
+        };
+    }
     const readme = [
         `# ${extensionName}`,
         "",
-        "Generated by `pm extension --init`.",
+        "Generated by `pm extension init`.",
         "",
         "## Included Files",
         "- `manifest.json`: extension metadata and capabilities.",
@@ -1186,12 +1451,12 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName) {
         "README.md": readme,
     };
 }
-async function scaffoldExtensionProject(target) {
+async function scaffoldExtensionProject(target, vocabulary = "extension") {
     const normalizedTarget = target.trim();
     const targetPath = path.resolve(process.cwd(), normalizedTarget);
     const extensionName = normalizeManagedDirectoryName(path.basename(targetPath));
     const commandName = `${extensionName} ping`;
-    const scaffoldFiles = buildStarterExtensionScaffoldFiles(extensionName, commandName);
+    const scaffoldFiles = buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary);
     let createdDirectory = false;
     if (await pathExists(targetPath)) {
         const existingTargetStats = await fs.stat(targetPath);
@@ -1206,6 +1471,7 @@ async function scaffoldExtensionProject(target) {
     const files = [];
     for (const [relativePath, content] of Object.entries(scaffoldFiles)) {
         const absolutePath = path.join(targetPath, relativePath);
+        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
         if (await pathExists(absolutePath)) {
             const existingContent = await fs.readFile(absolutePath, "utf8");
             if (existingContent !== content) {
@@ -1248,7 +1514,7 @@ function classifyDoctorLoadFailureWarnings(loadFailures) {
     }
     return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
 }
-function buildExtensionTriageSummary(scope, warnings, extensions) {
+function buildExtensionTriageSummary(scope, warnings, extensions, options = {}) {
     const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
     const managedTotal = extensions.filter((entry) => entry.managed).length;
     const enabledTotal = extensions.filter((entry) => entry.enabled).length;
@@ -1288,7 +1554,7 @@ function buildExtensionTriageSummary(scope, warnings, extensions) {
     const remediation = [];
     if (normalizedWarnings.length > 0) {
         if (normalizedWarnings.some((warning) => warning.startsWith("extension_manifest_"))) {
-            remediation.push(`Run pm extension --explore ${scopeFlag} to inspect discovered manifests and directories.`);
+            remediation.push(`Run ${lifecycleFlagCommand(options, "explore")} ${scopeFlag} to inspect discovered manifests and directories.`);
         }
         if (normalizedWarnings.some((warning) => warning.startsWith("extension_capability_unknown:"))) {
             remediation.push(`Unknown extension capabilities detected. Allowed capabilities: ${KNOWN_EXTENSION_CAPABILITIES.join(", ")}. ` +
@@ -1304,14 +1570,14 @@ function buildExtensionTriageSummary(scope, warnings, extensions) {
         }
         if (normalizedWarnings.some((warning) => warning.startsWith("extension_load_failed_sdk_dependency_missing:"))) {
             remediation.push(`Detected extension load failures caused by missing SDK dependency resolution. ` +
-                `Ensure extension package dependencies include "@unbrained/pm-cli" and reinstall dependencies before running pm extension --doctor ${scopeFlag}.`);
+                `Ensure extension package dependencies include "@unbrained/pm-cli" and reinstall dependencies before running ${lifecycleFlagCommand(options, "doctor")} ${scopeFlag}.`);
         }
         if (normalizedWarnings.some((warning) => warning.startsWith("extension_load_failed_module_mode_mismatch:"))) {
             remediation.push(`Detected extension module-mode mismatches. For ESM-based extension entries/imports, set package.json "type": "module" ` +
-                `or use an explicit .mjs entry and rerun pm extension --doctor ${scopeFlag}.`);
+                `or use an explicit .mjs entry and rerun ${lifecycleFlagCommand(options, "doctor")} ${scopeFlag}.`);
         }
         if (updateCheckFailedTotal > 0) {
-            remediation.push(`Run pm extension --manage ${scopeFlag} after validating network and repository access.`);
+            remediation.push(`Run ${lifecycleFlagCommand(options, "manage")} ${scopeFlag} after validating network and repository access.`);
         }
         if (normalizedWarnings.some((warning) => warning.startsWith("extension_manager_state_"))) {
             remediation.push(`Review and repair ${scope} managed extension state file if schema/read warnings persist.`);
@@ -1321,19 +1587,19 @@ function buildExtensionTriageSummary(scope, warnings, extensions) {
         }
     }
     if (updateHealthPartial) {
-        remediation.push(`Update-check coverage is partial because unmanaged extensions need adoption. Adopt existing installs via pm extension --manage ${scopeFlag} --fix-managed-state (or pm extension --adopt-all ${scopeFlag}, pm extension --adopt <name> ${scopeFlag}, or reinstall via pm extension --install ${scopeFlag} <source>).`);
+        remediation.push(`Update-check coverage is partial because unmanaged extensions need adoption. Adopt existing installs via ${lifecycleFlagCommand(options, "manage")} ${scopeFlag} --fix-managed-state (or ${lifecycleFlagCommand(options, "adopt-all")} ${scopeFlag}, ${lifecycleFlagCommand(options, "adopt")} <name> ${scopeFlag}, or reinstall via ${lifecycleFlagCommand(options, "install")} ${scopeFlag} <source>).`);
     }
     else if (skippedUnmanagedTotal > 0) {
-        remediation.push(`Loaded unmanaged extensions are currently treated as informational. Use pm extension --manage ${scopeFlag} --fix-managed-state to adopt them for update checks.`);
+        remediation.push(`Loaded unmanaged extensions are currently treated as informational. Use ${lifecycleFlagCommand(options, "manage")} ${scopeFlag} --fix-managed-state to adopt them for update checks.`);
     }
     if (skippedNonGithubTotal > 0) {
         remediation.push(`Non-GitHub managed extensions are skipped by update checks. Use doctor output for non-update diagnostics.`);
     }
     if (updateAvailableTotal > 0) {
-        remediation.push(`Update available managed extensions via pm extension --install ${scopeFlag} <source>.`);
+        remediation.push(`Update available managed extensions via ${lifecycleFlagCommand(options, "install")} ${scopeFlag} <source>.`);
     }
     if (remediation.length === 0) {
-        remediation.push(`No immediate action required. Re-run pm extension --manage ${scopeFlag} after extension changes.`);
+        remediation.push(`No immediate action required. Re-run ${lifecycleFlagCommand(options, "manage")} ${scopeFlag} after extension changes.`);
     }
     return {
         status: effectiveWarnings.length === 0 ? "ok" : "warn",
@@ -1485,6 +1751,9 @@ export async function runExtension(target, options, global) {
         if (action === "reload" && normalizedInput === "reload") {
             return undefined;
         }
+        if (action === "catalog" && normalizedInput === "catalog") {
+            return undefined;
+        }
         const inferredInitAlias = action === "init" &&
             options.init !== true &&
             options.scaffold !== true &&
@@ -1516,7 +1785,7 @@ export async function runExtension(target, options, global) {
             throw new PmCliError('Action "init" does not accept --gh/--github/--ref options.', EXIT_CODE.USAGE);
         }
         const scaffoldTarget = requireTarget(normalizedTarget, action);
-        const scaffold = await scaffoldExtensionProject(scaffoldTarget);
+        const scaffold = await scaffoldExtensionProject(scaffoldTarget, options.vocabulary ?? "extension");
         const quotedTargetPath = JSON.stringify(scaffold.target_path);
         return withResult({
             scaffolded: scaffold.created_directory || scaffold.files.some((entry) => entry.status === "created"),
@@ -1528,9 +1797,9 @@ export async function runExtension(target, options, global) {
             created_directory: scaffold.created_directory,
             files: scaffold.files,
             next_steps: [
-                `Install the scaffold: pm extension --install --project ${quotedTargetPath}`,
+                `Install the scaffold: ${options.vocabulary === "package" ? "pm install --project" : "pm extension --install --project"} ${quotedTargetPath}`,
                 `Smoke-test command path: pm ${scaffold.command_name}`,
-                "Run extension diagnostics: pm extension --doctor --project --detail summary",
+                `Run diagnostics: ${options.vocabulary === "package" ? "pm package doctor" : "pm extension --doctor"} --project --detail summary`,
             ],
         });
     }
@@ -1582,6 +1851,12 @@ export async function runExtension(target, options, global) {
         }
         return withResult(details);
     }
+    if (action === "catalog") {
+        if (typeof normalizedTarget === "string" && normalizedTarget.length > 0 && normalizedTarget !== "catalog") {
+            throw new PmCliError('Action "catalog" does not accept a package target.', EXIT_CODE.USAGE);
+        }
+        return withResult(await buildBundledPackageCatalog(scope, global));
+    }
     if (action === "install") {
         const githubOption = resolveGithubOption(options);
         const explicitSourceInput = githubOption ?? requireTarget(normalizedTarget, action);
@@ -1589,7 +1864,7 @@ export async function runExtension(target, options, global) {
             if (typeof options.ref === "string" && options.ref.trim().length > 0) {
                 throw new PmCliError('Action "install all" does not accept --ref.', EXIT_CODE.USAGE);
             }
-            const aliases = listBundledPackageAliases();
+            const aliases = await listBundledPackageAliases();
             const packages = [];
             for (const alias of aliases) {
                 packages.push({
@@ -1616,6 +1891,7 @@ export async function runExtension(target, options, global) {
             });
         }
         const bundledAliasSource = typeof githubOption === "string" ? null : await resolveBundledExtensionAliasSource(explicitSourceInput);
+        const bundledAliasName = bundledAliasSource === null ? null : explicitSourceInput.trim().toLowerCase();
         const sourceInput = bundledAliasSource ?? explicitSourceInput;
         const installSource = parseExtensionInstallSource(sourceInput, {
             forceGithub: typeof githubOption === "string",
@@ -1638,31 +1914,38 @@ export async function runExtension(target, options, global) {
                 }
                 await fs.cp(validated.directory, destinationDirectory, { recursive: true, force: true });
             }
-            const sourceRecord = installSource.kind === "local"
+            const sourceRecord = bundledAliasName
                 ? {
-                    kind: "local",
-                    input: installSource.input,
-                    location: installSource.absolute_path,
+                    kind: "builtin",
+                    input: bundledAliasName,
+                    location: bundledAliasName,
+                    name: bundledAliasName,
                 }
-                : installSource.kind === "npm"
+                : installSource.kind === "local"
                     ? {
-                        kind: "npm",
+                        kind: "local",
                         input: installSource.input,
-                        location: resolvedSource.resolved_subpath ?? ".",
-                        package: resolvedSource.npm_package,
-                        version: resolvedSource.npm_version,
+                        location: installSource.absolute_path,
                     }
-                    : {
-                        kind: "github",
-                        input: installSource.input,
-                        location: resolvedSource.resolved_subpath ?? installSource.subpath ?? ".",
-                        repository: installSource.repository,
-                        owner: installSource.owner,
-                        repo: installSource.repo,
-                        ref: installSource.ref,
-                        subpath: resolvedSource.resolved_subpath ?? installSource.subpath,
-                        commit: resolvedSource.commit,
-                    };
+                    : installSource.kind === "npm"
+                        ? {
+                            kind: "npm",
+                            input: installSource.input,
+                            location: resolvedSource.resolved_subpath ?? ".",
+                            package: resolvedSource.npm_package,
+                            version: resolvedSource.npm_version,
+                        }
+                        : {
+                            kind: "github",
+                            input: installSource.input,
+                            location: resolvedSource.resolved_subpath ?? installSource.subpath ?? ".",
+                            repository: installSource.repository,
+                            owner: installSource.owner,
+                            repo: installSource.repo,
+                            ref: installSource.ref,
+                            subpath: resolvedSource.resolved_subpath ?? installSource.subpath,
+                            commit: resolvedSource.commit,
+                        };
             const now = nowIso();
             const existingManagedEntry = managedStateRead.state.entries.find((entry) => normalizeExtensionNameForMatch(entry.name) === normalizeExtensionNameForMatch(validated.manifest.name));
             const managedState = upsertManagedEntry(managedStateRead.state, {
@@ -1719,7 +2002,7 @@ export async function runExtension(target, options, global) {
         const adoption = await adoptUnmanagedExtensions(resolvedRoots.selected_root, scope, installed.extensions, managedStateRead.state);
         const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, adoption.state);
         warnings.push(...refreshedInstalled.warnings);
-        const triage = buildExtensionTriageSummary(scope, warnings, refreshedInstalled.extensions);
+        const triage = buildExtensionTriageSummary(scope, warnings, refreshedInstalled.extensions, options);
         warnings.push(...triage.warnings);
         const adoptedDetails = adoption.adopted_entries.map((entry) => {
             const refreshedEntry = refreshedInstalled.extensions.find((candidate) => normalizeExtensionNameForMatch(candidate.name) === normalizeExtensionNameForMatch(entry.name) &&
@@ -1926,7 +2209,7 @@ export async function runExtension(target, options, global) {
             .filter((entry) => entry.update_check_status === "failed")
             .map((entry) => `extension_update_check_failed:${entry.name}`);
         warnings.push(...updateCheckWarnings);
-        const triage = buildExtensionTriageSummary(scope, warnings, runtimeInstalledExtensions);
+        const triage = buildExtensionTriageSummary(scope, warnings, runtimeInstalledExtensions, options);
         warnings.push(...triage.warnings);
         const normalizedWarnings = [...triage.warnings];
         const policySummary = {
@@ -1956,10 +2239,18 @@ export async function runExtension(target, options, global) {
             ...new Set([
                 ...triage.remediation,
                 ...(loadResult.failed.length > 0
-                    ? ["Run pm extension --explore --project and pm extension --explore --global to inspect load failures."]
+                    ? [
+                        options.vocabulary === "package"
+                            ? "Run pm package explore --project and pm package explore --global to inspect load failures."
+                            : "Run pm extension --explore --project and pm extension --explore --global to inspect load failures.",
+                    ]
                     : []),
                 ...(activationResult.failed.length > 0
-                    ? ["Review activation failures in pm extension --doctor --detail deep output."]
+                    ? [
+                        options.vocabulary === "package"
+                            ? "Review activation failures in pm package doctor --detail deep output."
+                            : "Review activation failures in pm extension --doctor --detail deep output.",
+                    ]
                     : []),
                 ...(managedStateFix && managedStateFix.adopted_entries.length > 0
                     ? [`Managed-state fix adopted ${managedStateFix.adopted_entries.length} extension(s).`]
@@ -2136,7 +2427,7 @@ export async function runExtension(target, options, global) {
         }
         let runtimeProbeSummary;
         let runtimeInstalledExtensions = refreshedInstalled.extensions;
-        if (action === "manage" && options.runtimeProbe === true) {
+        if (action === "explore" || options.runtimeProbe === true) {
             const loadResult = await loadExtensions({
                 pmRoot: resolvedRoots.pm_root,
                 settings,
@@ -2153,6 +2444,7 @@ export async function runExtension(target, options, global) {
             runtimeProbeSummary = {
                 requested: true,
                 executed: true,
+                reason: action === "explore" ? "explore_defaults_to_runtime_probe" : "runtime_probe_requested",
                 load_failure_count: loadResult.failed.length,
                 activation_failure_count: activationResult.failed.length,
                 warning_count: [...new Set([...loadResult.warnings, ...activationResult.warnings])].length,
@@ -2161,11 +2453,11 @@ export async function runExtension(target, options, global) {
         }
         else if (action === "manage") {
             runtimeProbeSummary = {
-                requested: options.runtimeProbe === true,
+                requested: false,
                 executed: false,
             };
         }
-        const triage = buildExtensionTriageSummary(scope, warnings, runtimeInstalledExtensions);
+        const triage = buildExtensionTriageSummary(scope, warnings, runtimeInstalledExtensions, options);
         warnings.push(...triage.warnings);
         const details = {
             total: runtimeInstalledExtensions.length,
@@ -2176,6 +2468,9 @@ export async function runExtension(target, options, global) {
             triage,
             policy: configuredPolicy,
         };
+        if (action === "explore") {
+            details.runtime_probe = runtimeProbeSummary;
+        }
         if (action === "manage") {
             details.runtime_probe = runtimeProbeSummary;
             details.managed_state_fix =
@@ -2199,4 +2494,5 @@ export async function runExtension(target, options, global) {
     }
     throw new PmCliError(`Unsupported extension action "${action}".`, EXIT_CODE.USAGE);
 }
-//# sourceMappingURL=extension.js.map
+//# sourceMappingURL=extension.js.map
+//# debugId=499323d3-24fc-5cd7-b97a-b27a0971ba12