@unbrained/pm-cli 2026.5.14 → 2026.5.24

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]="69ff4814-0641-5d85-962e-a798cfd1a78e")}catch(e){}}();
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -7,7 +9,9 @@ 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 { isPathWithinDirectory } from "../../core/fs/path-utils.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";
@@ -35,8 +39,7 @@ 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) {
@@ -253,13 +256,6 @@ function parseExtensionManifest(raw) {
         capabilities,
     };
 }
-function isPathWithinDirectory(directory, targetPath) {
-    const relative = path.relative(directory, targetPath);
-    if (relative.length === 0) {
-        return true;
-    }
-    return !relative.startsWith("..") && !path.isAbsolute(relative);
-}
 async function isCanonicalPathWithinDirectory(directory, targetPath) {
     const [resolvedDirectory, resolvedTargetPath] = await Promise.all([fs.realpath(directory), fs.realpath(targetPath)]);
     return isPathWithinDirectory(resolvedDirectory, resolvedTargetPath);
@@ -320,6 +316,21 @@ function sortManagedEntries(entries) {
         return left.directory.localeCompare(right.directory);
     });
 }
+function managedExtensionSourcesEquivalent(left, right) {
+    if (left.kind !== right.kind || left.input !== right.input || left.location !== right.location) {
+        return false;
+    }
+    if (left.kind === "npm" && right.kind === "npm") {
+        return left.package === right.package && left.version === right.version;
+    }
+    if (left.kind === "github" && right.kind === "github") {
+        return left.repository === right.repository && left.ref === right.ref && left.subpath === right.subpath && left.commit === right.commit;
+    }
+    if (left.kind === "builtin" && right.kind === "builtin") {
+        return left.name === right.name;
+    }
+    return true;
+}
 function normalizeManagedState(raw) {
     if (typeof raw !== "object" || raw === null) {
         return null;
@@ -350,7 +361,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;
@@ -368,6 +379,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,
@@ -557,7 +569,19 @@ function resolveAction(target, options) {
         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, --catalog, --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);
@@ -572,13 +596,19 @@ function resolveScope(options) {
     }
     return global ? "global" : "project";
 }
-async function buildBundledPackageCatalog(scope, global) {
+async function buildBundledPackageCatalog(scope, global, options = {}) {
     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);
@@ -599,7 +629,9 @@ async function buildBundledPackageCatalog(scope, global) {
         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 ? `https://www.npmjs.com/package/${encodeURIComponent(manifest.package_name)}` : undefined);
+            (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] ?? []])
@@ -608,10 +640,9 @@ async function buildBundledPackageCatalog(scope, global) {
             alias,
             bundled: true,
             available: true,
-            installed: installedLocations.has(path.resolve(packageRoot)),
+            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,
@@ -635,14 +666,68 @@ async function buildBundledPackageCatalog(scope, global) {
             },
         });
     }
+    const fields = parsePackageCatalogFields(options.fields);
+    const outputPackages = fields ? packages.map((entry) => projectPackageCatalogEntry(entry, fields)) : packages;
     return {
-        total: packages.length,
+        total: outputPackages.length,
         scope,
         installable_resource_kinds: ["extensions"],
         metadata_only_resource_kinds: PM_PACKAGE_RESOURCE_KINDS.filter((resourceKind) => resourceKind !== "extensions"),
-        packages,
+        packages: outputPackages,
     };
 }
+const PACKAGE_CATALOG_FIELD_KEYS = new Set([
+    "alias",
+    "bundled",
+    "available",
+    "installed",
+    "install_target",
+    "install_command",
+    "package_name",
+    "package_version",
+    "description",
+    "keywords",
+    "resources",
+    "installable_resources",
+    "metadata_only_resources",
+    "catalog",
+    "category",
+    "display_name",
+]);
+function parsePackageCatalogFields(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const fields = [...new Set(raw.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0))];
+    if (fields.length === 0) {
+        throw new PmCliError("Package catalog --fields requires a comma-separated list of field names", EXIT_CODE.USAGE);
+    }
+    const unknown = fields.filter((field) => !PACKAGE_CATALOG_FIELD_KEYS.has(field));
+    if (unknown.length > 0) {
+        throw new PmCliError(`Unknown package catalog --fields value(s): ${unknown.join(", ")}`, EXIT_CODE.USAGE, {
+            examples: [
+                "pm package list --project --fields alias,installed,install_command",
+                "pm package catalog --project --fields alias,package_name,category",
+            ],
+        });
+    }
+    return fields;
+}
+function projectPackageCatalogEntry(entry, fields) {
+    const projected = {};
+    for (const field of fields) {
+        if (field === "category") {
+            projected[field] = entry.catalog?.category ?? null;
+        }
+        else if (field === "display_name") {
+            projected[field] = entry.catalog?.display_name ?? null;
+        }
+        else {
+            projected[field] = entry[field] ?? null;
+        }
+    }
+    return projected;
+}
 function parseGithubPathSpec(pathSpec, input, refOverride) {
     const segments = pathSpec
         .split("/")
@@ -843,6 +928,7 @@ async function resolveNpmSourceDirectory(source) {
         const packed = parsePackedNpmPackage(packStdout, packDirectory);
         await execFileAsync("tar", ["-xzf", packed.tarball, "-C", extractDirectory], { encoding: "utf8" });
         const packageRoot = path.join(extractDirectory, "package");
+        await installNpmPackageRuntimeDependencies(packageRoot);
         const directory = await resolvePackageExtensionDirectory(packageRoot, source.input);
         return {
             directory,
@@ -858,6 +944,50 @@ async function resolveNpmSourceDirectory(source) {
         throw error;
     }
 }
+async function installNpmPackageRuntimeDependencies(packageRoot) {
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    if (!(await pathExists(packageJsonPath))) {
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+    }
+    catch {
+        return;
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return;
+    }
+    const manifest = parsed;
+    const dependencySpecs = runtimeDependencyInstallSpecs(manifest);
+    if (dependencySpecs.length === 0) {
+        return;
+    }
+    const runtimeOnlyManifest = { ...parsed };
+    delete runtimeOnlyManifest.devDependencies;
+    await fs.writeFile(packageJsonPath, `${JSON.stringify(runtimeOnlyManifest, null, 2)}\n`, "utf8");
+    await Promise.all([
+        fs.rm(path.join(packageRoot, "package-lock.json"), { force: true }),
+        fs.rm(path.join(packageRoot, "npm-shrinkwrap.json"), { force: true }),
+    ]);
+    await runNpmCommand(["install", "--ignore-scripts", "--no-audit", "--fund=false", "--package-lock=false", "--no-save", ...dependencySpecs], packageRoot);
+}
+function runtimeDependencyInstallSpecs(manifest) {
+    const specs = new Map();
+    for (const dependencyMap of [manifest.dependencies, manifest.optionalDependencies, manifest.peerDependencies]) {
+        if (typeof dependencyMap !== "object" || dependencyMap === null) {
+            continue;
+        }
+        for (const [name, version] of Object.entries(dependencyMap)) {
+            if (typeof version !== "string" || version.trim().length === 0 || specs.has(name)) {
+                continue;
+            }
+            specs.set(name, `${name}@${version.trim()}`);
+        }
+    }
+    return [...specs.values()];
+}
 async function resolvePackageExtensionDirectory(packageRoot, sourceLabel) {
     const discovered = await collectPackageExtensionDirectories(packageRoot);
     if (discovered.length === 1) {
@@ -896,11 +1026,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);
@@ -1319,6 +1452,7 @@ 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",
@@ -1344,10 +1478,63 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
         "};",
         "",
     ].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 \`${vocabulary === "package" ? "pm package init" : "pm extension init"}\`.`,
+        "Generated by `pm extension init`.",
         "",
         "## Included Files",
         "- `manifest.json`: extension metadata and capabilities.",
@@ -1355,9 +1542,9 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
         "",
         "## Quick Start",
         "```bash",
-        `${vocabulary === "package" ? "pm install" : "pm extension --install"} --project <scaffold-path>`,
+        "pm extension --install --project <scaffold-path>",
         `pm ${commandName}`,
-        `${vocabulary === "package" ? "pm package doctor" : "pm extension --doctor"} --project --detail summary`,
+        "pm extension --doctor --project --detail summary",
         "```",
         "",
         "## Notes",
@@ -1391,6 +1578,7 @@ async function scaffoldExtensionProject(target, vocabulary = "extension") {
     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) {
@@ -1689,12 +1877,19 @@ export async function runExtension(target, options, global) {
         ok: true,
         action,
         scope,
-        roots: {
-            project: resolvedRoots.roots.project,
-            global: resolvedRoots.roots.global,
-            selected: resolvedRoots.selected_root,
-            settings_root: resolvedRoots.settings_root,
-        },
+        roots: action === "catalog" && typeof options.fields === "string" && options.fields.trim().length > 0
+            ? {
+                project: "project",
+                global: "global",
+                selected: scope,
+                settings_root: "project",
+            }
+            : {
+                project: resolvedRoots.roots.project,
+                global: resolvedRoots.roots.global,
+                selected: resolvedRoots.selected_root,
+                settings_root: resolvedRoots.settings_root,
+            },
         warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
         details,
     });
@@ -1774,7 +1969,7 @@ export async function runExtension(target, options, global) {
         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));
+        return withResult(await buildBundledPackageCatalog(scope, global, options));
     }
     if (action === "install") {
         const githubOption = resolveGithubOption(options);
@@ -1810,6 +2005,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",
@@ -1832,33 +2028,43 @@ 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 sourceUnchanged = existingManagedEntry !== undefined &&
+                existingManagedEntry.manifest_version === validated.manifest.version &&
+                managedExtensionSourcesEquivalent(existingManagedEntry.source, sourceRecord);
             const managedState = upsertManagedEntry(managedStateRead.state, {
                 name: validated.manifest.name,
                 directory: destinationDirectoryName,
@@ -1867,7 +2073,7 @@ export async function runExtension(target, options, global) {
                 manifest_entry: validated.manifest.entry,
                 capabilities: [...validated.manifest.capabilities],
                 installed_at: existingManagedEntry?.installed_at ?? now,
-                updated_at: now,
+                updated_at: sourceUnchanged ? existingManagedEntry.updated_at : now,
                 source: sourceRecord,
             });
             await writeManagedExtensionState(resolvedRoots.selected_root, managedState);
@@ -2405,4 +2611,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=69ff4814-0641-5d85-962e-a798cfd1a78e