@unbrained/pm-cli 2026.5.3 → 2026.5.4

package/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2026.5.4] - 2026-05-04
+
+### Changed
+- Relaxed release workflow npx/bunx post-publish checks to emit warnings instead of hard-failing the pipeline when registry/executor convergence lags, while keeping npm publication metadata as a blocking verification gate.
+
+## [2026.5.3-8] - 2026-05-03
+
+### Changed
+- Updated release workflow npx verification to run the explicit package binary command (`npx @unbrained/pm-cli@<version> pm --version`) to avoid npm exec binary resolution drift on GitHub-hosted runners.
+
+## [2026.5.3-7] - 2026-05-03
+
+### Changed
+- Updated release post-publish verification commands to execute the package `pm` binary explicitly (`npm exec --package ... -- pm --version` and `bunx ... pm --version`) and parse terminal line output robustly.
+
+## [2026.5.3-6] - 2026-05-03
+
+### Changed
+- Added npm/npx/bunx propagation retries to release publication verification so post-publish checks wait for registry availability instead of failing immediately on transient 404 windows.
+
+## [2026.5.3-5] - 2026-05-03
+
+### Changed
+- Hardened release workflow reliability gating so Sentry threshold checks are skipped when the runner does not provide the `sentry` CLI binary, preventing false-negative publish blocks on GitHub-hosted runners.
+
+## [2026.5.3-4] - 2026-05-03
+
+### Changed
+- Relaxed tag release version policy guard in `.github/workflows/release.yml` to validate tag/version consistency without blocking same-day retry tags when a previous tag run failed before npm publication.
+- Hardened `scripts/release/run-release-pipeline.mjs` same-day retry version resolution so local retry cuts always advance beyond the currently checked-out package version when npm has not yet observed failed prior tags.
+
+## [2026.5.3-3] - 2026-05-03
+
+### Fixed
+- Relaxed release compatibility health evaluation so compatibility gating only blocks on failing health checks, not warning-only health states, preventing false negatives on GitHub-hosted release runs.
+
+## [2026.5.3-2] - 2026-05-03
+
+### Added
+- Added a scheduled auto-release workflow (`.github/workflows/auto-release.yml`) with one-release-per-UTC-day defaults, manual same-day override controls, and a shared release pipeline driver.
+- Added release automation scripts under `scripts/release/` for changelog promotion, strict static quality checks, temporary-project backward-compatibility validation, Sentry/telemetry threshold gating, unified release gate execution, and full local pipeline orchestration.
+- Added release automation contract coverage in `tests/integration/release-automation-contract.spec.ts`.
+
+### Changed
+- Hardened CI, nightly, and release workflows with explicit static quality and compatibility migration gates.
+- Release workflow now verifies published package availability via npm, npx, and bunx, and verifies GitHub release metadata after publication.
+- Expanded release-readiness runtime checks to cover new release scripts, package commands, and auto-release workflow presence.
+
 ## [2026.5.3] - 2026-05-03
 
 ### Added

package/README.md

@@ -17,7 +17,7 @@
 | Settings, storage, search, and output | [Configuration](docs/CONFIGURATION.md) |
 | Safe test execution and linked tests | [Testing](docs/TESTING.md) |
 | Extension authoring | [Extensions](docs/EXTENSIONS.md) and [SDK](docs/SDK.md) |
-| Maintainer release process | [Releasing](docs/RELEASING.md) |
+| Maintainer release process (daily auto-release + local parity) | [Releasing](docs/RELEASING.md) |
 | Contributor internals | [Architecture](docs/ARCHITECTURE.md) |
 
 Full documentation starts at [docs/README.md](docs/README.md).
@@ -76,6 +76,14 @@ pm list-in-progress --limit 20
 
 If no relevant item exists, create a parent lineage before child work, claim the child item, link changed files/docs/tests, and leave evidence comments before closing. The full workflow is in the [Agent Guide](docs/AGENT_GUIDE.md).
 
+## Release Automation
+
+- Daily release preparation runs in `.github/workflows/auto-release.yml`.
+- Tag-driven publishing remains in `.github/workflows/release.yml`.
+- Local parity commands:
+  - `pnpm release:pipeline:dry-run`
+  - `pnpm release:pipeline -- --telemetry-mode required`
+
 ## Core Model
 
 - Items live under `.agents/pm/` as TOON by default, with JSON-front-matter markdown also supported.

package/dist/cli/main.js

@@ -12,6 +12,7 @@ import { PmCliError } from "../core/shared/errors.js";
 import { printError, printResult, writeStdout } from "../core/output/output.js";
 import { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 import { emitTelemetryErrorEvent, finishTelemetryCommand, startTelemetryCommand, } from "../core/telemetry/runtime.js";
+import { deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";
 import { sentryCaptureCliError, sentryFinishCommandSpan, sentryFlush, sentryLogCliUsageError, sentrySetCommandContext, sentryStartCommandSpan, } from "../core/sentry/helpers.js";
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
@@ -38,6 +39,20 @@ if (typeof process.env[PM_PACKAGE_ROOT_ENV] !== "string" || process.env[PM_PACKA
 }
 let activeExtensionHookContext = null;
 let activeTelemetryCommandContext = null;
+const TELEMETRY_COMMAND_RESOLUTION_SET = new Set([
+    "success",
+    "nonexistent_command",
+    "invalid_option",
+    "missing_required_option",
+    "missing_required_argument",
+    "invalid_usage",
+    "validation_failed",
+    "conflict",
+    "runtime_failed",
+    "unknown_failed",
+]);
+const TELEMETRY_RESOLUTION_STAGE_SET = new Set(["parse", "preflight", "execute", "unknown"]);
+const TELEMETRY_ERROR_CATEGORY_SET = new Set(["usage", "validation", "conflict", "runtime", "unknown"]);
 let runtimeExtensionSnapshotCache = null;
 let activeRuntimeExtensionCommandDescriptors = new Map();
 function describeUnknownError(error) {
@@ -49,6 +64,163 @@ function describeUnknownError(error) {
     }
     return "Unknown failure";
 }
+function asRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function readRecordString(record, ...keys) {
+    if (!record) {
+        return undefined;
+    }
+    for (const key of keys) {
+        const candidate = record[key];
+        if (typeof candidate === "string") {
+            const normalized = candidate.trim();
+            if (normalized.length > 0) {
+                return normalized;
+            }
+        }
+    }
+    return undefined;
+}
+function readRecordBoolean(record, ...keys) {
+    if (!record) {
+        return undefined;
+    }
+    for (const key of keys) {
+        const candidate = record[key];
+        if (typeof candidate === "boolean") {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function readRecordNumber(record, ...keys) {
+    if (!record) {
+        return undefined;
+    }
+    for (const key of keys) {
+        const candidate = record[key];
+        if (typeof candidate === "number" && Number.isFinite(candidate)) {
+            return Math.max(0, Math.trunc(candidate));
+        }
+    }
+    return undefined;
+}
+function normalizeTelemetryCommandResolution(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!TELEMETRY_COMMAND_RESOLUTION_SET.has(normalized)) {
+        return undefined;
+    }
+    return normalized;
+}
+function normalizeTelemetryResolutionStage(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!TELEMETRY_RESOLUTION_STAGE_SET.has(normalized)) {
+        return undefined;
+    }
+    return normalized;
+}
+function normalizeTelemetryErrorCategory(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!TELEMETRY_ERROR_CATEGORY_SET.has(normalized)) {
+        return undefined;
+    }
+    return normalized;
+}
+function inferPostActionFailureMessage(result) {
+    const explicit = readRecordString(result, "error", "message");
+    if (explicit) {
+        return explicit;
+    }
+    const warnings = result?.warnings;
+    if (Array.isArray(warnings)) {
+        const firstWarning = warnings.find((value) => typeof value === "string" && value.trim().length > 0);
+        if (typeof firstWarning === "string") {
+            return firstWarning.trim();
+        }
+    }
+    const skippedTriggered = readRecordBoolean(result, "fail_on_skipped_triggered", "failOnSkippedTriggered");
+    if (skippedTriggered) {
+        return "linked_test_fail_on_skipped_triggered";
+    }
+    const failedCount = readRecordNumber(result, "failed");
+    if (typeof failedCount === "number" && failedCount > 0) {
+        return `failed_runs:${failedCount}`;
+    }
+    const runResults = result?.run_results;
+    if (Array.isArray(runResults)) {
+        const failedRuns = runResults.filter((entry) => {
+            const row = asRecord(entry);
+            return row?.status === "failed";
+        }).length;
+        if (failedRuns > 0) {
+            return `failed_runs:${failedRuns}`;
+        }
+    }
+    return undefined;
+}
+function inferPostActionErrorCode(ok, exitCode) {
+    if (ok) {
+        return undefined;
+    }
+    if (exitCode === EXIT_CODE.USAGE) {
+        return "invalid_command_usage";
+    }
+    if (exitCode === EXIT_CODE.NOT_FOUND) {
+        return "item_not_found";
+    }
+    if (exitCode === EXIT_CODE.CONFLICT) {
+        return "lock_conflict";
+    }
+    if (exitCode === EXIT_CODE.DEPENDENCY_FAILED) {
+        return "dependency_failed";
+    }
+    return "command_failed";
+}
+function buildPostActionTelemetryOutcome() {
+    const result = asRecord(getActiveCommandResult());
+    const processExitCode = typeof process.exitCode === "number" && Number.isFinite(process.exitCode)
+        ? Math.max(0, Math.trunc(process.exitCode))
+        : undefined;
+    const resultExitCode = readRecordNumber(result, "exit_code", "exitCode");
+    const exitCode = processExitCode ?? resultExitCode ?? EXIT_CODE.SUCCESS;
+    const resultOk = readRecordBoolean(result, "ok");
+    const ok = resultOk ?? exitCode === EXIT_CODE.SUCCESS;
+    const errorCode = readRecordString(result, "error_code", "errorCode") ?? inferPostActionErrorCode(ok, exitCode);
+    const errorCategory = normalizeTelemetryErrorCategory(readRecordString(result, "error_category", "errorCategory")) ??
+        (!ok ? resolveTelemetryErrorCategory(errorCode) : undefined);
+    const errorMessage = !ok
+        ? inferPostActionFailureMessage(result) ?? `command_exit_${exitCode}`
+        : undefined;
+    const commandResolution = normalizeTelemetryCommandResolution(readRecordString(result, "command_resolution", "commandResolution")) ??
+        deriveTelemetryCommandResolution({
+            ok,
+            errorCode,
+            errorCategory,
+        });
+    const resolutionStage = normalizeTelemetryResolutionStage(readRecordString(result, "resolution_stage", "resolutionStage")) ?? "execute";
+    return {
+        ok,
+        error: errorMessage,
+        exit_code: exitCode,
+        error_code: errorCode,
+        error_category: errorCategory,
+        command_resolution: commandResolution,
+        resolution_stage: resolutionStage,
+    };
+}
 async function runAndClearAfterCommandHooks(outcome) {
     const telemetryRuntime = activeTelemetryCommandContext;
     activeTelemetryCommandContext = null;
@@ -59,6 +231,8 @@ async function runAndClearAfterCommandHooks(outcome) {
         exit_code: outcome.exit_code,
         error_code: outcome.error_code,
         error_category: outcome.error_category,
+        command_resolution: outcome.command_resolution,
+        resolution_stage: outcome.resolution_stage,
     });
     const runtime = activeExtensionHookContext;
     activeExtensionHookContext = null;
@@ -640,7 +814,10 @@ program.hook("preAction", async (_thisCommand, actionCommand) => {
             global: globalOptions,
             pm_root: fallbackPmRoot,
         });
-        sentrySetCommandContext(commandPath, commandArgs, commandOptions);
+        sentrySetCommandContext(commandPath, commandArgs, commandOptions, {
+            source_context: activeTelemetryCommandContext?.source_context,
+            source_context_source: activeTelemetryCommandContext?.source_context_source,
+        });
         sentryStartCommandSpan(commandPath);
         await enforceItemFormatWriteGateAndPreflightMigration(commandPath, commandOptions, fallbackPmRoot, defaultPreflightDecision());
         return;
@@ -716,7 +893,10 @@ program.hook("preAction", async (_thisCommand, actionCommand) => {
         global: globalOptions,
         pm_root: runtimeExtensions.pmRoot,
     });
-    sentrySetCommandContext(commandPath, commandArgs, commandOptions);
+    sentrySetCommandContext(commandPath, commandArgs, commandOptions, {
+        source_context: activeTelemetryCommandContext?.source_context,
+        source_context_source: activeTelemetryCommandContext?.source_context_source,
+    });
     sentryStartCommandSpan(commandPath);
     const hookWarnings = await runBeforeCommandHooks(runtimeExtensions.hooks, {
         command: commandPath,
@@ -733,8 +913,15 @@ program.hook("preAction", async (_thisCommand, actionCommand) => {
     }
 });
 program.hook("postAction", async () => {
-    sentryFinishCommandSpan(true);
-    await runAndClearAfterCommandHooks({ ok: true, exit_code: EXIT_CODE.SUCCESS });
+    const outcome = buildPostActionTelemetryOutcome();
+    sentryFinishCommandSpan(outcome.ok, outcome.error, {
+        error_code: outcome.error_code,
+        error_category: outcome.error_category,
+        exit_code: outcome.exit_code,
+        command_resolution: outcome.command_resolution,
+        resolution_stage: outcome.resolution_stage,
+    });
+    await runAndClearAfterCommandHooks(outcome);
 });
 registerSetupCommands(program);
 registerListQueryCommands(program);
@@ -762,6 +949,11 @@ async function main() {
         const attemptedCommand = parseBootstrapCommandName(invocationArgv) ?? "<unknown>";
         const emitTelemetryCommandError = async (params) => {
             const errorCategory = resolveTelemetryErrorCategory(params.errorCode);
+            const commandResolution = deriveTelemetryCommandResolution({
+                ok: false,
+                errorCode: params.errorCode,
+                errorCategory,
+            });
             await emitTelemetryErrorEvent({
                 command: params.command,
                 args: invocationArgv,
@@ -773,8 +965,13 @@ async function main() {
                 error_message: params.errorMessage,
                 exit_code: params.exitCode,
                 error_category: errorCategory,
+                command_resolution: commandResolution,
+                resolution_stage: params.resolutionStage,
             });
-            return errorCategory;
+            return {
+                errorCategory,
+                commandResolution,
+            };
         };
         if (!bootstrapGlobal.noExtensions) {
             const bootstrapSnapshot = await loadRuntimeExtensionSnapshot(bootstrapPmRoot);
@@ -782,7 +979,7 @@ async function main() {
         }
         if (error instanceof PmCliError) {
             const classification = classifyPmCliError(error.message, error.context);
-            const errorCategory = await emitTelemetryCommandError({
+            const { errorCategory, commandResolution } = await emitTelemetryCommandError({
                 command: attemptedCommand,
                 errorCode: classification.code,
                 errorMessage: classification.detail,
@@ -790,6 +987,7 @@ async function main() {
                 options: {
                     bootstrap_global_options: bootstrapGlobal,
                 },
+                resolutionStage: "execute",
             });
             sentryLogCliUsageError({
                 command: attemptedCommand,
@@ -797,14 +995,25 @@ async function main() {
                 error_category: errorCategory,
                 exit_code: error.exitCode,
                 error_message: classification.detail,
+                command_resolution: commandResolution,
+                resolution_stage: "execute",
+                source_context: activeTelemetryCommandContext?.source_context,
+            });
+            sentryFinishCommandSpan(false, error.message, {
+                error_code: classification.code,
+                error_category: errorCategory,
+                exit_code: error.exitCode,
+                command_resolution: commandResolution,
+                resolution_stage: "execute",
             });
-            sentryFinishCommandSpan(false, error.message);
             await runAndClearAfterCommandHooks({
                 ok: false,
                 error: error.message,
                 exit_code: error.exitCode,
                 error_code: classification.code,
                 error_category: errorCategory,
+                command_resolution: commandResolution,
+                resolution_stage: "execute",
             });
             sentryCaptureCliError(error);
             if (jsonErrors) {
@@ -831,7 +1040,7 @@ async function main() {
                         unknownCommandExamples: usageContext.unknownCommandExamples,
                         unknownCommandNextSteps: usageContext.unknownCommandNextSteps,
                     });
-                    const errorCategory = await emitTelemetryCommandError({
+                    const { errorCategory, commandResolution } = await emitTelemetryCommandError({
                         command: unknownToken,
                         errorCode: classification.code,
                         errorMessage: classification.detail,
@@ -840,6 +1049,7 @@ async function main() {
                             bootstrap_global_options: bootstrapGlobal,
                             commander_code: code ?? "commander.helpDisplayed",
                         },
+                        resolutionStage: "parse",
                     });
                     sentryLogCliUsageError({
                         command: unknownToken,
@@ -847,17 +1057,28 @@ async function main() {
                         error_category: errorCategory,
                         exit_code: EXIT_CODE.USAGE,
                         error_message: classification.detail,
+                        command_resolution: commandResolution,
+                        resolution_stage: "parse",
+                        source_context: activeTelemetryCommandContext?.source_context,
                     });
                     const renderedUsage = jsonErrors
                         ? await formatCommanderUsageJson({ message: unknownMessage }, program, activeRuntimeExtensionCommandDescriptors)
                         : await formatCommanderUsageMessage({ message: unknownMessage }, program, activeRuntimeExtensionCommandDescriptors);
-                    sentryFinishCommandSpan(false, unknownMessage);
+                    sentryFinishCommandSpan(false, unknownMessage, {
+                        error_code: classification.code,
+                        error_category: errorCategory,
+                        exit_code: EXIT_CODE.USAGE,
+                        command_resolution: commandResolution,
+                        resolution_stage: "parse",
+                    });
                     await runAndClearAfterCommandHooks({
                         ok: false,
                         error: unknownMessage,
                         exit_code: EXIT_CODE.USAGE,
                         error_code: classification.code,
                         error_category: errorCategory,
+                        command_resolution: commandResolution,
+                        resolution_stage: "parse",
                     });
                     if (jsonErrors) {
                         printError(renderedUsage);
@@ -869,19 +1090,31 @@ async function main() {
                     process.exitCode = EXIT_CODE.USAGE;
                     return;
                 }
-                sentryFinishCommandSpan(true);
+                sentryFinishCommandSpan(true, undefined, {
+                    exit_code: EXIT_CODE.SUCCESS,
+                    command_resolution: "success",
+                    resolution_stage: "parse",
+                });
                 await runAndClearAfterCommandHooks({
                     ok: true,
                     exit_code: EXIT_CODE.SUCCESS,
+                    command_resolution: "success",
+                    resolution_stage: "parse",
                 });
                 process.exitCode = EXIT_CODE.SUCCESS;
                 return;
             }
             if (code === "commander.version") {
-                sentryFinishCommandSpan(true);
+                sentryFinishCommandSpan(true, undefined, {
+                    exit_code: EXIT_CODE.SUCCESS,
+                    command_resolution: "success",
+                    resolution_stage: "parse",
+                });
                 await runAndClearAfterCommandHooks({
                     ok: true,
                     exit_code: EXIT_CODE.SUCCESS,
+                    command_resolution: "success",
+                    resolution_stage: "parse",
                 });
                 process.exitCode = EXIT_CODE.SUCCESS;
                 return;
@@ -892,7 +1125,7 @@ async function main() {
                     unknownCommandExamples: usageContext.unknownCommandExamples,
                     unknownCommandNextSteps: usageContext.unknownCommandNextSteps,
                 });
-                const errorCategory = await emitTelemetryCommandError({
+                const { errorCategory, commandResolution } = await emitTelemetryCommandError({
                     command: attemptedCommand,
                     errorCode: classification.code,
                     errorMessage: classification.detail,
@@ -901,6 +1134,7 @@ async function main() {
                         bootstrap_global_options: bootstrapGlobal,
                         commander_code: code,
                     },
+                    resolutionStage: "parse",
                 });
                 sentryLogCliUsageError({
                     command: attemptedCommand,
@@ -908,17 +1142,28 @@ async function main() {
                     error_category: errorCategory,
                     exit_code: EXIT_CODE.USAGE,
                     error_message: classification.detail,
+                    command_resolution: commandResolution,
+                    resolution_stage: "parse",
+                    source_context: activeTelemetryCommandContext?.source_context,
                 });
                 const renderedUsage = jsonErrors
                     ? await formatCommanderUsageJson(error, program, activeRuntimeExtensionCommandDescriptors)
                     : await formatCommanderUsageMessage(error, program, activeRuntimeExtensionCommandDescriptors);
-                sentryFinishCommandSpan(false, usageContext.message);
+                sentryFinishCommandSpan(false, usageContext.message, {
+                    error_code: classification.code,
+                    error_category: errorCategory,
+                    exit_code: EXIT_CODE.USAGE,
+                    command_resolution: commandResolution,
+                    resolution_stage: "parse",
+                });
                 await runAndClearAfterCommandHooks({
                     ok: false,
                     error: usageContext.message,
                     exit_code: EXIT_CODE.USAGE,
                     error_code: classification.code,
                     error_category: errorCategory,
+                    command_resolution: commandResolution,
+                    resolution_stage: "parse",
                 });
                 if (jsonErrors) {
                     printError(renderedUsage);
@@ -934,7 +1179,7 @@ async function main() {
         sentryCaptureCliError(error);
         const message = describeUnknownError(error);
         const classification = classifyUnknownError(message);
-        const errorCategory = await emitTelemetryCommandError({
+        const { errorCategory, commandResolution } = await emitTelemetryCommandError({
             command: attemptedCommand,
             errorCode: classification.code,
             errorMessage: classification.detail,
@@ -942,14 +1187,23 @@ async function main() {
             options: {
                 bootstrap_global_options: bootstrapGlobal,
             },
+            resolutionStage: "execute",
+        });
+        sentryFinishCommandSpan(false, message, {
+            error_code: classification.code,
+            error_category: errorCategory,
+            exit_code: EXIT_CODE.GENERIC_FAILURE,
+            command_resolution: commandResolution,
+            resolution_stage: "execute",
         });
-        sentryFinishCommandSpan(false, message);
         await runAndClearAfterCommandHooks({
             ok: false,
             error: message,
             exit_code: EXIT_CODE.GENERIC_FAILURE,
             error_code: classification.code,
             error_category: errorCategory,
+            command_resolution: commandResolution,
+            resolution_stage: "execute",
         });
         if (jsonErrors) {
             printError(JSON.stringify(formatUnknownErrorForJson(message, EXIT_CODE.GENERIC_FAILURE), null, 2));