@unbrained/pm-cli 2026.6.30 → 2026.7.1

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

@@ -4,12 +4,14 @@
  * 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]="8a2ebc7a-02de-579c-8cf2-dbbbd401e622")}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]="9cc4cb5f-313d-5e8c-8c63-545a7a8d2a03")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
+import { EXECUTABLE_COMMAND_ALIASES } from "../../bootstrap-args.js";
 import { pathExists } from "../../../core/fs/fs-utils.js";
 import { EXIT_CODE } from "../../../core/shared/constants.js";
 import { PmCliError } from "../../../core/shared/errors.js";
+import { PM_CORE_COMMAND_NAMES } from "../../../sdk/cli-contracts.js";
 import { normalizeManagedDirectoryName } from "./shared.js";
 // Safe compatibility floor emitted into scaffolded manifests. The current
 // starters are loaded as TypeScript and use the SDK define*/testing helpers; the
@@ -26,6 +28,13 @@ const SCAFFOLD_DECLARED_PERMISSIONS = {
     env_write: false,
     process_spawn: false,
 };
+const RESERVED_SCAFFOLD_COMMAND_ROOTS = 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",
+]);
 // TypeScript dev-dependency floor for scaffolded packages, matching the CLI's own
 // toolchain so generated packages compile against the same compiler generation.
 const SCAFFOLD_TYPESCRIPT_VERSION = "^6.0.0";
@@ -34,6 +43,25 @@ const SCAFFOLD_TYPESCRIPT_VERSION = "^6.0.0";
 // to type-check. Pinned to the engines floor (Node >=22.18), matching the CLI
 // itself — the version where Node strips TypeScript types on load by default.
 const SCAFFOLD_TYPES_NODE_VERSION = "^22.0.0";
+const 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.",
+    "    }",
+    "  }",
+    "}",
+    "",
+];
+const SAMPLE_HARNESS_FINALLY_LINES = [
+    "  } finally {",
+    "    await deactivateIfNeeded(ext, deactivated);",
+    "  }",
+];
 // Strict NodeNext tsconfig emitted into every scaffold (ADR pm-2c28 / pm-m1uz:
 // extensions are authored AND loaded as TypeScript). It is a type-check-only
 // config (`noEmit`): there is no compile step — pm loads the `./index.ts`
@@ -448,6 +476,33 @@ function buildScaffoldActivationReadmeSection(capability, vocabulary) {
     }
     return LAZY_ACTIVATION_README_SECTION[vocabulary];
 }
+/**
+ * Builds the starter command path from the normalized package/extension name.
+ * Names that start with a built-in pm command or executable alias are prefixed
+ * with `starter` so the generated command dispatches to the package instead of
+ * being consumed by core command parsing.
+ */
+export 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 !== undefined && 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`;
+}
 /**
  * Build the project-profile archetype object literal the `profile` starter
  * registers — a complete {@link ProjectProfileDefinition} derived from the package
@@ -905,13 +960,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,
             "});",
             "",
         ]
@@ -963,13 +1012,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,
             "});",
             "",
         ]
@@ -1004,13 +1047,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,
             "});",
             "",
         ]
@@ -1041,13 +1078,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 +1102,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,
             "});",
             "",
         ]
@@ -1117,13 +1142,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,
             "});",
             "",
         ]
@@ -1169,13 +1188,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,
             "});",
             "",
         ]
@@ -1215,13 +1228,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,
             "});",
             "",
         ]
@@ -1260,13 +1267,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,
             "});",
             "",
         ]
@@ -1282,6 +1283,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.",
@@ -1321,13 +1323,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,
@@ -1629,13 +1625,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":
@@ -1928,6 +1918,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",
@@ -1986,13 +1977,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),
@@ -2088,6 +2073,133 @@ function buildDeclarativePackageReadme(packageName, commandName, capability) {
         "",
     ].join("\n");
 }
+/**
+ * Project the {@link ScaffoldSnippetNames} for `extensionName`, omitting a
+ * redundant self-alias when the de-hyphenated form already equals the type name.
+ */
+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`,
+    };
+}
+/**
+ * Build the comma-separated `define*` builder import list for the README
+ * snippet, including only the builders the chosen capability demonstrates.
+ */
+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(", ");
+}
+/**
+ * Build the exported `define*` declarations for the README snippet: the base
+ * `pingCommand` (with parser flags for the parser capability) plus the one
+ * capability-specific export the chosen capability demonstrates.
+ */
+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") {
+        // Abbreviated illustration; the generated index.ts populates every archetype
+        // dimension (types, statuses, fields, workflow, config, template, packages).
+        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;
+}
+/**
+ * Build the `activate` body registrations for the README snippet: one
+ * `api.register*`/`api.hooks.*` call wiring the capability-specific exports
+ * produced by {@link buildDefineBuilderExports}.
+ */
+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;
+}
 /**
  * Implements build starter extension scaffold files for the public runtime surface of this module.
  */
@@ -2204,108 +2316,25 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
             "*.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, "");
-        // Omit a redundant self-alias when the de-hyphenated form equals the type name.
-        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") {
-            // Abbreviated illustration; the generated index.ts populates every archetype
-            // dimension (types, statuses, fields, workflow, config, template, packages).
-            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}`,
             "",
@@ -2450,10 +2479,9 @@ export async function scaffoldExtensionProject(target, vocabulary = "extension",
     const normalizedTarget = target.trim();
     const targetPath = path.resolve(process.cwd(), normalizedTarget);
     const extensionName = normalizeManagedDirectoryName(path.basename(targetPath));
-    // Hyphenated top-level command groups can surface in help but fail dispatch in
-    // Commander, so generated starters use space-separated command words while the
-    // manifest and package identity keep their normalized directory names.
-    const commandName = `${extensionName.replace(/-/g, " ")} ping`;
+    // Hyphenated names become space-separated command words; reserved roots get a
+    // `starter` prefix so core commands and aliases cannot intercept dispatch.
+    const commandName = buildScaffoldCommandName(extensionName);
     const scaffoldFiles = buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary, resolvedCapability, declarative);
     let createdDirectory = false;
     if (await pathExists(targetPath)) {
@@ -2504,4 +2532,4 @@ export async function scaffoldExtensionProject(target, vocabulary = "extension",
     };
 }
 //# sourceMappingURL=scaffold.js.map
-//# debugId=8a2ebc7a-02de-579c-8cf2-dbbbd401e622
+//# debugId=9cc4cb5f-313d-5e8c-8c63-545a7a8d2a03