@unbrained/pm-cli 2026.5.1 → 2026.5.3-5

package/docs/TESTING.md

@@ -0,0 +1,125 @@
+# Testing
+
+This page describes safe local tests, linked tests, coverage, and release-readiness checks.
+
+## Agent Quick Context
+
+- Unit and integration tests must not read or write real `.agents/pm` data.
+- Prefer `node scripts/run-tests.mjs ...` because it creates sandboxed `PM_PATH` and `PM_GLOBAL_PATH`.
+- Linked tests added through `pm test` should use sandbox-safe commands.
+- Run linked tests before closing the item that owns the work.
+
+Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+
+## Standard Local Checks
+
+```bash
+pnpm build
+pnpm typecheck
+node scripts/run-tests.mjs test
+node scripts/run-tests.mjs coverage
+```
+
+`node scripts/run-tests.mjs` wraps Vitest in temporary tracker roots, then cleans them up.
+
+## Focused Test Runs
+
+```bash
+node scripts/run-tests.mjs test -- tests/unit/output.spec.ts
+node scripts/run-tests.mjs test -- tests/integration/cli.integration.spec.ts
+```
+
+Use focused runs while iterating, then run coverage before closure when risk or scope warrants it.
+
+## Linked Tests
+
+Add tests to the item that owns the work:
+
+```bash
+pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/output.spec.ts",scope=project,timeout_seconds=240
+pm test <item-id> --run --progress
+```
+
+For broader sweeps:
+
+```bash
+pm test-all --status in_progress --progress
+```
+
+Do not link `pm test-all` itself as an item-level test command. It creates recursive orchestration.
+
+## PM Context Modes
+
+Linked PM commands default to schema context: settings and extensions are seeded, but tracker item data stays isolated.
+
+Use explicit modes when needed:
+
+```bash
+pm test <item-id> --run --pm-context schema
+pm test <item-id> --run --pm-context tracker
+pm test <item-id> --run --pm-context auto --check-context --auto-pm-context
+```
+
+Strict governance flags:
+
+```bash
+pm test <item-id> --run \
+  --fail-on-context-mismatch \
+  --fail-on-skipped \
+  --fail-on-empty-test-run \
+  --require-assertions-for-pm
+```
+
+## Linked-Test Assertions
+
+Linked tests can include assertion metadata:
+
+```bash
+pm test <item-id> --add \
+  command="pm list-open --json",scope=project,timeout_seconds=120,assert_json_field_gte=count:0
+```
+
+Common assertion keys include:
+
+- `assert_stdout_contains`
+- `assert_stdout_regex`
+- `assert_stderr_contains`
+- `assert_stderr_regex`
+- `assert_stdout_min_lines`
+- `assert_json_field_equals`
+- `assert_json_field_gte`
+
+## Background Runs
+
+```bash
+pm test <item-id> --run --background
+pm test-all --status in_progress --background
+pm test-runs
+pm test-runs status <run-id>
+pm test-runs logs <run-id> --tail 100
+pm test-runs stop <run-id>
+pm test-runs resume <run-id>
+```
+
+Background run fingerprints prevent duplicate parallel runs for the same linked-test set.
+
+## Release-Readiness Checks
+
+For substantial changes:
+
+```bash
+pnpm build
+pnpm typecheck
+node scripts/run-tests.mjs coverage
+pm validate --check-resolution --check-history-drift
+pm health --check-only
+```
+
+For documentation-only changes, at minimum run:
+
+```bash
+pnpm build
+rg -n "forbidden-private-token-or-path" README.md docs
+```
+
+Replace the placeholder pattern with the actual sensitive term being guarded in the current task.

package/docs/examples/starter-extension/README.md

@@ -1,48 +1,62 @@
-# Starter Extension (All 9 Capabilities)
+# Starter Extension
 
-This example demonstrates a single extension that uses the public SDK only:
-`@unbrained/pm-cli/sdk`.
+This example demonstrates all extension capability categories through the public SDK import `@unbrained/pm-cli/sdk`.
 
-It is intentionally small and "feature complete" as a reference scaffold.
+## Agent Quick Context
+
+- Copy this folder when you need a complete capability reference.
+- Use `pm extension init ./my-extension` when you need a smaller scaffold.
+- Keep production extensions narrower than this example.
+
+Related docs:
+
+- [Extensions](../../EXTENSIONS.md)
+- [SDK](../../SDK.md)
 
 ## Files
 
-- `manifest.json` declares all 9 capabilities.
-- `package.json` declares the SDK dependency.
-- `index.js` registers one or more examples for each capability.
+| File | Purpose |
+|------|---------|
+| `manifest.json` | declares extension metadata and capabilities |
+| `package.json` | declares local package metadata and SDK dependency |
+| `index.js` | registers examples for each capability category |
 
 ## Capability Coverage
 
-1. `commands` - `api.registerCommand(...)` + `api.registerFlags(...)`
-2. `parser` - `api.registerParser(...)`
-3. `preflight` - `api.registerPreflight(...)`
-4. `services` - `api.registerService(...)`
-5. `renderers` - `api.registerRenderer(...)`
-6. `hooks` - `api.hooks.beforeCommand/afterCommand/onWrite/onRead/onIndex`
-7. `schema` - `api.registerItemFields/registerItemTypes/registerMigration`
-8. `importers` - `api.registerImporter/registerExporter`
-9. `search` - `api.registerSearchProvider/registerVectorStoreAdapter`
+| Capability | Example surface |
+|------------|-----------------|
+| `commands` | `api.registerCommand(...)` |
+| `parser` | `api.registerParser(...)` |
+| `preflight` | `api.registerPreflight(...)` |
+| `services` | `api.registerService(...)` |
+| `renderers` | `api.registerRenderer(...)` |
+| `hooks` | command, read, write, and index hooks |
+| `schema` | item fields, item types, migrations |
+| `importers` | importer and exporter registration |
+| `search` | search provider and vector adapter |
 
 ## Quick Start
 
-1. Copy this folder into an extension root:
-   - project: `.agents/pm/extensions/starter-extension`
-   - global: `~/.pm-cli/extensions/starter-extension`
-2. Install dependencies in that copied folder:
+Copy into an extension root:
 
 ```bash
+mkdir -p .agents/pm/extensions
+cp -R docs/examples/starter-extension .agents/pm/extensions/starter-extension
+cd .agents/pm/extensions/starter-extension
 npm install
 ```
 
-3. Activate and test:
+Activate and test from the repository root:
 
 ```bash
-pm extension --activate --project starter-extension
+pm extension activate starter-extension --project
 pm starter ping --name "agent"
+pm extension doctor --detail summary
 ```
 
 ## Notes
 
-- This starter is for learning and scaffolding, not production behavior.
-- Keep service/renderer overrides narrowly scoped in real extensions.
-- Prefer returning deterministic JSON-like objects from handlers.
+- This starter is for learning and scaffold reference.
+- Real extensions should declare only the capabilities they need.
+- Keep service, parser, and preflight overrides narrow and well tested.
+- Return deterministic JSON-like objects from command handlers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.5.1",
+  "version": "2026.5.3-5",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -54,13 +54,21 @@
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "start": "node dist/cli.js",
     "dev": "tsx src/cli.ts",
-    "test": "pnpm build && vitest run",
-    "test:coverage": "pnpm build && vitest run --coverage",
+    "test": "node scripts/run-tests.mjs test",
+    "test:coverage": "node scripts/run-tests.mjs coverage",
+    "quality:static": "node scripts/release/static-quality-gate.mjs",
     "version:check": "node scripts/release-version.mjs check",
     "version:next": "node scripts/release-version.mjs next",
     "release:notes": "node scripts/generate-release-notes.mjs",
+    "release:changelog": "node scripts/release/changelog-promote.mjs",
+    "release:gates": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",
+    "release:pipeline": "node scripts/release/run-release-pipeline.mjs",
+    "release:pipeline:dry-run": "node scripts/release/run-release-pipeline.mjs --dry-run",
     "security:scan": "node scripts/check-secrets.mjs",
     "smoke:npx": "node scripts/smoke-npx-from-pack.mjs",
+    "sentry:inject": "sentry-cli sourcemaps inject dist/",
+    "sentry:upload": "sentry-cli sourcemaps upload --org unbrained --project pm-cli --release \"pm-cli@$npm_package_version\" --validate dist/",
+    "build:sentry": "pnpm build && pnpm sentry:inject && pnpm sentry:upload",
     "prepublishOnly": "pnpm build"
   },
   "keywords": [
@@ -81,22 +89,27 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@toon-format/toon": "latest",
-    "commander": "latest",
+    "@sentry/node": "^10.51.0",
+    "@toon-format/toon": "^2.1.0",
+    "commander": "^14.0.3",
     "fast-glob": "^3.3.3",
-    "fast-json-patch": "latest",
-    "undici": "latest",
-    "zod": "latest"
+    "fast-json-patch": "^3.1.1",
+    "undici": "^8.1.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/node": "latest",
+    "@sentry/cli": "^3.4.1",
+    "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "^4.1.5",
     "c8": "^11.0.0",
-    "tsx": "latest",
-    "typescript": "latest",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   },
   "pnpm": {
+    "onlyBuiltDependencies": [
+      "@sentry/cli"
+    ],
     "overrides": {
       "rollup": ">=4.59.0",
       "brace-expansion": ">=5.0.5",

package/dist/command-types.d.ts

@@ -1 +0,0 @@
-export * from "./core/shared/command-types.js";

package/dist/command-types.js

@@ -1,2 +0,0 @@
-export * from "./core/shared/command-types.js";
-//# sourceMappingURL=command-types.js.map

package/dist/command-types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"command-types.js","sourceRoot":"","sources":["../src/command-types.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC"}

package/dist/constants.d.ts

@@ -1 +0,0 @@
-export * from "./core/shared/constants.js";

package/dist/constants.js

@@ -1,2 +0,0 @@
-export * from "./core/shared/constants.js";
-//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC"}

package/dist/errors.d.ts

@@ -1 +0,0 @@
-export * from "./core/shared/errors.js";

package/dist/errors.js

@@ -1,2 +0,0 @@
-export * from "./core/shared/errors.js";
-//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}

package/dist/fs-utils.d.ts

@@ -1 +0,0 @@
-export * from "./core/fs/fs-utils.js";

package/dist/fs-utils.js

@@ -1,2 +0,0 @@
-export * from "./core/fs/fs-utils.js";
-//# sourceMappingURL=fs-utils.js.map

package/dist/fs-utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"fs-utils.js","sourceRoot":"","sources":["../src/fs-utils.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dist/history.d.ts

@@ -1 +0,0 @@
-export * from "./core/history/history.js";

package/dist/history.js

@@ -1,2 +0,0 @@
-export * from "./core/history/history.js";
-//# sourceMappingURL=history.js.map

package/dist/history.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"history.js","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC"}

package/dist/id.d.ts

@@ -1 +0,0 @@
-export * from "./core/item/id.js";

package/dist/id.js

@@ -1,2 +0,0 @@
-export * from "./core/item/id.js";
-//# sourceMappingURL=id.js.map

package/dist/id.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"id.js","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/item-format.d.ts

@@ -1 +0,0 @@
-export * from "./core/item/item-format.js";

package/dist/item-format.js

@@ -1,2 +0,0 @@
-export * from "./core/item/item-format.js";
-//# sourceMappingURL=item-format.js.map

package/dist/item-format.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"item-format.js","sourceRoot":"","sources":["../src/item-format.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC"}

package/dist/item-store.d.ts

@@ -1 +0,0 @@
-export * from "./core/store/item-store.js";

package/dist/item-store.js

@@ -1,2 +0,0 @@
-export * from "./core/store/item-store.js";
-//# sourceMappingURL=item-store.js.map

package/dist/item-store.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"item-store.js","sourceRoot":"","sources":["../src/item-store.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC"}

package/dist/lock.d.ts

@@ -1 +0,0 @@
-export * from "./core/lock/lock.js";

package/dist/lock.js

@@ -1,2 +0,0 @@
-export * from "./core/lock/lock.js";
-//# sourceMappingURL=lock.js.map

package/dist/lock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"lock.js","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC"}

package/dist/output.d.ts

@@ -1 +0,0 @@
-export * from "./core/output/output.js";

package/dist/output.js

@@ -1,2 +0,0 @@
-export * from "./core/output/output.js";
-//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}

package/dist/parse.d.ts

@@ -1 +0,0 @@
-export * from "./core/item/parse.js";

package/dist/parse.js

@@ -1,2 +0,0 @@
-export * from "./core/item/parse.js";
-//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/paths.d.ts

@@ -1 +0,0 @@
-export * from "./core/store/paths.js";

package/dist/paths.js

@@ -1,2 +0,0 @@
-export * from "./core/store/paths.js";
-//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dist/serialization.d.ts

@@ -1 +0,0 @@
-export * from "./core/shared/serialization.js";

package/dist/serialization.js

@@ -1,2 +0,0 @@
-export * from "./core/shared/serialization.js";
-//# sourceMappingURL=serialization.js.map

package/dist/serialization.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"serialization.js","sourceRoot":"","sources":["../src/serialization.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC"}

package/dist/settings.d.ts

@@ -1 +0,0 @@
-export * from "./core/store/settings.js";

package/dist/settings.js

@@ -1,2 +0,0 @@
-export * from "./core/store/settings.js";
-//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"settings.js","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}

package/dist/time.d.ts

@@ -1 +0,0 @@
-export * from "./core/shared/time.js";

package/dist/time.js

@@ -1,2 +0,0 @@
-export * from "./core/shared/time.js";
-//# sourceMappingURL=time.js.map

package/dist/time.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"time.js","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}