@unbrained/pm-cli 2026.6.22 → 2026.6.24

package/dist/cli-bundle/chunks/{chunk-CLLVBO3I.js → chunk-JPJDP4VU.js}

@@ -6,7 +6,7 @@ import {
   runActiveRendererOverride,
   runActiveServiceOverrideSync,
   setActiveCommandResult
-} from "./chunk-KL5ELX2X.js";
+} from "./chunk-VSAABFGQ.js";
 
 // dist/core/output/mutation-projection.js
 var CHANGED_FIELDS_KEY = "changed_fields";
@@ -334,6 +334,6 @@ export {
   printResult,
   printError
 };
-//# sourceMappingURL=chunk-CLLVBO3I.js.map
+//# sourceMappingURL=chunk-JPJDP4VU.js.map
 
 //# debugId=2f6ea7ca-7f24-526b-ba18-1a10d4a0d3b7

package/dist/cli-bundle/chunks/{chunk-PJS2J7Z4.js → chunk-JV27C7OZ.js}

@@ -1,10 +1,10 @@
 import {
   resolveTypeName
-} from "./chunk-3VLPDG3J.js";
+} from "./chunk-ZV7IQ23N.js";
 import {
   EXIT_CODE,
   PmCliError
-} from "./chunk-RZZMSY4P.js";
+} from "./chunk-EYPINTFR.js";
 
 // dist/cli/shared-parsers.js
 !(function() {
@@ -57,4 +57,4 @@ export {
   parsePriority,
   parseType
 };
-//# sourceMappingURL=chunk-PJS2J7Z4.js.map
+//# sourceMappingURL=chunk-JV27C7OZ.js.map

package/dist/cli-bundle/chunks/{chunk-K25UDYJ4.js → chunk-KIEAK7YE.js}

@@ -3,7 +3,7 @@
 import {
   EXIT_CODE,
   PmCliError
-} from "./chunk-KL5ELX2X.js";
+} from "./chunk-VSAABFGQ.js";
 
 // dist/core/item/parse.js
 var STDIN_TOKEN = "-";
@@ -351,6 +351,6 @@ export {
   createStdinTokenResolver,
   parseOptionalNumber
 };
-//# sourceMappingURL=chunk-K25UDYJ4.js.map
+//# sourceMappingURL=chunk-KIEAK7YE.js.map
 
 //# debugId=41b3db5d-9c78-5ab6-9868-2b31d0e5eac2

package/dist/cli-bundle/chunks/{chunk-GGAXE22C.js → chunk-KJZOSF7J.js}

@@ -3,18 +3,18 @@
 import {
   normalizeItemId,
   normalizeRawItemId
-} from "./chunk-Y4BZEND6.js";
+} from "./chunk-FBLT6WGK.js";
 import {
   canonicalDocument,
   parseItemDocument,
   serializeItemDocument
-} from "./chunk-P7ZU73BO.js";
+} from "./chunk-ZLWRPBOW.js";
 import {
   resolveItemTypeRegistry
-} from "./chunk-KK4TQ3ZP.js";
+} from "./chunk-TKPP4GOO.js";
 import {
   nowIso
-} from "./chunk-PCH2JTEO.js";
+} from "./chunk-FMWW2JDU.js";
 import {
   EMPTY_CANONICAL_DOCUMENT,
   EXIT_CODE,
@@ -44,7 +44,7 @@ import {
   stableStringify,
   toErrorMessage,
   writeFileAtomic
-} from "./chunk-KL5ELX2X.js";
+} from "./chunk-VSAABFGQ.js";
 
 // dist/core/extensions/item-fields.js
 var RESERVED_ITEM_FIELD_NAMES = new Set(FRONT_MATTER_KEY_ORDER);
@@ -1345,6 +1345,6 @@ export {
   mutateItem,
   deleteItem
 };
-//# sourceMappingURL=chunk-GGAXE22C.js.map
+//# sourceMappingURL=chunk-KJZOSF7J.js.map
 
 //# debugId=5960bc7c-dc68-5ab2-b5b1-5d4dda400205

package/dist/cli-bundle/chunks/{chunk-GXBSFKSX.js → chunk-KKX4Z2SE.js}

@@ -2,14 +2,14 @@
 !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]="7919579f-9834-5809-8c55-f7618807569e")}catch(e){}}();
 import {
   verifyHistoryChain
-} from "./chunk-YQSWTVZF.js";
+} from "./chunk-WB5BYQMF.js";
 import {
   hashDocument
-} from "./chunk-GGAXE22C.js";
+} from "./chunk-KJZOSF7J.js";
 import {
   getHistoryPath,
   writeFileAtomic
-} from "./chunk-KL5ELX2X.js";
+} from "./chunk-VSAABFGQ.js";
 
 // dist/core/history/drift-scan.js
 import fs from "fs/promises";
@@ -187,6 +187,6 @@ async function scanHistoryDrift(pmRoot, items, options = {}) {
 export {
   scanHistoryDrift
 };
-//# sourceMappingURL=chunk-GXBSFKSX.js.map
+//# sourceMappingURL=chunk-KKX4Z2SE.js.map
 
 //# debugId=7919579f-9834-5809-8c55-f7618807569e

package/dist/cli-bundle/chunks/{chunk-D35LTIFR.js → chunk-L7UXKP2I.js}

@@ -1,30 +1,32 @@
 
-!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]="5b87215b-bb14-5510-af50-0d572df794ca")}catch(e){}}();
+!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]="528448db-9659-5c81-8819-a5e83880c8fc")}catch(e){}}();
 import {
   scaffoldExtensionProject
-} from "./chunk-3GL6LTUL.js";
+} from "./chunk-NJ73ALW2.js";
 import {
   normalizeExtensionNameForMatch,
   normalizeManagedDirectoryName,
   normalizeStringList,
   parseExtensionManifest,
   validateExtensionDirectory
-} from "./chunk-DMT4ODVN.js";
+} from "./chunk-J3NMWFIN.js";
 import {
   splitCommaList
 } from "./chunk-P4SESZGT.js";
 import {
   nowIso
-} from "./chunk-PCH2JTEO.js";
+} from "./chunk-FMWW2JDU.js";
 import {
   EXIT_CODE,
   EXTENSION_CAPABILITY_CONTRACT,
   KNOWN_EXTENSION_CAPABILITIES,
   PmCliError,
   activateExtensions,
+  collectUsedExtensionCapabilities,
   isPathWithinDirectory,
   loadExtensions,
   nextExtensionReloadToken,
+  normalizeExtensionName,
   parseLegacyExtensionCapabilityAliasWarning,
   parseUnknownExtensionCapabilityWarning,
   pathExists,
@@ -35,7 +37,7 @@ import {
   resolvePmPackageRootFromModule,
   resolvePmRoot,
   writeSettings
-} from "./chunk-KL5ELX2X.js";
+} from "./chunk-VSAABFGQ.js";
 
 // dist/cli/commands/extension.js
 import { execFile as execFile2 } from "node:child_process";
@@ -1156,6 +1158,76 @@ function projectPackageCatalogEntry(entry, fields) {
   return projected;
 }
 
+// dist/core/extensions/activation-summary.js
+var HOOK_REGISTRY_FIELD_TO_KIND = [
+  ["beforeCommand", "before_command"],
+  ["afterCommand", "after_command"],
+  ["onWrite", "on_write"],
+  ["onRead", "on_read"],
+  ["onIndex", "on_index"]
+];
+function describeExtensionActivation(activation, options = {}) {
+  const filter = options.extensionName !== void 0 ? normalizeExtensionName(options.extensionName) : null;
+  const matches = (name) => filter === null || normalizeExtensionName(name) === filter;
+  const collect = (entries, identify) => sortUnique(entries.filter((entry) => matches(entry.name)).map(identify));
+  const collectFlat = (entries, expand) => sortUnique(entries.filter((entry) => matches(entry.name)).flatMap(expand));
+  const { registrations, commands, parsers, preflight, services, renderers, hooks } = activation;
+  return {
+    capabilities: collectUsedExtensionCapabilities(activation, options),
+    commands: collect(registrations.commands, (entry) => entry.command),
+    command_overrides: collect(commands.overrides, (entry) => entry.command),
+    command_handlers: collect(commands.handlers, (entry) => entry.command),
+    hooks: HOOK_REGISTRY_FIELD_TO_KIND.filter(([field]) => hooks[field].some((entry) => matches(entry.name))).map(([, kind]) => kind),
+    flag_commands: collect(registrations.flags, (entry) => entry.target_command),
+    item_types: collectFlat(registrations.item_types, (entry) => entry.types.map((type) => type.name)),
+    item_fields: collectFlat(registrations.item_fields, (entry) => entry.fields.map((field) => field.name)),
+    migrations: collectFlat(registrations.migrations, (entry) => typeof entry.definition.id === "string" ? [entry.definition.id] : []),
+    importers: collect(registrations.importers, (entry) => entry.importer),
+    exporters: collect(registrations.exporters, (entry) => entry.exporter),
+    search_providers: collect(registrations.search_providers, (entry) => entry.definition.name),
+    vector_store_adapters: collect(registrations.vector_store_adapters, (entry) => entry.definition.name),
+    parser_overrides: collect(parsers.overrides, (entry) => entry.command),
+    service_overrides: collect(services.overrides, (entry) => entry.service),
+    renderer_overrides: collect(renderers.overrides, (entry) => entry.format),
+    preflight_overrides: preflight.overrides.filter((entry) => matches(entry.name)).length
+  };
+}
+function sortUnique(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+// dist/cli/commands/extension/describe.js
+function layerNameKey(layer, name) {
+  return `${layer}:${normalizeExtensionNameForMatch(name)}`;
+}
+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 extensions = normalizedTarget === null ? candidates : candidates.filter((entry) => normalizeExtensionNameForMatch(entry.name) === normalizedTarget);
+  return {
+    target: typeof target === "string" ? target.trim() : null,
+    total: extensions.length,
+    extensions,
+    union: describeExtensionActivation(activationResult, normalizedTarget === null ? {} : { extensionName: target })
+  };
+}
+
 // dist/cli/commands/extension/doctor.js
 function applyDoctorRuntimeActivationState(extensions, loadResult, activationResult) {
   const loadedNames = new Set(loadResult.loaded.map((entry) => normalizeExtensionNameForMatch(entry.name)));
@@ -1847,6 +1919,7 @@ function resolveAction(target, options) {
     options.uninstall ? "uninstall" : null,
     options.explore ? "explore" : null,
     options.manage ? "manage" : null,
+    options.describe ? "describe" : null,
     options.reload ? "reload" : null,
     options.doctor ? "doctor" : null,
     options.catalog ? "catalog" : null,
@@ -1882,7 +1955,7 @@ function resolveAction(target, options) {
     if (target === void 0) {
       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);
+    throw new PmCliError("One action flag is required. Use one of: --install, --uninstall, --explore, --manage, --describe, --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);
@@ -2338,9 +2411,14 @@ async function runExtension(target, options, global) {
       created_directory: scaffold.created_directory,
       files: scaffold.files,
       next_steps: [
+        // The scaffold is authored in TypeScript (ADR pm-2c28); the manifest's
+        // ./index.js entry only exists after a compile, so building comes first.
+        ...options.vocabulary === "package" ? [`Build the package: cd ${quotedShellTargetPath}, then run "npm install" and "npm run build"`] : [
+          `Build the extension: cd ${quotedShellTargetPath}, then run "npm install -D typescript @types/node @unbrained/pm-cli" and "npx tsc"`
+        ],
         `Install the scaffold: ${options.vocabulary === "package" ? "pm install --project" : "pm extension --install --project"} ${quotedTargetPath}`,
         `Smoke-test command path: pm ${scaffold.command_name}`,
-        ...options.vocabulary === "package" ? [`Validate the sample test: cd ${quotedShellTargetPath}, then run "npm install" and "npm test"`] : [],
+        ...options.vocabulary === "package" ? [`Validate the sample test: cd ${quotedShellTargetPath}, then run "npm test"`] : [],
         `Run diagnostics: ${options.vocabulary === "package" ? "pm package doctor" : "pm extension --doctor"} --project --detail summary`
       ]
     });
@@ -2922,6 +3000,29 @@ async function runExtension(target, options, global) {
     }
     return withResult(details);
   }
+  if (action === "describe") {
+    const settings = await readSettings(resolvedRoots.settings_root);
+    const loadResult = await loadExtensions({
+      pmRoot: resolvedRoots.pm_root,
+      settings,
+      cwd: process.cwd(),
+      noExtensions: global.noExtensions === true
+    });
+    const activationResult = await activateExtensions(loadResult);
+    warnings.push(...loadResult.warnings);
+    warnings.push(...activationResult.warnings);
+    const describeResult = buildExtensionDescribeResult(normalizedTarget, loadResult, activationResult);
+    if (normalizedTarget !== void 0 && describeResult.extensions.length === 0) {
+      const noun = options.vocabulary === "package" ? "package" : "extension";
+      throw new PmCliError(`No loaded ${noun} named "${normalizedTarget}" was found in ${scope} scope. Run pm ${noun} explore to list discovered ${noun}s.`, EXIT_CODE.NOT_FOUND);
+    }
+    return withResult({
+      target: describeResult.target,
+      total: describeResult.total,
+      extensions: describeResult.extensions,
+      union: describeResult.union
+    });
+  }
   if (action === "explore" || action === "manage") {
     const settings = await readSettings(resolvedRoots.settings_root);
     const configuredPolicy = buildExtensionPolicyDetails(settings.extensions.policy);
@@ -3070,6 +3171,6 @@ export {
   runExtension,
   _testOnly
 };
-//# sourceMappingURL=chunk-D35LTIFR.js.map
+//# sourceMappingURL=chunk-L7UXKP2I.js.map
 
-//# debugId=5b87215b-bb14-5510-af50-0d572df794ca
+//# debugId=528448db-9659-5c81-8819-a5e83880c8fc