@unbrained/pm-cli 2026.3.9

package/docs/EXTENSIONS.md

@@ -0,0 +1,329 @@
+# pm-cli Extension Development Guide
+
+Extensions let you add commands, renderers, importers, exporters, schema fields, search providers, and lifecycle hooks to `pm-cli` without modifying core.
+
+## Extension Locations
+
+| Scope | Path |
+|-------|------|
+| Global | `~/.pm-cli/extensions/<name>/` (override: `PM_GLOBAL_PATH/extensions/<name>/`) |
+| Project | `.agents/pm/extensions/<name>/` (override: `PM_PATH/extensions/<name>/`) |
+
+**Load order:** core built-ins → global → project. Project-local extensions take precedence over global when they declare the same command name or renderer key.
+
+## Manifest
+
+Every extension directory must contain a `manifest.json`:
+
+```json
+{
+  "name": "pm-ext-example",
+  "version": "0.1.0",
+  "entry": "./dist/index.js",
+  "priority": 100,
+  "capabilities": [
+    "commands",
+    "renderers",
+    "hooks",
+    "schema",
+    "importers",
+    "search"
+  ]
+}
+```
+
+- `entry` must resolve inside the extension directory (no path traversal).
+- `capabilities` declares what the extension will register. API calls that exceed declared capabilities fail activation deterministically.
+- Unknown capability names are silently ignored for gating but emit discovery diagnostics.
+
+## Extension Module
+
+The entry module must export an `activate` function:
+
+```ts
+import type { ExtensionApi } from "pm-cli";
+
+export function activate(api: ExtensionApi): void {
+  // register commands, hooks, renderers, etc.
+}
+```
+
+`activate` may be synchronous or return `Promise<void>`.
+
+## API Reference
+
+### `api.registerCommand(def)`
+
+Register a new command or override an existing core command's result.
+
+**New command path:**
+
+```ts
+api.registerCommand({
+  name: "acme sync",
+  run: async (args, options, global) => {
+    // args: string[] — positional CLI arguments
+    // options: Record<string,unknown> — parsed flags
+    // global: GlobalOptions — --json, --quiet, --path, etc.
+    return { ok: true, synced: 42 };
+  },
+});
+```
+
+The command name is canonicalized (trimmed, lowercased, repeated whitespace collapsed). The handler receives cloned snapshots so mutation cannot leak into caller state.
+
+**Override existing core command result:**
+
+```ts
+api.registerCommand("list", (priorResult, args, options, global, pmRoot) => {
+  // priorResult: the core command's output object (cloned)
+  // return a modified result object, or undefined to use priorResult as-is
+  return { ...priorResult, _ext: "annotated" };
+});
+```
+
+### `api.registerFlags(targetCommand, flags)`
+
+Declare flags for a command (displayed in `--help` for dynamic extension commands):
+
+```ts
+api.registerFlags("acme sync", [
+  { name: "--dry-run", description: "Simulate without writing" },
+  { name: "--org <name>", description: "Organization name" },
+]);
+```
+
+### `api.registerRenderer(format, renderer)`
+
+Override TOON or JSON output for a command:
+
+```ts
+api.registerRenderer("toon", (command, result, args, options, global, pmRoot) => {
+  if (command !== "stats") return undefined; // pass through
+  return customToonFormat(result);
+});
+```
+
+Return `undefined` to fall back to the built-in renderer.
+
+### `api.registerImporter(name, importer)`
+
+Register an importer (also wires `<name> import` command path):
+
+```ts
+api.registerImporter("jira", async (options, global) => {
+  // options: parsed flags from `pm jira import ...`
+  return { ok: true, imported: 5, skipped: 0, ids: ["pm-xxxx"], warnings: [] };
+});
+```
+
+### `api.registerExporter(name, exporter)`
+
+Register an exporter (also wires `<name> export` command path):
+
+```ts
+api.registerExporter("jira", async (options, global) => {
+  return { ok: true, exported: 5, ids: ["pm-xxxx"], warnings: [] };
+});
+```
+
+### `api.registerItemFields(fields)`
+
+Declare additional front-matter fields for schema-awareness:
+
+```ts
+api.registerItemFields([
+  { name: "acme_epic_id", type: "string", optional: true },
+]);
+```
+
+### `api.registerMigration(def)`
+
+Declare a schema migration (tracked in `pm health`):
+
+```ts
+api.registerMigration({
+  id: "add-acme-epic-id",
+  description: "Add acme_epic_id field to existing items",
+  mandatory: false,
+  status: "pending",
+  run: async (pmRoot) => {
+    // migrate items; update status to "applied" when done
+  },
+});
+```
+
+Migrations with `mandatory: true` and `status` not `"applied"` block write commands until resolved (bypass with `--force`).
+
+### `api.registerSearchProvider(provider)`
+
+Register a custom search provider:
+
+```ts
+api.registerSearchProvider({
+  name: "elastic",
+  query: async (query, options, settings) => {
+    return [{ id: "pm-xxxx", score: 0.95 }];
+  },
+});
+```
+
+### `api.registerVectorStoreAdapter(adapter)`
+
+Register a custom vector store:
+
+```ts
+api.registerVectorStoreAdapter({
+  name: "pinecone",
+  upsert: async (records, settings) => { ... },
+  query: async (vector, topK, settings) => { ... },
+  delete: async (ids, settings) => { ... },
+});
+```
+
+## Lifecycle Hooks
+
+Hooks run for every applicable core operation. Hook handlers receive cloned context snapshots — mutations do not leak back into caller state.
+
+### `api.hooks.beforeCommand(hook)`
+
+Runs before any command executes:
+
+```ts
+api.hooks.beforeCommand((ctx) => {
+  // ctx.command: string
+  // ctx.args: string[]
+  // ctx.options: Record<string,unknown>
+  // ctx.global: GlobalOptions
+  // ctx.pm_root: string
+  console.log(`[ext] before: ${ctx.command}`);
+});
+```
+
+### `api.hooks.afterCommand(hook)`
+
+Runs after a command completes (even on failure):
+
+```ts
+api.hooks.afterCommand((ctx) => {
+  // ctx.ok: boolean
+  // ctx.result?: unknown
+  // ctx.error?: unknown
+  // same fields as beforeCommand
+});
+```
+
+### `api.hooks.onWrite(hook)`
+
+Runs before each item file write:
+
+```ts
+api.hooks.onWrite((ctx) => {
+  // ctx.path: string
+  // ctx.op: string (create, update, restore, etc.)
+  // ctx.item_id: string
+});
+```
+
+### `api.hooks.onRead(hook)`
+
+Runs after each item file read:
+
+```ts
+api.hooks.onRead((ctx) => {
+  // ctx.path: string
+  // ctx.item_id: string
+});
+```
+
+### `api.hooks.onIndex(hook)`
+
+Runs during reindex/gc operations:
+
+```ts
+api.hooks.onIndex((ctx) => {
+  // ctx.mode: "keyword" | "semantic" | "hybrid" | "gc"
+  // ctx.total?: number
+});
+```
+
+## Health and Diagnostics
+
+`pm health` probes all loaded extensions and surfaces:
+
+- `extension_load_failed:<layer>:<name>` — manifest parse or module import error
+- `extension_activate_failed:<layer>:<name>` — exception in `activate()`
+- `extension_entry_outside_extension:<layer>:<name>` — entry path escapes directory
+- `extension_capability_unknown:<layer>:<name>:<capability>` — unknown capability in manifest
+
+Use `pm health --json` to parse diagnostics programmatically.
+
+## Disabling Extensions
+
+```bash
+pm --no-extensions list-open   # disable all extensions for this invocation
+```
+
+Or configure per-project in `.agents/pm/settings.json`:
+
+```json
+{
+  "extensions": {
+    "disabled": ["pm-ext-example"]
+  }
+}
+```
+
+## Example: Minimal Custom Command
+
+**`~/.pm-cli/extensions/hello/manifest.json`:**
+
+```json
+{
+  "name": "hello",
+  "version": "0.1.0",
+  "entry": "./index.js",
+  "priority": 100,
+  "capabilities": ["commands"]
+}
+```
+
+**`~/.pm-cli/extensions/hello/index.js`:**
+
+```js
+export function activate(api) {
+  api.registerCommand({
+    name: "hello",
+    run: async (_args, _options, _global) => {
+      return { message: "Hello from extension!" };
+    },
+  });
+}
+```
+
+```bash
+pm hello
+# => message: Hello from extension!
+```
+
+## Built-in Extensions
+
+`pm-cli` ships two built-in extensions compiled into the package:
+
+| Extension | Commands | Purpose |
+|-----------|----------|---------|
+| `builtin-beads-import` | `pm beads import` | Import Beads JSONL records into pm items |
+| `builtin-todos-import-export` | `pm todos import`, `pm todos export` | Round-trip todos markdown format |
+
+Built-in extensions are loaded automatically and cannot be disabled via settings (use `--no-extensions` to disable all extensions including built-ins).
+
+## Pi Agent Extension
+
+The bundled Pi tool wrapper lives at `.pi/extensions/pm-cli/index.ts` and is a Pi agent extension (not a pm-cli extension). Install it with:
+
+```bash
+pm install pi          # to current project .pi/extensions/pm-cli/index.ts
+pm install pi --global # to PI_CODING_AGENT_DIR/extensions/pm-cli/index.ts
+```
+
+See [AGENTS.md](../AGENTS.md) section 9 for full usage details.

package/docs/RELEASING.md

@@ -0,0 +1,65 @@
+# Releasing `@unbrained/pm-cli`
+
+This repository uses a tag-driven GitHub Actions release pipeline that publishes to npm and creates a GitHub Release.
+
+## Version policy
+
+`pm-cli` uses a calendar SemVer-compatible scheme:
+
+- `YYYY.M.D` for the first release on a date
+- `YYYY.M.D-N` for additional releases on the same date (`N >= 2`)
+
+Examples:
+
+- First release on 2026-03-09: `2026.3.9`
+- Second release on 2026-03-09: `2026.3.9-2`
+
+Use:
+
+```bash
+pnpm version:next
+```
+
+to compute the next expected release version from the npm registry.
+
+## One-time GitHub setup
+
+- Create GitHub Environment `release`
+- Add environment secret `NPM_TOKEN` (npm automation token with publish rights for `@unbrained/pm-cli`)
+
+## Release checklist
+
+1) Update `package.json` version and `CHANGELOG.md`
+
+2) Run release gates locally:
+
+```bash
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm test:coverage
+pnpm version:check
+pnpm security:scan
+pnpm smoke:npx
+```
+
+3) Commit and tag:
+
+```bash
+git tag v<version>
+git push origin main
+git push origin v<version>
+```
+
+4) Verify Actions:
+
+- `CI` passes for commit
+- `Release` workflow passes for tag
+- npm package published at `@unbrained/pm-cli`
+- GitHub Release created with generated notes
+
+## Notes
+
+- Do not run manual `npm publish`; publishing is owned by `.github/workflows/release.yml`.
+- Release workflow enforces tag/version alignment and calendar version sequencing before publish.

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@unbrained/pm-cli",
+  "version": "2026.3.9",
+  "description": "Git-native project management CLI for humans and agents.",
+  "type": "module",
+  "author": "unbrained",
+  "homepage": "https://github.com/unbraind/pm-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unbraind/pm-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/unbraind/pm-cli/issues"
+  },
+  "bin": {
+    "pm": "dist/cli.js"
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE",
+    "AGENTS.md",
+    "PRD.md",
+    "docs/**",
+    ".pi/extensions/pm-cli/index.ts",
+    "scripts/install.sh",
+    "scripts/install.ps1"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "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",
+    "version:check": "node scripts/release-version.mjs check",
+    "version:next": "node scripts/release-version.mjs next",
+    "security:scan": "node scripts/check-secrets.mjs",
+    "smoke:npx": "node scripts/smoke-npx-from-pack.mjs",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "cli",
+    "project-management",
+    "agents",
+    "ai",
+    "git-native",
+    "typescript",
+    "task-tracker",
+    "coding-agents"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@toon-format/toon": "latest",
+    "commander": "latest",
+    "fast-json-patch": "latest",
+    "undici": "latest",
+    "zod": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "@vitest/coverage-v8": "^4.0.18",
+    "c8": "^11.0.0",
+    "tsx": "latest",
+    "typescript": "latest",
+    "vitest": "^4.0.18"
+  },
+  "pnpm": {
+    "overrides": {
+      "rollup": ">=4.59.0"
+    }
+  }
+}

package/scripts/install.ps1

@@ -0,0 +1,112 @@
+param(
+  [string]$Version = "latest",
+  [string]$Prefix = "",
+  [string]$PackageName = ""
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$envPackageName = $env:PM_CLI_PACKAGE
+if ([string]::IsNullOrWhiteSpace($PackageName)) {
+  if ([string]::IsNullOrWhiteSpace($envPackageName)) {
+    $PackageName = "@unbrained/pm-cli"
+  } else {
+    $PackageName = $envPackageName
+  }
+}
+
+function Require-Command {
+  param([string]$Name)
+  if (-not (Get-Command $Name -ErrorAction SilentlyContinue)) {
+    throw "Required command not found: $Name"
+  }
+}
+
+function Use-LiteralInstallSpec {
+  param([string]$Name)
+
+  if ([string]::IsNullOrWhiteSpace($Name)) {
+    return $false
+  }
+
+  if ($Name -match "^(file:|https?://|git\+|npm:)") {
+    return $true
+  }
+
+  if ($Name.StartsWith("./") -or $Name.StartsWith("../") -or $Name.StartsWith("/") -or $Name.StartsWith("~/")) {
+    return $true
+  }
+
+  if ($Name.Contains('\') -or $Name -match "^[A-Za-z]:[\\/]") {
+    return $true
+  }
+
+  if ($Name.EndsWith(".tgz") -or $Name.EndsWith(".tar.gz")) {
+    return $true
+  }
+
+  if ($Name.StartsWith("@")) {
+    return $Name -match "^@[^/]+/[^@]+@.+$"
+  }
+
+  return $Name.Contains("@")
+}
+
+Require-Command "node"
+Require-Command "npm"
+
+$installSpec = $null
+if (Use-LiteralInstallSpec $PackageName) {
+  $installSpec = $PackageName
+} else {
+  $installSpec = "$PackageName@$Version"
+}
+Write-Host "Installing or updating $installSpec..."
+$npmArgs = @("install", "-g", $installSpec)
+if ($Prefix -ne "") {
+  $npmArgs += @("--prefix", $Prefix)
+}
+
+& npm @npmArgs
+if ($LASTEXITCODE -ne 0) {
+  throw "npm install failed with exit code $LASTEXITCODE"
+}
+
+$pmCommand = Get-Command "pm" -ErrorAction SilentlyContinue
+if ($pmCommand) {
+  $pmExecutable = $pmCommand.Source
+} else {
+  $candidates = @()
+  if ($Prefix -ne "") {
+    $candidates += (Join-Path $Prefix "pm.cmd")
+    $candidates += (Join-Path $Prefix "bin/pm.cmd")
+    $candidates += (Join-Path $Prefix "pm")
+    $candidates += (Join-Path $Prefix "bin/pm")
+  }
+
+  $resolved = $null
+  foreach ($candidate in $candidates) {
+    if (Test-Path $candidate) {
+      $resolved = $candidate
+      break
+    }
+  }
+
+  if (-not $resolved) {
+    $hint = ""
+    if ($Prefix -ne "") {
+      $hint = " Add '$Prefix' (or '$Prefix\bin') to PATH and retry."
+    }
+    throw "pm binary not found after install.$hint"
+  }
+  $pmExecutable = $resolved
+}
+
+$versionOutput = & $pmExecutable --version
+if ($LASTEXITCODE -ne 0) {
+  throw "pm --version failed with exit code $LASTEXITCODE"
+}
+
+Write-Host "Installed pm version: $versionOutput"
+Write-Host "Done."

package/scripts/install.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE_NAME="${PM_CLI_PACKAGE:-@unbrained/pm-cli}"
+TARGET_VERSION="latest"
+PREFIX=""
+
+usage() {
+  cat <<'EOF'
+Install or update @unbrained/pm-cli globally via npm.
+
+Usage:
+  bash scripts/install.sh [--version <tag>] [--prefix <dir>]
+
+Options:
+  --version <tag>   Package tag/version to install (default: latest)
+  --prefix <dir>    npm global prefix override
+  -h, --help        Show this help message
+EOF
+}
+
+require_command() {
+  local cmd="$1"
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "error: required command not found: $cmd" >&2
+    exit 1
+  fi
+}
+
+is_literal_install_spec() {
+  local name="$1"
+
+  if [[ "$name" == file:* || "$name" == http://* || "$name" == https://* || "$name" == git+* || "$name" == npm:* ]]; then
+    return 0
+  fi
+
+  if [[ "$name" == ./* || "$name" == ../* || "$name" == /* || "$name" == ~/* || "$name" == *.tgz || "$name" == *.tar.gz || "$name" == *\\* ]]; then
+    return 0
+  fi
+
+  # Scoped names use @scope/pkg; only treat them as literal when explicitly versioned.
+  if [[ "$name" == @*/*@* ]]; then
+    return 0
+  fi
+
+  if [[ "$name" != @* && "$name" == *@* ]]; then
+    return 0
+  fi
+
+  return 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --version)
+      if [[ $# -lt 2 ]]; then
+        echo "error: --version requires a value" >&2
+        exit 2
+      fi
+      TARGET_VERSION="$2"
+      shift 2
+      ;;
+    --prefix)
+      if [[ $# -lt 2 ]]; then
+        echo "error: --prefix requires a value" >&2
+        exit 2
+      fi
+      PREFIX="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "error: unknown argument: $1" >&2
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+require_command node
+require_command npm
+
+if is_literal_install_spec "$PACKAGE_NAME"; then
+  INSTALL_SPEC="$PACKAGE_NAME"
+else
+  INSTALL_SPEC="${PACKAGE_NAME}@${TARGET_VERSION}"
+fi
+INSTALL_CMD=(npm install -g "$INSTALL_SPEC")
+if [[ -n "$PREFIX" ]]; then
+  INSTALL_CMD+=(--prefix "$PREFIX")
+fi
+
+echo "Installing ${INSTALL_SPEC}..."
+"${INSTALL_CMD[@]}"
+
+PM_BIN="pm"
+if ! command -v "$PM_BIN" >/dev/null 2>&1; then
+  if [[ -n "$PREFIX" && -x "${PREFIX}/bin/pm" ]]; then
+    PM_BIN="${PREFIX}/bin/pm"
+  else
+    echo "error: pm binary not found on PATH after install." >&2
+    if [[ -n "$PREFIX" ]]; then
+      echo "hint: add ${PREFIX}/bin to your PATH or rerun without --prefix." >&2
+    fi
+    exit 1
+  fi
+fi
+
+echo "Installed pm version: $($PM_BIN --version)"
+echo "Done."