@unbrained/pm-cli 2026.5.3 → 2026.5.5

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));