@unbrained/pm-cli 2026.6.22 → 2026.6.23

package/dist/cli/commands/extension/describe.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module cli/commands/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.
+ */
+import { type ExtensionActivationSummary } from "../../../core/extensions/activation-summary.js";
+import type { ExtensionActivationResult, ExtensionLayer, ExtensionLoadResult } from "../../../core/extensions/loader.js";
+/**
+ * Runtime state of a described extension. `ok` loaded and activated cleanly,
+ * `failed` loaded but threw during `activate`, and `not_loaded` failed to import
+ * at all -- the latter two register nothing, so their `surfaces` are empty and
+ * the status explains why (rather than implying the extension contributes
+ * nothing).
+ */
+export type ExtensionDescribeActivationStatus = "ok" | "failed" | "not_loaded";
+/**
+ * One extension's contribution to the workspace: its identity plus the
+ * {@link ExtensionActivationSummary} of every surface it registered.
+ *
+ * `surfaces` is matched by extension *name* (mirroring
+ * {@link describeExtensionActivation}'s name filter), so when the same name is
+ * loaded in both the project and global layers each entry reflects that name's
+ * combined surfaces -- the `layer`/`version` fields still distinguish the
+ * physical entries.
+ */
+export interface ExtensionSurfaceDescription {
+    name: string;
+    layer: ExtensionLayer;
+    version: string;
+    activation_status: ExtensionDescribeActivationStatus;
+    surfaces: ExtensionActivationSummary;
+}
+/**
+ * Result of {@link buildExtensionDescribeResult}: the per-extension surface maps
+ * plus a deduplicated `union` across the described set. `target` echoes the
+ * requested name filter (or `null` for the whole workspace) and `total` counts
+ * the described entries so callers need not re-measure `extensions`.
+ */
+export interface ExtensionDescribeResult {
+    target: string | null;
+    total: number;
+    extensions: ExtensionSurfaceDescription[];
+    union: ExtensionActivationSummary;
+}
+/**
+ * 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 name; otherwise every loaded extension contributes.
+ * An unmatched `target` yields an empty `extensions` array -- the caller decides
+ * whether that is a not-found error.
+ */
+export declare function buildExtensionDescribeResult(target: string | undefined, loadResult: ExtensionLoadResult, activationResult: ExtensionActivationResult): ExtensionDescribeResult;

package/dist/cli/commands/extension/describe.js

@@ -0,0 +1,76 @@
+/**
+ * @module cli/commands/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]="7a92163a-99b2-5969-acc2-e2b6b0336c2e")}catch(e){}}();
+import { describeExtensionActivation } from "../../../core/extensions/activation-summary.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)}`;
+}
+/**
+ * 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 name; otherwise every loaded extension contributes.
+ * 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 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 }),
+    };
+}
+//# sourceMappingURL=describe.js.map
+//# debugId=7a92163a-99b2-5969-acc2-e2b6b0336c2e

package/dist/cli/commands/extension/describe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.js","sources":["cli/commands/extension/describe.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/extension/describe\n *\n * Builds the `pm extension describe` / `pm package describe` payload: a flat,\n * by-name map of every surface each loaded extension registered.\n *\n * The SDK already ships {@link describeExtensionActivation} -- the `describe`\n * (enumerate-all) verb that complements the `assert*` (verify-one) and `run*`\n * (invoke-one) testing helpers -- but until now it was reachable only from a test\n * that hand-built an {@link ExtensionActivationResult}. This module is the thin\n * orchestration that lets an agent at the CLI (or over MCP) ask \"what does this\n * installed extension add to my context?\" in one call, instead of stitching\n * together `doctor` (errors), `manage` (update metadata), and a manifest read.\n *\n * It is intentionally pure: the caller performs the load+activate cycle (exactly\n * as `explore`/`doctor` already do) and hands the results here, so the same\n * builder is trivially unit-testable against synthetic activations.\n */\nimport { describeExtensionActivation, type ExtensionActivationSummary } from \"../../../core/extensions/activation-summary.js\";\nimport type { ExtensionActivationResult, ExtensionLayer, ExtensionLoadResult } from \"../../../core/extensions/loader.js\";\nimport { normalizeExtensionNameForMatch } from \"./shared.js\";\n\n/**\n * Runtime state of a described extension. `ok` loaded and activated cleanly,\n * `failed` loaded but threw during `activate`, and `not_loaded` failed to import\n * at all -- the latter two register nothing, so their `surfaces` are empty and\n * the status explains why (rather than implying the extension contributes\n * nothing).\n */\nexport type ExtensionDescribeActivationStatus = \"ok\" | \"failed\" | \"not_loaded\";\n\n/**\n * One extension's contribution to the workspace: its identity plus the\n * {@link ExtensionActivationSummary} of every surface it registered.\n *\n * `surfaces` is matched by extension *name* (mirroring\n * {@link describeExtensionActivation}'s name filter), so when the same name is\n * loaded in both the project and global layers each entry reflects that name's\n * combined surfaces -- the `layer`/`version` fields still distinguish the\n * physical entries.\n */\nexport interface ExtensionSurfaceDescription {\n  name: string;\n  layer: ExtensionLayer;\n  version: string;\n  activation_status: ExtensionDescribeActivationStatus;\n  surfaces: ExtensionActivationSummary;\n}\n\n/**\n * Result of {@link buildExtensionDescribeResult}: the per-extension surface maps\n * plus a deduplicated `union` across the described set. `target` echoes the\n * requested name filter (or `null` for the whole workspace) and `total` counts\n * the described entries so callers need not re-measure `extensions`.\n */\nexport interface ExtensionDescribeResult {\n  target: string | null;\n  total: number;\n  extensions: ExtensionSurfaceDescription[];\n  union: ExtensionActivationSummary;\n}\n\n/**\n * Compose a collision-free identity key for an extension from its layer and\n * normalized name. The two parts are joined with a colon; the layer prefix is\n * always a colon-free enum value, so distinct (layer, name) pairs never collide\n * even when a name itself contains a colon.\n */\nfunction layerNameKey(layer: ExtensionLayer, name: string): string {\n  return `${layer}:${normalizeExtensionNameForMatch(name)}`;\n}\n\n/**\n * Summarize, by name, every registration surface the loaded extensions exercised.\n *\n * Walks `loadResult.loaded` (annotating each with `failed` when its layer+name is\n * in `activationResult.failed`) and `loadResult.failed` (as `not_loaded`), sorts\n * the entries by name then layer for deterministic output, and attaches each\n * extension's {@link describeExtensionActivation} summary. When `target` is\n * provided only the case-insensitively matching extensions are described and the\n * `union` is scoped to that name; otherwise every loaded extension contributes.\n * An unmatched `target` yields an empty `extensions` array -- the caller decides\n * whether that is a not-found error.\n */\nexport function buildExtensionDescribeResult(\n  target: string | undefined,\n  loadResult: ExtensionLoadResult,\n  activationResult: ExtensionActivationResult,\n): ExtensionDescribeResult {\n  const activationFailedKeys = new Set(activationResult.failed.map((entry) => layerNameKey(entry.layer, entry.name)));\n  const candidates: ExtensionSurfaceDescription[] = [\n    ...loadResult.loaded.map((entry) => ({\n      name: entry.name,\n      layer: entry.layer,\n      version: entry.version,\n      activation_status: activationFailedKeys.has(layerNameKey(entry.layer, entry.name))\n        ? (\"failed\" as const)\n        : (\"ok\" as const),\n      surfaces: describeExtensionActivation(activationResult, { extensionName: entry.name }),\n    })),\n    ...loadResult.failed.map((entry) => ({\n      name: entry.name,\n      layer: entry.layer,\n      version: \"unknown\",\n      activation_status: \"not_loaded\" as const,\n      surfaces: describeExtensionActivation(activationResult, { extensionName: entry.name }),\n    })),\n  ].sort((left, right) => left.name.localeCompare(right.name) || left.layer.localeCompare(right.layer));\n\n  const normalizedTarget = typeof target === \"string\" ? normalizeExtensionNameForMatch(target) : null;\n  const extensions =\n    normalizedTarget === null\n      ? candidates\n      : candidates.filter((entry) => normalizeExtensionNameForMatch(entry.name) === normalizedTarget);\n\n  return {\n    target: typeof target === \"string\" ? target.trim() : null,\n    total: extensions.length,\n    extensions,\n    union: describeExtensionActivation(activationResult, normalizedTarget === null ? {} : { extensionName: target }),\n  };\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AACH,OAAO,EAAE,2BAA2B,EAAmC,MAAM,gDAAgD,CAAC;AAE9H,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AA0C7D;;;;;GAKG;AACH,SAAS,YAAY,CAAC,KAAqB,EAAE,IAAY;IACvD,OAAO,GAAG,KAAK,IAAI,8BAA8B,CAAC,IAAI,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAA0B,EAC1B,UAA+B,EAC/B,gBAA2C;IAE3C,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpH,MAAM,UAAU,GAAkC;QAChD,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACnC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,iBAAiB,EAAE,oBAAoB,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;gBAChF,CAAC,CAAE,QAAkB;gBACrB,CAAC,CAAE,IAAc;YACnB,QAAQ,EAAE,2BAA2B,CAAC,gBAAgB,EAAE,EAAE,aAAa,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;SACvF,CAAC,CAAC;QACH,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACnC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,OAAO,EAAE,SAAS;YAClB,iBAAiB,EAAE,YAAqB;YACxC,QAAQ,EAAE,2BAA2B,CAAC,gBAAgB,EAAE,EAAE,aAAa,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;SACvF,CAAC,CAAC;KACJ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAEtG,MAAM,gBAAgB,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,8BAA8B,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpG,MAAM,UAAU,GACd,gBAAgB,KAAK,IAAI;QACvB,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,8BAA8B,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,gBAAgB,CAAC,CAAC;IAEpG,OAAO;QACL,MAAM,EAAE,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI;QACzD,KAAK,EAAE,UAAU,CAAC,MAAM;QACxB,UAAU;QACV,KAAK,EAAE,2BAA2B,CAAC,gBAAgB,EAAE,gBAAgB,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;KACjH,CAAC;AACJ,CAAC","debugId":"7a92163a-99b2-5969-acc2-e2b6b0336c2e"}

package/dist/cli/commands/extension/scaffold.js

@@ -4,7 +4,7 @@
  * Implements extension package-management support for Scaffold.
  */
 
-!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]="61e2eb79-305a-5636-b5ca-ab0c6aa4afcc")}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]="4513e1ea-24a5-55b1-9465-78d5d9febba7")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists } from "../../../core/fs/fs-utils.js";
@@ -525,6 +525,45 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
         const sampleTest = buildSampleTestSource(extensionName, commandName, capability);
         const sampleTestBullet = SAMPLE_TEST_BULLETS[capability];
         const gitignore = ["node_modules/", "*.log", ""].join("\n");
+        const searchProviderName = `${extensionName}-search`;
+        const vectorAdapterName = `${extensionName}-vector`;
+        const adapterName = `${extensionName.replace(/-/g, " ")} items`;
+        const defineBuilderImports = [
+            "defineCommand",
+            ...(capability === "hooks" ? ["defineAfterCommandHook"] : []),
+            ...(capability === "search" ? ["defineSearchProvider", "defineVectorStoreAdapter"] : []),
+            ...(capability === "importers" ? ["defineImporter", "defineExporter"] : []),
+        ].join(", ");
+        const defineBuilderSnippet = [
+            "```js",
+            `import { ${defineBuilderImports} } from "@unbrained/pm-cli/sdk";`,
+            "",
+            "export const pingCommand = defineCommand({",
+            `  name: ${JSON.stringify(commandName)},`,
+            '  description: "Starter scaffold command. Replace with your own behavior.",',
+            "  run: (context) => ({ ok: true, command: context.command }),",
+            "});",
+        ];
+        if (capability === "hooks") {
+            defineBuilderSnippet.push("", "export const afterCommandHook = defineAfterCommandHook((context) => {", "  if (!context.ok) return;", "  // React to context.affected here as your package grows.", "});");
+        }
+        if (capability === "search") {
+            defineBuilderSnippet.push("", "export const searchProvider = defineSearchProvider({", `  name: ${JSON.stringify(searchProviderName)},`, "  query: async (context) => ({", "    hits: context.documents", "      .filter((document) => String(document.metadata.title ?? \"\").toLowerCase().includes(context.query.toLowerCase()))", "      .map((document) => ({ id: document.metadata.id, score: 1, matched_fields: [\"title\"] })),", "  }),", "  embed: async (context) => [context.input.length],", "});", "", "export const vectorStoreAdapter = defineVectorStoreAdapter({", `  name: ${JSON.stringify(vectorAdapterName)},`, "  query: async (context) => [{ id: \"starter-vector-hit\", score: context.limit }],", "  upsert: async (context) => ({ upserted: context.points.length }),", "  delete: async (context) => ({ deleted: context.ids.length }),", "});");
+        }
+        if (capability === "importers") {
+            defineBuilderSnippet.push("", "export const importer = defineImporter(async (context) => ({", "  imported: 1,", "  source: context.options.source ?? \"starter\",", "  args: context.args,", "}));", "", "export const exporter = defineExporter(async (context) => ({", "  exported: true,", "  destination: context.options.destination ?? \"stdout\",", "  args: context.args,", "}));");
+        }
+        defineBuilderSnippet.push("", "export function activate(api) {", "  api.registerCommand(pingCommand);");
+        if (capability === "hooks") {
+            defineBuilderSnippet.push("  api.hooks.afterCommand(afterCommandHook);");
+        }
+        if (capability === "search") {
+            defineBuilderSnippet.push("  api.registerSearchProvider(searchProvider);", "  api.registerVectorStoreAdapter(vectorStoreAdapter);");
+        }
+        if (capability === "importers") {
+            defineBuilderSnippet.push(`  api.registerImporter(${JSON.stringify(adapterName)}, importer, {`, `    action: ${JSON.stringify(`${adapterName} import`)},`, '    description: "Import starter records into pm context.",', "    flags: [", "      {", '        long: "--source",', '        value_name: "name",', '        value_type: "string",', '        description: "Source name or path to import from.",', "      },", "    ],", "  });", `  api.registerExporter(${JSON.stringify(adapterName)}, exporter, {`, `    action: ${JSON.stringify(`${adapterName} export`)},`, '    description: "Export pm context into starter records.",', "    flags: [", "      {", '        long: "--destination",', '        value_name: "name",', '        value_type: "string",', '        description: "Destination name or path to export to.",', "      },", "    ],", "  });");
+        }
+        defineBuilderSnippet.push("}", "", "export function deactivate() {}", "", "export default { activate, deactivate };", "```");
         const packageReadme = [
             `# ${packageName}`,
             "",
@@ -552,6 +591,15 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
             "```",
             "`npm test` runs `node --test`, which executes `index.test.js` against the",
             "`@unbrained/pm-cli/sdk/testing` helpers - no extra test runner required.",
+            "",
+            "## Authoring With define* Builders",
+            "`index.js` stays import-free so the package can be installed locally before",
+            "`npm install` materializes peer dependencies. After installing dependencies,",
+            "use the public SDK authoring builders for exported definitions you want",
+            "editor type-checking, contextual handler inference, and direct unit tests for:",
+            ...defineBuilderSnippet,
+            "The builders return their argument unchanged; runtime validation still lives",
+            "in `api.register*`, and behavior validation lives in `sdk/testing`.",
             ...PACKAGE_CAPABILITY_README_SECTIONS[capability],
             "",
             "## Compatibility Bounds",
@@ -682,4 +730,4 @@ export async function scaffoldExtensionProject(target, vocabulary = "extension",
     };
 }
 //# sourceMappingURL=scaffold.js.map
-//# debugId=61e2eb79-305a-5636-b5ca-ab0c6aa4afcc
+//# debugId=4513e1ea-24a5-55b1-9465-78d5d9febba7

package/dist/cli/commands/extension/scaffold.js.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.js","sources":["cli/commands/extension/scaffold.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/extension/scaffold\n *\n * Implements extension package-management support for Scaffold.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { pathExists } from \"../../../core/fs/fs-utils.js\";\nimport { EXIT_CODE } from \"../../../core/shared/constants.js\";\nimport { PmCliError } from \"../../../core/shared/errors.js\";\nimport { normalizeManagedDirectoryName } from \"./shared.js\";\n\n// Safe compatibility floor emitted into scaffolded manifests. Mirrors the\n// first-party package manifests (pm-nf2q): every current 2026.5.x CLI\n// satisfies it, and it models the field for external authors. manifest_version\n// tracks the manifest schema generation (currently 1).\nconst SCAFFOLD_MANIFEST_VERSION = 1;\nconst SCAFFOLD_PM_MIN_VERSION = \"2026.5.0\";\nconst SCAFFOLD_DECLARED_PERMISSIONS = {\n  fs_read: false,\n  fs_write: false,\n  network: false,\n  env_read: false,\n  env_write: false,\n  process_spawn: false,\n};\n\n/**\n * Capability shapes the package/extension scaffolder can target via the\n * `--capability` selector. `commands` emits the default command-only starter;\n * `hooks` additionally wires an `after_command` lifecycle reactor, `search`\n * wires an in-memory provider/adapter pair, and `importers` wires importer and\n * exporter command primitives so authors can customize project context movement\n * without starting from a blank extension.\n */\nexport const SCAFFOLD_CAPABILITIES = [\"commands\", \"hooks\", \"search\", \"importers\"] as const;\n\n/**\n * Restricts the `--capability` selector to a {@link SCAFFOLD_CAPABILITIES} value.\n */\nexport type ExtensionScaffoldCapability = (typeof SCAFFOLD_CAPABILITIES)[number];\n\nconst SCAFFOLD_MANIFEST_CAPABILITIES: Record<ExtensionScaffoldCapability, readonly string[]> = {\n  commands: [\"commands\"],\n  hooks: [\"commands\", \"hooks\"],\n  search: [\"commands\", \"search\"],\n  importers: [\"commands\", \"schema\", \"importers\"],\n};\n\nconst SAMPLE_TEST_CAPABILITIES_LITERAL: Record<ExtensionScaffoldCapability, string> = {\n  commands: '[\"commands\"]',\n  hooks: '[\"commands\", \"hooks\"]',\n  search: '[\"commands\", \"search\"]',\n  importers: '[\"commands\", \"schema\", \"importers\"]',\n};\n\nconst ENTRYPOINT_BULLETS: Record<ExtensionScaffoldCapability, string> = {\n  commands: \"- `index.js`: starter command registration plus a `deactivate` teardown stub.\",\n  hooks:\n    \"- `index.js`: starter command registration, an `after_command` lifecycle hook, and a `deactivate` teardown stub.\",\n  search:\n    \"- `index.js`: starter command registration, a search provider, a vector-store adapter, and a `deactivate` teardown stub.\",\n  importers:\n    \"- `index.js`: starter command registration, importer/exporter command registrations, and a `deactivate` teardown stub.\",\n};\n\nconst SAMPLE_TEST_BULLETS: Record<ExtensionScaffoldCapability, string> = {\n  commands:\n    \"- `index.test.js`: sample `node:test` suite covering activation, command invocation, and teardown via the SDK testing helpers.\",\n  hooks:\n    \"- `index.test.js`: sample `node:test` suite covering activation, command invocation, the after_command hook, and teardown via the SDK testing helpers.\",\n  search:\n    \"- `index.test.js`: sample `node:test` suite covering activation, command invocation, search provider/vector adapter invocation, and teardown via the SDK testing helpers.\",\n  importers:\n    \"- `index.test.js`: sample `node:test` suite covering activation, command invocation, importer/exporter invocation, and teardown via the SDK testing helpers.\",\n};\n\nconst PACKAGE_CAPABILITY_README_SECTIONS: Record<ExtensionScaffoldCapability, readonly string[]> = {\n  commands: [],\n  hooks: [\n    \"\",\n    \"## Lifecycle Hook\",\n    \"`index.js` registers an `after_command` hook via `api.hooks.afterCommand`.\",\n    \"pm fires it once a command finishes, passing the command outcome and the\",\n    \"items it mutated (`context.affected`). React there to keep external context\",\n    \"in sync - sync records, emit telemetry, or refresh derived state. The\",\n    \"`hooks` capability in `manifest.json` is what grants the hook registration;\",\n    \"remove it (and the hook) if your package only needs commands.\",\n  ],\n  search: [\n    \"\",\n    \"## Search Provider\",\n    \"`index.js` registers a deterministic in-memory search provider and\",\n    \"vector-store adapter through `api.registerSearchProvider` and\",\n    \"`api.registerVectorStoreAdapter`. Replace the sample scoring,\",\n    \"embedding, and storage behavior with your project-specific retrieval\",\n    \"logic. The `search` capability in `manifest.json` grants both\",\n    \"registrations.\",\n  ],\n  importers: [\n    \"\",\n    \"## Importer and Exporter\",\n    \"`index.js` registers paired project-context import/export commands through\",\n    \"`api.registerImporter` and `api.registerExporter`. Replace the starter\",\n    \"payloads with your domain adapter: GitHub issues, CSV rows, documents,\",\n    \"tickets, or another project-management source of truth. The `importers`\",\n    \"capability grants both registrations, and `schema` grants the example\",\n    \"command flag metadata.\",\n  ],\n};\n\nconst EXTENSION_CAPABILITY_README_SECTIONS: Record<ExtensionScaffoldCapability, readonly string[]> = {\n  commands: [],\n  hooks: [\n    \"\",\n    \"## Lifecycle Hook\",\n    \"`index.js` registers an `after_command` hook via `api.hooks.afterCommand`.\",\n    \"pm fires it once a command finishes, passing the command outcome and the\",\n    \"items it mutated (`context.affected`). React there to keep external context\",\n    \"in sync. The `hooks` capability in `manifest.json` grants the registration;\",\n    \"remove it (and the hook) if your extension only needs commands.\",\n  ],\n  search: [\n    \"\",\n    \"## Search Provider\",\n    \"`index.js` registers a deterministic in-memory search provider and\",\n    \"vector-store adapter through `api.registerSearchProvider` and\",\n    \"`api.registerVectorStoreAdapter`. Replace the sample scoring, embedding,\",\n    \"and storage behavior with your project-specific retrieval logic. The\",\n    \"`search` capability in `manifest.json` grants both registrations.\",\n  ],\n  importers: [\n    \"\",\n    \"## Importer and Exporter\",\n    \"`index.js` registers paired project-context import/export commands through\",\n    \"`api.registerImporter` and `api.registerExporter`. Replace the starter\",\n    \"payloads with your domain adapter. The `importers` capability grants both\",\n    \"registrations, and `schema` grants the example command flag metadata.\",\n  ],\n};\n\ninterface ExtensionScaffoldFileResult {\n  path: string;\n  status: \"created\" | \"unchanged\";\n}\n\ninterface ExtensionScaffoldResult {\n  extension_name: string;\n  command_name: string;\n  capability: ExtensionScaffoldCapability;\n  target_path: string;\n  created_directory: boolean;\n  files: ExtensionScaffoldFileResult[];\n}\n\n/**\n * Build the `activate` body lines for the starter entrypoint. The base body\n * always registers the starter command; capability-specific variants append\n * the matching SDK surface so generated packages demonstrate one runnable\n * customization primitive end to end.\n */\nfunction buildActivateBodyLines(\n  extensionName: string,\n  commandName: string,\n  capability: ExtensionScaffoldCapability,\n): string[] {\n  const searchProviderName = `${extensionName}-search`;\n  const vectorAdapterName = `${extensionName}-vector`;\n  const adapterName = `${extensionName.replace(/-/g, \" \")} items`;\n  const commandLines = [\n    \"  api.registerCommand({\",\n    `    name: ${JSON.stringify(commandName)},`,\n    '    description: \"Starter scaffold command. Replace with your own behavior.\",',\n    \"    run: async (context) => ({\",\n    \"      ok: true,\",\n    `      source: ${JSON.stringify(extensionName)},`,\n    \"      command: context.command,\",\n    '      message: \"Starter extension scaffold is active.\",',\n    \"    }),\",\n    \"  });\",\n  ];\n  if (capability === \"commands\") {\n    return commandLines;\n  }\n  if (capability === \"search\") {\n    return [\n      ...commandLines,\n      \"\",\n      \"  // Search providers let packages customize how pm ranks and retrieves\",\n      \"  // project context. This starter is deterministic and dependency-free:\",\n      \"  // replace the scoring with your domain retrieval, embedding, or rerank\",\n      \"  // logic as the package grows.\",\n      \"  api.registerSearchProvider({\",\n      `    name: ${JSON.stringify(searchProviderName)},`,\n      \"    query: async (context) => {\",\n      \"      const needle = context.query.toLowerCase();\",\n      \"      const hits = context.documents\",\n      \"        .filter((document) => {\",\n      \"          const title = String(document.metadata.title ?? \\\"\\\").toLowerCase();\",\n      \"          return title.includes(needle);\",\n      \"        })\",\n      \"        .map((document) => ({\",\n      \"          id: document.metadata.id,\",\n      \"          score: 1,\",\n      '          matched_fields: [\"title\"],',\n      \"        }));\",\n      \"      return { hits };\",\n      \"    },\",\n      \"    embed: async (context) => [context.input.length],\",\n      \"  });\",\n      \"\",\n      \"  // Vector-store adapters let packages own semantic index storage. This\",\n      \"  // starter returns a stable in-memory hit so generated tests can exercise\",\n      \"  // the adapter without external services.\",\n      \"  api.registerVectorStoreAdapter({\",\n      `    name: ${JSON.stringify(vectorAdapterName)},`,\n      \"    query: async (context) => [{ id: \\\"starter-vector-hit\\\", score: context.limit }],\",\n      \"    upsert: async (context) => ({ upserted: context.points.length }),\",\n      \"    delete: async (context) => ({ deleted: context.ids.length }),\",\n      \"  });\",\n    ];\n  }\n  if (capability === \"importers\") {\n    return [\n      ...commandLines,\n      \"\",\n      \"  // Importers/exporters are the bridge between pm's context graph and\",\n      \"  // another project-management system. Keep the starter deterministic so\",\n      \"  // package tests can run without touching the network or filesystem; replace\",\n      \"  // these payloads with your adapter's real mapping as the package grows.\",\n      \"  api.registerImporter(\",\n      `    ${JSON.stringify(adapterName)},`,\n      \"    async (context) => ({\",\n      \"      imported: 1,\",\n      \"      source: context.options.source ?? \\\"starter\\\",\",\n      \"      args: context.args,\",\n      \"    }),\",\n      \"    {\",\n      `      action: ${JSON.stringify(`${adapterName} import`)},`,\n      '      description: \"Import starter records into pm context.\",',\n      \"      flags: [\",\n      \"        {\",\n      '          long: \"--source\",',\n      '          value_name: \"name\",',\n      '          value_type: \"string\",',\n      '          description: \"Source name or path to import from.\",',\n      \"        },\",\n      \"      ],\",\n      \"    },\",\n      \"  );\",\n      \"\",\n      \"  api.registerExporter(\",\n      `    ${JSON.stringify(adapterName)},`,\n      \"    async (context) => ({\",\n      \"      exported: true,\",\n      \"      destination: context.options.destination ?? \\\"stdout\\\",\",\n      \"      args: context.args,\",\n      \"    }),\",\n      \"    {\",\n      `      action: ${JSON.stringify(`${adapterName} export`)},`,\n      '      description: \"Export pm context into starter records.\",',\n      \"      flags: [\",\n      \"        {\",\n      '          long: \"--destination\",',\n      '          value_name: \"name\",',\n      '          value_type: \"string\",',\n      '          description: \"Destination name or path to export to.\",',\n      \"        },\",\n      \"      ],\",\n      \"    },\",\n      \"  );\",\n    ];\n  }\n  return [\n    ...commandLines,\n    \"\",\n    \"  // after_command hooks fire once pm finishes a command, receiving the items\",\n    \"  // it mutated. This is the natural place to react to every change - sync to\",\n    \"  // an external system, emit telemetry, or refresh derived context\",\n    '  // (\"project management = context management\"). This starter is a documented',\n    \"  // no-op on the success path; replace the body with your own reaction.\",\n    \"  api.hooks.afterCommand((context) => {\",\n    \"    if (!context.ok) {\",\n    \"      return;\",\n    \"    }\",\n    \"    // `context.affected` lists the items pm mutated (id, status,\",\n    \"    // changed_fields). React here, e.g.:\",\n    \"    //   for (const item of context.affected ?? []) { /* ...item.id... */ }\",\n    \"  });\",\n  ];\n}\n\n/**\n * Build the colocated `node:test` sample suite for the chosen capability. Every\n * variant covers activation, command invocation, and teardown via the SDK\n * testing helpers; the `hooks` variant adds a test that asserts the\n * `after_command` hook is registered and fires cleanly through the public SDK\n * testing helper `runRegisteredHookForTest`.\n */\nfunction buildSampleTestSource(\n  extensionName: string,\n  commandName: string,\n  capability: ExtensionScaffoldCapability,\n): string {\n  const hooksEnabled = capability === \"hooks\";\n  const searchEnabled = capability === \"search\";\n  const importersEnabled = capability === \"importers\";\n  const capabilitiesLiteral = SAMPLE_TEST_CAPABILITIES_LITERAL[capability];\n  const searchProviderName = `${extensionName}-search`;\n  const vectorAdapterName = `${extensionName}-vector`;\n  const adapterName = `${extensionName.replace(/-/g, \" \")} items`;\n  const importNames = [\n    \"  activateExtensionForTest,\",\n    \"  assertExtensionDeactivated,\",\n    \"  assertRegisteredCommandContract,\",\n    ...(hooksEnabled ? [\"  assertRegisteredHook,\"] : []),\n    ...(searchEnabled ? [\"  assertRegisteredSearchProvider,\", \"  assertRegisteredVectorStoreAdapter,\"] : []),\n    ...(importersEnabled ? [\"  assertRegisteredImporter,\", \"  assertRegisteredExporter,\"] : []),\n    \"  deactivateExtensionForTest,\",\n    \"  runRegisteredCommandForTest,\",\n    ...(hooksEnabled ? [\"  runRegisteredHookForTest,\"] : []),\n    ...(searchEnabled ? [\"  runRegisteredSearchProviderForTest,\", \"  runRegisteredVectorStoreAdapterForTest,\"] : []),\n    ...(importersEnabled ? [\"  runRegisteredImporterForTest,\", \"  runRegisteredExporterForTest,\"] : []),\n  ];\n  const hookTestLines = hooksEnabled\n    ? [\n        `test(${JSON.stringify(`${extensionName} reacts to commands via its after_command hook`)}, async () => {`,\n        \"  const activation = await activateExtensionForTest(extension, {\",\n        `    name: ${JSON.stringify(extensionName)},`,\n        `    capabilities: ${capabilitiesLiteral},`,\n        \"  });\",\n        \"  // assertRegisteredHook throws unless an after_command hook is registered,\",\n        \"  // so reaching the next line already proves the hook is wired.\",\n        \"  assertRegisteredHook(activation.hooks, {\",\n        '    kind: \"after_command\",',\n        `    extensionName: ${JSON.stringify(extensionName)},`,\n        \"  });\",\n        \"  // runRegisteredHookForTest fires the hook through pm's real runner with a\",\n        \"  // synthetic context and returns the warnings it produced; a clean hook\",\n        \"  // returns none. Replace the context/assertions as your hook grows.\",\n        \"  const warnings = await runRegisteredHookForTest(activation.hooks, {\",\n        '    kind: \"after_command\",',\n        \"    context: {\",\n        `      command: ${JSON.stringify(commandName)},`,\n        \"      args: [],\",\n        '      pm_root: \"\",',\n        \"      ok: true,\",\n        \"      affected: [],\",\n        \"    },\",\n        \"  });\",\n        \"  assert.deepEqual(warnings, []);\",\n        \"});\",\n        \"\",\n      ]\n    : [];\n  const searchTestLines = searchEnabled\n    ? [\n        `test(${JSON.stringify(`${extensionName} registers and invokes search primitives`)}, async () => {`,\n        \"  const activation = await activateExtensionForTest(extension, {\",\n        `    name: ${JSON.stringify(extensionName)},`,\n        `    capabilities: ${capabilitiesLiteral},`,\n        \"  });\",\n        \"  assertRegisteredSearchProvider(activation.registrations, {\",\n        `    provider: ${JSON.stringify(searchProviderName)},`,\n        `    extensionName: ${JSON.stringify(extensionName)},`,\n        \"  });\",\n        \"  assertRegisteredVectorStoreAdapter(activation.registrations, {\",\n        `    adapter: ${JSON.stringify(vectorAdapterName)},`,\n        `    extensionName: ${JSON.stringify(extensionName)},`,\n        \"  });\",\n        \"\",\n        \"  const query = await runRegisteredSearchProviderForTest(activation.registrations, {\",\n        `    provider: ${JSON.stringify(searchProviderName)},`,\n        '    operation: \"query\",',\n        \"    context: {\",\n        '      query: \"sync\",',\n        '      mode: \"semantic\",',\n        '      tokens: [\"sync\"],',\n        \"      options: {},\",\n        \"      settings: {},\",\n        \"      documents: [\",\n        '        { metadata: { id: \"pm-1\", title: \"Sync external context\" }, body: \"\" },',\n        '        { metadata: { id: \"pm-2\", title: \"Unrelated task\" }, body: \"\" },',\n        \"      ],\",\n        \"    },\",\n        \"  });\",\n        '  assert.deepEqual(query, { hits: [{ id: \"pm-1\", score: 1, matched_fields: [\"title\"] }] });',\n        \"\",\n        \"  const embedding = await runRegisteredSearchProviderForTest(activation.registrations, {\",\n        `    provider: ${JSON.stringify(searchProviderName)},`,\n        '    operation: \"embed\",',\n        '    context: { input: \"abc\", settings: {}, model: \"starter-model\" },',\n        \"  });\",\n        \"  assert.deepEqual(embedding, [3]);\",\n        \"\",\n        \"  const vectorHits = await runRegisteredVectorStoreAdapterForTest(activation.registrations, {\",\n        `    adapter: ${JSON.stringify(vectorAdapterName)},`,\n        '    operation: \"query\",',\n        \"    context: { vector: [0.1, 0.2], limit: 2, settings: {} },\",\n        \"  });\",\n        '  assert.deepEqual(vectorHits, [{ id: \"starter-vector-hit\", score: 2 }]);',\n        \"});\",\n        \"\",\n      ]\n    : [];\n  const importerTestLines = importersEnabled\n    ? [\n        `test(${JSON.stringify(`${extensionName} registers and invokes import/export primitives`)}, async () => {`,\n        \"  const activation = await activateExtensionForTest(extension, {\",\n        `    name: ${JSON.stringify(extensionName)},`,\n        `    capabilities: ${capabilitiesLiteral},`,\n        \"  });\",\n        \"  assertRegisteredImporter(activation.registrations, {\",\n        `    importer: ${JSON.stringify(adapterName)},`,\n        `    extensionName: ${JSON.stringify(extensionName)},`,\n        \"  });\",\n        \"  assertRegisteredExporter(activation.registrations, {\",\n        `    exporter: ${JSON.stringify(adapterName)},`,\n        `    extensionName: ${JSON.stringify(extensionName)},`,\n        \"  });\",\n        \"\",\n        \"  const imported = await runRegisteredImporterForTest(activation, {\",\n        `    importer: ${JSON.stringify(adapterName)},`,\n        '    options: { source: \"tickets\" },',\n        '    args: [\"batch-1\"],',\n        \"  });\",\n        \"  assert.equal(imported.handled, true);\",\n        '  assert.deepEqual(imported.result, { imported: 1, source: \"tickets\", args: [\"batch-1\"] });',\n        \"\",\n        \"  const exported = await runRegisteredExporterForTest(activation, {\",\n        `    exporter: ${JSON.stringify(adapterName)},`,\n        '    options: { destination: \"archive\" },',\n        '    args: [\"done\"],',\n        \"  });\",\n        \"  assert.equal(exported.handled, true);\",\n        '  assert.deepEqual(exported.result, { exported: true, destination: \"archive\", args: [\"done\"] });',\n        \"});\",\n        \"\",\n      ]\n    : [];\n  return [\n    'import assert from \"node:assert/strict\";',\n    'import { test } from \"node:test\";',\n    \"import {\",\n    ...importNames,\n    '} from \"@unbrained/pm-cli/sdk/testing\";',\n    'import extension from \"./index.js\";',\n    \"\",\n    `test(${JSON.stringify(`${extensionName} registers its starter command`)}, async () => {`,\n    \"  // `capabilities` mirrors manifest.json so the in-memory activation grants\",\n    \"  // the capabilities the entrypoint relies on.\",\n    \"  const activation = await activateExtensionForTest(extension, {\",\n    `    name: ${JSON.stringify(extensionName)},`,\n    `    capabilities: ${capabilitiesLiteral},`,\n    \"  });\",\n    \"  // assertRegisteredCommandContract throws if the command is not\",\n    \"  // registered, so reaching here already proves the wiring; assert on the\",\n    \"  // returned definition to demonstrate inspecting registered metadata.\",\n    \"  const registered = assertRegisteredCommandContract(activation.registrations, {\",\n    `    command: ${JSON.stringify(commandName)},`,\n    `    extensionName: ${JSON.stringify(extensionName)},`,\n    \"  });\",\n    '  assert.equal(typeof registered.command.description, \"string\");',\n    \"\",\n    \"  // runRegisteredCommandForTest invokes the handler through pm's real\",\n    \"  // dispatch engine, so this asserts behavior - not just that the command\",\n    \"  // is wired. Replace these assertions as you flesh out your command.\",\n    \"  const invocation = await runRegisteredCommandForTest(activation.commands, {\",\n    `    command: ${JSON.stringify(commandName)},`,\n    \"  });\",\n    \"  assert.equal(invocation.handled, true);\",\n    \"  assert.equal(invocation.result.ok, true);\",\n    `  assert.equal(invocation.result.command, ${JSON.stringify(commandName)});`,\n    \"});\",\n    \"\",\n    ...hookTestLines,\n    ...searchTestLines,\n    ...importerTestLines,\n    `test(${JSON.stringify(`${extensionName} tears down cleanly via deactivate`)}, async () => {`,\n    \"  // deactivateExtensionForTest runs pm's real teardown engine over the\",\n    \"  // module, so this proves your `deactivate` hook runs without throwing.\",\n    \"  const teardown = await deactivateExtensionForTest(extension, {\",\n    `    name: ${JSON.stringify(extensionName)},`,\n    \"  });\",\n    \"  // assertExtensionDeactivated throws unless exactly one extension tore down\",\n    \"  // with no failures, so reaching the next line already proves teardown ran.\",\n    \"  assertExtensionDeactivated(teardown);\",\n    \"  assert.equal(teardown.deactivated, 1);\",\n    \"});\",\n    \"\",\n  ].join(\"\\n\");\n}\n\n/**\n * Implements build starter extension scaffold files for the public runtime surface of this module.\n */\nexport function buildStarterExtensionScaffoldFiles(\n  extensionName: string,\n  commandName: string,\n  vocabulary: \"extension\" | \"package\",\n  capability: ExtensionScaffoldCapability = \"commands\",\n): Record<string, string> {\n  const packageName = `pm-${extensionName}`;\n  const capabilities = SCAFFOLD_MANIFEST_CAPABILITIES[capability];\n  const manifest = `${JSON.stringify(\n    {\n      name: extensionName,\n      version: \"0.1.0\",\n      entry: \"./index.js\",\n      manifest_version: SCAFFOLD_MANIFEST_VERSION,\n      pm_min_version: SCAFFOLD_PM_MIN_VERSION,\n      trusted: true,\n      sandbox_profile: \"strict\",\n      permissions: { ...SCAFFOLD_DECLARED_PERMISSIONS },\n      capabilities,\n    },\n    null,\n    2,\n  )}\\n`;\n  // Keep scaffolds dependency-light by default: even package mode can be\n  // installed before peer dependencies are materialized in the generated root.\n  // The JSDoc import preserves editor narrowing without forcing the runtime\n  // loader to resolve @unbrained/pm-cli/sdk from a freshly generated scaffold.\n  const entrypoint = [\n    '/** @param {import(\"@unbrained/pm-cli/sdk\").ExtensionApi} api */',\n    \"export function activate(api) {\",\n    ...buildActivateBodyLines(extensionName, commandName, capability),\n    \"}\",\n    \"\",\n    \"// `deactivate` is the teardown counterpart to `activate`: pm runs it on host\",\n    \"// shutdown/reload (e.g. the MCP server between requests) to release anything\",\n    \"// `activate` opened - timers, connections, caches. This starter holds no such\",\n    \"// resources, so it stays a documented no-op; add cleanup here as you grow.\",\n    \"export function deactivate() {}\",\n    \"\",\n    \"export default {\",\n    \"  activate,\",\n    \"  deactivate,\",\n    \"};\",\n    \"\",\n  ].join(\"\\n\");\n  // README bullet describing what index.js wires, kept in sync with the chosen\n  // capability so the generated docs match the generated code.\n  const entrypointBullet = ENTRYPOINT_BULLETS[capability];\n  if (vocabulary === \"package\") {\n    const packageJson = `${JSON.stringify(\n      {\n        name: packageName,\n        version: \"0.1.0\",\n        private: true,\n        type: \"module\",\n        keywords: [\"pm-package\"],\n        // `node --test` runs the colocated *.test.js sample against the peer SDK\n        // testing helpers; no extra dev-dependency or test runner is required.\n        scripts: {\n          test: \"node --test\",\n        },\n        peerDependencies: {\n          \"@unbrained/pm-cli\": \"*\",\n        },\n        pm: {\n          aliases: [extensionName],\n          extensions: [\".\"],\n          docs: [\"README.md\"],\n          examples: [\"README.md\"],\n          catalog: {\n            display_name: extensionName,\n            category: \"workflow\",\n            summary: \"Starter pm package scaffold.\",\n            tags: [\"starter\"],\n          },\n        },\n      },\n      null,\n      2,\n    )}\\n`;\n    // node:test sample: demonstrates validating the package with the SDK testing\n    // helpers without adding a third-party test runner. The suite covers the\n    // capability the scaffold targets (command invocation, and for the hooks\n    // capability, the after_command lifecycle hook).\n    const sampleTest = buildSampleTestSource(extensionName, commandName, capability);\n    const sampleTestBullet = SAMPLE_TEST_BULLETS[capability];\n    const gitignore = [\"node_modules/\", \"*.log\", \"\"].join(\"\\n\");\n    const packageReadme = [\n      `# ${packageName}`,\n      \"\",\n      \"Generated by `pm package init`.\",\n      \"\",\n      \"## Included Files\",\n      \"- `package.json`: package metadata, `test` script, and `pm` resource manifest.\",\n      \"- `manifest.json`: extension metadata and capabilities.\",\n      entrypointBullet,\n      sampleTestBullet,\n      \"- `.gitignore`: ignores `node_modules/` and log files.\",\n      \"\",\n      \"## Quick Start\",\n      \"```bash\",\n      \"pm install --project <package-path>\",\n      `pm ${commandName}`,\n      \"pm package doctor --project --detail summary\",\n      \"```\",\n      \"\",\n      \"## Validate the Package\",\n      \"Install the peer SDK once, then run the colocated sample test:\",\n      \"```bash\",\n      \"npm install\",\n      \"npm test\",\n      \"```\",\n      \"`npm test` runs `node --test`, which executes `index.test.js` against the\",\n      \"`@unbrained/pm-cli/sdk/testing` helpers - no extra test runner required.\",\n      ...PACKAGE_CAPABILITY_README_SECTIONS[capability],\n      \"\",\n      \"## Compatibility Bounds\",\n      \"`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:\",\n      `- \\`manifest_version\\` (integer): manifest schema generation. Leave at \\`${SCAFFOLD_MANIFEST_VERSION}\\` unless you adopt a newer manifest schema.`,\n      `- \\`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.`,\n      \"- `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.\",\n      \"\",\n      \"## Policy Metadata\",\n      \"The starter command is pure compute, so `manifest.json` declares `trusted: true`, `sandbox_profile: \\\"strict\\\"`, and all six permission keys as `false`. Keep that least-privilege shape for pure packages; relax only the specific permission your package actually needs and verify with `pm package doctor --project --detail deep --trace`.\",\n      \"\",\n      \"## Notes\",\n      \"- Keep simple starter runtime behavior at the package root so local installs work without dependency bootstrapping.\",\n      \"- Move larger runtimes into subdirectories only after adding package dependencies and validating `pm package doctor`.\",\n      \"- Add capabilities to the extension manifest only when the entrypoint uses the matching SDK API.\",\n      \"- Use `@unbrained/pm-cli/sdk` as the public SDK import for richer package runtimes.\",\n      \"\",\n    ].join(\"\\n\");\n    return {\n      \"package.json\": packageJson,\n      \"manifest.json\": manifest,\n      \"index.js\": entrypoint,\n      \"index.test.js\": sampleTest,\n      \".gitignore\": gitignore,\n      \"README.md\": packageReadme,\n    };\n  }\n  const readme = [\n    `# ${extensionName}`,\n    \"\",\n    \"Generated by `pm extension init`.\",\n    \"\",\n    \"## Included Files\",\n    \"- `manifest.json`: extension metadata and capabilities.\",\n    entrypointBullet,\n    \"\",\n    \"## Quick Start\",\n    \"```bash\",\n    \"pm extension --install --project <scaffold-path>\",\n    `pm ${commandName}`,\n    \"pm extension --doctor --project --detail summary\",\n    \"```\",\n    ...EXTENSION_CAPABILITY_README_SECTIONS[capability],\n    \"\",\n    \"## Compatibility Bounds\",\n    \"`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:\",\n    `- \\`manifest_version\\` (integer): manifest schema generation. Leave at \\`${SCAFFOLD_MANIFEST_VERSION}\\` unless you adopt a newer manifest schema.`,\n    `- \\`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.`,\n    \"- `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.\",\n    \"\",\n    \"## Policy Metadata\",\n    \"The starter command is pure compute, so `manifest.json` declares `trusted: true`, `sandbox_profile: \\\"strict\\\"`, and all six permission keys as `false`. Keep that least-privilege shape for pure extensions; relax only the specific permission your extension actually needs and verify with `pm extension --doctor --project --detail deep --trace`.\",\n    \"\",\n    \"## Notes\",\n    \"- This scaffold uses ESM exports so it works in package scopes with `type: module`.\",\n    \"- Update `manifest.json` capabilities and `index.js` command behavior as your extension evolves.\",\n    \"- Release any resources `activate` opens (timers, connections, caches) in the `deactivate` teardown hook.\",\n    \"\",\n  ].join(\"\\n\");\n  return {\n    \"manifest.json\": manifest,\n    \"index.js\": entrypoint,\n    \"README.md\": readme,\n  };\n}\n\n/**\n * Implements scaffold extension project for the public runtime surface of this module.\n */\nexport async function scaffoldExtensionProject(\n  target: string,\n  vocabulary: \"extension\" | \"package\" = \"extension\",\n  capability: string = \"commands\",\n): Promise<ExtensionScaffoldResult> {\n  const normalizedCapability = capability.trim().toLowerCase();\n  if (!(SCAFFOLD_CAPABILITIES as readonly string[]).includes(normalizedCapability)) {\n    throw new PmCliError(\n      `Unknown scaffold capability \"${capability}\". Supported capabilities: ${SCAFFOLD_CAPABILITIES.join(\", \")}.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  const resolvedCapability = normalizedCapability as ExtensionScaffoldCapability;\n  const normalizedTarget = target.trim();\n  const targetPath = path.resolve(process.cwd(), normalizedTarget);\n  const extensionName = normalizeManagedDirectoryName(path.basename(targetPath));\n  // Hyphenated top-level command groups can surface in help but fail dispatch in\n  // Commander, so generated starters use space-separated command words while the\n  // manifest and package identity keep their normalized directory names.\n  const commandName = `${extensionName.replace(/-/g, \" \")} ping`;\n  const scaffoldFiles = buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary, resolvedCapability);\n\n  let createdDirectory = false;\n  if (await pathExists(targetPath)) {\n    const existingTargetStats = await fs.stat(targetPath);\n    if (!existingTargetStats.isDirectory()) {\n      throw new PmCliError(\n        `Scaffold target \"${targetPath}\" exists and is not a directory.`,\n        EXIT_CODE.CONFLICT,\n      );\n    }\n  } else {\n    await fs.mkdir(targetPath, { recursive: true });\n    createdDirectory = true;\n  }\n\n  for (const [relativePath, content] of Object.entries(scaffoldFiles)) {\n    const absolutePath = path.join(targetPath, relativePath);\n    if (!(await pathExists(absolutePath))) {\n      continue;\n    }\n    const existingContent = await fs.readFile(absolutePath, \"utf8\");\n    if (existingContent !== content) {\n      throw new PmCliError(\n        `Scaffold file \"${relativePath}\" already exists with different content in \"${targetPath}\". Choose a new target path or remove conflicting files.`,\n        EXIT_CODE.CONFLICT,\n      );\n    }\n  }\n\n  const files: ExtensionScaffoldFileResult[] = [];\n  for (const [relativePath, content] of Object.entries(scaffoldFiles)) {\n    const absolutePath = path.join(targetPath, relativePath);\n    if (await pathExists(absolutePath)) {\n      files.push({\n        path: relativePath,\n        status: \"unchanged\",\n      });\n      continue;\n    }\n    await fs.mkdir(path.dirname(absolutePath), { recursive: true });\n    await fs.writeFile(absolutePath, content, \"utf8\");\n    files.push({\n      path: relativePath,\n      status: \"created\",\n    });\n  }\n\n  return {\n    extension_name: extensionName,\n    command_name: commandName,\n    capability: resolvedCapability,\n    target_path: targetPath,\n    created_directory: createdDirectory,\n    files,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"61e2eb79-305a-5636-b5ca-ab0c6aa4afcc"}
+{"version":3,"file":"scaffold.js","sources":["cli/commands/extension/scaffold.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/extension/scaffold\n *\n * Implements extension package-management support for Scaffold.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { pathExists } from \"../../../core/fs/fs-utils.js\";\nimport { EXIT_CODE } from \"../../../core/shared/constants.js\";\nimport { PmCliError } from \"../../../core/shared/errors.js\";\nimport { normalizeManagedDirectoryName } from \"./shared.js\";\n\n// Safe compatibility floor emitted into scaffolded manifests. Mirrors the\n// first-party package manifests (pm-nf2q): every current 2026.5.x CLI\n// satisfies it, and it models the field for external authors. manifest_version\n// tracks the manifest schema generation (currently 1).\nconst SCAFFOLD_MANIFEST_VERSION = 1;\nconst SCAFFOLD_PM_MIN_VERSION = \"2026.5.0\";\nconst SCAFFOLD_DECLARED_PERMISSIONS = {\n  fs_read: false,\n  fs_write: false,\n  network: false,\n  env_read: false,\n  env_write: false,\n  process_spawn: false,\n};\n\n/**\n * Capability shapes the package/extension scaffolder can target via the\n * `--capability` selector. `commands` emits the default command-only starter;\n * `hooks` additionally wires an `after_command` lifecycle reactor, `search`\n * wires an in-memory provider/adapter pair, and `importers` wires importer and\n * exporter command primitives so authors can customize project context movement\n * without starting from a blank extension.\n */\nexport const SCAFFOLD_CAPABILITIES = [\"commands\", \"hooks\", \"search\", \"importers\"] as const;\n\n/**\n * Restricts the `--capability` selector to a {@link SCAFFOLD_CAPABILITIES} value.\n */\nexport type ExtensionScaffoldCapability = (typeof SCAFFOLD_CAPABILITIES)[number];\n\nconst SCAFFOLD_MANIFEST_CAPABILITIES: Record<ExtensionScaffoldCapability, readonly string[]> = {\n  commands: [\"commands\"],\n  hooks: [\"commands\", \"hooks\"],\n  search: [\"commands\", \"search\"],\n  importers: [\"commands\", \"schema\", \"importers\"],\n};\n\nconst SAMPLE_TEST_CAPABILITIES_LITERAL: Record<ExtensionScaffoldCapability, string> = {\n  commands: '[\"commands\"]',\n  hooks: '[\"commands\", \"hooks\"]',\n  search: '[\"commands\", \"search\"]',\n  importers: '[\"commands\", \"schema\", \"importers\"]',\n};\n\nconst ENTRYPOINT_BULLETS: Record<ExtensionScaffoldCapability, string> = {\n  commands: \"- `index.js`: starter command registration plus a `deactivate` teardown stub.\",\n  hooks:\n    \"- `index.js`: starter command registration, an `after_command` lifecycle hook, and a `deactivate` teardown stub.\",\n  search:\n    \"- `index.js`: starter command registration, a search provider, a vector-store adapter, and a `deactivate` teardown stub.\",\n  importers:\n    \"- `index.js`: starter command registration, importer/exporter command registrations, and a `deactivate` teardown stub.\",\n};\n\nconst SAMPLE_TEST_BULLETS: Record<ExtensionScaffoldCapability, string> = {\n  commands:\n    \"- `index.test.js`: sample `node:test` suite covering activation, command invocation, and teardown via the SDK testing helpers.\",\n  hooks:\n    \"- `index.test.js`: sample `node:test` suite covering activation, command invocation, the after_command hook, and teardown via the SDK testing helpers.\",\n  search:\n    \"- `index.test.js`: sample `node:test` suite covering activation, command invocation, search provider/vector adapter invocation, and teardown via the SDK testing helpers.\",\n  importers:\n    \"- `index.test.js`: sample `node:test` suite covering activation, command invocation, importer/exporter invocation, and teardown via the SDK testing helpers.\",\n};\n\nconst PACKAGE_CAPABILITY_README_SECTIONS: Record<ExtensionScaffoldCapability, readonly string[]> = {\n  commands: [],\n  hooks: [\n    \"\",\n    \"## Lifecycle Hook\",\n    \"`index.js` registers an `after_command` hook via `api.hooks.afterCommand`.\",\n    \"pm fires it once a command finishes, passing the command outcome and the\",\n    \"items it mutated (`context.affected`). React there to keep external context\",\n    \"in sync - sync records, emit telemetry, or refresh derived state. The\",\n    \"`hooks` capability in `manifest.json` is what grants the hook registration;\",\n    \"remove it (and the hook) if your package only needs commands.\",\n  ],\n  search: [\n    \"\",\n    \"## Search Provider\",\n    \"`index.js` registers a deterministic in-memory search provider and\",\n    \"vector-store adapter through `api.registerSearchProvider` and\",\n    \"`api.registerVectorStoreAdapter`. Replace the sample scoring,\",\n    \"embedding, and storage behavior with your project-specific retrieval\",\n    \"logic. The `search` capability in `manifest.json` grants both\",\n    \"registrations.\",\n  ],\n  importers: [\n    \"\",\n    \"## Importer and Exporter\",\n    \"`index.js` registers paired project-context import/export commands through\",\n    \"`api.registerImporter` and `api.registerExporter`. Replace the starter\",\n    \"payloads with your domain adapter: GitHub issues, CSV rows, documents,\",\n    \"tickets, or another project-management source of truth. The `importers`\",\n    \"capability grants both registrations, and `schema` grants the example\",\n    \"command flag metadata.\",\n  ],\n};\n\nconst EXTENSION_CAPABILITY_README_SECTIONS: Record<ExtensionScaffoldCapability, readonly string[]> = {\n  commands: [],\n  hooks: [\n    \"\",\n    \"## Lifecycle Hook\",\n    \"`index.js` registers an `after_command` hook via `api.hooks.afterCommand`.\",\n    \"pm fires it once a command finishes, passing the command outcome and the\",\n    \"items it mutated (`context.affected`). React there to keep external context\",\n    \"in sync. The `hooks` capability in `manifest.json` grants the registration;\",\n    \"remove it (and the hook) if your extension only needs commands.\",\n  ],\n  search: [\n    \"\",\n    \"## Search Provider\",\n    \"`index.js` registers a deterministic in-memory search provider and\",\n    \"vector-store adapter through `api.registerSearchProvider` and\",\n    \"`api.registerVectorStoreAdapter`. Replace the sample scoring, embedding,\",\n    \"and storage behavior with your project-specific retrieval logic. The\",\n    \"`search` capability in `manifest.json` grants both registrations.\",\n  ],\n  importers: [\n    \"\",\n    \"## Importer and Exporter\",\n    \"`index.js` registers paired project-context import/export commands through\",\n    \"`api.registerImporter` and `api.registerExporter`. Replace the starter\",\n    \"payloads with your domain adapter. The `importers` capability grants both\",\n    \"registrations, and `schema` grants the example command flag metadata.\",\n  ],\n};\n\ninterface ExtensionScaffoldFileResult {\n  path: string;\n  status: \"created\" | \"unchanged\";\n}\n\ninterface ExtensionScaffoldResult {\n  extension_name: string;\n  command_name: string;\n  capability: ExtensionScaffoldCapability;\n  target_path: string;\n  created_directory: boolean;\n  files: ExtensionScaffoldFileResult[];\n}\n\n/**\n * Build the `activate` body lines for the starter entrypoint. The base body\n * always registers the starter command; capability-specific variants append\n * the matching SDK surface so generated packages demonstrate one runnable\n * customization primitive end to end.\n */\nfunction buildActivateBodyLines(\n  extensionName: string,\n  commandName: string,\n  capability: ExtensionScaffoldCapability,\n): string[] {\n  const searchProviderName = `${extensionName}-search`;\n  const vectorAdapterName = `${extensionName}-vector`;\n  const adapterName = `${extensionName.replace(/-/g, \" \")} items`;\n  const commandLines = [\n    \"  api.registerCommand({\",\n    `    name: ${JSON.stringify(commandName)},`,\n    '    description: \"Starter scaffold command. Replace with your own behavior.\",',\n    \"    run: async (context) => ({\",\n    \"      ok: true,\",\n    `      source: ${JSON.stringify(extensionName)},`,\n    \"      command: context.command,\",\n    '      message: \"Starter extension scaffold is active.\",',\n    \"    }),\",\n    \"  });\",\n  ];\n  if (capability === \"commands\") {\n    return commandLines;\n  }\n  if (capability === \"search\") {\n    return [\n      ...commandLines,\n      \"\",\n      \"  // Search providers let packages customize how pm ranks and retrieves\",\n      \"  // project context. This starter is deterministic and dependency-free:\",\n      \"  // replace the scoring with your domain retrieval, embedding, or rerank\",\n      \"  // logic as the package grows.\",\n      \"  api.registerSearchProvider({\",\n      `    name: ${JSON.stringify(searchProviderName)},`,\n      \"    query: async (context) => {\",\n      \"      const needle = context.query.toLowerCase();\",\n      \"      const hits = context.documents\",\n      \"        .filter((document) => {\",\n      \"          const title = String(document.metadata.title ?? \\\"\\\").toLowerCase();\",\n      \"          return title.includes(needle);\",\n      \"        })\",\n      \"        .map((document) => ({\",\n      \"          id: document.metadata.id,\",\n      \"          score: 1,\",\n      '          matched_fields: [\"title\"],',\n      \"        }));\",\n      \"      return { hits };\",\n      \"    },\",\n      \"    embed: async (context) => [context.input.length],\",\n      \"  });\",\n      \"\",\n      \"  // Vector-store adapters let packages own semantic index storage. This\",\n      \"  // starter returns a stable in-memory hit so generated tests can exercise\",\n      \"  // the adapter without external services.\",\n      \"  api.registerVectorStoreAdapter({\",\n      `    name: ${JSON.stringify(vectorAdapterName)},`,\n      \"    query: async (context) => [{ id: \\\"starter-vector-hit\\\", score: context.limit }],\",\n      \"    upsert: async (context) => ({ upserted: context.points.length }),\",\n      \"    delete: async (context) => ({ deleted: context.ids.length }),\",\n      \"  });\",\n    ];\n  }\n  if (capability === \"importers\") {\n    return [\n      ...commandLines,\n      \"\",\n      \"  // Importers/exporters are the bridge between pm's context graph and\",\n      \"  // another project-management system. Keep the starter deterministic so\",\n      \"  // package tests can run without touching the network or filesystem; replace\",\n      \"  // these payloads with your adapter's real mapping as the package grows.\",\n      \"  api.registerImporter(\",\n      `    ${JSON.stringify(adapterName)},`,\n      \"    async (context) => ({\",\n      \"      imported: 1,\",\n      \"      source: context.options.source ?? \\\"starter\\\",\",\n      \"      args: context.args,\",\n      \"    }),\",\n      \"    {\",\n      `      action: ${JSON.stringify(`${adapterName} import`)},`,\n      '      description: \"Import starter records into pm context.\",',\n      \"      flags: [\",\n      \"        {\",\n      '          long: \"--source\",',\n      '          value_name: \"name\",',\n      '          value_type: \"string\",',\n      '          description: \"Source name or path to import from.\",',\n      \"        },\",\n      \"      ],\",\n      \"    },\",\n      \"  );\",\n      \"\",\n      \"  api.registerExporter(\",\n      `    ${JSON.stringify(adapterName)},`,\n      \"    async (context) => ({\",\n      \"      exported: true,\",\n      \"      destination: context.options.destination ?? \\\"stdout\\\",\",\n      \"      args: context.args,\",\n      \"    }),\",\n      \"    {\",\n      `      action: ${JSON.stringify(`${adapterName} export`)},`,\n      '      description: \"Export pm context into starter records.\",',\n      \"      flags: [\",\n      \"        {\",\n      '          long: \"--destination\",',\n      '          value_name: \"name\",',\n      '          value_type: \"string\",',\n      '          description: \"Destination name or path to export to.\",',\n      \"        },\",\n      \"      ],\",\n      \"    },\",\n      \"  );\",\n    ];\n  }\n  return [\n    ...commandLines,\n    \"\",\n    \"  // after_command hooks fire once pm finishes a command, receiving the items\",\n    \"  // it mutated. This is the natural place to react to every change - sync to\",\n    \"  // an external system, emit telemetry, or refresh derived context\",\n    '  // (\"project management = context management\"). This starter is a documented',\n    \"  // no-op on the success path; replace the body with your own reaction.\",\n    \"  api.hooks.afterCommand((context) => {\",\n    \"    if (!context.ok) {\",\n    \"      return;\",\n    \"    }\",\n    \"    // `context.affected` lists the items pm mutated (id, status,\",\n    \"    // changed_fields). React here, e.g.:\",\n    \"    //   for (const item of context.affected ?? []) { /* ...item.id... */ }\",\n    \"  });\",\n  ];\n}\n\n/**\n * Build the colocated `node:test` sample suite for the chosen capability. Every\n * variant covers activation, command invocation, and teardown via the SDK\n * testing helpers; the `hooks` variant adds a test that asserts the\n * `after_command` hook is registered and fires cleanly through the public SDK\n * testing helper `runRegisteredHookForTest`.\n */\nfunction buildSampleTestSource(\n  extensionName: string,\n  commandName: string,\n  capability: ExtensionScaffoldCapability,\n): string {\n  const hooksEnabled = capability === \"hooks\";\n  const searchEnabled = capability === \"search\";\n  const importersEnabled = capability === \"importers\";\n  const capabilitiesLiteral = SAMPLE_TEST_CAPABILITIES_LITERAL[capability];\n  const searchProviderName = `${extensionName}-search`;\n  const vectorAdapterName = `${extensionName}-vector`;\n  const adapterName = `${extensionName.replace(/-/g, \" \")} items`;\n  const importNames = [\n    \"  activateExtensionForTest,\",\n    \"  assertExtensionDeactivated,\",\n    \"  assertRegisteredCommandContract,\",\n    ...(hooksEnabled ? [\"  assertRegisteredHook,\"] : []),\n    ...(searchEnabled ? [\"  assertRegisteredSearchProvider,\", \"  assertRegisteredVectorStoreAdapter,\"] : []),\n    ...(importersEnabled ? [\"  assertRegisteredImporter,\", \"  assertRegisteredExporter,\"] : []),\n    \"  deactivateExtensionForTest,\",\n    \"  runRegisteredCommandForTest,\",\n    ...(hooksEnabled ? [\"  runRegisteredHookForTest,\"] : []),\n    ...(searchEnabled ? [\"  runRegisteredSearchProviderForTest,\", \"  runRegisteredVectorStoreAdapterForTest,\"] : []),\n    ...(importersEnabled ? [\"  runRegisteredImporterForTest,\", \"  runRegisteredExporterForTest,\"] : []),\n  ];\n  const hookTestLines = hooksEnabled\n    ? [\n        `test(${JSON.stringify(`${extensionName} reacts to commands via its after_command hook`)}, async () => {`,\n        \"  const activation = await activateExtensionForTest(extension, {\",\n        `    name: ${JSON.stringify(extensionName)},`,\n        `    capabilities: ${capabilitiesLiteral},`,\n        \"  });\",\n        \"  // assertRegisteredHook throws unless an after_command hook is registered,\",\n        \"  // so reaching the next line already proves the hook is wired.\",\n        \"  assertRegisteredHook(activation.hooks, {\",\n        '    kind: \"after_command\",',\n        `    extensionName: ${JSON.stringify(extensionName)},`,\n        \"  });\",\n        \"  // runRegisteredHookForTest fires the hook through pm's real runner with a\",\n        \"  // synthetic context and returns the warnings it produced; a clean hook\",\n        \"  // returns none. Replace the context/assertions as your hook grows.\",\n        \"  const warnings = await runRegisteredHookForTest(activation.hooks, {\",\n        '    kind: \"after_command\",',\n        \"    context: {\",\n        `      command: ${JSON.stringify(commandName)},`,\n        \"      args: [],\",\n        '      pm_root: \"\",',\n        \"      ok: true,\",\n        \"      affected: [],\",\n        \"    },\",\n        \"  });\",\n        \"  assert.deepEqual(warnings, []);\",\n        \"});\",\n        \"\",\n      ]\n    : [];\n  const searchTestLines = searchEnabled\n    ? [\n        `test(${JSON.stringify(`${extensionName} registers and invokes search primitives`)}, async () => {`,\n        \"  const activation = await activateExtensionForTest(extension, {\",\n        `    name: ${JSON.stringify(extensionName)},`,\n        `    capabilities: ${capabilitiesLiteral},`,\n        \"  });\",\n        \"  assertRegisteredSearchProvider(activation.registrations, {\",\n        `    provider: ${JSON.stringify(searchProviderName)},`,\n        `    extensionName: ${JSON.stringify(extensionName)},`,\n        \"  });\",\n        \"  assertRegisteredVectorStoreAdapter(activation.registrations, {\",\n        `    adapter: ${JSON.stringify(vectorAdapterName)},`,\n        `    extensionName: ${JSON.stringify(extensionName)},`,\n        \"  });\",\n        \"\",\n        \"  const query = await runRegisteredSearchProviderForTest(activation.registrations, {\",\n        `    provider: ${JSON.stringify(searchProviderName)},`,\n        '    operation: \"query\",',\n        \"    context: {\",\n        '      query: \"sync\",',\n        '      mode: \"semantic\",',\n        '      tokens: [\"sync\"],',\n        \"      options: {},\",\n        \"      settings: {},\",\n        \"      documents: [\",\n        '        { metadata: { id: \"pm-1\", title: \"Sync external context\" }, body: \"\" },',\n        '        { metadata: { id: \"pm-2\", title: \"Unrelated task\" }, body: \"\" },',\n        \"      ],\",\n        \"    },\",\n        \"  });\",\n        '  assert.deepEqual(query, { hits: [{ id: \"pm-1\", score: 1, matched_fields: [\"title\"] }] });',\n        \"\",\n        \"  const embedding = await runRegisteredSearchProviderForTest(activation.registrations, {\",\n        `    provider: ${JSON.stringify(searchProviderName)},`,\n        '    operation: \"embed\",',\n        '    context: { input: \"abc\", settings: {}, model: \"starter-model\" },',\n        \"  });\",\n        \"  assert.deepEqual(embedding, [3]);\",\n        \"\",\n        \"  const vectorHits = await runRegisteredVectorStoreAdapterForTest(activation.registrations, {\",\n        `    adapter: ${JSON.stringify(vectorAdapterName)},`,\n        '    operation: \"query\",',\n        \"    context: { vector: [0.1, 0.2], limit: 2, settings: {} },\",\n        \"  });\",\n        '  assert.deepEqual(vectorHits, [{ id: \"starter-vector-hit\", score: 2 }]);',\n        \"});\",\n        \"\",\n      ]\n    : [];\n  const importerTestLines = importersEnabled\n    ? [\n        `test(${JSON.stringify(`${extensionName} registers and invokes import/export primitives`)}, async () => {`,\n        \"  const activation = await activateExtensionForTest(extension, {\",\n        `    name: ${JSON.stringify(extensionName)},`,\n        `    capabilities: ${capabilitiesLiteral},`,\n        \"  });\",\n        \"  assertRegisteredImporter(activation.registrations, {\",\n        `    importer: ${JSON.stringify(adapterName)},`,\n        `    extensionName: ${JSON.stringify(extensionName)},`,\n        \"  });\",\n        \"  assertRegisteredExporter(activation.registrations, {\",\n        `    exporter: ${JSON.stringify(adapterName)},`,\n        `    extensionName: ${JSON.stringify(extensionName)},`,\n        \"  });\",\n        \"\",\n        \"  const imported = await runRegisteredImporterForTest(activation, {\",\n        `    importer: ${JSON.stringify(adapterName)},`,\n        '    options: { source: \"tickets\" },',\n        '    args: [\"batch-1\"],',\n        \"  });\",\n        \"  assert.equal(imported.handled, true);\",\n        '  assert.deepEqual(imported.result, { imported: 1, source: \"tickets\", args: [\"batch-1\"] });',\n        \"\",\n        \"  const exported = await runRegisteredExporterForTest(activation, {\",\n        `    exporter: ${JSON.stringify(adapterName)},`,\n        '    options: { destination: \"archive\" },',\n        '    args: [\"done\"],',\n        \"  });\",\n        \"  assert.equal(exported.handled, true);\",\n        '  assert.deepEqual(exported.result, { exported: true, destination: \"archive\", args: [\"done\"] });',\n        \"});\",\n        \"\",\n      ]\n    : [];\n  return [\n    'import assert from \"node:assert/strict\";',\n    'import { test } from \"node:test\";',\n    \"import {\",\n    ...importNames,\n    '} from \"@unbrained/pm-cli/sdk/testing\";',\n    'import extension from \"./index.js\";',\n    \"\",\n    `test(${JSON.stringify(`${extensionName} registers its starter command`)}, async () => {`,\n    \"  // `capabilities` mirrors manifest.json so the in-memory activation grants\",\n    \"  // the capabilities the entrypoint relies on.\",\n    \"  const activation = await activateExtensionForTest(extension, {\",\n    `    name: ${JSON.stringify(extensionName)},`,\n    `    capabilities: ${capabilitiesLiteral},`,\n    \"  });\",\n    \"  // assertRegisteredCommandContract throws if the command is not\",\n    \"  // registered, so reaching here already proves the wiring; assert on the\",\n    \"  // returned definition to demonstrate inspecting registered metadata.\",\n    \"  const registered = assertRegisteredCommandContract(activation.registrations, {\",\n    `    command: ${JSON.stringify(commandName)},`,\n    `    extensionName: ${JSON.stringify(extensionName)},`,\n    \"  });\",\n    '  assert.equal(typeof registered.command.description, \"string\");',\n    \"\",\n    \"  // runRegisteredCommandForTest invokes the handler through pm's real\",\n    \"  // dispatch engine, so this asserts behavior - not just that the command\",\n    \"  // is wired. Replace these assertions as you flesh out your command.\",\n    \"  const invocation = await runRegisteredCommandForTest(activation.commands, {\",\n    `    command: ${JSON.stringify(commandName)},`,\n    \"  });\",\n    \"  assert.equal(invocation.handled, true);\",\n    \"  assert.equal(invocation.result.ok, true);\",\n    `  assert.equal(invocation.result.command, ${JSON.stringify(commandName)});`,\n    \"});\",\n    \"\",\n    ...hookTestLines,\n    ...searchTestLines,\n    ...importerTestLines,\n    `test(${JSON.stringify(`${extensionName} tears down cleanly via deactivate`)}, async () => {`,\n    \"  // deactivateExtensionForTest runs pm's real teardown engine over the\",\n    \"  // module, so this proves your `deactivate` hook runs without throwing.\",\n    \"  const teardown = await deactivateExtensionForTest(extension, {\",\n    `    name: ${JSON.stringify(extensionName)},`,\n    \"  });\",\n    \"  // assertExtensionDeactivated throws unless exactly one extension tore down\",\n    \"  // with no failures, so reaching the next line already proves teardown ran.\",\n    \"  assertExtensionDeactivated(teardown);\",\n    \"  assert.equal(teardown.deactivated, 1);\",\n    \"});\",\n    \"\",\n  ].join(\"\\n\");\n}\n\n/**\n * Implements build starter extension scaffold files for the public runtime surface of this module.\n */\nexport function buildStarterExtensionScaffoldFiles(\n  extensionName: string,\n  commandName: string,\n  vocabulary: \"extension\" | \"package\",\n  capability: ExtensionScaffoldCapability = \"commands\",\n): Record<string, string> {\n  const packageName = `pm-${extensionName}`;\n  const capabilities = SCAFFOLD_MANIFEST_CAPABILITIES[capability];\n  const manifest = `${JSON.stringify(\n    {\n      name: extensionName,\n      version: \"0.1.0\",\n      entry: \"./index.js\",\n      manifest_version: SCAFFOLD_MANIFEST_VERSION,\n      pm_min_version: SCAFFOLD_PM_MIN_VERSION,\n      trusted: true,\n      sandbox_profile: \"strict\",\n      permissions: { ...SCAFFOLD_DECLARED_PERMISSIONS },\n      capabilities,\n    },\n    null,\n    2,\n  )}\\n`;\n  // Keep scaffolds dependency-light by default: even package mode can be\n  // installed before peer dependencies are materialized in the generated root.\n  // The JSDoc import preserves editor narrowing without forcing the runtime\n  // loader to resolve @unbrained/pm-cli/sdk from a freshly generated scaffold.\n  const entrypoint = [\n    '/** @param {import(\"@unbrained/pm-cli/sdk\").ExtensionApi} api */',\n    \"export function activate(api) {\",\n    ...buildActivateBodyLines(extensionName, commandName, capability),\n    \"}\",\n    \"\",\n    \"// `deactivate` is the teardown counterpart to `activate`: pm runs it on host\",\n    \"// shutdown/reload (e.g. the MCP server between requests) to release anything\",\n    \"// `activate` opened - timers, connections, caches. This starter holds no such\",\n    \"// resources, so it stays a documented no-op; add cleanup here as you grow.\",\n    \"export function deactivate() {}\",\n    \"\",\n    \"export default {\",\n    \"  activate,\",\n    \"  deactivate,\",\n    \"};\",\n    \"\",\n  ].join(\"\\n\");\n  // README bullet describing what index.js wires, kept in sync with the chosen\n  // capability so the generated docs match the generated code.\n  const entrypointBullet = ENTRYPOINT_BULLETS[capability];\n  if (vocabulary === \"package\") {\n    const packageJson = `${JSON.stringify(\n      {\n        name: packageName,\n        version: \"0.1.0\",\n        private: true,\n        type: \"module\",\n        keywords: [\"pm-package\"],\n        // `node --test` runs the colocated *.test.js sample against the peer SDK\n        // testing helpers; no extra dev-dependency or test runner is required.\n        scripts: {\n          test: \"node --test\",\n        },\n        peerDependencies: {\n          \"@unbrained/pm-cli\": \"*\",\n        },\n        pm: {\n          aliases: [extensionName],\n          extensions: [\".\"],\n          docs: [\"README.md\"],\n          examples: [\"README.md\"],\n          catalog: {\n            display_name: extensionName,\n            category: \"workflow\",\n            summary: \"Starter pm package scaffold.\",\n            tags: [\"starter\"],\n          },\n        },\n      },\n      null,\n      2,\n    )}\\n`;\n    // node:test sample: demonstrates validating the package with the SDK testing\n    // helpers without adding a third-party test runner. The suite covers the\n    // capability the scaffold targets (command invocation, and for the hooks\n    // capability, the after_command lifecycle hook).\n    const sampleTest = buildSampleTestSource(extensionName, commandName, capability);\n    const sampleTestBullet = SAMPLE_TEST_BULLETS[capability];\n    const gitignore = [\"node_modules/\", \"*.log\", \"\"].join(\"\\n\");\n    const searchProviderName = `${extensionName}-search`;\n    const vectorAdapterName = `${extensionName}-vector`;\n    const adapterName = `${extensionName.replace(/-/g, \" \")} items`;\n    const defineBuilderImports = [\n      \"defineCommand\",\n      ...(capability === \"hooks\" ? [\"defineAfterCommandHook\"] : []),\n      ...(capability === \"search\" ? [\"defineSearchProvider\", \"defineVectorStoreAdapter\"] : []),\n      ...(capability === \"importers\" ? [\"defineImporter\", \"defineExporter\"] : []),\n    ].join(\", \");\n    const defineBuilderSnippet = [\n      \"```js\",\n      `import { ${defineBuilderImports} } from \"@unbrained/pm-cli/sdk\";`,\n      \"\",\n      \"export const pingCommand = defineCommand({\",\n      `  name: ${JSON.stringify(commandName)},`,\n      '  description: \"Starter scaffold command. Replace with your own behavior.\",',\n      \"  run: (context) => ({ ok: true, command: context.command }),\",\n      \"});\",\n    ];\n    if (capability === \"hooks\") {\n      defineBuilderSnippet.push(\n        \"\",\n        \"export const afterCommandHook = defineAfterCommandHook((context) => {\",\n        \"  if (!context.ok) return;\",\n        \"  // React to context.affected here as your package grows.\",\n        \"});\",\n      );\n    }\n    if (capability === \"search\") {\n      defineBuilderSnippet.push(\n        \"\",\n        \"export const searchProvider = defineSearchProvider({\",\n        `  name: ${JSON.stringify(searchProviderName)},`,\n        \"  query: async (context) => ({\",\n        \"    hits: context.documents\",\n        \"      .filter((document) => String(document.metadata.title ?? \\\"\\\").toLowerCase().includes(context.query.toLowerCase()))\",\n        \"      .map((document) => ({ id: document.metadata.id, score: 1, matched_fields: [\\\"title\\\"] })),\",\n        \"  }),\",\n        \"  embed: async (context) => [context.input.length],\",\n        \"});\",\n        \"\",\n        \"export const vectorStoreAdapter = defineVectorStoreAdapter({\",\n        `  name: ${JSON.stringify(vectorAdapterName)},`,\n        \"  query: async (context) => [{ id: \\\"starter-vector-hit\\\", score: context.limit }],\",\n        \"  upsert: async (context) => ({ upserted: context.points.length }),\",\n        \"  delete: async (context) => ({ deleted: context.ids.length }),\",\n        \"});\",\n      );\n    }\n    if (capability === \"importers\") {\n      defineBuilderSnippet.push(\n        \"\",\n        \"export const importer = defineImporter(async (context) => ({\",\n        \"  imported: 1,\",\n        \"  source: context.options.source ?? \\\"starter\\\",\",\n        \"  args: context.args,\",\n        \"}));\",\n        \"\",\n        \"export const exporter = defineExporter(async (context) => ({\",\n        \"  exported: true,\",\n        \"  destination: context.options.destination ?? \\\"stdout\\\",\",\n        \"  args: context.args,\",\n        \"}));\",\n      );\n    }\n    defineBuilderSnippet.push(\n      \"\",\n      \"export function activate(api) {\",\n      \"  api.registerCommand(pingCommand);\",\n    );\n    if (capability === \"hooks\") {\n      defineBuilderSnippet.push(\"  api.hooks.afterCommand(afterCommandHook);\");\n    }\n    if (capability === \"search\") {\n      defineBuilderSnippet.push(\"  api.registerSearchProvider(searchProvider);\", \"  api.registerVectorStoreAdapter(vectorStoreAdapter);\");\n    }\n    if (capability === \"importers\") {\n      defineBuilderSnippet.push(\n        `  api.registerImporter(${JSON.stringify(adapterName)}, importer, {`,\n        `    action: ${JSON.stringify(`${adapterName} import`)},`,\n        '    description: \"Import starter records into pm context.\",',\n        \"    flags: [\",\n        \"      {\",\n        '        long: \"--source\",',\n        '        value_name: \"name\",',\n        '        value_type: \"string\",',\n        '        description: \"Source name or path to import from.\",',\n        \"      },\",\n        \"    ],\",\n        \"  });\",\n        `  api.registerExporter(${JSON.stringify(adapterName)}, exporter, {`,\n        `    action: ${JSON.stringify(`${adapterName} export`)},`,\n        '    description: \"Export pm context into starter records.\",',\n        \"    flags: [\",\n        \"      {\",\n        '        long: \"--destination\",',\n        '        value_name: \"name\",',\n        '        value_type: \"string\",',\n        '        description: \"Destination name or path to export to.\",',\n        \"      },\",\n        \"    ],\",\n        \"  });\",\n      );\n    }\n    defineBuilderSnippet.push(\n      \"}\",\n      \"\",\n      \"export function deactivate() {}\",\n      \"\",\n      \"export default { activate, deactivate };\",\n      \"```\",\n    );\n    const packageReadme = [\n      `# ${packageName}`,\n      \"\",\n      \"Generated by `pm package init`.\",\n      \"\",\n      \"## Included Files\",\n      \"- `package.json`: package metadata, `test` script, and `pm` resource manifest.\",\n      \"- `manifest.json`: extension metadata and capabilities.\",\n      entrypointBullet,\n      sampleTestBullet,\n      \"- `.gitignore`: ignores `node_modules/` and log files.\",\n      \"\",\n      \"## Quick Start\",\n      \"```bash\",\n      \"pm install --project <package-path>\",\n      `pm ${commandName}`,\n      \"pm package doctor --project --detail summary\",\n      \"```\",\n      \"\",\n      \"## Validate the Package\",\n      \"Install the peer SDK once, then run the colocated sample test:\",\n      \"```bash\",\n      \"npm install\",\n      \"npm test\",\n      \"```\",\n      \"`npm test` runs `node --test`, which executes `index.test.js` against the\",\n      \"`@unbrained/pm-cli/sdk/testing` helpers - no extra test runner required.\",\n      \"\",\n      \"## Authoring With define* Builders\",\n      \"`index.js` stays import-free so the package can be installed locally before\",\n      \"`npm install` materializes peer dependencies. After installing dependencies,\",\n      \"use the public SDK authoring builders for exported definitions you want\",\n      \"editor type-checking, contextual handler inference, and direct unit tests for:\",\n      ...defineBuilderSnippet,\n      \"The builders return their argument unchanged; runtime validation still lives\",\n      \"in `api.register*`, and behavior validation lives in `sdk/testing`.\",\n      ...PACKAGE_CAPABILITY_README_SECTIONS[capability],\n      \"\",\n      \"## Compatibility Bounds\",\n      \"`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:\",\n      `- \\`manifest_version\\` (integer): manifest schema generation. Leave at \\`${SCAFFOLD_MANIFEST_VERSION}\\` unless you adopt a newer manifest schema.`,\n      `- \\`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.`,\n      \"- `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.\",\n      \"\",\n      \"## Policy Metadata\",\n      \"The starter command is pure compute, so `manifest.json` declares `trusted: true`, `sandbox_profile: \\\"strict\\\"`, and all six permission keys as `false`. Keep that least-privilege shape for pure packages; relax only the specific permission your package actually needs and verify with `pm package doctor --project --detail deep --trace`.\",\n      \"\",\n      \"## Notes\",\n      \"- Keep simple starter runtime behavior at the package root so local installs work without dependency bootstrapping.\",\n      \"- Move larger runtimes into subdirectories only after adding package dependencies and validating `pm package doctor`.\",\n      \"- Add capabilities to the extension manifest only when the entrypoint uses the matching SDK API.\",\n      \"- Use `@unbrained/pm-cli/sdk` as the public SDK import for richer package runtimes.\",\n      \"\",\n    ].join(\"\\n\");\n    return {\n      \"package.json\": packageJson,\n      \"manifest.json\": manifest,\n      \"index.js\": entrypoint,\n      \"index.test.js\": sampleTest,\n      \".gitignore\": gitignore,\n      \"README.md\": packageReadme,\n    };\n  }\n  const readme = [\n    `# ${extensionName}`,\n    \"\",\n    \"Generated by `pm extension init`.\",\n    \"\",\n    \"## Included Files\",\n    \"- `manifest.json`: extension metadata and capabilities.\",\n    entrypointBullet,\n    \"\",\n    \"## Quick Start\",\n    \"```bash\",\n    \"pm extension --install --project <scaffold-path>\",\n    `pm ${commandName}`,\n    \"pm extension --doctor --project --detail summary\",\n    \"```\",\n    ...EXTENSION_CAPABILITY_README_SECTIONS[capability],\n    \"\",\n    \"## Compatibility Bounds\",\n    \"`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:\",\n    `- \\`manifest_version\\` (integer): manifest schema generation. Leave at \\`${SCAFFOLD_MANIFEST_VERSION}\\` unless you adopt a newer manifest schema.`,\n    `- \\`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.`,\n    \"- `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.\",\n    \"\",\n    \"## Policy Metadata\",\n    \"The starter command is pure compute, so `manifest.json` declares `trusted: true`, `sandbox_profile: \\\"strict\\\"`, and all six permission keys as `false`. Keep that least-privilege shape for pure extensions; relax only the specific permission your extension actually needs and verify with `pm extension --doctor --project --detail deep --trace`.\",\n    \"\",\n    \"## Notes\",\n    \"- This scaffold uses ESM exports so it works in package scopes with `type: module`.\",\n    \"- Update `manifest.json` capabilities and `index.js` command behavior as your extension evolves.\",\n    \"- Release any resources `activate` opens (timers, connections, caches) in the `deactivate` teardown hook.\",\n    \"\",\n  ].join(\"\\n\");\n  return {\n    \"manifest.json\": manifest,\n    \"index.js\": entrypoint,\n    \"README.md\": readme,\n  };\n}\n\n/**\n * Implements scaffold extension project for the public runtime surface of this module.\n */\nexport async function scaffoldExtensionProject(\n  target: string,\n  vocabulary: \"extension\" | \"package\" = \"extension\",\n  capability: string = \"commands\",\n): Promise<ExtensionScaffoldResult> {\n  const normalizedCapability = capability.trim().toLowerCase();\n  if (!(SCAFFOLD_CAPABILITIES as readonly string[]).includes(normalizedCapability)) {\n    throw new PmCliError(\n      `Unknown scaffold capability \"${capability}\". Supported capabilities: ${SCAFFOLD_CAPABILITIES.join(\", \")}.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  const resolvedCapability = normalizedCapability as ExtensionScaffoldCapability;\n  const normalizedTarget = target.trim();\n  const targetPath = path.resolve(process.cwd(), normalizedTarget);\n  const extensionName = normalizeManagedDirectoryName(path.basename(targetPath));\n  // Hyphenated top-level command groups can surface in help but fail dispatch in\n  // Commander, so generated starters use space-separated command words while the\n  // manifest and package identity keep their normalized directory names.\n  const commandName = `${extensionName.replace(/-/g, \" \")} ping`;\n  const scaffoldFiles = buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary, resolvedCapability);\n\n  let createdDirectory = false;\n  if (await pathExists(targetPath)) {\n    const existingTargetStats = await fs.stat(targetPath);\n    if (!existingTargetStats.isDirectory()) {\n      throw new PmCliError(\n        `Scaffold target \"${targetPath}\" exists and is not a directory.`,\n        EXIT_CODE.CONFLICT,\n      );\n    }\n  } else {\n    await fs.mkdir(targetPath, { recursive: true });\n    createdDirectory = true;\n  }\n\n  for (const [relativePath, content] of Object.entries(scaffoldFiles)) {\n    const absolutePath = path.join(targetPath, relativePath);\n    if (!(await pathExists(absolutePath))) {\n      continue;\n    }\n    const existingContent = await fs.readFile(absolutePath, \"utf8\");\n    if (existingContent !== content) {\n      throw new PmCliError(\n        `Scaffold file \"${relativePath}\" already exists with different content in \"${targetPath}\". Choose a new target path or remove conflicting files.`,\n        EXIT_CODE.CONFLICT,\n      );\n    }\n  }\n\n  const files: ExtensionScaffoldFileResult[] = [];\n  for (const [relativePath, content] of Object.entries(scaffoldFiles)) {\n    const absolutePath = path.join(targetPath, relativePath);\n    if (await pathExists(absolutePath)) {\n      files.push({\n        path: relativePath,\n        status: \"unchanged\",\n      });\n      continue;\n    }\n    await fs.mkdir(path.dirname(absolutePath), { recursive: true });\n    await fs.writeFile(absolutePath, content, \"utf8\");\n    files.push({\n      path: relativePath,\n      status: \"created\",\n    });\n  }\n\n  return {\n    extension_name: extensionName,\n    command_name: commandName,\n    capability: resolvedCapability,\n    target_path: targetPath,\n    created_directory: createdDirectory,\n    files,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"4513e1ea-24a5-55b1-9465-78d5d9febba7"}

package/dist/cli/commands/extension.d.ts

@@ -11,7 +11,7 @@ export type { ManagedExtensionStateReadResult } from "./extension/managed-state.
 /**
  * Restricts extension command action values accepted by command, SDK, and storage contracts.
  */
-export type ExtensionCommandAction = "install" | "uninstall" | "explore" | "manage" | "reload" | "doctor" | "catalog" | "adopt" | "adopt-all" | "activate" | "deactivate" | "init";
+export type ExtensionCommandAction = "install" | "uninstall" | "explore" | "manage" | "describe" | "reload" | "doctor" | "catalog" | "adopt" | "adopt-all" | "activate" | "deactivate" | "init";
 /**
  * Restricts extension scope values accepted by command, SDK, and storage contracts.
  */
@@ -28,6 +28,7 @@ export interface ExtensionCommandOptions {
     uninstall?: boolean;
     explore?: boolean;
     manage?: boolean;
+    describe?: boolean;
     reload?: boolean;
     doctor?: boolean;
     catalog?: boolean;

package/dist/cli/commands/extension.js

@@ -4,7 +4,7 @@
  * Implements the pm extension command surface and its agent-facing runtime behavior.
  */
 
-!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]="1402dcb1-4fe9-5ec7-a34f-990b54437d1e")}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]="bc327a80-93b0-5be9-9ebf-8864cf67d23d")}catch(e){}}();
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -29,6 +29,7 @@ import { sortManagedEntries, managedExtensionSourcesEquivalent, readManagedExten
 import { parseExtensionInstallSource, resolveInstallSource, areDirectoriesEquivalent, runGitCommand, } from "./extension/install-sources.js";
 import { resolveBundledExtensionAliasSource, isBundledPackageInstallAllTarget, listBundledPackageAliases, resolveBundledAliasManifestName, buildBundledPackageCatalog, } from "./extension/bundled-catalog.js";
 import { scaffoldExtensionProject } from "./extension/scaffold.js";
+import { buildExtensionDescribeResult } from "./extension/describe.js";
 import { applyDoctorRuntimeActivationState, classifyDoctorLoadFailureWarnings, classifyDoctorActivationFailureWarnings, classifyUnusedCapabilityWarnings, buildExtensionTriageSummary, parseDoctorDetailMode, collectUnknownCapabilityGuidance, buildCapabilityContractMetadata, buildDoctorConsistencySummary, } from "./extension/doctor.js";
 // Re-export the public surface that lives in sibling modules but was previously
 // exported from this file (used by sdk barrels, upgrade.ts, and tests).
@@ -273,6 +274,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,
@@ -308,7 +310,7 @@ function resolveAction(target, options) {
         if (target === undefined) {
             return "explore";
         }
-        throw new PmCliError("One action flag is required. Use one of: --install, --uninstall, --explore, --manage, --reload, --doctor, --catalog, --init/--scaffold, --adopt, --adopt-all, --activate, --deactivate. Bare `pm package` and `pm extension` default to --explore.", EXIT_CODE.USAGE);
+        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);
@@ -1436,6 +1438,29 @@ export 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 !== undefined && 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,
+        });
+    }
     /* c8 ignore start -- explore/manage action split is validated by dedicated command-action tests */
     if (action === "explore" || action === "manage") {
         const settings = await readSettings(resolvedRoots.settings_root);
@@ -1584,4 +1609,4 @@ export const _testOnly = {
     withExtensionInstallLock,
 };
 //# sourceMappingURL=extension.js.map
-//# debugId=1402dcb1-4fe9-5ec7-a34f-990b54437d1e
+//# debugId=bc327a80-93b0-5be9-9ebf-8864cf67d23d