Expose SDK runtime action client

Merged
UN
4mo ago
+2711-1226

Summary

  • Exposes runAction and PmClient from the SDK runtime/barrel so integrations can execute pm actions in-process without spawning the CLI.
  • Moves the MCP action dispatch path onto the SDK runtime surface so MCP tools and SDK consumers share the same implementation.
  • Documents the runtime SDK usage and expands SDK/docs/MCP regression coverage, including extension activation/deactivation around workspace contracts.

PM tracking

  • Implements pm-xzhz under the SDK customization lineage pm-usfg.
  • Accepts and closes pm-muhw as the architecture decision supporting the SDK runtime-first path.
  • Closes #439.

Verification

  • node scripts/run-tests.mjs test -- tests/unit/sdk/sdk-index.spec.ts tests/integration/mcp-handshake.spec.ts tests/unit/mcp/mcp-server-branch-residual.spec.ts
  • node scripts/run-tests.mjs test -- tests/unit/docs-examples/sdk-app-embedding.spec.ts tests/unit/docs-examples/sdk-contract-consumer.spec.ts
  • pnpm typecheck
  • pnpm build
  • pnpm lint (ESLint, jscpd 0 clones, static quality gate)
  • pnpm quality:docs-skills
  • pnpm security:scan
  • pnpm audit --audit-level moderate
  • pm validate --check-resolution --check-history-drift (history drift ok; existing closed-item resolution metadata warnings remain)
  • pnpm changelog:pm && pnpm changelog:pm:check
  • node scripts/run-tests.mjs coverage -> 264 files, 5424 tests, 100% statements/branches/functions/lines
  • Installed-package smoke in a fresh temp consumer: packed @unbrained/pm-cli, installed it, imported @unbrained/pm-cli/sdk/runtime, initialized a tracker, and used PmClient/runAction for create/list/search/get/update/context/direct-context/close.
  • node scripts/release/sentry-telemetry-gate.mjs --json --telemetry-mode best-effort --sentry-window-days 14 --max-critical 0 --max-high 0 passed with recent critical/high Sentry counts at 0 and telemetry rows present.
  • greptile review --agent --branch origin/main ran before push. The CLI returned cached review 88db4c20-531f-4c98-8148-df5f43caf6d2; both returned comments were already fixed in the pushed head (src/mcp/server.ts no duplicate helper; src/sdk/runtime.ts deactivates after activation).

External state checked

  • No open Dependabot, code scanning, or secret scanning alerts via GitHub APIs before PR creation.
  • pm-changelog latest available npm version is 2026.6.30; package-owned changelog generation/check passed with that version.
  • CodeFactor public page reported Rating A and no issues when checked before PR creation.

Summary by cubic

Expose an in-process action client in the SDK so integrations can run pm actions without spawning the CLI; MCP tools now use the same dispatcher. Adds workspace contracts caching and typed action alias support, with tighter dispatch and safer example parsing.

  • New Features

    • PmClient and runAction are exported from @unbrained/pm-cli/sdk/runtime and re-exported in @unbrained/pm-cli/sdk; MCP pm_run and narrow tools use this dispatcher; docs add usage, shared SDK/MCP activation serialization, and per-call runtime overrides.
    • Supports typed action aliases (list-* status, ctx, task lifecycle, and package-* flows) via the shared runtime path.
    • Workspace contracts memoization with clearWorkspaceContractsCache to reset long‑lived hosts.

  • Bug Fixes

    • Dispatch fixes: corrected plan top-level dispatch from narrow tool calls and routed aliases through the runtime.
    • Hardening: replaced regex sanitization with a linear scanner; guarded SDK runtime test hooks to test environments only; wrapped example JSON parsing with contextual errors and handled empty pm contracts stdout.