@unbrained/pm-cli 2026.6.23 → 2026.6.24

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 2026.6.24 - 2026-06-24
+
+### Added
+
+- TypeScript-first extension & package scaffolding + SDK docs reframe ([pm-09rh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-09rh.toon))
+- Modular declarative authoring: mergeExtensionBlueprints + composeExtensionPackage ([pm-2p38](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-2p38.toon))
+- SDK unified author-time preflight capstone: preflightExtension + assertExtensionPreflight ([pm-ozaf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-ozaf.toon))
+- SDK author-time version-compatibility preflight: checkExtensionManifestCompatibility + assertExtensionManifestCompatible ([pm-1w0d](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-1w0d.toon))
+- SDK author-once manifest synthesis: synthesizeExtensionManifest + assertExtensionManifestMatchesBlueprint ([pm-u5le](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-u5le.toon))
+
+### Changed
+
+- Extract shared version-compat core (core/extensions/version-compat.ts); loader delegates, behavior-preserving ([pm-sjea](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-sjea.toon))
+
+### Other
+
+- Reframe SDK docs & docstrings TypeScript-first (SDK.md, EXTENSIONS.md, define\*/compose\*) ([pm-l2ud](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-l2ud.toon))
+- Scaffolder emits TypeScript: index.ts + tsconfig.json + build script, compiled ./index.js entry ([pm-frou](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-frou.toon))
+- defineExtensionBlueprint: typed identity helper for partial blueprint fragments ([pm-nvgy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-nvgy.toon))
+- composeExtensionPackage: author-once capstone returning { module, manifest } ([pm-cn0c](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-cn0c.toon))
+- mergeExtensionBlueprints: pure modular composition of partial ExtensionBlueprints ([pm-high](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-high.toon))
+- assertExtensionPreflight(blueprint, options) — throwing CI/test bookend (testing.ts) + barrel re-export ([pm-t8yl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-t8yl.toon))
+- preflightExtension(blueprint, options) — pure unified author-time analyzer (compose.ts) ([pm-tcw1](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-tcw1.toon))
+- assertExtensionManifestCompatible(manifest, target) — SDK testing assert ([pm-hng2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-hng2.toon))
+- checkExtensionManifestCompatibility(manifest, target) — pure author-time analyzer ([pm-knma](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-knma.toon))
+- assertExtensionManifestMatchesBlueprint(manifest, blueprint): strict least-privilege CI guard against capability drift ([pm-pfxi](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-pfxi.toon))
+- synthesizeExtensionManifest(blueprint, identity): generate a complete least-privilege ExtensionManifest from a blueprint ([pm-nr5j](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-nr5j.toon))
+
 ## 2026.6.23 - 2026-06-23
 
 ### Added

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

@@ -4,7 +4,7 @@
  * Implements extension package-management support for Scaffold.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4513e1ea-24a5-55b1-9465-78d5d9febba7")}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]="9eecdd82-fe71-5803-9186-a33244c4722d")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists } from "../../../core/fs/fs-utils.js";
@@ -25,6 +25,40 @@ const SCAFFOLD_DECLARED_PERMISSIONS = {
     env_write: false,
     process_spawn: false,
 };
+// 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";
+// `@types/node` floor for scaffolded packages: the colocated `index.test.ts`
+// imports `node:test`/`node:assert`, which need Node's ambient type definitions
+// to compile. Pinned to the engines floor (Node >=20), matching the CLI itself.
+const SCAFFOLD_TYPES_NODE_VERSION = "^20.0.0";
+// Strict NodeNext tsconfig emitted into every scaffold (ADR pm-2c28: extensions
+// are authored fully in TypeScript). It compiles `index.ts` (and the colocated
+// `index.test.ts`) in place to the `./index.js` entry the manifest loads, so the
+// authored source is type-checked against the SDK contracts while the loader keeps
+// importing plain compiled JavaScript. NodeNext resolution matches the explicit
+// `.js` import specifiers the emitted ESM uses. No `outDir` is set on purpose:
+// tsc auto-excludes its `outDir`, and an in-package `outDir` would exclude the
+// whole package root, leaving the `*.ts` inputs unmatched (TS18003). Emitting
+// beside the source mirrors the first-party `packages/pm-*` layout.
+const 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"],
+};
 /**
  * Capability shapes the package/extension scaffolder can target via the
  * `--capability` selector. `commands` emits the default command-only starter;
@@ -47,23 +81,24 @@ const SAMPLE_TEST_CAPABILITIES_LITERAL = {
     importers: '["commands", "schema", "importers"]',
 };
 const 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`).",
 };
 const 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.",
 };
+const TSCONFIG_BULLET = "- `tsconfig.json`: strict TypeScript config that compiles `index.ts` to the `./index.js` entry.";
 const 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",
@@ -73,7 +108,7 @@ const 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",
@@ -83,7 +118,7 @@ const 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`",
@@ -96,7 +131,7 @@ const 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;",
@@ -105,7 +140,7 @@ const 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",
@@ -114,7 +149,7 @@ const 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.",
@@ -253,8 +288,10 @@ function buildActivateBodyLines(extensionName, commandName, capability) {
     ];
 }
 /**
- * Build the colocated `node:test` sample suite for the chosen capability. Every
- * variant covers activation, command invocation, and teardown via the SDK
+ * Build the colocated `node:test` sample suite (`index.test.ts`) for the chosen
+ * capability. Authored in TypeScript and run through `npm test` (`tsc && node
+ * --test`), it imports the compiled `./index.js` entry under NodeNext resolution.
+ * Every variant covers activation, command invocation, and teardown via the SDK
  * testing helpers; the `hooks` variant adds a test that asserts the
  * `after_command` hook is registered and fires cleanly through the public SDK
  * testing helper `runRegisteredHookForTest`.
@@ -327,6 +364,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",',
@@ -335,11 +374,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"] }] });',
@@ -347,14 +386,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 }]);',
             "});",
@@ -402,6 +441,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 () => {`,
@@ -427,8 +469,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,
@@ -465,13 +513,15 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
         permissions: { ...SCAFFOLD_DECLARED_PERMISSIONS },
         capabilities,
     }, null, 2)}\n`;
-    // Keep scaffolds dependency-light by default: even package mode can be
-    // installed before peer dependencies are materialized in the generated root.
-    // The JSDoc import preserves editor narrowing without forcing the runtime
-    // loader to resolve @unbrained/pm-cli/sdk from a freshly generated scaffold.
+    // The entrypoint is authored fully in TypeScript (ADR pm-2c28): the `import
+    // type` is erased at compile time, so the typed `ExtensionApi` parameter is
+    // checked against the SDK contract at author time while the emitted ./index.js
+    // stays import-light. `npm run build` (tsc) compiles this index.ts to the
+    // ./index.js the manifest entry loads.
     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),
         "}",
         "",
@@ -479,7 +529,7 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
         "// 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,",
@@ -487,7 +537,8 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
         "};",
         "",
     ].join("\n");
-    // README bullet describing what index.js wires, kept in sync with the chosen
+    const tsconfig = `${JSON.stringify(SCAFFOLD_TSCONFIG, null, 2)}\n`;
+    // README bullet describing what index.ts wires, kept in sync with the chosen
     // capability so the generated docs match the generated code.
     const entrypointBullet = ENTRYPOINT_BULLETS[capability];
     if (vocabulary === "package") {
@@ -497,14 +548,21 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
             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: ["."],
@@ -524,7 +582,20 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
         // capability, the after_command lifecycle hook).
         const sampleTest = buildSampleTestSource(extensionName, commandName, capability);
         const sampleTestBullet = SAMPLE_TEST_BULLETS[capability];
-        const gitignore = ["node_modules/", "*.log", ""].join("\n");
+        // Ignore compiled TypeScript output wherever tsc emits it. Authors can add
+        // sibling or subdirectory modules, and tsc writes each .js next to its source.
+        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`;
@@ -535,8 +606,9 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
             ...(capability === "importers" ? ["defineImporter", "defineExporter"] : []),
         ].join(", ");
         const defineBuilderSnippet = [
-            "```js",
+            "```ts",
             `import { ${defineBuilderImports} } from "@unbrained/pm-cli/sdk";`,
+            'import type { ExtensionApi } from "@unbrained/pm-cli/sdk";',
             "",
             "export const pingCommand = defineCommand({",
             `  name: ${JSON.stringify(commandName)},`,
@@ -553,7 +625,7 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
         if (capability === "importers") {
             defineBuilderSnippet.push("", "export const importer = defineImporter(async (context) => ({", "  imported: 1,", "  source: context.options.source ?? \"starter\",", "  args: context.args,", "}));", "", "export const exporter = defineExporter(async (context) => ({", "  exported: true,", "  destination: context.options.destination ?? \"stdout\",", "  args: context.args,", "}));");
         }
-        defineBuilderSnippet.push("", "export function activate(api) {", "  api.registerCommand(pingCommand);");
+        defineBuilderSnippet.push("", "export function activate(api: ExtensionApi): void {", "  api.registerCommand(pingCommand);");
         if (capability === "hooks") {
             defineBuilderSnippet.push("  api.hooks.afterCommand(afterCommandHook);");
         }
@@ -563,40 +635,47 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
         if (capability === "importers") {
             defineBuilderSnippet.push(`  api.registerImporter(${JSON.stringify(adapterName)}, importer, {`, `    action: ${JSON.stringify(`${adapterName} import`)},`, '    description: "Import starter records into pm context.",', "    flags: [", "      {", '        long: "--source",', '        value_name: "name",', '        value_type: "string",', '        description: "Source name or path to import from.",', "      },", "    ],", "  });", `  api.registerExporter(${JSON.stringify(adapterName)}, exporter, {`, `    action: ${JSON.stringify(`${adapterName} export`)},`, '    description: "Export pm context into starter records.",', "    flags: [", "      {", '        long: "--destination",', '        value_name: "name",', '        value_type: "string",', '        description: "Destination name or path to export to.",', "      },", "    ],", "  });");
         }
-        defineBuilderSnippet.push("}", "", "export function deactivate() {}", "", "export default { activate, deactivate };", "```");
+        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.js` stays import-free so the package can be installed locally before",
-            "`npm install` materializes peer dependencies. After installing dependencies,",
-            "use the public SDK authoring builders for exported definitions you want",
-            "editor type-checking, contextual handler inference, and direct unit tests for:",
+            "`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`.",
@@ -612,8 +691,8 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
             "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.",
             "",
@@ -621,8 +700,9 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
         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,
         };
@@ -635,9 +715,16 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
         "## 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",
@@ -654,14 +741,15 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
         "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,
     };
 }
@@ -730,4 +818,4 @@ export async function scaffoldExtensionProject(target, vocabulary = "extension",
     };
 }
 //# sourceMappingURL=scaffold.js.map
-//# debugId=4513e1ea-24a5-55b1-9465-78d5d9febba7
+//# debugId=9eecdd82-fe71-5803-9186-a33244c4722d