@unbrained/pm-cli 2026.6.30 → 2026.7.1

package/dist/cli-bundle/chunks/{chunk-IBU2LLWM.js → chunk-64HNBBFQ.js}

@@ -3,10 +3,10 @@ import {
   normalizeReplayPatchOps,
   tryApplyReplayPatch,
   verifyHistoryChain
-} from "./chunk-E2Q2ULMR.js";
+} from "./chunk-G7I7DEZA.js";
 import {
   parseLimit
-} from "./chunk-7L6TXOOC.js";
+} from "./chunk-4DUVCVLZ.js";
 import {
   enforceHistoryStreamPolicyForItem,
   hashDocument,
@@ -14,10 +14,10 @@ import {
   locateItem,
   normalizeItemId,
   readLocatedItem
-} from "./chunk-LBH7UYKY.js";
+} from "./chunk-3K2M5OYU.js";
 import {
   findFirstMergeConflictMarker
-} from "./chunk-ZFIEEDTJ.js";
+} from "./chunk-BHO33VBQ.js";
 import {
   EXIT_CODE,
   PmCliError,
@@ -30,7 +30,7 @@ import {
   resolveItemTypeRegistry,
   resolvePmRoot,
   runActiveOnReadHooks
-} from "./chunk-SNUK7H5J.js";
+} from "./chunk-RVUALSJF.js";
 
 // dist/core/history/history-diff.js
 !(function() {
@@ -272,4 +272,4 @@ export {
   readHistoryEntries,
   runHistory
 };
-//# sourceMappingURL=chunk-IBU2LLWM.js.map
+//# sourceMappingURL=chunk-64HNBBFQ.js.map

package/dist/cli-bundle/chunks/{chunk-T7ZMQI4J.js → chunk-6AQZPVHQ.js}

@@ -1,16 +1,20 @@
 
-!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]="cabc95dd-5428-533e-b3e2-d45eb7ef7409")}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]="da6d1484-9f3c-56e4-a493-4b4296d741c1")}catch(e){}}();
 import {
+  EXECUTABLE_COMMAND_ALIASES,
   normalizeExtensionNameForMatch,
   normalizeManagedDirectoryName
-} from "./chunk-C2KCIZKZ.js";
+} from "./chunk-4A3BJ675.js";
+import {
+  PM_CORE_COMMAND_NAMES
+} from "./chunk-HXTQJXWT.js";
 import {
   EXIT_CODE,
   PmCliError,
   collectUsedExtensionCapabilities,
   normalizeExtensionName,
   pathExists
-} from "./chunk-CY5IJMUM.js";
+} from "./chunk-7R4QEMZZ.js";
 
 // dist/cli/commands/extension/scaffold.js
 import fs from "node:fs/promises";
@@ -26,8 +30,34 @@ var SCAFFOLD_DECLARED_PERMISSIONS = {
   env_write: false,
   process_spawn: false
 };
+var RESERVED_SCAFFOLD_COMMAND_ROOTS = /* @__PURE__ */ new Set([
+  ...PM_CORE_COMMAND_NAMES.map((commandName) => commandName.split("-")[0].toLowerCase()),
+  ...Object.keys(EXECUTABLE_COMMAND_ALIASES).map((alias) => alias.toLowerCase()),
+  // "scaffold" is a Commander command that currently lives outside both
+  // PM_CORE_COMMAND_NAMES and EXECUTABLE_COMMAND_ALIASES.
+  "scaffold"
+]);
 var SCAFFOLD_TYPESCRIPT_VERSION = "^6.0.0";
 var SCAFFOLD_TYPES_NODE_VERSION = "^22.0.0";
+var SAMPLE_HARNESS_CLEANUP_LINES = [
+  "type StarterHarness = Awaited<ReturnType<typeof createExtensionTestHarness>>;",
+  "",
+  "async function deactivateIfNeeded(ext: StarterHarness, deactivated: boolean): Promise<void> {",
+  "  if (!deactivated) {",
+  "    try {",
+  "      await ext.deactivate();",
+  "    } catch {",
+  "      // Preserve the original assertion error; cleanup is best effort.",
+  "    }",
+  "  }",
+  "}",
+  ""
+];
+var SAMPLE_HARNESS_FINALLY_LINES = [
+  "  } finally {",
+  "    await deactivateIfNeeded(ext, deactivated);",
+  "  }"
+];
 var SCAFFOLD_TSCONFIG = {
   compilerOptions: {
     target: "ES2022",
@@ -396,6 +426,22 @@ function buildScaffoldActivationReadmeSection(capability, vocabulary) {
   }
   return LAZY_ACTIVATION_README_SECTION[vocabulary];
 }
+function buildScaffoldCommandName(extensionName) {
+  const commandWords = extensionName.replace(/-/g, " ").trim().split(/\s+/).filter((word) => word.length > 0);
+  if (commandWords.length === 0) {
+    return "starter ping";
+  }
+  const firstWordLower = commandWords[0].toLowerCase();
+  let leadingStarterWords = 0;
+  while (commandWords[leadingStarterWords]?.toLowerCase() === "starter") {
+    leadingStarterWords += 1;
+  }
+  const nextStarterWord = commandWords[leadingStarterWords]?.toLowerCase();
+  const starterRootCollision = leadingStarterWords > 0 && (leadingStarterWords === commandWords.length || nextStarterWord !== void 0 && RESERVED_SCAFFOLD_COMMAND_ROOTS.has(nextStarterWord));
+  const reservedRoot = RESERVED_SCAFFOLD_COMMAND_ROOTS.has(firstWordLower) || starterRootCollision;
+  const resolvedWords = reservedRoot ? ["starter", ...commandWords] : commandWords;
+  return `${resolvedWords.join(" ")} ping`;
+}
 function buildProfileArchetypeFieldLines(extensionName) {
   const typeName = extensionName;
   const typeFolder = `${extensionName}s`;
@@ -819,13 +865,7 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     "    const teardown = await ext.deactivate();",
     "    assertExtensionDeactivated(teardown);",
     "    deactivated = true;",
-    "  } finally {",
-    "    if (!deactivated) {",
-    "      try {",
-    "        await ext.deactivate();",
-    "      } catch {}",
-    "    }",
-    "  }",
+    ...SAMPLE_HARNESS_FINALLY_LINES,
     "});",
     ""
   ] : [];
@@ -875,13 +915,7 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     "    const teardown = await ext.deactivate();",
     "    assertExtensionDeactivated(teardown);",
     "    deactivated = true;",
-    "  } finally {",
-    "    if (!deactivated) {",
-    "      try {",
-    "        await ext.deactivate();",
-    "      } catch {}",
-    "    }",
-    "  }",
+    ...SAMPLE_HARNESS_FINALLY_LINES,
     "});",
     ""
   ] : [];
@@ -914,13 +948,7 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     "    const teardown = await ext.deactivate();",
     "    assertExtensionDeactivated(teardown);",
     "    deactivated = true;",
-    "  } finally {",
-    "    if (!deactivated) {",
-    "      try {",
-    "        await ext.deactivate();",
-    "      } catch {}",
-    "    }",
-    "  }",
+    ...SAMPLE_HARNESS_FINALLY_LINES,
     "});",
     ""
   ] : [];
@@ -949,13 +977,7 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     "    const teardown = await ext.deactivate();",
     "    assertExtensionDeactivated(teardown);",
     "    deactivated = true;",
-    "  } finally {",
-    "    if (!deactivated) {",
-    "      try {",
-    "        await ext.deactivate();",
-    "      } catch {}",
-    "    }",
-    "  }",
+    ...SAMPLE_HARNESS_FINALLY_LINES,
     "});",
     ""
   ] : [];
@@ -977,13 +999,7 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     "    const teardown = await ext.deactivate();",
     "    assertExtensionDeactivated(teardown);",
     "    deactivated = true;",
-    "  } finally {",
-    "    if (!deactivated) {",
-    "      try {",
-    "        await ext.deactivate();",
-    "      } catch {}",
-    "    }",
-    "  }",
+    ...SAMPLE_HARNESS_FINALLY_LINES,
     "});",
     ""
   ] : [];
@@ -1021,13 +1037,7 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     "    const teardown = await ext.deactivate();",
     "    assertExtensionDeactivated(teardown);",
     "    deactivated = true;",
-    "  } finally {",
-    "    if (!deactivated) {",
-    "      try {",
-    "        await ext.deactivate();",
-    "      } catch {}",
-    "    }",
-    "  }",
+    ...SAMPLE_HARNESS_FINALLY_LINES,
     "});",
     ""
   ] : [];
@@ -1071,13 +1081,7 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     "    const teardown = await ext.deactivate();",
     "    assertExtensionDeactivated(teardown);",
     "    deactivated = true;",
-    "  } finally {",
-    "    if (!deactivated) {",
-    "      try {",
-    "        await ext.deactivate();",
-    "      } catch {}",
-    "    }",
-    "  }",
+    ...SAMPLE_HARNESS_FINALLY_LINES,
     "});",
     ""
   ] : [];
@@ -1115,13 +1119,7 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     "    const teardown = await ext.deactivate();",
     "    assertExtensionDeactivated(teardown);",
     "    deactivated = true;",
-    "  } finally {",
-    "    if (!deactivated) {",
-    "      try {",
-    "        await ext.deactivate();",
-    "      } catch {}",
-    "    }",
-    "  }",
+    ...SAMPLE_HARNESS_FINALLY_LINES,
     "});",
     ""
   ] : [];
@@ -1158,13 +1156,7 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     "    const teardown = await ext.deactivate();",
     "    assertExtensionDeactivated(teardown);",
     "    deactivated = true;",
-    "  } finally {",
-    "    if (!deactivated) {",
-    "      try {",
-    "        await ext.deactivate();",
-    "      } catch {}",
-    "    }",
-    "  }",
+    ...SAMPLE_HARNESS_FINALLY_LINES,
     "});",
     ""
   ] : [];
@@ -1179,6 +1171,7 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     ...searchEnabled ? ['import type { ItemDocument, PmSettings } from "@unbrained/pm-cli/sdk";'] : [],
     'import extension from "./index.ts";',
     "",
+    ...SAMPLE_HARNESS_CLEANUP_LINES,
     `test(${JSON.stringify(`${extensionName} registers its starter command`)}, async () => {`,
     "  // `capabilities` mirrors manifest.json so the in-memory activation grants",
     "  // the capabilities the entrypoint relies on.",
@@ -1218,13 +1211,7 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     "    const teardown = await ext.deactivate();",
     "    assertExtensionDeactivated(teardown);",
     "    deactivated = true;",
-    "  } finally {",
-    "    if (!deactivated) {",
-    "      try {",
-    "        await ext.deactivate();",
-    "      } catch {}",
-    "    }",
-    "  }",
+    ...SAMPLE_HARNESS_FINALLY_LINES,
     "});",
     "",
     ...hookTestLines,
@@ -1441,13 +1428,7 @@ function buildDeclarativeCapabilityTestBlock(extensionName, commandName, capabil
     "    const teardown = await ext.deactivate();",
     "    assertExtensionDeactivated(teardown);",
     "    deactivated = true;",
-    "  } finally {",
-    "    if (!deactivated) {",
-    "      try {",
-    "        await ext.deactivate();",
-    "      } catch {}",
-    "    }",
-    "  }"
+    ...SAMPLE_HARNESS_FINALLY_LINES
   ];
   switch (capability) {
     case "hooks":
@@ -1720,6 +1701,7 @@ function buildDeclarativeSampleTestSource(extensionName, commandName, capability
     ...capability === "search" ? ['import type { ItemDocument, PmSettings } from "@unbrained/pm-cli/sdk";'] : [],
     'import extension, { blueprint } from "./index.ts";',
     "",
+    ...SAMPLE_HARNESS_CLEANUP_LINES,
     `test(${JSON.stringify(`${extensionName} passes author-time preflight`)}, () => {`,
     "  // assertExtensionPreflight is the author-time capstone: it lints the blueprint,",
     "  // synthesizes the least-privilege manifest from `identity`, and checks the version",
@@ -1778,13 +1760,7 @@ function buildDeclarativeSampleTestSource(extensionName, commandName, capability
     "    const teardown = await ext.deactivate();",
     "    assertExtensionDeactivated(teardown);",
     "    deactivated = true;",
-    "  } finally {",
-    "    if (!deactivated) {",
-    "      try {",
-    "        await ext.deactivate();",
-    "      } catch {}",
-    "    }",
-    "  }",
+    ...SAMPLE_HARNESS_FINALLY_LINES,
     "});",
     "",
     ...buildDeclarativeCapabilityTestBlock(extensionName, commandName, capability, capabilitiesLiteral)
@@ -1865,6 +1841,111 @@ function buildDeclarativePackageReadme(packageName, commandName, capability) {
     ""
   ].join("\n");
 }
+function buildScaffoldSnippetNames(extensionName) {
+  const itemTypeName = extensionName;
+  const itemTypeAlias = extensionName.replace(/-/g, "");
+  return {
+    searchProviderName: `${extensionName}-search`,
+    vectorAdapterName: `${extensionName}-vector`,
+    adapterName: `${extensionName.replace(/-/g, " ")} items`,
+    itemTypeName,
+    itemTypeFolder: `${extensionName}s`,
+    itemTypeAliases: itemTypeAlias === itemTypeName ? [] : [itemTypeAlias],
+    fieldName: `${extensionName.replace(/-/g, "_")}_note`,
+    migrationId: `${extensionName}-0001-init`
+  };
+}
+function buildDefineBuilderImports(capability) {
+  return [
+    "defineCommand",
+    ...capability === "hooks" ? ["defineAfterCommandHook"] : [],
+    ...capability === "search" ? ["defineSearchProvider", "defineVectorStoreAdapter"] : [],
+    ...capability === "importers" ? ["defineImporter", "defineExporter"] : [],
+    ...capability === "schema" ? ["defineItemType", "defineItemField", "defineMigration"] : [],
+    ...capability === "profile" ? ["defineProjectProfile"] : [],
+    ...capability === "renderers" ? ["defineRendererOverride"] : [],
+    ...capability === "parser" ? ["defineParserOverride"] : [],
+    ...capability === "preflight" ? ["definePreflightOverride"] : [],
+    ...capability === "services" ? ["defineServiceOverride"] : []
+  ].join(", ");
+}
+function buildDefineBuilderExports(extensionName, commandName, capability, names) {
+  const lines = [
+    "export const pingCommand = defineCommand({",
+    `  name: ${JSON.stringify(commandName)},`,
+    '  description: "Starter scaffold command. Replace with your own behavior.",',
+    // The parser starter's command declares the flags its override normalizes so
+    // the demo is runnable through `pm <command> --shout`, and surfaces the
+    // canonical `upper` flag in the result.
+    ...capability === "parser" ? [
+      "  flags: [",
+      '    { long: "--shout", value_type: "boolean", description: "Deprecated alias for --upper." },',
+      '    { long: "--upper", value_type: "boolean", description: "Canonical flag the parser produces." },',
+      "  ],",
+      "  run: (context) => ({ ok: true, command: context.command, upper: context.options.upper === true }),"
+    ] : ["  run: (context) => ({ ok: true, command: context.command }),"],
+    "});"
+  ];
+  if (capability === "hooks") {
+    lines.push("", "export const afterCommandHook = defineAfterCommandHook((context) => {", "  if (!context.ok) return;", "  // React to context.affected here as your package grows.", "});");
+  }
+  if (capability === "search") {
+    lines.push("", "export const searchProvider = defineSearchProvider({", `  name: ${JSON.stringify(names.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(names.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") {
+    lines.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,", "}));");
+  }
+  if (capability === "schema") {
+    lines.push("", `export const noteField = defineItemField({ name: ${JSON.stringify(names.fieldName)}, type: "string", optional: true });`, "", "export const itemType = defineItemType({", `  name: ${JSON.stringify(names.itemTypeName)},`, `  folder: ${JSON.stringify(names.itemTypeFolder)},`, `  aliases: ${JSON.stringify(names.itemTypeAliases)},`, "  required_create_fields: [],", "});", "", "export const initMigration = defineMigration({", `  id: ${JSON.stringify(names.migrationId)},`, `  description: ${JSON.stringify(`Initialize ${extensionName} schema state.`)},`, "  mandatory: false,", "  run: async (context) => ({ migrated: true, id: context.id }),", "});");
+  }
+  if (capability === "profile") {
+    lines.push("", "export const starterProfile = defineProjectProfile({", `  name: ${JSON.stringify(extensionName)},`, `  title: ${JSON.stringify(`${extensionName} archetype`)},`, '  summary: "Starter project profile. Replace these dimensions with your own archetype.",', "  types: [", `    { name: ${JSON.stringify(names.itemTypeName)}, folder: ${JSON.stringify(names.itemTypeFolder)} },`, "  ],", "  // ...plus statuses, fields, workflows, config, templates, and packages.", "});");
+  }
+  if (capability === "renderers") {
+    lines.push("", "export const toonRenderer = defineRendererOverride((context) => {", `  if (context.command !== ${JSON.stringify(commandName)}) return null;`, `  return ${JSON.stringify(`${extensionName}: `)} + JSON.stringify(context.result);`, "});");
+  }
+  if (capability === "parser") {
+    lines.push("", "export const pingParser = defineParserOverride((context) => {", "  const options = { ...context.options };", "  if (options.shout === true) options.upper = true;", "  delete options.shout;", "  return { options };", "});");
+  }
+  if (capability === "preflight") {
+    lines.push("", "// Return a delta of the gate-decision keys you want to change; returning", "// context.decision unchanged is a safe no-op (e.g. { run_extension_migrations: false }).", "export const preflightOverride = definePreflightOverride((context) => context.decision);");
+  }
+  if (capability === "services") {
+    lines.push("", "export const outputService = defineServiceOverride((context) => {", `  if (context.command !== ${JSON.stringify(commandName)}) return context.payload;`, `  return { rendered_by: ${JSON.stringify(extensionName)}, payload: context.payload };`, "});");
+  }
+  return lines;
+}
+function buildDefineBuilderActivate(commandName, capability, names) {
+  const lines = [];
+  if (capability === "renderers") {
+    lines.push('  api.registerRenderer("toon", toonRenderer);');
+  }
+  if (capability === "parser") {
+    lines.push(`  api.registerParser(${JSON.stringify(commandName)}, pingParser);`);
+  }
+  if (capability === "preflight") {
+    lines.push("  api.registerPreflight(preflightOverride);");
+  }
+  if (capability === "services") {
+    lines.push('  api.registerService("output_format", outputService);');
+  }
+  if (capability === "hooks") {
+    lines.push("  api.hooks.afterCommand(afterCommandHook);");
+  }
+  if (capability === "search") {
+    lines.push("  api.registerSearchProvider(searchProvider);", "  api.registerVectorStoreAdapter(vectorStoreAdapter);");
+  }
+  if (capability === "schema") {
+    lines.push("  api.registerItemFields([noteField]);", "  api.registerItemTypes([itemType]);", "  api.registerMigration(initMigration);");
+  }
+  if (capability === "profile") {
+    lines.push("  api.registerProfile(starterProfile);");
+  }
+  if (capability === "importers") {
+    lines.push(`  api.registerImporter(${JSON.stringify(names.adapterName)}, importer, {`, `    action: ${JSON.stringify(`${names.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(names.adapterName)}, exporter, {`, `    action: ${JSON.stringify(`${names.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.",', "      },", "    ],", "  });");
+  }
+  return lines;
+}
 function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary, capability = "commands", declarative = false) {
   const packageName = `pm-${extensionName}`;
   const capabilities = SCAFFOLD_MANIFEST_CAPABILITIES[capability];
@@ -1964,103 +2045,25 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
       "*.tsbuildinfo",
       ""
     ].join("\n");
-    const searchProviderName = `${extensionName}-search`;
-    const vectorAdapterName = `${extensionName}-vector`;
-    const adapterName = `${extensionName.replace(/-/g, " ")} items`;
-    const itemTypeName = extensionName;
-    const itemTypeFolder = `${extensionName}s`;
-    const itemTypeAlias = extensionName.replace(/-/g, "");
-    const itemTypeAliases = itemTypeAlias === itemTypeName ? [] : [itemTypeAlias];
-    const fieldName = `${extensionName.replace(/-/g, "_")}_note`;
-    const migrationId = `${extensionName}-0001-init`;
-    const defineBuilderImports = [
-      "defineCommand",
-      ...capability === "hooks" ? ["defineAfterCommandHook"] : [],
-      ...capability === "search" ? ["defineSearchProvider", "defineVectorStoreAdapter"] : [],
-      ...capability === "importers" ? ["defineImporter", "defineExporter"] : [],
-      ...capability === "schema" ? ["defineItemType", "defineItemField", "defineMigration"] : [],
-      ...capability === "profile" ? ["defineProjectProfile"] : [],
-      ...capability === "renderers" ? ["defineRendererOverride"] : [],
-      ...capability === "parser" ? ["defineParserOverride"] : [],
-      ...capability === "preflight" ? ["definePreflightOverride"] : [],
-      ...capability === "services" ? ["defineServiceOverride"] : []
-    ].join(", ");
+    const names = buildScaffoldSnippetNames(extensionName);
+    const defineBuilderImports = buildDefineBuilderImports(capability);
     const defineBuilderSnippet = [
       "```ts",
       `import { ${defineBuilderImports} } from "@unbrained/pm-cli/sdk";`,
       'import type { ExtensionApi } from "@unbrained/pm-cli/sdk";',
       "",
-      "export const pingCommand = defineCommand({",
-      `  name: ${JSON.stringify(commandName)},`,
-      '  description: "Starter scaffold command. Replace with your own behavior.",',
-      // The parser starter's command declares the flags its override normalizes so
-      // the demo is runnable through `pm <command> --shout`, and surfaces the
-      // canonical `upper` flag in the result.
-      ...capability === "parser" ? [
-        "  flags: [",
-        '    { long: "--shout", value_type: "boolean", description: "Deprecated alias for --upper." },',
-        '    { long: "--upper", value_type: "boolean", description: "Canonical flag the parser produces." },',
-        "  ],",
-        "  run: (context) => ({ ok: true, command: context.command, upper: context.options.upper === true }),"
-      ] : ["  run: (context) => ({ ok: true, command: context.command }),"],
-      "});"
+      ...buildDefineBuilderExports(extensionName, commandName, capability, names),
+      "",
+      "export function activate(api: ExtensionApi): void {",
+      "  api.registerCommand(pingCommand);",
+      ...buildDefineBuilderActivate(commandName, capability, names),
+      "}",
+      "",
+      "export function deactivate(): void {}",
+      "",
+      "export default { activate, deactivate };",
+      "```"
     ];
-    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,", "}));");
-    }
-    if (capability === "schema") {
-      defineBuilderSnippet.push("", `export const noteField = defineItemField({ name: ${JSON.stringify(fieldName)}, type: "string", optional: true });`, "", "export const itemType = defineItemType({", `  name: ${JSON.stringify(itemTypeName)},`, `  folder: ${JSON.stringify(itemTypeFolder)},`, `  aliases: ${JSON.stringify(itemTypeAliases)},`, "  required_create_fields: [],", "});", "", "export const initMigration = defineMigration({", `  id: ${JSON.stringify(migrationId)},`, `  description: ${JSON.stringify(`Initialize ${extensionName} schema state.`)},`, "  mandatory: false,", "  run: async (context) => ({ migrated: true, id: context.id }),", "});");
-    }
-    if (capability === "profile") {
-      defineBuilderSnippet.push("", "export const starterProfile = defineProjectProfile({", `  name: ${JSON.stringify(extensionName)},`, `  title: ${JSON.stringify(`${extensionName} archetype`)},`, '  summary: "Starter project profile. Replace these dimensions with your own archetype.",', "  types: [", `    { name: ${JSON.stringify(itemTypeName)}, folder: ${JSON.stringify(itemTypeFolder)} },`, "  ],", "  // ...plus statuses, fields, workflows, config, templates, and packages.", "});");
-    }
-    if (capability === "renderers") {
-      defineBuilderSnippet.push("", "export const toonRenderer = defineRendererOverride((context) => {", `  if (context.command !== ${JSON.stringify(commandName)}) return null;`, `  return ${JSON.stringify(`${extensionName}: `)} + JSON.stringify(context.result);`, "});");
-    }
-    if (capability === "parser") {
-      defineBuilderSnippet.push("", "export const pingParser = defineParserOverride((context) => {", "  const options = { ...context.options };", "  if (options.shout === true) options.upper = true;", "  delete options.shout;", "  return { options };", "});");
-    }
-    if (capability === "preflight") {
-      defineBuilderSnippet.push("", "// Return a delta of the gate-decision keys you want to change; returning", "// context.decision unchanged is a safe no-op (e.g. { run_extension_migrations: false }).", "export const preflightOverride = definePreflightOverride((context) => context.decision);");
-    }
-    if (capability === "services") {
-      defineBuilderSnippet.push("", "export const outputService = defineServiceOverride((context) => {", `  if (context.command !== ${JSON.stringify(commandName)}) return context.payload;`, `  return { rendered_by: ${JSON.stringify(extensionName)}, payload: context.payload };`, "});");
-    }
-    defineBuilderSnippet.push("", "export function activate(api: ExtensionApi): void {", "  api.registerCommand(pingCommand);");
-    if (capability === "renderers") {
-      defineBuilderSnippet.push('  api.registerRenderer("toon", toonRenderer);');
-    }
-    if (capability === "parser") {
-      defineBuilderSnippet.push(`  api.registerParser(${JSON.stringify(commandName)}, pingParser);`);
-    }
-    if (capability === "preflight") {
-      defineBuilderSnippet.push("  api.registerPreflight(preflightOverride);");
-    }
-    if (capability === "services") {
-      defineBuilderSnippet.push('  api.registerService("output_format", outputService);');
-    }
-    if (capability === "hooks") {
-      defineBuilderSnippet.push("  api.hooks.afterCommand(afterCommandHook);");
-    }
-    if (capability === "search") {
-      defineBuilderSnippet.push("  api.registerSearchProvider(searchProvider);", "  api.registerVectorStoreAdapter(vectorStoreAdapter);");
-    }
-    if (capability === "schema") {
-      defineBuilderSnippet.push("  api.registerItemFields([noteField]);", "  api.registerItemTypes([itemType]);", "  api.registerMigration(initMigration);");
-    }
-    if (capability === "profile") {
-      defineBuilderSnippet.push("  api.registerProfile(starterProfile);");
-    }
-    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(): void {}", "", "export default { activate, deactivate };", "```");
     const packageReadme = [
       `# ${packageName}`,
       "",
@@ -2193,7 +2196,7 @@ async function scaffoldExtensionProject(target, vocabulary = "extension", capabi
   const normalizedTarget = target.trim();
   const targetPath = path.resolve(process.cwd(), normalizedTarget);
   const extensionName = normalizeManagedDirectoryName(path.basename(targetPath));
-  const commandName = `${extensionName.replace(/-/g, " ")} ping`;
+  const commandName = buildScaffoldCommandName(extensionName);
   const scaffoldFiles = buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary, resolvedCapability, declarative);
   let createdDirectory = false;
   if (await pathExists(targetPath)) {
@@ -2334,6 +2337,17 @@ function renderSection(heading, level, entries) {
   lines.push(...entries.map((entry) => `- ${code(entry)}`), "");
   return lines;
 }
+function renderPreflightSection(count, level, includeEmpty) {
+  if (count === 0 && !includeEmpty) {
+    return [];
+  }
+  return [
+    `${headingPrefix(level)} Preflight overrides`,
+    "",
+    count > 0 ? `- ${count} registered (this surface carries no per-entry identifier)` : "_None._",
+    ""
+  ];
+}
 function renderExtensionSurfaceMarkdown(summary, options = {}) {
   const titleLevel = options.headingLevel ?? 2;
   if (!Number.isInteger(titleLevel) || titleLevel < MIN_HEADING_LEVEL || titleLevel > MAX_HEADING_LEVEL) {
@@ -2346,21 +2360,16 @@ function renderExtensionSurfaceMarkdown(summary, options = {}) {
   if (includeEmpty || summary.capabilities.length > 0) {
     lines.push(renderCapabilitiesLine(summary.capabilities), "");
   }
-  let renderedSurface = false;
   for (const [field, heading] of SURFACE_SECTIONS) {
     const entries = summary[field];
     if (entries.length === 0 && !includeEmpty) {
       continue;
     }
-    renderedSurface = renderedSurface || entries.length > 0;
     lines.push(...renderSection(heading, sectionLevel, entries));
   }
-  if (summary.preflight_overrides > 0 || includeEmpty) {
-    renderedSurface = renderedSurface || summary.preflight_overrides > 0;
-    lines.push(`${headingPrefix(sectionLevel)} Preflight overrides`, "");
-    lines.push(summary.preflight_overrides > 0 ? `- ${summary.preflight_overrides} registered (this surface carries no per-entry identifier)` : "_None._", "");
-  }
-  if (!renderedSurface && !includeEmpty) {
+  lines.push(...renderPreflightSection(summary.preflight_overrides, sectionLevel, includeEmpty));
+  const hasAnySurface = summary.preflight_overrides > 0 || SURFACE_SECTIONS.some(([field]) => summary[field].length > 0);
+  if (!hasAnySurface && !includeEmpty) {
     lines.push("_This extension registers no surfaces._", "");
   }
   return `${lines.join("\n").trimEnd()}
@@ -2430,6 +2439,6 @@ export {
   buildExtensionDescribeResult,
   renderExtensionDescribeMarkdown
 };
-//# sourceMappingURL=chunk-T7ZMQI4J.js.map
+//# sourceMappingURL=chunk-6AQZPVHQ.js.map
 
-//# debugId=cabc95dd-5428-533e-b3e2-d45eb7ef7409
+//# debugId=da6d1484-9f3c-56e4-a493-4b4296d741c1