@unbrained/pm-cli 2026.7.7 → 2026.7.8

package/docs/EXTENSIONS.md

@@ -179,16 +179,9 @@ useful for agents without inflating context or leaking private item content.
 
 ## Extension Manifest
 
-Runnable manifest examples are the source of truth:
+Runnable manifest examples are the source of truth: [starter extension manifest](examples/starter-extension/manifest.json) and [policy-restricted manifest](examples/policy-restricted-extension/manifest.json).
 
-- [starter extension manifest](examples/starter-extension/manifest.json)
-- [policy-restricted manifest](examples/policy-restricted-extension/manifest.json)
-
-Schema:
-
-- Use [extension-manifest.schema.json](schemas/extension-manifest.schema.json) as the
-  `$schema` value for inline editor validation. The loader ignores `$schema` and
-  tolerates future manifest fields, but the schema documents the fields pm reads.
+Use [extension-manifest.schema.json](schemas/extension-manifest.schema.json) as the `$schema` value for inline editor validation. The loader ignores `$schema` and tolerates future manifest fields, but the schema documents the fields pm reads.
 
 Rules:
 
@@ -347,9 +340,12 @@ Run diagnostics:
 ```bash
 pm package doctor --project --detail summary
 pm package doctor --project --detail deep --trace
+pm package doctor --project --isolated --detail deep --trace
 pm package doctor --project --strict-exit
 ```
 
+Use `--isolated` (alias `--ignore-global`) when a package smoke test must inspect only the project install. Non-isolated project diagnostics include global registrations and emit an isolation remediation hint when global package state can affect the result; subprocess-based test suites can also set `PM_GLOBAL_PATH` to a temporary directory for the whole run.
+
 Manage state and update checks:
 
 ```bash
@@ -359,22 +355,12 @@ pm package adopt my-extension --project
 pm package adopt-all --project
 ```
 
-Activate or deactivate:
+Activate, deactivate, uninstall, and reload:
 
 ```bash
 pm package activate my-extension --project
 pm package deactivate my-extension --project
-```
-
-Uninstall:
-
-```bash
 pm package uninstall my-extension --project
-```
-
-Reload local edits:
-
-```bash
 pm package reload --project
 pm package reload --project --watch
 ```
@@ -432,6 +418,7 @@ Prefer `createExtensionTestHarness(module, { capabilities })` in package unit te
 
 - Manifest or entry failure: run `pm package explore --project`.
 - Activation failure: run `pm package doctor --detail deep --trace`.
+- Machine-dependent package diagnostics: run `pm package doctor --project --isolated --detail deep --trace` or set `PM_GLOBAL_PATH` to a temp directory.
 - Policy block: inspect `settings.extensions.policy` and `details.summary.policy`.
 - Runtime drift: compare with `pm --no-extensions <command>`.
 - Managed-state update-check gap: run `pm package manage --fix-managed-state`.

package/docs/RELEASING.md

@@ -139,6 +139,12 @@ Minimum coverage:
 
 Use maintainer-only local workflows for reliability checks and incident triage. Keep operational details, infrastructure topology, and raw diagnostics out of tracked release documentation and release notes.
 
+Run the public Sentry/telemetry threshold gate through the package script alias:
+
+```bash
+pnpm sentry:telemetry:gate -- --telemetry-mode best-effort
+```
+
 If private reliability checks identify repeated user friction, either confirm the current release already contains the remediation with regression coverage or fix it before continuing.
 
 4. Run the same release pipeline locally.

package/docs/SDK.md

@@ -106,6 +106,8 @@ Command/action contract exports:
 - `PmClient` / `runAction` (high-level in-process action execution for custom tools, bots, CI, and embedded runtimes)
 - Typed read primitives on `PmClient`: `get`, `list`, `search`, `context`, `next`, `aggregate`, and `stats`
 - Read primitive option/result contracts: `GetOptions` / `GetResult`, `ListOptions` / `ListResult`, `SearchOptions` / `SearchResult`, `ContextOptions` / `ContextResult`, `NextOptions` / `NextResult`, `AggregateOptions` / `AggregateResult`, `StatsCommandOptions` / `StatsResult`
+- Typed package and extension lifecycle primitives on `PmClient`: `extension`, `extensionList`, `extensionActivate`, `extensionDeactivate`, `package`, `packageList`, `packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`, `packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`, `packageDeactivate`, and `upgrade`
+- Lifecycle primitive option/result contracts: `ExtensionCommandOptions` / `ExtensionCommandResult`, `PackageCommandOptions` / `PackageCommandResult`, `UpgradeCommandOptions` / `UpgradeResult`
 - `PM_CORE_COMMAND_NAMES`
 - `PM_TOOL_ACTIONS`
 - `PM_TOOL_PARAMETERS_SCHEMA`
@@ -448,6 +450,9 @@ const open = await pm.list({ status: "open", limit: "20" });
 const recommendation = await pm.next({ readyOnly: true });
 const grouped = await pm.aggregate({ groupBy: "status", count: true });
 const stats = await pm.stats({ metadataCoverage: true });
+const packages = await pm.packageList({ project: true });
+const doctor = await pm.packageDoctor({ project: true, isolated: true });
+const plannedUpgrade = await pm.upgrade(undefined, { dryRun: true, cliOnly: true });
 
 await runAction({
   action: "context",
@@ -477,6 +482,25 @@ Lifecycle convenience methods and the matching top-level functions (`create`,
 as the CLI and MCP dispatcher. They are the baseline primitives for custom PM
 tools that need to own item state without spawning `pm`.
 
+Package and extension lifecycle convenience methods are the SDK primitive layer
+for custom PM tools that need to manage their own package surface without
+shelling out. Use `pm.packageList`, `pm.packageInstall`,
+`pm.packageUninstall`, `pm.packageDoctor`, `pm.packageManage`,
+`pm.packageDescribe`, `pm.packageReload`, `pm.packageCatalog`,
+`pm.packageActivate`, `pm.packageDeactivate`, and `pm.upgrade` for package-mode
+automation; use `pm.extensionList`, `pm.extensionActivate`, and
+`pm.extensionDeactivate` when the UI vocabulary is explicitly extension-focused.
+The matching top-level helpers (`packageLifecycle`, `packageList`,
+`packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`,
+`packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`,
+`packageDeactivate`, `extension`, `extensionList`, `extensionActivate`,
+`extensionDeactivate`, and `upgrade`) construct a short-lived `PmClient` for
+one-off calls. Package helpers return `PackageCommandResult` and extension
+helpers return `ExtensionCommandResult`; both names describe the same lifecycle
+payload shape with vocabulary-appropriate SDK signatures. `UpgradeResult` is the
+same structured payload rendered by the CLI, so embedded tools can own their
+presentation layer while sharing pm's package/install/doctor semantics.
+
 `PmClient` and `runAction` share the same process-wide extension activation
 queue as MCP. Calls from one process are serialized across extension load,
 activation, dispatch, cleanup, and deactivate so active extension registries stay
@@ -579,9 +603,15 @@ Some override surfaces are single-winner: command overrides, parser overrides, p
 
 ```bash
 pm package doctor --project --detail deep --trace
+pm package doctor --project --isolated --detail deep --trace
 pm health --check-only --brief
 ```
 
+Use `--isolated` (alias `--ignore-global`) for hermetic package smoke tests:
+project diagnostics skip global registrations and avoid machine-local
+renderer/service overrides. The same isolation can be applied to a whole
+subprocess suite by setting `PM_GLOBAL_PATH` to a temporary directory.
+
 Collision warnings are deterministic and include package names plus deactivation guidance.
 If extension code calls a `register*` API without declaring the matching
 manifest capability, activation fails with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.7.7",
+  "version": "2026.7.8",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -103,6 +103,7 @@
     "review:greptile:gate": "node scripts/release/greptile-review-gate.mjs",
     "security:scan": "node scripts/check-secrets.mjs",
     "smoke:npx": "node scripts/smoke-npx-from-pack.mjs",
+    "sentry:telemetry:gate": "node scripts/release/sentry-telemetry-gate.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",

package/dist/cli-bundle/chunks/append-F7WPGIQL.js

@@ -1,11 +0,0 @@
-import {
-  runAppend
-} from "./chunk-DDDWVPID.js";
-import "./chunk-WW4E2DC3.js";
-import "./chunk-2TILG6F2.js";
-import "./chunk-YNCFP5AR.js";
-import "./chunk-LCFJ7XAM.js";
-export {
-  runAppend
-};
-//# sourceMappingURL=append-F7WPGIQL.js.map