@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/extension/bundled-catalog.js

@@ -1,333 +1,2 @@
-/**
- * @module sdk/extension/bundled-catalog
- *
- * Implements extension package-management support for Bundled Catalog.
- */
-
-!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]="259656b0-09b7-52c5-8f54-52ac29eec607")}catch(e){}}();
-import fs from "node:fs/promises";
-import path from "node:path";
-import { collectPackageExtensionDirectories, PM_PACKAGE_RESOURCE_KINDS, readPmPackageManifest, } from "../../core/packages/manifest.js";
-import { resolvePmPackageRootFromModule } from "../../core/packages/root.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 { splitCommaList } from "../../core/shared/split-comma-list.js";
-import { resolveExtensionRoots } from "../../core/extensions/loader.js";
-import { resolvePmRoot } from "../../core/store/paths.js";
-import { validateExtensionDirectory } from "./shared.js";
-import { readManagedExtensionState } from "./managed-state.js";
-const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
-const LEGACY_BUNDLED_PACKAGE_ALIASES = {
-    beads: {
-        package_directory: "pm-beads",
-        legacy_extension_directory: "beads",
-    },
-    todos: {
-        package_directory: "pm-todos",
-        legacy_extension_directory: "todos",
-    },
-};
-const BUNDLED_PACKAGE_INSTALL_ALL_TARGETS = new Set(["*", "all"]);
-function resolvePackageRootCandidates() {
-    const candidates = [];
-    const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
-    /* c8 ignore start -- env-root override branch is exercised by package-root integration tests */
-    if (typeof envRoot === "string" && envRoot.trim().length > 0) {
-        candidates.push(path.resolve(envRoot.trim()));
-    }
-    /* c8 ignore stop */
-    candidates.push(resolvePmPackageRootFromModule(import.meta.url, ["../../.."]));
-    return [...new Set(candidates)];
-}
-/** Implements resolve bundled extension alias source for the public runtime surface of this module. */
-export async function resolveBundledExtensionAliasSource(input) {
-    const normalized = input.trim().toLowerCase();
-    const packageRoot = await resolveBundledPackageRoot(normalized);
-    if (packageRoot) {
-        return packageRoot;
-    }
-    const alias = LEGACY_BUNDLED_PACKAGE_ALIASES[normalized];
-    /* c8 ignore start -- known aliases resolve through package manifests in normal runtime */
-    if (!alias) {
-        return null;
-    }
-    /* c8 ignore stop */
-    /* c8 ignore start -- exercised only when legacy extension paths exist without package manifests */
-    for (const packageRoot of resolvePackageRootCandidates()) {
-        const legacyExtensionPath = path.join(packageRoot, ".agents", "pm", "extensions", alias.legacy_extension_directory);
-        if (await pathExists(path.join(legacyExtensionPath, "manifest.json"))) {
-            return legacyExtensionPath;
-        }
-    }
-    return null;
-    /* c8 ignore stop */
-}
-/** Implements check whether bundled package install all target for the public runtime surface of this module. */
-export function isBundledPackageInstallAllTarget(input) {
-    return BUNDLED_PACKAGE_INSTALL_ALL_TARGETS.has(input.trim().toLowerCase());
-}
-function derivePackageAlias(packageDirectory) {
-    return packageDirectory.replace(/^pm-/i, "").trim().toLowerCase();
-}
-async function collectManifestPackageEntries(packagesRoot, entriesByAlias) {
-    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,
-                package_name: manifest.package_name ?? null,
-            });
-        }
-    }
-}
-async function collectBundledPackageEntries() {
-    const entriesByAlias = new Map();
-    for (const packageRoot of resolvePackageRootCandidates()) {
-        const packagesRoot = path.join(packageRoot, "packages");
-        if (!(await pathExists(packagesRoot))) {
-            continue;
-        }
-        await collectManifestPackageEntries(packagesRoot, entriesByAlias);
-    }
-    for (const [alias, legacy] of Object.entries(LEGACY_BUNDLED_PACKAGE_ALIASES)) {
-        /* c8 ignore start -- canonical aliases are present in bundled package manifests */
-        if (entriesByAlias.has(alias)) {
-            continue;
-        }
-        /* c8 ignore stop */
-        /* c8 ignore start -- compatibility fallback when only legacy package layout exists */
-        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,
-                    package_name: null,
-                });
-                break;
-            }
-        }
-        /* c8 ignore stop */
-    }
-    return [...entriesByAlias.values()].sort((left, right) => left.alias.localeCompare(right.alias));
-}
-/** Implements list bundled package aliases for the public runtime surface of this module. */
-export async function listBundledPackageAliases() {
-    return (await collectBundledPackageEntries()).map((entry) => entry.alias);
-}
-/**
- * Implements resolve bundled package root for the public runtime surface of this module.
- * Accepts every spelling agents naturally reach for: the catalog alias
- * ("kanban"), the package directory ("pm-kanban"), and the published npm name
- * ("@unbrained/pm-kanban").
- */
-export async function resolveBundledPackageRoot(alias) {
-    const normalized = alias.trim().toLowerCase();
-    const entry = (await collectBundledPackageEntries()).find((candidate) => candidate.alias === normalized ||
-        candidate.package_directory.toLowerCase() === normalized ||
-        candidate.package_name?.toLowerCase() === normalized);
-    return entry?.package_root ?? null;
-}
-/** Resolve the published npm package name for a bundled alias so install flows can persist it as managed-source provenance (`source.package`). Returns null when the alias is unknown or the bundled package manifest lacks a name. */
-export async function resolveBundledPackageNpmName(alias) {
-    const packageRoot = await resolveBundledPackageRoot(alias);
-    if (!packageRoot) {
-        return null;
-    }
-    const manifest = await readPmPackageManifest(packageRoot);
-    return manifest.package_name ?? null;
-}
-/** Implements resolve bundled alias manifest name for the public runtime surface of this module. */
-export async function resolveBundledAliasManifestName(input) {
-    const bundledAliasSource = await resolveBundledExtensionAliasSource(input);
-    if (!bundledAliasSource) {
-        return null;
-    }
-    try {
-        const extensionDirectories = await collectPackageExtensionDirectories(bundledAliasSource);
-        if (extensionDirectories.length !== 1) {
-            return null;
-        }
-        const validated = await validateExtensionDirectory(extensionDirectories[0]);
-        return validated.manifest.name;
-    }
-    catch {
-        return null;
-    }
-}
-/** Resolve the catalog link block for a bundled package, preferring the explicit `catalog.links.*` manifest fields and falling back to the package's repository/bugs/homepage/npm metadata. The npm link is synthesized from the package name unless the package is private or unnamed. */
-function buildBundledCatalogLinks(manifest) {
-    return {
-        docs: manifest.catalog?.links?.docs ?? manifest.package_homepage,
-        npm: manifest.catalog?.links?.npm ??
-            (manifest.package_name && manifest.package_private !== true
-                ? `https://www.npmjs.com/package/${encodeURIComponent(manifest.package_name)}`
-                : undefined),
-        repository: manifest.catalog?.links?.repository ?? manifest.package_repository_url,
-        report: manifest.catalog?.links?.report ?? manifest.package_bugs_url,
-    };
-}
-/** Build one bundled-package catalog entry from its manifest, marking it `installed` when the managed state for `scope` already records the package by built-in alias or resolved location, and projecting the metadata-only resource kinds (everything except installable `extensions`) that the package ships. */
-function buildBundledCatalogPackageEntry(manifest, bundledEntry, aliases, scope, installedBuiltinAliases, installedLocations) {
-    const installScopeFlag = scope === "global" ? "--global" : "--project";
-    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));
-    return {
-        alias: bundledEntry.alias,
-        aliases,
-        bundled: true,
-        available: true,
-        installed: aliases.some((alias) => installedBuiltinAliases.has(alias)) ||
-            installedLocations.has(path.resolve(bundledEntry.package_root)),
-        install_target: bundledEntry.alias,
-        install_command: `pm install ${bundledEntry.alias} ${installScopeFlag}`,
-        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: buildBundledCatalogLinks(manifest),
-            media: manifest.catalog?.media,
-        },
-    };
-}
-/** Implements build bundled package catalog for the public runtime surface of this module. */
-export 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 = [];
-    const bundledEntriesByRoot = new Map();
-    for (const entry of await collectBundledPackageEntries()) {
-        const packageRoot = path.resolve(entry.package_root);
-        const groupedEntries = bundledEntriesByRoot.get(packageRoot) ?? [];
-        groupedEntries.push(entry);
-        bundledEntriesByRoot.set(packageRoot, groupedEntries);
-    }
-    for (const bundledEntries of bundledEntriesByRoot.values()) {
-        const bundledEntry = bundledEntries[0];
-        const aliases = bundledEntries
-            .map((entry) => entry.alias)
-            .sort((left, right) => left.localeCompare(right));
-        const manifest = await readPmPackageManifest(bundledEntry.package_root);
-        packages.push(buildBundledCatalogPackageEntry(manifest, bundledEntry, aliases, scope, installedBuiltinAliases, installedLocations));
-    }
-    const fields = parsePackageCatalogFields(options.fields);
-    const outputPackages = fields
-        ? packages.map((entry) => projectPackageCatalogEntry(entry, fields))
-        : packages;
-    return {
-        total: outputPackages.length,
-        scope,
-        installable_resource_kinds: ["extensions"],
-        metadata_only_resource_kinds: PM_PACKAGE_RESOURCE_KINDS.filter((resourceKind) => resourceKind !== "extensions"),
-        packages: outputPackages,
-    };
-}
-const PACKAGE_CATALOG_FIELD_KEYS = new Set([
-    "alias",
-    "aliases",
-    "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 = splitCommaList(raw);
-    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;
-}
-/** Public contract for test only bundled catalog, shared by SDK and presentation-layer consumers. */
-export const _testOnlyBundledCatalog = {
-    parsePackageCatalogFields,
-    projectPackageCatalogEntry,
-};
+!(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]="96c5708d-1f4d-5f94-9945-7f8baa337106")}catch(e2){}})();import fs from"node:fs/promises";import path from"node:path";import{collectPackageExtensionDirectories,PM_PACKAGE_RESOURCE_KINDS,readPmPackageManifest}from"../../core/packages/manifest.js";import{resolvePmPackageRootFromModule}from"../../core/packages/root.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{splitCommaList}from"../../core/shared/split-comma-list.js";import{resolveExtensionRoots}from"../../core/extensions/loader.js";import{resolvePmRoot}from"../../core/store/paths.js";import{validateExtensionDirectory}from"./shared.js";import{readManagedExtensionState}from"./managed-state.js";const PM_PACKAGE_ROOT_ENV="PM_CLI_PACKAGE_ROOT";const LEGACY_BUNDLED_PACKAGE_ALIASES={beads:{package_directory:"pm-beads",legacy_extension_directory:"beads"},todos:{package_directory:"pm-todos",legacy_extension_directory:"todos"}};const BUNDLED_PACKAGE_INSTALL_ALL_TARGETS=new Set(["*","all"]);function resolvePackageRootCandidates(){const candidates=[];const envRoot=process.env[PM_PACKAGE_ROOT_ENV];if(typeof envRoot==="string"&&envRoot.trim().length>0){candidates.push(path.resolve(envRoot.trim()))}candidates.push(resolvePmPackageRootFromModule(import.meta.url,["../../.."]));return[...new Set(candidates)]}async function resolveBundledExtensionAliasSource(input){const normalized=input.trim().toLowerCase();const packageRoot=await resolveBundledPackageRoot(normalized);if(packageRoot){return packageRoot}const alias=LEGACY_BUNDLED_PACKAGE_ALIASES[normalized];if(!alias){return null}for(const packageRoot2 of resolvePackageRootCandidates()){const legacyExtensionPath=path.join(packageRoot2,".agents","pm","extensions",alias.legacy_extension_directory);if(await pathExists(path.join(legacyExtensionPath,"manifest.json"))){return legacyExtensionPath}}return null}function isBundledPackageInstallAllTarget(input){return BUNDLED_PACKAGE_INSTALL_ALL_TARGETS.has(input.trim().toLowerCase())}function derivePackageAlias(packageDirectory){return packageDirectory.replace(/^pm-/i,"").trim().toLowerCase()}async function collectManifestPackageEntries(packagesRoot,entriesByAlias){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,package_name:manifest.package_name??null})}}}async function collectBundledPackageEntries(){const entriesByAlias=new Map;for(const packageRoot of resolvePackageRootCandidates()){const packagesRoot=path.join(packageRoot,"packages");if(!await pathExists(packagesRoot)){continue}await collectManifestPackageEntries(packagesRoot,entriesByAlias)}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,package_name:null});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||candidate.package_directory.toLowerCase()===normalized||candidate.package_name?.toLowerCase()===normalized);return entry?.package_root??null}async function resolveBundledPackageNpmName(alias){const packageRoot=await resolveBundledPackageRoot(alias);if(!packageRoot){return null}const manifest=await readPmPackageManifest(packageRoot);return manifest.package_name??null}async function resolveBundledAliasManifestName(input){const bundledAliasSource=await resolveBundledExtensionAliasSource(input);if(!bundledAliasSource){return null}try{const extensionDirectories=await collectPackageExtensionDirectories(bundledAliasSource);if(extensionDirectories.length!==1){return null}const validated=await validateExtensionDirectory(extensionDirectories[0]);return validated.manifest.name}catch{return null}}function buildBundledCatalogLinks(manifest){return{docs:manifest.catalog?.links?.docs??manifest.package_homepage,npm:manifest.catalog?.links?.npm??(manifest.package_name&&manifest.package_private!==true?`https://www.npmjs.com/package/${encodeURIComponent(manifest.package_name)}`:void 0),repository:manifest.catalog?.links?.repository??manifest.package_repository_url,report:manifest.catalog?.links?.report??manifest.package_bugs_url}}function buildBundledCatalogPackageEntry(manifest,bundledEntry,aliases,scope,installedBuiltinAliases,installedLocations){const installScopeFlag=scope==="global"?"--global":"--project";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));return{alias:bundledEntry.alias,aliases,bundled:true,available:true,installed:aliases.some(alias=>installedBuiltinAliases.has(alias))||installedLocations.has(path.resolve(bundledEntry.package_root)),install_target:bundledEntry.alias,install_command:`pm install ${bundledEntry.alias} ${installScopeFlag}`,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:buildBundledCatalogLinks(manifest),media:manifest.catalog?.media}}}async function buildBundledPackageCatalog(scope,global2,options={}){const roots=resolveExtensionRoots(resolvePmRoot(process.cwd(),global2.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=[];const bundledEntriesByRoot=new Map;for(const entry of await collectBundledPackageEntries()){const packageRoot=path.resolve(entry.package_root);const groupedEntries=bundledEntriesByRoot.get(packageRoot)??[];groupedEntries.push(entry);bundledEntriesByRoot.set(packageRoot,groupedEntries)}for(const bundledEntries of bundledEntriesByRoot.values()){const bundledEntry=bundledEntries[0];const aliases=bundledEntries.map(entry=>entry.alias).sort((left,right)=>left.localeCompare(right));const manifest=await readPmPackageManifest(bundledEntry.package_root);packages.push(buildBundledCatalogPackageEntry(manifest,bundledEntry,aliases,scope,installedBuiltinAliases,installedLocations))}const fields=parsePackageCatalogFields(options.fields);const outputPackages=fields?packages.map(entry=>projectPackageCatalogEntry(entry,fields)):packages;return{total:outputPackages.length,scope,installable_resource_kinds:["extensions"],metadata_only_resource_kinds:PM_PACKAGE_RESOURCE_KINDS.filter(resourceKind=>resourceKind!=="extensions"),packages:outputPackages}}const PACKAGE_CATALOG_FIELD_KEYS=new Set(["alias","aliases","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===void 0){return void 0}const fields=splitCommaList(raw);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}const _testOnlyBundledCatalog={parsePackageCatalogFields,projectPackageCatalogEntry};export{_testOnlyBundledCatalog,buildBundledPackageCatalog,isBundledPackageInstallAllTarget,listBundledPackageAliases,resolveBundledAliasManifestName,resolveBundledExtensionAliasSource,resolveBundledPackageNpmName,resolveBundledPackageRoot};
 //# sourceMappingURL=bundled-catalog.js.map
-//# debugId=259656b0-09b7-52c5-8f54-52ac29eec607

package/dist/sdk/extension/concurrency.js

@@ -1,26 +1,2 @@
-/**
- * @module sdk/extension/concurrency
- *
- * Provides resource-bounded asynchronous collection transforms for extension workflows.
- */
-/** Map inputs with a fixed worker pool so remote checks cannot exhaust process resources. */
-
-!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]="4d3c62e9-9116-5cdc-bbda-48bbd2e39476")}catch(e){}}();
-export const mapWithFixedConcurrency = async (inputs, concurrency, mapper) => {
-    if (!Number.isInteger(concurrency) || concurrency < 1) {
-        throw new RangeError("concurrency must be a positive integer");
-    }
-    const results = new Array(inputs.length);
-    let nextIndex = 0;
-    const workers = Array.from({ length: Math.min(concurrency, inputs.length) }, async () => {
-        while (nextIndex < inputs.length) {
-            const index = nextIndex;
-            nextIndex += 1;
-            results[index] = await mapper(inputs[index]);
-        }
-    });
-    await Promise.all(workers);
-    return results;
-};
+!(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]="96a05fa4-b833-56ca-b501-40a427d03201")}catch(e2){}})();const mapWithFixedConcurrency=async(inputs,concurrency,mapper)=>{if(!Number.isInteger(concurrency)||concurrency<1){throw new RangeError("concurrency must be a positive integer")}const results=new Array(inputs.length);let nextIndex=0;const workers=Array.from({length:Math.min(concurrency,inputs.length)},async()=>{while(nextIndex<inputs.length){const index=nextIndex;nextIndex+=1;results[index]=await mapper(inputs[index])}});await Promise.all(workers);return results};export{mapWithFixedConcurrency};
 //# sourceMappingURL=concurrency.js.map
-//# debugId=4d3c62e9-9116-5cdc-bbda-48bbd2e39476

package/dist/sdk/extension/copy-scope.d.ts

@@ -0,0 +1,2 @@
+/** Decide whether a lexical source path belongs in a nested-destination snapshot. Symlinks remain links. */
+export declare function includesExtensionCopyPath(source: string, destination: string, candidate: string): boolean;

package/dist/sdk/extension/copy-scope.js

@@ -0,0 +1,2 @@
+!(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]="a77d8d8d-f429-5154-ab3a-2caddc44472e")}catch(e2){}})();import path from"node:path";import{isPathWithinDirectory}from"../../core/fs/path-utils.js";function includesExtensionCopyPath(source,destination,candidate){const relative=path.relative(source,candidate);if(relative!==""&&!isPathWithinDirectory(source,candidate))return false;if(candidate===destination||isPathWithinDirectory(destination,candidate))return false;const segments=relative.split(path.sep);return!segments.some(segment=>segment===".agents"||segment==="node_modules"||segment.startsWith(".pm-extension-install-backup-"))}export{includesExtensionCopyPath};
+//# sourceMappingURL=copy-scope.js.map

package/dist/sdk/extension/custom-field-collisions.js

@@ -1,31 +1,2 @@
-/**
- * @module SDK extension diagnostics for custom fields that shadow MCP inputs.
- */
-
-!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]="17145dd7-3938-5f20-b5b5-49f8d38d3d8d")}catch(e){}}();
-import { resolvePmToolCustomFieldCollision } from "../cli-contracts/tool-schema.js";
-/** Report extension and extension-profile fields shadowed by canonical MCP inputs. */
-export const collectMcpCustomFieldCollisionDoctorWarnings = (activationResult) => [
-    ...activationResult.registrations.item_fields.flatMap((registration) => registration.fields.map((field) => ({
-        layer: registration.layer,
-        extension: registration.name,
-        field: field.name,
-    }))),
-    ...activationResult.registrations.profiles.flatMap((registration) => registration.profile.fields.map((field) => ({
-        layer: registration.layer,
-        extension: registration.name,
-        field: field.key ?? "",
-    }))),
-]
-    .flatMap((entry) => {
-    const collision = resolvePmToolCustomFieldCollision(entry.field);
-    return collision
-        ? [
-            `extension_custom_field_mcp_input_collision:${entry.layer}:${entry.extension}:${collision.field}:${collision.property}:${collision.owner}:use=${collision.nested_path}`,
-        ]
-        : [];
-})
-    .filter((warning, index, warnings) => warnings.indexOf(warning) === index)
-    .sort((left, right) => left.localeCompare(right));
+!(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]="a1803149-25ca-5bb0-a178-afa2d85d2ec9")}catch(e2){}})();import{resolvePmToolCustomFieldCollision}from"../cli-contracts/tool-schema.js";const collectMcpCustomFieldCollisionDoctorWarnings=activationResult=>[...activationResult.registrations.item_fields.flatMap(registration=>registration.fields.map(field=>({layer:registration.layer,extension:registration.name,field:field.name}))),...activationResult.registrations.profiles.flatMap(registration=>registration.profile.fields.map(field=>({layer:registration.layer,extension:registration.name,field:field.key??""})))].flatMap(entry=>{const collision=resolvePmToolCustomFieldCollision(entry.field);return collision?[`extension_custom_field_mcp_input_collision:${entry.layer}:${entry.extension}:${collision.field}:${collision.property}:${collision.owner}:use=${collision.nested_path}`]:[]}).filter((warning,index,warnings)=>warnings.indexOf(warning)===index).sort((left,right)=>left.localeCompare(right));export{collectMcpCustomFieldCollisionDoctorWarnings};
 //# sourceMappingURL=custom-field-collisions.js.map
-//# debugId=17145dd7-3938-5f20-b5b5-49f8d38d3d8d

package/dist/sdk/extension/describe.js

@@ -1,190 +1,4 @@
-/**
- * @module sdk/extension/describe
- *
- * Builds the `pm extension describe` / `pm package describe` payload: a flat,
- * by-name map of every surface each loaded extension registered.
- *
- * The SDK already ships {@link describeExtensionActivation} -- the `describe`
- * (enumerate-all) verb that complements the `assert*` (verify-one) and `run*`
- * (invoke-one) testing helpers -- but until now it was reachable only from a test
- * that hand-built an {@link ExtensionActivationResult}. This module is the thin
- * orchestration that lets an agent at the CLI (or over MCP) ask "what does this
- * installed extension add to my context?" in one call, instead of stitching
- * together `doctor` (errors), `manage` (update metadata), and a manifest read.
- *
- * It is intentionally pure: the caller performs the load+activate cycle (exactly
- * as `explore`/`doctor` already do) and hands the results here, so the same
- * builder is trivially unit-testable against synthetic activations.
- */
-
-!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]="536ed530-7726-50ab-bb2d-ace030818f1d")}catch(e){}}();
-import { describeExtensionActivation, } from "../../core/extensions/activation-summary.js";
-import { renderExtensionSurfaceMarkdown } from "../../core/extensions/activation-summary-markdown.js";
-import { normalizeExtensionNameForMatch } from "./shared.js";
-/** Compose a collision-free identity key for an extension from its layer and normalized name. The two parts are joined with a colon; the layer prefix is always a colon-free enum value, so distinct (layer, name) pairs never collide even when a name itself contains a colon. */
-function layerNameKey(layer, name) {
-    return `${layer}:${normalizeExtensionNameForMatch(name)}`;
-}
-function buildExtensionCommandOwnership(activationResult, matchedNames) {
-    const rows = [];
-    for (const [surface, entries] of [
-        ["handler", activationResult.commands.handlers],
-        ["override", activationResult.commands.overrides],
-    ]) {
-        const byCommand = new Map();
-        for (const entry of entries) {
-            const bucket = byCommand.get(entry.command) ?? [];
-            byCommand.set(entry.command, [...bucket, entry]);
-        }
-        for (const [command, claimants] of byCommand) {
-            if (matchedNames !== null &&
-                !claimants.some((entry) => matchedNames.has(normalizeExtensionNameForMatch(entry.name)))) {
-                continue;
-            }
-            const winner = claimants.at(-1);
-            rows.push({
-                command,
-                surface,
-                policy: "last_activated_wins",
-                collision: claimants.length > 1,
-                claimants: claimants.map((entry) => ({
-                    name: entry.name,
-                    layer: entry.layer,
-                    winner: entry === winner,
-                })),
-            });
-        }
-    }
-    return rows.sort((left, right) => left.command.localeCompare(right.command) ||
-        left.surface.localeCompare(right.surface));
-}
-/**
- * Summarize, by name, every registration surface the loaded extensions exercised.
- *
- * Walks `loadResult.loaded` (annotating each with `failed` when its layer+name is
- * in `activationResult.failed`) and `loadResult.failed` (as `not_loaded`), sorts
- * the entries by name then layer for deterministic output, and attaches each
- * extension's {@link describeExtensionActivation} summary. When `target` is
- * provided only the case-insensitively matching extensions are described and the
- * `union` is scoped to that resolved name set; otherwise every loaded extension contributes.
- * A target may name either the extension itself or its source npm package
- * (`source_package`) or any persisted install-source identity (`source_aliases`),
- * so agents can reuse the exact catalog, local, GitHub, or npm spelling passed
- * to install without a second lookup. An unmatched `target` yields an empty
- * `extensions` array -- the caller decides whether that is a not-found error.
- */
-export function buildExtensionDescribeResult(target, loadResult, activationResult) {
-    const activationFailedKeys = new Set(activationResult.failed.map((entry) => layerNameKey(entry.layer, entry.name)));
-    const candidates = [
-        ...loadResult.loaded.map((entry) => ({
-            name: entry.name,
-            layer: entry.layer,
-            version: entry.version,
-            activation_status: activationFailedKeys.has(layerNameKey(entry.layer, entry.name))
-                ? "failed"
-                : "ok",
-            surfaces: describeExtensionActivation(activationResult, {
-                extensionName: entry.name,
-            }),
-        })),
-        ...loadResult.failed.map((entry) => ({
-            name: entry.name,
-            layer: entry.layer,
-            version: "unknown",
-            activation_status: "not_loaded",
-            surfaces: describeExtensionActivation(activationResult, {
-                extensionName: entry.name,
-            }),
-        })),
-    ].sort((left, right) => left.name.localeCompare(right.name) ||
-        left.layer.localeCompare(right.layer));
-    const normalizedTarget = typeof target === "string" ? normalizeExtensionNameForMatch(target) : null;
-    const matchedNames = normalizedTarget === null
-        ? null
-        : new Set(loadResult.loaded
-            .filter((entry) => normalizeExtensionNameForMatch(entry.name) ===
-            normalizedTarget ||
-            (typeof entry.source_package === "string" &&
-                normalizeExtensionNameForMatch(entry.source_package) ===
-                    normalizedTarget) ||
-            (entry.source_aliases ?? []).some((alias) => normalizeExtensionNameForMatch(alias) === normalizedTarget))
-            .map((entry) => normalizeExtensionNameForMatch(entry.name))
-            .concat(normalizedTarget));
-    const extensions = matchedNames === null
-        ? candidates
-        : candidates.filter((entry) => matchedNames.has(normalizeExtensionNameForMatch(entry.name)));
-    const unionOptions = matchedNames === null ? {} : { extensionNames: [...matchedNames] };
-    return {
-        target: typeof target === "string" ? target.trim() : null,
-        total: extensions.length,
-        extensions,
-        union: describeExtensionActivation(activationResult, unionOptions),
-        command_ownership: buildExtensionCommandOwnership(activationResult, matchedNames),
-    };
-}
-/**
- * Human-readable label for each {@link ExtensionDescribeActivationStatus}, used
- * in the Markdown per-extension heading so a reader sees *why* an entry has no
- * surfaces (activation failed / never loaded) rather than assuming it
- * contributes nothing.
- */
-const ACTIVATION_STATUS_LABELS = {
-    ok: "loaded",
-    failed: "activation failed",
-    not_loaded: "not loaded",
-};
-/**
- * Render an {@link ExtensionDescribeResult} as a Markdown reference document: a
- * top-level title and scope line, one section per described extension (titled
- * with its identity and activation status), and — only when more than one
- * extension was described — a final union section spanning them all. Each
- * extension and the union are rendered with the shared
- * {@link renderExtensionSurfaceMarkdown} primitive at heading level 2, so the
- * document nests cleanly under the level-1 title.
- *
- * `noun` is the lifecycle vocabulary (`"extension"` or `"package"`) so the prose
- * matches the command the agent invoked. When no extensions match (an unmatched
- * target is already a not-found error upstream, so this is the "nothing loaded"
- * case) the document is the title plus a single explanatory note.
- */
-export function renderExtensionDescribeMarkdown(result, noun) {
-    const titleNoun = `${noun[0].toUpperCase()}${noun.slice(1)}`;
-    const lines = [`# ${titleNoun} surface reference`, ""];
-    lines.push(result.target === null
-        ? `Scope: all loaded ${noun}s`
-        : `Scope: \`${result.target}\``);
-    lines.push(`Described: ${result.total} ${noun}${result.total === 1 ? "" : "s"}`, "");
-    if ((result.command_ownership?.length ?? 0) > 0) {
-        lines.push("## Command ownership", "");
-        for (const ownership of result.command_ownership) {
-            const winner = ownership.claimants.find((claimant) => claimant.winner);
-            const claimantNames = ownership.claimants
-                .map((claimant) => `${claimant.layer}:${claimant.name}`)
-                .join(", ");
-            lines.push(`- \`${ownership.command}\` (${ownership.surface}): ${winner.layer}:${winner.name}; policy=${ownership.policy}; collision=${String(ownership.collision)}; claimants=${claimantNames}`);
-        }
-        lines.push("");
-    }
-    if (result.extensions.length === 0) {
-        lines.push(`_No ${noun}s are loaded._`, "");
-        return `${lines.join("\n").trimEnd()}\n`;
-    }
-    for (const entry of result.extensions) {
-        const title = `${entry.name} (${entry.layer} v${entry.version}, ${ACTIVATION_STATUS_LABELS[entry.activation_status]})`;
-        // renderExtensionSurfaceMarkdown already ends with a newline; the join adds a
-        // single blank line between sections, so no extra "" separator is pushed.
-        lines.push(renderExtensionSurfaceMarkdown(entry.surfaces, {
-            title,
-            headingLevel: 2,
-        }));
-    }
-    if (result.extensions.length > 1) {
-        lines.push(renderExtensionSurfaceMarkdown(result.union, {
-            title: `Union across all described ${noun}s`,
-            headingLevel: 2,
-        }));
-    }
-    return `${lines.join("\n").trimEnd()}\n`;
-}
+!(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]="6c9e36f8-0f95-5768-8893-bf33bbb4d848")}catch(e2){}})();import{describeExtensionActivation}from"../../core/extensions/activation-summary.js";import{renderExtensionSurfaceMarkdown}from"../../core/extensions/activation-summary-markdown.js";import{normalizeExtensionNameForMatch}from"./shared.js";function layerNameKey(layer,name){return`${layer}:${normalizeExtensionNameForMatch(name)}`}function buildExtensionCommandOwnership(activationResult,matchedNames){const rows=[];for(const[surface,entries]of[["handler",activationResult.commands.handlers],["override",activationResult.commands.overrides]]){const byCommand=new Map;for(const entry of entries){const bucket=byCommand.get(entry.command)??[];byCommand.set(entry.command,[...bucket,entry])}for(const[command,claimants]of byCommand){if(matchedNames!==null&&!claimants.some(entry=>matchedNames.has(normalizeExtensionNameForMatch(entry.name)))){continue}const winner=claimants.at(-1);rows.push({command,surface,policy:"last_activated_wins",collision:claimants.length>1,claimants:claimants.map(entry=>({name:entry.name,layer:entry.layer,winner:entry===winner}))})}}return rows.sort((left,right)=>left.command.localeCompare(right.command)||left.surface.localeCompare(right.surface))}function buildExtensionDescribeResult(target,loadResult,activationResult){const activationFailedKeys=new Set(activationResult.failed.map(entry=>layerNameKey(entry.layer,entry.name)));const candidates=[...loadResult.loaded.map(entry=>({name:entry.name,layer:entry.layer,version:entry.version,activation_status:activationFailedKeys.has(layerNameKey(entry.layer,entry.name))?"failed":"ok",surfaces:describeExtensionActivation(activationResult,{extensionName:entry.name})})),...loadResult.failed.map(entry=>({name:entry.name,layer:entry.layer,version:"unknown",activation_status:"not_loaded",surfaces:describeExtensionActivation(activationResult,{extensionName:entry.name})}))].sort((left,right)=>left.name.localeCompare(right.name)||left.layer.localeCompare(right.layer));const normalizedTarget=typeof target==="string"?normalizeExtensionNameForMatch(target):null;const matchedNames=normalizedTarget===null?null:new Set(loadResult.loaded.filter(entry=>normalizeExtensionNameForMatch(entry.name)===normalizedTarget||typeof entry.source_package==="string"&&normalizeExtensionNameForMatch(entry.source_package)===normalizedTarget||(entry.source_aliases??[]).some(alias=>normalizeExtensionNameForMatch(alias)===normalizedTarget)).map(entry=>normalizeExtensionNameForMatch(entry.name)).concat(normalizedTarget));const extensions=matchedNames===null?candidates:candidates.filter(entry=>matchedNames.has(normalizeExtensionNameForMatch(entry.name)));const unionOptions=matchedNames===null?{}:{extensionNames:[...matchedNames]};return{target:typeof target==="string"?target.trim():null,total:extensions.length,extensions,union:describeExtensionActivation(activationResult,unionOptions),command_ownership:buildExtensionCommandOwnership(activationResult,matchedNames)}}const ACTIVATION_STATUS_LABELS={ok:"loaded",failed:"activation failed",not_loaded:"not loaded"};function renderExtensionDescribeMarkdown(result,noun){const titleNoun=`${noun[0].toUpperCase()}${noun.slice(1)}`;const lines=[`# ${titleNoun} surface reference`,""];lines.push(result.target===null?`Scope: all loaded ${noun}s`:`Scope: \`${result.target}\``);lines.push(`Described: ${result.total} ${noun}${result.total===1?"":"s"}`,"");if((result.command_ownership?.length??0)>0){lines.push("## Command ownership","");for(const ownership of result.command_ownership){const winner=ownership.claimants.find(claimant=>claimant.winner);const claimantNames=ownership.claimants.map(claimant=>`${claimant.layer}:${claimant.name}`).join(", ");lines.push(`- \`${ownership.command}\` (${ownership.surface}): ${winner.layer}:${winner.name}; policy=${ownership.policy}; collision=${String(ownership.collision)}; claimants=${claimantNames}`)}lines.push("")}if(result.extensions.length===0){lines.push(`_No ${noun}s are loaded._`,"");return`${lines.join("\n").trimEnd()}
+`}for(const entry of result.extensions){const title=`${entry.name} (${entry.layer} v${entry.version}, ${ACTIVATION_STATUS_LABELS[entry.activation_status]})`;lines.push(renderExtensionSurfaceMarkdown(entry.surfaces,{title,headingLevel:2}))}if(result.extensions.length>1){lines.push(renderExtensionSurfaceMarkdown(result.union,{title:`Union across all described ${noun}s`,headingLevel:2}))}return`${lines.join("\n").trimEnd()}
+`}export{buildExtensionDescribeResult,renderExtensionDescribeMarkdown};
 //# sourceMappingURL=describe.js.map
-//# debugId=536ed530-7726-50ab-bb2d-ace030818f1d