pm-starter 2026.11.5 → 2026.11.9

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2026.11.9 - 2026-11-09
+
+### Dependencies
+
+- Bump the pm-toolchain group with 3 updates ([#199](https://github.com/unbraind/pm-starter/pull/199))
+- Bump unbraind/pm-github/.github/workflows/pm-github-closeout.yml ([#198](https://github.com/unbraind/pm-starter/pull/198))
+- Bump unbraind/pm-github/.github/workflows/pm-github-sync.yml ([#197](https://github.com/unbraind/pm-starter/pull/197))
+- Bump the codeql-action group with 2 updates ([#196](https://github.com/unbraind/pm-starter/pull/196))
+
 ## 2026.11.5 - 2026-11-05
 
 ### Fixed

package/README.md

@@ -213,6 +213,73 @@ npm run build
 pm install ./my-extension --project
 ```
 
+## Recommended extension tests
+
+Use `createExtensionTestHarness` from `@unbrained/pm-cli/sdk/testing` for positive
+registration and handler tests. It activates the real host registration API and
+runs registered handlers through host dispatch. Pair it with an initialized
+`PmClient` tracker in a temporary directory, including a tracker outside Git:
+
+```ts
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { PmClient } from "@unbrained/pm-cli/sdk";
+import { createExtensionTestHarness } from "@unbrained/pm-cli/sdk/testing";
+import extension from "../index.ts";
+
+test("registered command reads a real tracker", async (t) => {
+  const directory = mkdtempSync(join(tmpdir(), "extension-test-"));
+  t.after(() => rmSync(directory, { recursive: true, force: true }));
+  const pmRoot = join(directory, ".agents", "pm"); // Tracker storage, not workspace root.
+  const client = new PmClient({ pmRoot, noExtensions: true, author: "test" });
+  await client.init("example", { defaults: true, mergeFence: false, agentGuidance: "skip" });
+  await client.create({ id: "example", type: "Task", title: "Example" });
+
+  const manifest: unknown = JSON.parse(readFileSync(new URL("../manifest.json", import.meta.url), "utf8"));
+  const harness = await createExtensionTestHarness({ default: extension, manifest });
+  t.after(() => harness.deactivate());
+  harness.assertCommandContract({ name: "starter greet", flags: ["--name", "--uppercase"] });
+  harness.assertFlags({ name: "list", flags: ["--starter-tag"] });
+  harness.assertItemField({ name: "starter_origin", type: "string" });
+  harness.assertItemType({ name: "StarterNote", folder: "starter-notes" });
+
+  // A nonempty pmRoot makes the harness inject a real host-bound ctx.sdk.
+  const outcome = await harness.runCommand({ command: "starter demo", pmRoot });
+  assert.equal(outcome.handled, true);
+  assert.deepEqual(outcome.warnings, []);
+  assert.equal((outcome.result as { item_count: number }).item_count, 1);
+});
+```
+
+Keep the manifest's capabilities accurate; this example uses the package's actual
+manifest so missing declarations fail activation. Copy the assertion names and
+expected receipts to match your own extension. The pinned development SDK supplies
+these testing helpers; they do not change the installed extension's host floor.
+
+Use `assertHook`, `assertImporter`, `assertExporter` and the other `assert*`
+methods to verify registered surfaces, then `runCommand`, `runRendererOverride`,
+`runImporter`, `runExporter` or `runHook` to exercise behavior. Importers and
+exporters also register command paths, so they appear in the host command registry.
+The harness dispatches one requested surface; it does not run the entire CLI
+parser/preflight/render pipeline or automatically install hooks on a separate
+`PmClient`. Pass parsed command flags in `options`, global host options in `global`,
+and real committed mutation data when invoking an observe-only write hook.
+
+Retain package rules as assertions: USAGE errors, inert importer and laboratory
+mutation refusals, renderer ownership, and receipt contents are starter behavior
+the SDK cannot prescribe. Pure option tests and the focused callback/subprocess
+failure doubles in `test/commands.test.ts` stay unit tests; use
+`activateExtensionForTest` directly for deliberate failed-activation or old-host
+compatibility tests. Positive smoke tests must use the supported harness instead
+of a handwritten `ExtensionApi` registration sink. See `test/smoke.test.ts` for
+registration, invocation, output receipt and mutation-context examples.
+
+Run `node --test --test-concurrency=2 test/smoke.test.ts` and `npm run build:test`
+when adapting this pattern, then the package's full gate.
+
 ## License
 
 MIT

package/dist/index.js

@@ -1060,7 +1060,7 @@ function setupFlags(api) {
 const defineExtension = (module) => module;
 export default defineExtension({
     name: "pm-starter",
-    version: "2026.11.5",
+    version: "2026.11.9",
     activate(api) {
         // Register every capability group. Each helper is defensive enough to be
         // safely deleted when you fork this scaffold for a real extension.

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-starter",
-  "version": "2026.11.5",
+  "version": "2026.11.9",
   "description": "Complete scaffold showing all 9 capability types: commands, renderers, hooks, schema, importers, search, parser, preflight, services. Includes plan workflow, context, and search integration examples plus guided setup. Use as a starting template for new extensions.",
   "author": "@unbraind",
   "entry": "./dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-starter",
-  "version": "2026.11.5",
+  "version": "2026.11.9",
   "description": "Complete starter/scaffold extension for pm-cli showing all capability types",
   "repository": {
     "type": "git",
@@ -51,9 +51,9 @@
   },
   "devDependencies": {
     "@types/node": "26.6.6",
-    "@unbrained/pm-cli": "2026.11.4",
-    "pm-changelog": "2026.10.31",
-    "pm-ops": "2026.11.4",
+    "@unbrained/pm-cli": "2026.11.5",
+    "pm-changelog": "2026.11.5",
+    "pm-ops": "2026.11.5",
     "typescript": "7.0.2"
   },
   "keywords": [