@unbrained/pm-cli 2026.6.22 → 2026.6.24

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

@@ -0,0 +1,70 @@
+/**
+ * @module cli/commands/extension/describe
+ *
+ * Builds the `pm extension describe` / `pm package describe` payload: a flat,
+ * by-name map of every surface each loaded extension registered.
+ *
+ * The SDK already ships {@link describeExtensionActivation} -- the `describe`
+ * (enumerate-all) verb that complements the `assert*` (verify-one) and `run*`
+ * (invoke-one) testing helpers -- but until now it was reachable only from a test
+ * that hand-built an {@link ExtensionActivationResult}. This module is the thin
+ * orchestration that lets an agent at the CLI (or over MCP) ask "what does this
+ * installed extension add to my context?" in one call, instead of stitching
+ * together `doctor` (errors), `manage` (update metadata), and a manifest read.
+ *
+ * It is intentionally pure: the caller performs the load+activate cycle (exactly
+ * as `explore`/`doctor` already do) and hands the results here, so the same
+ * builder is trivially unit-testable against synthetic activations.
+ */
+import { type ExtensionActivationSummary } from "../../../core/extensions/activation-summary.js";
+import type { ExtensionActivationResult, ExtensionLayer, ExtensionLoadResult } from "../../../core/extensions/loader.js";
+/**
+ * Runtime state of a described extension. `ok` loaded and activated cleanly,
+ * `failed` loaded but threw during `activate`, and `not_loaded` failed to import
+ * at all -- the latter two register nothing, so their `surfaces` are empty and
+ * the status explains why (rather than implying the extension contributes
+ * nothing).
+ */
+export type ExtensionDescribeActivationStatus = "ok" | "failed" | "not_loaded";
+/**
+ * One extension's contribution to the workspace: its identity plus the
+ * {@link ExtensionActivationSummary} of every surface it registered.
+ *
+ * `surfaces` is matched by extension *name* (mirroring
+ * {@link describeExtensionActivation}'s name filter), so when the same name is
+ * loaded in both the project and global layers each entry reflects that name's
+ * combined surfaces -- the `layer`/`version` fields still distinguish the
+ * physical entries.
+ */
+export interface ExtensionSurfaceDescription {
+    name: string;
+    layer: ExtensionLayer;
+    version: string;
+    activation_status: ExtensionDescribeActivationStatus;
+    surfaces: ExtensionActivationSummary;
+}
+/**
+ * Result of {@link buildExtensionDescribeResult}: the per-extension surface maps
+ * plus a deduplicated `union` across the described set. `target` echoes the
+ * requested name filter (or `null` for the whole workspace) and `total` counts
+ * the described entries so callers need not re-measure `extensions`.
+ */
+export interface ExtensionDescribeResult {
+    target: string | null;
+    total: number;
+    extensions: ExtensionSurfaceDescription[];
+    union: ExtensionActivationSummary;
+}
+/**
+ * Summarize, by name, every registration surface the loaded extensions exercised.
+ *
+ * Walks `loadResult.loaded` (annotating each with `failed` when its layer+name is
+ * in `activationResult.failed`) and `loadResult.failed` (as `not_loaded`), sorts
+ * the entries by name then layer for deterministic output, and attaches each
+ * extension's {@link describeExtensionActivation} summary. When `target` is
+ * provided only the case-insensitively matching extensions are described and the
+ * `union` is scoped to that name; otherwise every loaded extension contributes.
+ * An unmatched `target` yields an empty `extensions` array -- the caller decides
+ * whether that is a not-found error.
+ */
+export declare function buildExtensionDescribeResult(target: string | undefined, loadResult: ExtensionLoadResult, activationResult: ExtensionActivationResult): ExtensionDescribeResult;

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

@@ -0,0 +1,76 @@
+/**
+ * @module cli/commands/extension/describe
+ *
+ * Builds the `pm extension describe` / `pm package describe` payload: a flat,
+ * by-name map of every surface each loaded extension registered.
+ *
+ * The SDK already ships {@link describeExtensionActivation} -- the `describe`
+ * (enumerate-all) verb that complements the `assert*` (verify-one) and `run*`
+ * (invoke-one) testing helpers -- but until now it was reachable only from a test
+ * that hand-built an {@link ExtensionActivationResult}. This module is the thin
+ * orchestration that lets an agent at the CLI (or over MCP) ask "what does this
+ * installed extension add to my context?" in one call, instead of stitching
+ * together `doctor` (errors), `manage` (update metadata), and a manifest read.
+ *
+ * It is intentionally pure: the caller performs the load+activate cycle (exactly
+ * as `explore`/`doctor` already do) and hands the results here, so the same
+ * builder is trivially unit-testable against synthetic activations.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7a92163a-99b2-5969-acc2-e2b6b0336c2e")}catch(e){}}();
+import { describeExtensionActivation } from "../../../core/extensions/activation-summary.js";
+import { normalizeExtensionNameForMatch } from "./shared.js";
+/**
+ * Compose a collision-free identity key for an extension from its layer and
+ * normalized name. The two parts are joined with a colon; the layer prefix is
+ * always a colon-free enum value, so distinct (layer, name) pairs never collide
+ * even when a name itself contains a colon.
+ */
+function layerNameKey(layer, name) {
+    return `${layer}:${normalizeExtensionNameForMatch(name)}`;
+}
+/**
+ * Summarize, by name, every registration surface the loaded extensions exercised.
+ *
+ * Walks `loadResult.loaded` (annotating each with `failed` when its layer+name is
+ * in `activationResult.failed`) and `loadResult.failed` (as `not_loaded`), sorts
+ * the entries by name then layer for deterministic output, and attaches each
+ * extension's {@link describeExtensionActivation} summary. When `target` is
+ * provided only the case-insensitively matching extensions are described and the
+ * `union` is scoped to that name; otherwise every loaded extension contributes.
+ * An unmatched `target` yields an empty `extensions` array -- the caller decides
+ * whether that is a not-found error.
+ */
+export function buildExtensionDescribeResult(target, loadResult, activationResult) {
+    const activationFailedKeys = new Set(activationResult.failed.map((entry) => layerNameKey(entry.layer, entry.name)));
+    const candidates = [
+        ...loadResult.loaded.map((entry) => ({
+            name: entry.name,
+            layer: entry.layer,
+            version: entry.version,
+            activation_status: activationFailedKeys.has(layerNameKey(entry.layer, entry.name))
+                ? "failed"
+                : "ok",
+            surfaces: describeExtensionActivation(activationResult, { extensionName: entry.name }),
+        })),
+        ...loadResult.failed.map((entry) => ({
+            name: entry.name,
+            layer: entry.layer,
+            version: "unknown",
+            activation_status: "not_loaded",
+            surfaces: describeExtensionActivation(activationResult, { extensionName: entry.name }),
+        })),
+    ].sort((left, right) => left.name.localeCompare(right.name) || left.layer.localeCompare(right.layer));
+    const normalizedTarget = typeof target === "string" ? normalizeExtensionNameForMatch(target) : null;
+    const extensions = normalizedTarget === null
+        ? candidates
+        : candidates.filter((entry) => normalizeExtensionNameForMatch(entry.name) === normalizedTarget);
+    return {
+        target: typeof target === "string" ? target.trim() : null,
+        total: extensions.length,
+        extensions,
+        union: describeExtensionActivation(activationResult, normalizedTarget === null ? {} : { extensionName: target }),
+    };
+}
+//# sourceMappingURL=describe.js.map
+//# debugId=7a92163a-99b2-5969-acc2-e2b6b0336c2e

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

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

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

@@ -4,7 +4,7 @@
  * Implements extension package-management support for Scaffold.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="61e2eb79-305a-5636-b5ca-ab0c6aa4afcc")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="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,34 +582,103 @@ 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`;
+        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",
@@ -564,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.",
             "",
@@ -573,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,
         };
@@ -587,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",
@@ -606,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,
     };
 }
@@ -682,4 +818,4 @@ export async function scaffoldExtensionProject(target, vocabulary = "extension",
     };
 }
 //# sourceMappingURL=scaffold.js.map
-//# debugId=61e2eb79-305a-5636-b5ca-ab0c6aa4afcc
+//# debugId=9eecdd82-fe71-5803-9186-a33244c4722d