@unbrained/pm-cli 2026.6.21 → 2026.6.23

package/dist/cli-bundle/chunks/{chunk-32R4PIC6.js → chunk-KQMUV6LX.js}

@@ -1,43 +1,49 @@
 
-!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]="5b1918c3-a3a1-53f2-b547-2724ff2a4f28")}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]="db37d572-333e-53e5-a56d-c59f51332387")}catch(e){}}();
+import {
+  scaffoldExtensionProject
+} from "./chunk-C5AOG6D2.js";
 import {
   normalizeExtensionNameForMatch,
   normalizeManagedDirectoryName,
   normalizeStringList,
   parseExtensionManifest,
   validateExtensionDirectory
-} from "./chunk-SRYYRVPB.js";
+} from "./chunk-4BHT5VDC.js";
 import {
   splitCommaList
 } from "./chunk-P4SESZGT.js";
 import {
   nowIso
-} from "./chunk-NSBZ2CKF.js";
+} from "./chunk-2T3JG6V4.js";
 import {
   EXIT_CODE,
   EXTENSION_CAPABILITY_CONTRACT,
   KNOWN_EXTENSION_CAPABILITIES,
   PmCliError,
   activateExtensions,
+  collectUsedExtensionCapabilities,
   isPathWithinDirectory,
   loadExtensions,
   nextExtensionReloadToken,
+  normalizeExtensionName,
   parseLegacyExtensionCapabilityAliasWarning,
   parseUnknownExtensionCapabilityWarning,
   pathExists,
   readSettings,
+  reconcileExtensionCapabilityUsage,
   resolveExtensionRoots,
   resolveGlobalPmRoot,
   resolvePmPackageRootFromModule,
   resolvePmRoot,
   writeSettings
-} from "./chunk-434HM6Z5.js";
+} from "./chunk-UELRKQQU.js";
 
 // dist/cli/commands/extension.js
 import { execFile as execFile2 } from "node:child_process";
-import fs6 from "node:fs/promises";
+import fs5 from "node:fs/promises";
 import os2 from "node:os";
-import path6 from "node:path";
+import path5 from "node:path";
 import { promisify as promisify2 } from "node:util";
 
 // dist/cli/commands/extension/managed-state.js
@@ -1152,228 +1158,73 @@ function projectPackageCatalogEntry(entry, fields) {
   return projected;
 }
 
-// dist/cli/commands/extension/scaffold.js
-import fs5 from "node:fs/promises";
-import path5 from "node:path";
-var SCAFFOLD_MANIFEST_VERSION = 1;
-var SCAFFOLD_PM_MIN_VERSION = "2026.5.0";
-function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary) {
-  const packageName = `pm-${extensionName}`;
-  const manifest = `${JSON.stringify({
-    name: extensionName,
-    version: "0.1.0",
-    entry: "./index.js",
-    capabilities: ["commands"],
-    manifest_version: SCAFFOLD_MANIFEST_VERSION,
-    pm_min_version: SCAFFOLD_PM_MIN_VERSION
-  }, null, 2)}
-`;
-  const entrypoint = [
-    '/** @param {import("@unbrained/pm-cli/sdk").ExtensionApi} api */',
-    "export function activate(api) {",
-    "  api.registerCommand({",
-    `    name: ${JSON.stringify(commandName)},`,
-    '    description: "Starter scaffold command. Replace with your own behavior.",',
-    "    run: async (context) => ({",
-    "      ok: true,",
-    `      source: ${JSON.stringify(extensionName)},`,
-    "      command: context.command,",
-    '      message: "Starter extension scaffold is active.",',
-    "    }),",
-    "  });",
-    "}",
-    "",
-    "export default {",
-    "  activate,",
-    "};",
-    ""
-  ].join("\n");
-  if (vocabulary === "package") {
-    const packageJson = `${JSON.stringify({
-      name: packageName,
-      version: "0.1.0",
-      private: true,
-      type: "module",
-      keywords: ["pm-package"],
-      // `node --test` runs the colocated *.test.js sample against the peer SDK
-      // testing helpers; no extra dev-dependency or test runner is required.
-      scripts: {
-        test: "node --test"
-      },
-      peerDependencies: {
-        "@unbrained/pm-cli": "*"
-      },
-      pm: {
-        aliases: [extensionName],
-        extensions: ["."],
-        docs: ["README.md"],
-        examples: ["README.md"],
-        catalog: {
-          display_name: extensionName,
-          category: "workflow",
-          summary: "Starter pm package scaffold.",
-          tags: ["starter"]
-        }
-      }
-    }, null, 2)}
-`;
-    const sampleTest = [
-      'import assert from "node:assert/strict";',
-      'import { test } from "node:test";',
-      'import { activateExtensionForTest, assertRegisteredCommandContract } from "@unbrained/pm-cli/sdk/testing";',
-      'import extension from "./index.js";',
-      "",
-      `test(${JSON.stringify(`${extensionName} registers its starter command`)}, async () => {`,
-      "  // `capabilities` mirrors manifest.json so the in-memory activation grants",
-      "  // the `commands` capability the entrypoint relies on.",
-      "  const activation = await activateExtensionForTest(extension, {",
-      `    name: ${JSON.stringify(extensionName)},`,
-      '    capabilities: ["commands"],',
-      "  });",
-      "  // assertRegisteredCommandContract throws if the command is not",
-      "  // registered, so reaching here already proves the wiring; assert on the",
-      "  // returned definition to demonstrate inspecting registered metadata.",
-      "  const registered = assertRegisteredCommandContract(activation.registrations, {",
-      `    command: ${JSON.stringify(commandName)},`,
-      `    extensionName: ${JSON.stringify(extensionName)},`,
-      "  });",
-      '  assert.equal(typeof registered.command.description, "string");',
-      "});",
-      ""
-    ].join("\n");
-    const gitignore = ["node_modules/", "*.log", ""].join("\n");
-    const packageReadme = [
-      `# ${packageName}`,
-      "",
-      "Generated by `pm package init`.",
-      "",
-      "## Included Files",
-      "- `package.json`: package metadata, `test` script, and `pm` resource manifest.",
-      "- `manifest.json`: extension metadata and capabilities.",
-      "- `index.js`: starter command registration using the `commands` capability.",
-      "- `index.test.js`: sample `node:test` suite using the SDK testing helpers.",
-      "- `.gitignore`: ignores `node_modules/` and log files.",
-      "",
-      "## Quick Start",
-      "```bash",
-      "pm install --project <package-path>",
-      `pm ${commandName}`,
-      "pm package doctor --project --detail summary",
-      "```",
-      "",
-      "## Validate the Package",
-      "Install the peer SDK once, then run the colocated sample test:",
-      "```bash",
-      "npm install",
-      "npm test",
-      "```",
-      "`npm test` runs `node --test`, which executes `index.test.js` against the",
-      "`@unbrained/pm-cli/sdk/testing` helpers \u2014 no extra test runner required.",
-      "",
-      "## Compatibility Bounds",
-      "`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:",
-      `- \`manifest_version\` (integer): manifest schema generation. Leave at \`${SCAFFOLD_MANIFEST_VERSION}\` unless you adopt a newer manifest schema.`,
-      `- \`pm_min_version\` (string): lowest pm CLI version that may load this package. Scaffolded as \`${SCAFFOLD_PM_MIN_VERSION}\`. The loader blocks the package on older CLIs.`,
-      "- `pm_max_version` (string, optional): highest pm CLI version that may load this package. Add it to block CLIs that are newer than the version you have validated against. The loader blocks the package when the CLI exceeds this bound.",
-      "",
-      "## Notes",
-      "- Keep simple starter runtime behavior at the package root so local installs work without dependency bootstrapping.",
-      "- Move larger runtimes into subdirectories only after adding package dependencies and validating `pm package doctor`.",
-      "- 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,
-      "manifest.json": manifest,
-      "index.js": entrypoint,
-      "index.test.js": sampleTest,
-      ".gitignore": gitignore,
-      "README.md": packageReadme
-    };
-  }
-  const readme = [
-    `# ${extensionName}`,
-    "",
-    "Generated by `pm extension init`.",
-    "",
-    "## Included Files",
-    "- `manifest.json`: extension metadata and capabilities.",
-    "- `index.js`: starter command registration using the `commands` capability.",
-    "",
-    "## Quick Start",
-    "```bash",
-    "pm extension --install --project <scaffold-path>",
-    `pm ${commandName}`,
-    "pm extension --doctor --project --detail summary",
-    "```",
-    "",
-    "## Compatibility Bounds",
-    "`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:",
-    `- \`manifest_version\` (integer): manifest schema generation. Leave at \`${SCAFFOLD_MANIFEST_VERSION}\` unless you adopt a newer manifest schema.`,
-    `- \`pm_min_version\` (string): lowest pm CLI version that may load this extension. Scaffolded as \`${SCAFFOLD_PM_MIN_VERSION}\`. The loader blocks the extension on older CLIs.`,
-    "- `pm_max_version` (string, optional): highest pm CLI version that may load this extension. Add it to block CLIs that are newer than the version you have validated against. The loader blocks the extension when the CLI exceeds this bound.",
-    "",
-    "## Notes",
-    "- This scaffold uses ESM exports so it works in package scopes with `type: module`.",
-    "- Update `manifest.json` capabilities and `index.js` command behavior as your extension evolves.",
-    ""
-  ].join("\n");
+// 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 {
-    "manifest.json": manifest,
-    "index.js": entrypoint,
-    "README.md": readme
+    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
   };
 }
-async function scaffoldExtensionProject(target, vocabulary = "extension") {
-  const normalizedTarget = target.trim();
-  const targetPath = path5.resolve(process.cwd(), normalizedTarget);
-  const extensionName = normalizeManagedDirectoryName(path5.basename(targetPath));
-  const commandName = `${extensionName} ping`;
-  const scaffoldFiles = buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary);
-  let createdDirectory = false;
-  if (await pathExists(targetPath)) {
-    const existingTargetStats = await fs5.stat(targetPath);
-    if (!existingTargetStats.isDirectory()) {
-      throw new PmCliError(`Scaffold target "${targetPath}" exists and is not a directory.`, EXIT_CODE.CONFLICT);
-    }
-  } else {
-    await fs5.mkdir(targetPath, { recursive: true });
-    createdDirectory = true;
-  }
-  for (const [relativePath, content] of Object.entries(scaffoldFiles)) {
-    const absolutePath = path5.join(targetPath, relativePath);
-    if (!await pathExists(absolutePath)) {
-      continue;
-    }
-    const existingContent = await fs5.readFile(absolutePath, "utf8");
-    if (existingContent !== content) {
-      throw new PmCliError(`Scaffold file "${relativePath}" already exists with different content in "${targetPath}". Choose a new target path or remove conflicting files.`, EXIT_CODE.CONFLICT);
-    }
-  }
-  const files = [];
-  for (const [relativePath, content] of Object.entries(scaffoldFiles)) {
-    const absolutePath = path5.join(targetPath, relativePath);
-    if (await pathExists(absolutePath)) {
-      files.push({
-        path: relativePath,
-        status: "unchanged"
-      });
-      continue;
-    }
-    await fs5.mkdir(path5.dirname(absolutePath), { recursive: true });
-    await fs5.writeFile(absolutePath, content, "utf8");
-    files.push({
-      path: relativePath,
-      status: "created"
-    });
-  }
+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 {
-    extension_name: extensionName,
-    command_name: commandName,
-    target_path: targetPath,
-    created_directory: createdDirectory,
-    files
+    target: typeof target === "string" ? target.trim() : null,
+    total: extensions.length,
+    extensions,
+    union: describeExtensionActivation(activationResult, normalizedTarget === null ? {} : { extensionName: target })
   };
 }
 
@@ -1621,6 +1472,15 @@ function classifyDoctorActivationFailureWarnings(activationFailures = []) {
   }
   return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
 }
+function classifyUnusedCapabilityWarnings(loadResult, activationResult) {
+  const warnings = [];
+  for (const entry of reconcileExtensionCapabilityUsage(loadResult.loaded, activationResult)) {
+    for (const capability of entry.unused) {
+      warnings.push(`extension_capability_unused:${entry.layer}:${entry.name}:${capability}`);
+    }
+  }
+  return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
+}
 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;
@@ -1671,6 +1531,9 @@ function buildExtensionTriageSummary(scope, warnings, extensions, options = {})
     if (normalizedWarnings.some((warning) => warning.startsWith("extension_capability_missing:"))) {
       remediation.push(`Extension activation failed because code registered a surface missing from manifest capabilities. Run ${lifecycleFlagCommand(options, "doctor")} ${scopeFlag} --detail deep --trace and add the reported missing_capability to manifest.json before publishing.`);
     }
+    if (normalizedWarnings.some((warning) => warning.startsWith("extension_capability_unused:"))) {
+      remediation.push(`Extension manifests declare capabilities that are never registered against. Remove each reported unused capability from manifest.json to keep least privilege, or add the matching registration. Run ${lifecycleFlagCommand(options, "doctor")} ${scopeFlag} --detail deep --trace for per-extension registration counts.`);
+    }
     if (normalizedWarnings.some((warning) => warning.startsWith("extension_command_definition_legacy_handler_alias:"))) {
       remediation.push("Extension command definitions using legacy handler were auto-remapped. Update command definitions to use run: (context) => ... for forward compatibility.");
     }
@@ -1905,11 +1768,11 @@ function sleep(ms) {
     setTimeout(resolve, ms);
   });
 }
-async function copyExtensionDirectoryForInstall(sourceDirectory, destinationDirectory, copyDirectory = fs6.cp) {
+async function copyExtensionDirectoryForInstall(sourceDirectory, destinationDirectory, copyDirectory = fs5.cp) {
   for (let attempt = 1; attempt <= EXTENSION_INSTALL_COPY_ATTEMPTS; attempt += 1) {
     try {
       if (await pathExists(destinationDirectory)) {
-        await fs6.rm(destinationDirectory, { recursive: true, force: true });
+        await fs5.rm(destinationDirectory, { recursive: true, force: true });
       }
       await copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destinationDirectory, copyDirectory);
       return;
@@ -1922,8 +1785,8 @@ async function copyExtensionDirectoryForInstall(sourceDirectory, destinationDire
   }
 }
 async function copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destinationDirectory, copyDirectory) {
-  const resolvedSource = path6.resolve(sourceDirectory);
-  const resolvedDestination = path6.resolve(destinationDirectory);
+  const resolvedSource = path5.resolve(sourceDirectory);
+  const resolvedDestination = path5.resolve(destinationDirectory);
   if (resolvedSource === resolvedDestination) {
     return;
   }
@@ -1931,28 +1794,28 @@ async function copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destina
     await copyDirectory(sourceDirectory, destinationDirectory, { recursive: true, force: true });
     return;
   }
-  const stagingRoot = await fs6.mkdtemp(path6.join(os2.tmpdir(), "pm-extension-copy-"));
-  const stagedDirectory = path6.join(stagingRoot, "extension");
+  const stagingRoot = await fs5.mkdtemp(path5.join(os2.tmpdir(), "pm-extension-copy-"));
+  const stagedDirectory = path5.join(stagingRoot, "extension");
   try {
     await copyDirectory(sourceDirectory, stagedDirectory, { recursive: true, force: true });
     await copyDirectory(stagedDirectory, destinationDirectory, { recursive: true, force: true });
   } finally {
-    await fs6.rm(stagingRoot, { recursive: true, force: true });
+    await fs5.rm(stagingRoot, { recursive: true, force: true });
   }
 }
 async function withExtensionInstallLock(settingsRoot, destinationDirectoryName, run, options) {
-  const lockRoot = path6.join(settingsRoot, "runtime", "extension-install-locks");
-  const lockPath = path6.join(lockRoot, `${destinationDirectoryName}.lock`);
-  await fs6.mkdir(lockRoot, { recursive: true });
+  const lockRoot = path5.join(settingsRoot, "runtime", "extension-install-locks");
+  const lockPath = path5.join(lockRoot, `${destinationDirectoryName}.lock`);
+  await fs5.mkdir(lockRoot, { recursive: true });
   const attempts = Math.max(1, Math.floor(options?.attempts ?? EXTENSION_INSTALL_LOCK_ATTEMPTS));
   const delayMs = Math.max(0, Math.floor(options?.delay_ms ?? EXTENSION_INSTALL_LOCK_DELAY_MS));
   const staleMs = Math.max(0, Math.floor(options?.stale_ms ?? EXTENSION_INSTALL_LOCK_STALE_MS));
   let acquired = false;
   for (let attempt = 1; attempt <= attempts; attempt += 1) {
     try {
-      await fs6.mkdir(lockPath);
+      await fs5.mkdir(lockPath);
       acquired = true;
-      await fs6.writeFile(path6.join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, created_at: nowIso(), destination: destinationDirectoryName }, null, 2)}
+      await fs5.writeFile(path5.join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, created_at: nowIso(), destination: destinationDirectoryName }, null, 2)}
 `, "utf8");
       break;
     } catch (error) {
@@ -1961,12 +1824,12 @@ async function withExtensionInstallLock(settingsRoot, destinationDirectoryName,
       }
       let stat = null;
       try {
-        stat = await fs6.stat(lockPath);
+        stat = await fs5.stat(lockPath);
       } catch {
         stat = null;
       }
       if (stat && Date.now() - stat.mtimeMs > staleMs) {
-        await fs6.rm(lockPath, { recursive: true, force: true });
+        await fs5.rm(lockPath, { recursive: true, force: true });
         continue;
       }
       await sleep(delayMs);
@@ -1978,7 +1841,7 @@ async function withExtensionInstallLock(settingsRoot, destinationDirectoryName,
   try {
     return await run();
   } finally {
-    await fs6.rm(lockPath, { recursive: true, force: true }).catch(() => void 0);
+    await fs5.rm(lockPath, { recursive: true, force: true }).catch(() => void 0);
   }
 }
 async function resolveInstalledExtensionCandidate(installed, extensionTarget) {
@@ -2056,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,
@@ -2091,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);
@@ -2156,7 +2020,7 @@ async function listInstalledExtensions(extensionsRoot, scope, settings, state) {
       warnings: []
     };
   }
-  const entries = await fs6.readdir(extensionsRoot, { withFileTypes: true });
+  const entries = await fs5.readdir(extensionsRoot, { withFileTypes: true });
   const directories = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
   const managedByName = /* @__PURE__ */ new Map();
   const managedByDirectory = /* @__PURE__ */ new Map();
@@ -2167,8 +2031,8 @@ async function listInstalledExtensions(extensionsRoot, scope, settings, state) {
   const warnings = [];
   const summaries = [];
   for (const directoryName of directories) {
-    const extensionDirectory = path6.join(extensionsRoot, directoryName);
-    const manifestPath = path6.join(extensionDirectory, "manifest.json");
+    const extensionDirectory = path5.join(extensionsRoot, directoryName);
+    const manifestPath = path5.join(extensionDirectory, "manifest.json");
     if (!await pathExists(manifestPath)) {
       warnings.push(`extension_manifest_missing:${scope}:${directoryName}`);
       const managedEntry2 = managedByDirectory.get(normalizeExtensionNameForMatch(directoryName));
@@ -2197,7 +2061,7 @@ async function listInstalledExtensions(extensionsRoot, scope, settings, state) {
     }
     let rawManifest;
     try {
-      rawManifest = JSON.parse(await fs6.readFile(manifestPath, "utf8"));
+      rawManifest = JSON.parse(await fs5.readFile(manifestPath, "utf8"));
     } catch {
       warnings.push(`extension_manifest_invalid_json:${scope}:${directoryName}`);
       continue;
@@ -2374,7 +2238,7 @@ async function adoptUnmanagedExtensions(extensionsRoot, scope, installedExtensio
   let nextState = state;
   const adoptedEntries = [];
   for (const candidate of sortedCandidates) {
-    const extensionDirectory = path6.join(extensionsRoot, candidate.directory);
+    const extensionDirectory = path5.join(extensionsRoot, candidate.directory);
     const validated = await validateExtensionDirectory(extensionDirectory);
     const now = nowIso();
     const sourceRecord = {
@@ -2476,6 +2340,9 @@ async function runExtension(target, options, global) {
   if (options.fixManagedState === true && action !== "manage" && action !== "doctor") {
     throw new PmCliError("--fix-managed-state is only valid with --manage or --doctor.", EXIT_CODE.USAGE);
   }
+  if (options.capability !== void 0 && action !== "init") {
+    throw new PmCliError("--capability is only valid with --init/--scaffold.", EXIT_CODE.USAGE);
+  }
   const normalizedTarget = (() => {
     const normalizedInput = target?.trim().toLowerCase();
     if (action === "doctor" && normalizedInput === "doctor") {
@@ -2530,7 +2397,7 @@ 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, options.vocabulary ?? "extension");
+    const scaffold = await scaffoldExtensionProject(scaffoldTarget, options.vocabulary ?? "extension", options.capability);
     const quotedTargetPath = JSON.stringify(scaffold.target_path);
     const quotedShellTargetPath = JSON.stringify(scaffold.target_path.replace(/\\/g, "/"));
     return withResult({
@@ -2539,6 +2406,7 @@ async function runExtension(target, options, global) {
         name: scaffold.extension_name,
         command: scaffold.command_name
       },
+      capability: scaffold.capability,
       target_path: scaffold.target_path,
       created_directory: scaffold.created_directory,
       files: scaffold.files,
@@ -2655,10 +2523,10 @@ async function runExtension(target, options, global) {
         const settings = await readSettings(resolvedRoots.settings_root);
         const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
         warnings.push(...managedStateRead.warnings);
-        const destinationDirectory = path6.join(resolvedRoots.selected_root, destinationDirectoryName);
+        const destinationDirectory = path5.join(resolvedRoots.selected_root, destinationDirectoryName);
         const destinationExists = await pathExists(destinationDirectory);
         const installInPlace = await areDirectoriesEquivalent(validated.directory, destinationDirectory);
-        await fs6.mkdir(resolvedRoots.selected_root, { recursive: true });
+        await fs5.mkdir(resolvedRoots.selected_root, { recursive: true });
         if (!installInPlace) {
           await copyExtensionDirectoryForInstall(validated.directory, destinationDirectory);
         }
@@ -2805,7 +2673,7 @@ async function runExtension(target, options, global) {
         }
       });
     }
-    const extensionDirectory = path6.join(resolvedRoots.selected_root, candidate.directory);
+    const extensionDirectory = path5.join(resolvedRoots.selected_root, candidate.directory);
     const validated = await validateExtensionDirectory(extensionDirectory);
     const now = nowIso();
     const sourceRecord = githubOption === void 0 ? {
@@ -2870,8 +2738,8 @@ async function runExtension(target, options, global) {
     if (!candidate) {
       throw new PmCliError(`Installed extension "${extensionTarget}" was not found in ${scope} scope.`, EXIT_CODE.NOT_FOUND);
     }
-    const destinationDirectory = path6.join(resolvedRoots.selected_root, candidate.directory);
-    await fs6.rm(destinationDirectory, { recursive: true, force: true });
+    const destinationDirectory = path5.join(resolvedRoots.selected_root, candidate.directory);
+    await fs5.rm(destinationDirectory, { recursive: true, force: true });
     const updatedState = {
       ...managedStateRead.state,
       updated_at: nowIso(),
@@ -2957,6 +2825,7 @@ async function runExtension(target, options, global) {
     warnings.push(...classifyDoctorLoadFailureWarnings(loadResult.failed));
     warnings.push(...activationResult.warnings);
     warnings.push(...classifyDoctorActivationFailureWarnings(activationResult.failed));
+    warnings.push(...classifyUnusedCapabilityWarnings(loadResult, activationResult));
     warnings.push(...collectGlobalOutputOverrideDoctorWarnings(activationResult));
     const runtimeInstalledExtensions = applyDoctorRuntimeActivationState(refreshedInstalled.extensions, loadResult, activationResult);
     const doctorConsistency = buildDoctorConsistencySummary(scope, runtimeInstalledExtensions, loadResult.loaded.map((entry) => ({ layer: entry.layer, name: entry.name })), loadResult.failed.map((entry) => ({ name: entry.name })), loadResult.disabled_by_flag);
@@ -3126,6 +2995,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);
@@ -3274,6 +3166,6 @@ export {
   runExtension,
   _testOnly
 };
-//# sourceMappingURL=chunk-32R4PIC6.js.map
+//# sourceMappingURL=chunk-KQMUV6LX.js.map
 
-//# debugId=5b1918c3-a3a1-53f2-b547-2724ff2a4f28
+//# debugId=db37d572-333e-53e5-a56d-c59f51332387