@unbrained/pm-cli 2026.6.22 → 2026.6.24

package/dist/cli-bundle/chunks/{chunk-YJICYNAV.js → chunk-MWMHZOZZ.js}

@@ -5,26 +5,26 @@ import {
   normalizeReplayPatchOps,
   tryApplyReplayPatch,
   verifyHistoryChain
-} from "./chunk-YQSWTVZF.js";
+} from "./chunk-WB5BYQMF.js";
 import {
   parseLimit
-} from "./chunk-EVPVCE4R.js";
+} from "./chunk-V4UYNSEM.js";
 import {
   enforceHistoryStreamPolicyForItem,
   hashDocument,
   hashEmptyDocument,
   locateItem,
   readLocatedItem
-} from "./chunk-GGAXE22C.js";
+} from "./chunk-KJZOSF7J.js";
 import {
   normalizeItemId
-} from "./chunk-Y4BZEND6.js";
+} from "./chunk-FBLT6WGK.js";
 import {
   findFirstMergeConflictMarker
-} from "./chunk-P7ZU73BO.js";
+} from "./chunk-ZLWRPBOW.js";
 import {
   resolveItemTypeRegistry
-} from "./chunk-KK4TQ3ZP.js";
+} from "./chunk-TKPP4GOO.js";
 import {
   EXIT_CODE,
   PmCliError,
@@ -36,7 +36,7 @@ import {
   readSettings,
   resolvePmRoot,
   runActiveOnReadHooks
-} from "./chunk-KL5ELX2X.js";
+} from "./chunk-VSAABFGQ.js";
 
 // dist/core/history/history-diff.js
 function decodeJsonPointerSegment(segment) {
@@ -264,6 +264,6 @@ export {
   readHistoryEntries,
   runHistory
 };
-//# sourceMappingURL=chunk-YJICYNAV.js.map
+//# sourceMappingURL=chunk-MWMHZOZZ.js.map
 
 //# debugId=bcfc5ee3-530b-5b04-8b4c-6510049c5b19

package/dist/cli-bundle/chunks/{chunk-SFKQAVZA.js → chunk-N5B6WZC5.js}

@@ -15,27 +15,27 @@ import {
   parseLinkedTestMinLines,
   parseLinkedTestRegexList,
   parseLinkedTestStringList
-} from "./chunk-NIWY4V4Z.js";
+} from "./chunk-AYPQUFCX.js";
 import {
   createStdinTokenResolver,
   parseCsvKv,
   parseOptionalNumber
-} from "./chunk-K25UDYJ4.js";
+} from "./chunk-KIEAK7YE.js";
 import {
   runInit
-} from "./chunk-YATDFWYK.js";
+} from "./chunk-EWRSXOIZ.js";
 import {
   locateItem,
   mutateItem,
   readLocatedItem
-} from "./chunk-GGAXE22C.js";
+} from "./chunk-KJZOSF7J.js";
 import {
   resolveItemTypeRegistry
-} from "./chunk-KK4TQ3ZP.js";
+} from "./chunk-TKPP4GOO.js";
 import {
   compareTimestampStrings,
   nowIso
-} from "./chunk-PCH2JTEO.js";
+} from "./chunk-FMWW2JDU.js";
 import {
   EXIT_CODE,
   ITEM_FILE_EXTENSIONS,
@@ -48,7 +48,7 @@ import {
   resolveGlobalPmRoot,
   resolvePmRoot,
   stableValueEquals
-} from "./chunk-KL5ELX2X.js";
+} from "./chunk-VSAABFGQ.js";
 
 // dist/cli/commands/test.js
 import { spawn } from "node:child_process";
@@ -1884,6 +1884,6 @@ export {
   runTest,
   _testOnlyTestCommand
 };
-//# sourceMappingURL=chunk-SFKQAVZA.js.map
+//# sourceMappingURL=chunk-N5B6WZC5.js.map
 
 //# debugId=eca9038d-c58d-57e0-9b7d-a32f72ff68b8

package/dist/cli-bundle/chunks/{chunk-3GL6LTUL.js → chunk-NJ73ALW2.js}

@@ -1,13 +1,13 @@
 
-!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]="d666bfbb-94ee-5886-993c-ca3e13327017")}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]="e68ba064-77cc-5c36-bb28-275d9fe97142")}catch(e){}}();
 import {
   normalizeManagedDirectoryName
-} from "./chunk-DMT4ODVN.js";
+} from "./chunk-J3NMWFIN.js";
 import {
   EXIT_CODE,
   PmCliError,
   pathExists
-} from "./chunk-KL5ELX2X.js";
+} from "./chunk-VSAABFGQ.js";
 
 // dist/cli/commands/extension/scaffold.js
 import fs from "node:fs/promises";
@@ -22,6 +22,26 @@ var SCAFFOLD_DECLARED_PERMISSIONS = {
   env_write: false,
   process_spawn: false
 };
+var SCAFFOLD_TYPESCRIPT_VERSION = "^6.0.0";
+var SCAFFOLD_TYPES_NODE_VERSION = "^20.0.0";
+var SCAFFOLD_TSCONFIG = {
+  compilerOptions: {
+    target: "ES2022",
+    module: "NodeNext",
+    moduleResolution: "NodeNext",
+    strict: true,
+    esModuleInterop: true,
+    skipLibCheck: true,
+    declaration: false,
+    // `node:test`/`node:assert` in the colocated test (and Node globals) resolve
+    // from `@types/node`; name it explicitly so it is loaded regardless of how the
+    // package manager lays out `node_modules/@types`.
+    types: ["node"]
+  },
+  // Recursive so a package that grows into subdirectory `*.ts` modules still
+  // type-checks and compiles them; tsc excludes `node_modules` by default.
+  include: ["**/*.ts"]
+};
 var SCAFFOLD_CAPABILITIES = ["commands", "hooks", "search", "importers"];
 var SCAFFOLD_MANIFEST_CAPABILITIES = {
   commands: ["commands"],
@@ -36,23 +56,24 @@ var SAMPLE_TEST_CAPABILITIES_LITERAL = {
   importers: '["commands", "schema", "importers"]'
 };
 var ENTRYPOINT_BULLETS = {
-  commands: "- `index.js`: starter command registration plus a `deactivate` teardown stub.",
-  hooks: "- `index.js`: starter command registration, an `after_command` lifecycle hook, and a `deactivate` teardown stub.",
-  search: "- `index.js`: starter command registration, a search provider, a vector-store adapter, and a `deactivate` teardown stub.",
-  importers: "- `index.js`: starter command registration, importer/exporter command registrations, and a `deactivate` teardown stub."
+  commands: "- `index.ts`: starter command registration plus a `deactivate` teardown stub (compiled to `index.js`).",
+  hooks: "- `index.ts`: starter command registration, an `after_command` lifecycle hook, and a `deactivate` teardown stub (compiled to `index.js`).",
+  search: "- `index.ts`: starter command registration, a search provider, a vector-store adapter, and a `deactivate` teardown stub (compiled to `index.js`).",
+  importers: "- `index.ts`: starter command registration, importer/exporter command registrations, and a `deactivate` teardown stub (compiled to `index.js`)."
 };
 var SAMPLE_TEST_BULLETS = {
-  commands: "- `index.test.js`: sample `node:test` suite covering activation, command invocation, and teardown via the SDK testing helpers.",
-  hooks: "- `index.test.js`: sample `node:test` suite covering activation, command invocation, the after_command hook, and teardown via the SDK testing helpers.",
-  search: "- `index.test.js`: sample `node:test` suite covering activation, command invocation, search provider/vector adapter invocation, and teardown via the SDK testing helpers.",
-  importers: "- `index.test.js`: sample `node:test` suite covering activation, command invocation, importer/exporter invocation, and teardown via the SDK testing helpers."
+  commands: "- `index.test.ts`: sample `node:test` suite covering activation, command invocation, and teardown via the SDK testing helpers.",
+  hooks: "- `index.test.ts`: sample `node:test` suite covering activation, command invocation, the after_command hook, and teardown via the SDK testing helpers.",
+  search: "- `index.test.ts`: sample `node:test` suite covering activation, command invocation, search provider/vector adapter invocation, and teardown via the SDK testing helpers.",
+  importers: "- `index.test.ts`: sample `node:test` suite covering activation, command invocation, importer/exporter invocation, and teardown via the SDK testing helpers."
 };
+var TSCONFIG_BULLET = "- `tsconfig.json`: strict TypeScript config that compiles `index.ts` to the `./index.js` entry.";
 var PACKAGE_CAPABILITY_README_SECTIONS = {
   commands: [],
   hooks: [
     "",
     "## Lifecycle Hook",
-    "`index.js` registers an `after_command` hook via `api.hooks.afterCommand`.",
+    "`index.ts` registers an `after_command` hook via `api.hooks.afterCommand`.",
     "pm fires it once a command finishes, passing the command outcome and the",
     "items it mutated (`context.affected`). React there to keep external context",
     "in sync - sync records, emit telemetry, or refresh derived state. The",
@@ -62,7 +83,7 @@ var PACKAGE_CAPABILITY_README_SECTIONS = {
   search: [
     "",
     "## Search Provider",
-    "`index.js` registers a deterministic in-memory search provider and",
+    "`index.ts` registers a deterministic in-memory search provider and",
     "vector-store adapter through `api.registerSearchProvider` and",
     "`api.registerVectorStoreAdapter`. Replace the sample scoring,",
     "embedding, and storage behavior with your project-specific retrieval",
@@ -72,7 +93,7 @@ var PACKAGE_CAPABILITY_README_SECTIONS = {
   importers: [
     "",
     "## Importer and Exporter",
-    "`index.js` registers paired project-context import/export commands through",
+    "`index.ts` registers paired project-context import/export commands through",
     "`api.registerImporter` and `api.registerExporter`. Replace the starter",
     "payloads with your domain adapter: GitHub issues, CSV rows, documents,",
     "tickets, or another project-management source of truth. The `importers`",
@@ -85,7 +106,7 @@ var EXTENSION_CAPABILITY_README_SECTIONS = {
   hooks: [
     "",
     "## Lifecycle Hook",
-    "`index.js` registers an `after_command` hook via `api.hooks.afterCommand`.",
+    "`index.ts` registers an `after_command` hook via `api.hooks.afterCommand`.",
     "pm fires it once a command finishes, passing the command outcome and the",
     "items it mutated (`context.affected`). React there to keep external context",
     "in sync. The `hooks` capability in `manifest.json` grants the registration;",
@@ -94,7 +115,7 @@ var EXTENSION_CAPABILITY_README_SECTIONS = {
   search: [
     "",
     "## Search Provider",
-    "`index.js` registers a deterministic in-memory search provider and",
+    "`index.ts` registers a deterministic in-memory search provider and",
     "vector-store adapter through `api.registerSearchProvider` and",
     "`api.registerVectorStoreAdapter`. Replace the sample scoring, embedding,",
     "and storage behavior with your project-specific retrieval logic. The",
@@ -103,7 +124,7 @@ var EXTENSION_CAPABILITY_README_SECTIONS = {
   importers: [
     "",
     "## Importer and Exporter",
-    "`index.js` registers paired project-context import/export commands through",
+    "`index.ts` registers paired project-context import/export commands through",
     "`api.registerImporter` and `api.registerExporter`. Replace the starter",
     "payloads with your domain adapter. The `importers` capability grants both",
     "registrations, and `schema` grants the example command flag metadata."
@@ -300,6 +321,8 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     `    extensionName: ${JSON.stringify(extensionName)},`,
     "  });",
     "",
+    "  // The starter provider reads only document title/id, so `settings` is a",
+    "  // minimal typed stub and `documents` carry just the fields it inspects.",
     "  const query = await runRegisteredSearchProviderForTest(activation.registrations, {",
     `    provider: ${JSON.stringify(searchProviderName)},`,
     '    operation: "query",',
@@ -308,11 +331,11 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     '      mode: "semantic",',
     '      tokens: ["sync"],',
     "      options: {},",
-    "      settings: {},",
+    "      settings: {} as PmSettings,",
     "      documents: [",
     '        { metadata: { id: "pm-1", title: "Sync external context" }, body: "" },',
     '        { metadata: { id: "pm-2", title: "Unrelated task" }, body: "" },',
-    "      ],",
+    "      ] as ItemDocument[],",
     "    },",
     "  });",
     '  assert.deepEqual(query, { hits: [{ id: "pm-1", score: 1, matched_fields: ["title"] }] });',
@@ -320,14 +343,14 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     "  const embedding = await runRegisteredSearchProviderForTest(activation.registrations, {",
     `    provider: ${JSON.stringify(searchProviderName)},`,
     '    operation: "embed",',
-    '    context: { input: "abc", settings: {}, model: "starter-model" },',
+    '    context: { input: "abc", settings: {} as PmSettings, model: "starter-model" },',
     "  });",
     "  assert.deepEqual(embedding, [3]);",
     "",
     "  const vectorHits = await runRegisteredVectorStoreAdapterForTest(activation.registrations, {",
     `    adapter: ${JSON.stringify(vectorAdapterName)},`,
     '    operation: "query",',
-    "    context: { vector: [0.1, 0.2], limit: 2, settings: {} },",
+    "    context: { vector: [0.1, 0.2], limit: 2, settings: {} as PmSettings },",
     "  });",
     '  assert.deepEqual(vectorHits, [{ id: "starter-vector-hit", score: 2 }]);',
     "});",
@@ -372,6 +395,9 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     "import {",
     ...importNames,
     '} from "@unbrained/pm-cli/sdk/testing";',
+    // The search sample's synthetic query/vector contexts reference these SDK types
+    // for their typed-stub fixtures; other capabilities need no extra type imports.
+    ...searchEnabled ? ['import type { ItemDocument, PmSettings } from "@unbrained/pm-cli/sdk";'] : [],
     'import extension from "./index.js";',
     "",
     `test(${JSON.stringify(`${extensionName} registers its starter command`)}, async () => {`,
@@ -397,8 +423,14 @@ function buildSampleTestSource(extensionName, commandName, capability) {
     `    command: ${JSON.stringify(commandName)},`,
     "  });",
     "  assert.equal(invocation.handled, true);",
-    "  assert.equal(invocation.result.ok, true);",
-    `  assert.equal(invocation.result.command, ${JSON.stringify(commandName)});`,
+    "  // The handler result is typed `unknown`, so deep-equality on the whole",
+    "  // structured payload keeps the assertion type-safe without a cast.",
+    "  assert.deepEqual(invocation.result, {",
+    "    ok: true,",
+    `    source: ${JSON.stringify(extensionName)},`,
+    `    command: ${JSON.stringify(commandName)},`,
+    '    message: "Starter extension scaffold is active.",',
+    "  });",
     "});",
     "",
     ...hookTestLines,
@@ -434,8 +466,9 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
   }, null, 2)}
 `;
   const entrypoint = [
-    '/** @param {import("@unbrained/pm-cli/sdk").ExtensionApi} api */',
-    "export function activate(api) {",
+    'import type { ExtensionApi } from "@unbrained/pm-cli/sdk";',
+    "",
+    "export function activate(api: ExtensionApi): void {",
     ...buildActivateBodyLines(extensionName, commandName, capability),
     "}",
     "",
@@ -443,7 +476,7 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
     "// shutdown/reload (e.g. the MCP server between requests) to release anything",
     "// `activate` opened - timers, connections, caches. This starter holds no such",
     "// resources, so it stays a documented no-op; add cleanup here as you grow.",
-    "export function deactivate() {}",
+    "export function deactivate(): void {}",
     "",
     "export default {",
     "  activate,",
@@ -451,6 +484,8 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
     "};",
     ""
   ].join("\n");
+  const tsconfig = `${JSON.stringify(SCAFFOLD_TSCONFIG, null, 2)}
+`;
   const entrypointBullet = ENTRYPOINT_BULLETS[capability];
   if (vocabulary === "package") {
     const packageJson = `${JSON.stringify({
@@ -459,14 +494,21 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
       private: true,
       type: "module",
       keywords: ["pm-package"],
-      // `node --test` runs the colocated *.test.js sample against the peer SDK
-      // testing helpers; no extra dev-dependency or test runner is required.
+      // `build` compiles index.ts to the ./index.js the manifest loads; `test`
+      // compiles first (Node's `node --test` runs the emitted *.test.js, not the
+      // TypeScript source) then runs the colocated sample against the peer SDK
+      // testing helpers — no third-party test runner required.
       scripts: {
-        test: "node --test"
+        build: "tsc",
+        test: "tsc && node --test"
       },
       peerDependencies: {
         "@unbrained/pm-cli": "*"
       },
+      devDependencies: {
+        "@types/node": SCAFFOLD_TYPES_NODE_VERSION,
+        typescript: SCAFFOLD_TYPESCRIPT_VERSION
+      },
       pm: {
         aliases: [extensionName],
         extensions: ["."],
@@ -483,34 +525,101 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
 `;
     const sampleTest = buildSampleTestSource(extensionName, commandName, capability);
     const sampleTestBullet = SAMPLE_TEST_BULLETS[capability];
-    const gitignore = ["node_modules/", "*.log", ""].join("\n");
+    const gitignore = [
+      "node_modules/",
+      "*.log",
+      "",
+      "# Compiled TypeScript output (npm run build)",
+      "*.js",
+      "*.test.js",
+      "*.js.map",
+      "*.d.ts",
+      "*.d.ts.map",
+      ""
+    ].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 = [
+      "```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.",',
+      "  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: ExtensionApi): void {", "  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(): void {}", "", "export default { activate, deactivate };", "```");
     const packageReadme = [
       `# ${packageName}`,
       "",
       "Generated by `pm package init`.",
       "",
       "## Included Files",
-      "- `package.json`: package metadata, `test` script, and `pm` resource manifest.",
+      "- `package.json`: package metadata, `build`/`test` scripts, and `pm` resource manifest.",
       "- `manifest.json`: extension metadata and capabilities.",
       entrypointBullet,
       sampleTestBullet,
-      "- `.gitignore`: ignores `node_modules/` and log files.",
+      TSCONFIG_BULLET,
+      "- `.gitignore`: ignores `node_modules/`, logs, and compiled JavaScript/declaration output.",
       "",
       "## Quick Start",
+      "This package is authored in TypeScript; build it once so the manifest's",
+      "`./index.js` entry exists, then install it:",
       "```bash",
+      "npm install",
+      "npm run build",
       "pm install --project <package-path>",
       `pm ${commandName}`,
       "pm package doctor --project --detail summary",
       "```",
       "",
       "## Validate the Package",
-      "Install the peer SDK once, then run the colocated sample test:",
+      "`npm install` pulls the peer SDK and TypeScript; `npm test` compiles and runs",
+      "the colocated sample test:",
       "```bash",
       "npm install",
       "npm test",
       "```",
-      "`npm test` runs `node --test`, which executes `index.test.js` against the",
+      "`npm test` runs `tsc && node --test`: it compiles `index.ts`/`index.test.ts`",
+      "then executes the emitted `index.test.js` against the",
       "`@unbrained/pm-cli/sdk/testing` helpers - no extra test runner required.",
+      "",
+      "## Authoring With define* Builders",
+      "`index.ts` is authored fully in TypeScript so every registration is checked",
+      "against the SDK contracts at author time. Use the public SDK authoring",
+      "builders for exported definitions you want literal-type preservation,",
+      "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",
@@ -523,8 +632,8 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
       '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`.',
       "",
       "## Notes",
-      "- Keep simple starter runtime behavior at the package root so local installs work without dependency bootstrapping.",
-      "- Move larger runtimes into subdirectories only after adding package dependencies and validating `pm package doctor`.",
+      "- Author in `index.ts`; `npm run build` (tsc) emits the `./index.js` the manifest loads, so rebuild after editing before installing or reloading.",
+      "- Move larger runtimes into sibling or subdirectory `*.ts` modules and import them; `tsconfig.json` compiles every `*.ts` in the package (recursively).",
       "- Add capabilities to the extension manifest only when the entrypoint uses the matching SDK API.",
       "- Use `@unbrained/pm-cli/sdk` as the public SDK import for richer package runtimes.",
       ""
@@ -532,8 +641,9 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
     return {
       "package.json": packageJson,
       "manifest.json": manifest,
-      "index.js": entrypoint,
-      "index.test.js": sampleTest,
+      "index.ts": entrypoint,
+      "index.test.ts": sampleTest,
+      "tsconfig.json": tsconfig,
       ".gitignore": gitignore,
       "README.md": packageReadme
     };
@@ -546,9 +656,16 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
     "## Included Files",
     "- `manifest.json`: extension metadata and capabilities.",
     entrypointBullet,
+    TSCONFIG_BULLET,
     "",
     "## Quick Start",
+    "This extension is authored in TypeScript; compile `index.ts` to the manifest's",
+    "`./index.js` entry, then install it. The SDK types resolve once",
+    "`@unbrained/pm-cli` is available to the compiler (install it, Node types, and TypeScript, or",
+    "build from a project that already depends on the CLI):",
     "```bash",
+    "npm install -D typescript @types/node @unbrained/pm-cli",
+    "npx tsc",
     "pm extension --install --project <scaffold-path>",
     `pm ${commandName}`,
     "pm extension --doctor --project --detail summary",
@@ -565,14 +682,15 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
     '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`.',
     "",
     "## Notes",
-    "- This scaffold uses ESM exports so it works in package scopes with `type: module`.",
-    "- Update `manifest.json` capabilities and `index.js` command behavior as your extension evolves.",
+    "- This scaffold uses TypeScript ESM source compiled to ESM output, so it works in package scopes with `type: module`.",
+    "- Author in `index.ts` and recompile to `index.js` (the manifest entry) after editing capabilities or command behavior.",
     "- Release any resources `activate` opens (timers, connections, caches) in the `deactivate` teardown hook.",
     ""
   ].join("\n");
   return {
     "manifest.json": manifest,
-    "index.js": entrypoint,
+    "index.ts": entrypoint,
+    "tsconfig.json": tsconfig,
     "README.md": readme
   };
 }
@@ -638,6 +756,6 @@ export {
   SCAFFOLD_CAPABILITIES,
   scaffoldExtensionProject
 };
-//# sourceMappingURL=chunk-3GL6LTUL.js.map
+//# sourceMappingURL=chunk-NJ73ALW2.js.map
 
-//# debugId=d666bfbb-94ee-5886-993c-ca3e13327017
+//# debugId=e68ba064-77cc-5c36-bb28-275d9fe97142