feat(sdk): own workspace customization and author provenance

Merged
UN
4mo ago
+14850-13331

Summary

  • move config, profile, init, agent-guidance, templates, and command rendering into public SDK ownership while retaining thin CLI compatibility adapters
  • export reusable CLI construction and invocation-author scoping primitives, add global --author, and persist non-empty init author defaults
  • scan append-only history for missing provenance and surface non-blocking health/validate remediation
  • remove 54 obsolete CLI-to-core import-boundary allowances and document the composable customization surface

pm items

Closes #444

Verification

  • all-source coverage: 291 files / 5,709 tests, exact 100% statements (36,933), branches (26,518), functions (7,451), and lines (36,048)
  • strict ESLint, zero-clone jscpd, 100% module/export/member docstrings, package boundary, token budgets, contracts, context evaluation, secret scan, and dependency audit
  • packed npm install plus clean temporary consumer proof for SDK exports, config/profile/init, global author precedence, and advisory diagnostics
  • packed npx smoke and 88-command package-first dogfood
  • pre-push Greptile: confidence 5/5, safe to merge, no comments after both initial findings were fixed

Observability

Telemetry is healthy at 0.34% finish errors with zero failures missing error codes. The aggregate release gate stops only on two pre-existing handled external-integration Sentry highs already tracked as pm-d4ns (PM-CLI-2B) and pm-7n5a (PM-CLI-29); neither implementation belongs to this bundle.

Summary by cubic

Moves workspace customization and extension lifecycle into the public SDK with thin CLI adapters. Adds global --author with default persistence, unknown-author advisories with remediation in pm health/pm validate, and enforces exact static-quality budgets (165 ESLint suppressions, 477 coverage pragmas) (addresses #444).

  • New Features

    • SDK exports: runConfig, runInit, runInitAgentGuidance, runProfile{List,Show,Apply,Lint}, runTemplates{List,Show,Save}, runExtension, createPmCliProgram, applyInvocationAuthorOverride, quoteCommandArg/renderPmCommand, EXECUTABLE_COMMAND_ALIASES.
    • Author provenance: global --author, pm init writes author_default, scanHistoryAuthorAttribution powers advisories history_unknown_author_events and validate_history_unknown_author_events with remediation entries.
    • Hardening: serialized extension installs with scoped transactions and activation verification; active install locks lease via heartbeat; --author empty/missing value errors unified; corrected completion metadata; CodeQL-safe extension slug normalization; atomic guidance writes; workspace targeting in init; stricter config integer parsing; removed unreachable config paths; DeepSource module_system = "es-modules"; static-quality and release/readiness gates pinned to 165/477.
    • Docs: docs/SDK_CUSTOMIZATION_PRIMITIVES.md describes the composition surface.

  • Migration

    • Embedded hosts should import from @unbrained/pm-cli/sdk instead of spawning pm.
    • To avoid unknown authors: set PM_AUTHOR, pass --author, or run pm config project set author_default <id>.
    • CLI flags and behavior remain compatible; internal CLI-to-core import allowances reduced.