@unbrained/pm-cli 2026.5.2 → 2026.5.3-6

package/dist/core/telemetry/runtime.js

@@ -2,9 +2,11 @@ import crypto from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { appendLineAtomic, readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
+import { resolveTelemetryErrorCategory } from "../shared/constants.js";
 import { nowIso } from "../shared/time.js";
 import { resolveGlobalPmRoot } from "../store/paths.js";
 import { readSettings, writeSettings } from "../store/settings.js";
+import { deriveTelemetryCommandResolution, deriveTelemetryCommandTaxonomy, inferTelemetryErrorCode, } from "./observability.js";
 const TELEMETRY_QUEUE_RELATIVE_PATH = path.join("runtime", "telemetry", "events.jsonl");
 const TELEMETRY_STATE_RELATIVE_PATH = path.join("runtime", "telemetry", "state.json");
 const TELEMETRY_SCHEMA_VERSION = 1;
@@ -52,6 +54,9 @@ const SENSITIVE_INLINE_KEY_PATTERN = "(?:token|secret|password|passwd|api[_-]?ke
 const INLINE_SENSITIVE_ASSIGNMENT_PATTERN = new RegExp(`\\b(${SENSITIVE_INLINE_KEY_PATTERN})\\s*([:=])\\s*([^\\s,;]+)`, "giu");
 const INLINE_SENSITIVE_FLAG_PATTERN = new RegExp(`(--${SENSITIVE_INLINE_KEY_PATTERN})(=|\\s+)([^\\s,;]+)`, "giu");
 const ABSOLUTE_PATH_TOKEN_PATTERN = /(^|[\s"'`(=])\/(?:[^\s"'`),;]+)/g;
+const EMAIL_PATTERN = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/giu;
+const BEARER_TOKEN_PATTERN = /bearer\s+[a-z0-9._=-]+/giu;
+const PRIVATE_IP_PATTERN = /\b(?:10\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)|172\.(?:1[6-9]|2\d|3[01])\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)|192\.168\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.(?:25[0-5]|2[0-4]\d|[01]?\d?\d))\b/g;
 function queuePath(globalPmRoot) {
     return path.join(globalPmRoot, TELEMETRY_QUEUE_RELATIVE_PATH);
 }
@@ -102,10 +107,14 @@ function redactInlineSensitiveAssignments(input) {
 function redactAbsolutePathTokens(input) {
     return input.replaceAll(ABSOLUTE_PATH_TOKEN_PATTERN, (_match, prefix) => `${prefix}[redacted_path]`);
 }
+function sanitizeCommonSensitiveTokens(input) {
+    const withoutEmails = input.replaceAll(EMAIL_PATTERN, "[redacted_email]");
+    const withoutBearer = withoutEmails.replaceAll(BEARER_TOKEN_PATTERN, "bearer [redacted_token]");
+    return withoutBearer.replaceAll(PRIVATE_IP_PATTERN, "[redacted_ip]");
+}
 function sanitizeStringRedacted(input) {
-    const withoutEmails = input.replaceAll(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/giu, "[redacted_email]");
-    const withoutBearer = withoutEmails.replaceAll(/bearer\s+[a-z0-9._=-]+/giu, "bearer [redacted_token]");
-    const withoutInlineSecrets = redactInlineSensitiveAssignments(withoutBearer);
+    const withoutCommonSensitiveTokens = sanitizeCommonSensitiveTokens(input);
+    const withoutInlineSecrets = redactInlineSensitiveAssignments(withoutCommonSensitiveTokens);
     const withoutAbsolutePaths = redactAbsolutePathTokens(withoutInlineSecrets);
     const trimmed = withoutAbsolutePaths.trim();
     if (trimmed.startsWith("/") && trimmed.length > 1) {
@@ -117,12 +126,17 @@ function sanitizeStringRedacted(input) {
     return withoutAbsolutePaths;
 }
 function sanitizeStringMax(input) {
-    const withoutBearer = input.replaceAll(/bearer\s+[a-z0-9._=-]+/giu, "bearer [redacted_token]");
-    const withoutInlineSecrets = redactInlineSensitiveAssignments(withoutBearer);
-    if (withoutInlineSecrets.length > 2048) {
-        return `${withoutInlineSecrets.slice(0, 2045)}...`;
+    const withoutCommonSensitiveTokens = sanitizeCommonSensitiveTokens(input);
+    const withoutInlineSecrets = redactInlineSensitiveAssignments(withoutCommonSensitiveTokens);
+    const withoutAbsolutePaths = redactAbsolutePathTokens(withoutInlineSecrets);
+    const trimmed = withoutAbsolutePaths.trim();
+    if (trimmed.startsWith("/") && trimmed.length > 1) {
+        return "[redacted_path]";
+    }
+    if (withoutAbsolutePaths.length > 2048) {
+        return `${withoutAbsolutePaths.slice(0, 2045)}...`;
     }
-    return withoutInlineSecrets;
+    return withoutAbsolutePaths;
 }
 function sanitizeString(input, captureLevel = "redacted") {
     if (captureLevel === "max") {
@@ -207,6 +221,28 @@ function normalizePmVersion(value) {
     const trimmed = value?.trim() ?? "";
     return trimmed.length > 0 ? trimmed : "0.0.0";
 }
+function normalizeTelemetryErrorCode(value) {
+    const normalized = value?.trim();
+    return normalized && normalized.length > 0 ? normalized : undefined;
+}
+function normalizeTelemetryExitCode(exitCode, ok) {
+    if (Number.isFinite(exitCode)) {
+        return Math.max(0, Math.trunc(exitCode ?? 0));
+    }
+    return ok ? 0 : 1;
+}
+function normalizeTelemetryErrorCategory(params) {
+    if (params.ok) {
+        return undefined;
+    }
+    if (typeof params.errorCategory === "string" && params.errorCategory.trim().length > 0) {
+        return params.errorCategory;
+    }
+    if (typeof params.errorCode === "string" && params.errorCode.trim().length > 0) {
+        return resolveTelemetryErrorCategory(params.errorCode);
+    }
+    return "unknown";
+}
 function resolveTelemetrySourceContext(globalOptions) {
     const override = (process.env[PM_TELEMETRY_SOURCE_CONTEXT_ENV] ?? "").trim().toLowerCase();
     if (PM_TELEMETRY_SOURCE_CONTEXT_SET.has(override)) {
@@ -239,6 +275,44 @@ function resolveTelemetrySourceContext(globalOptions) {
 function hashWithInstallationId(installationId, value) {
     return crypto.createHash("sha256").update(`${installationId}:${value}`).digest("hex");
 }
+function normalizeForHash(value, depth = 0) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return value;
+    }
+    if (depth >= TELEMETRY_SANITIZE_MAX_DEPTH) {
+        return "[depth_truncated]";
+    }
+    if (Array.isArray(value)) {
+        return value.slice(0, TELEMETRY_SANITIZE_MAX_ARRAY_ITEMS).map((entry) => normalizeForHash(entry, depth + 1));
+    }
+    if (typeof value === "object") {
+        const record = value;
+        const normalized = {};
+        const sortedKeys = Object.keys(record).sort((left, right) => left.localeCompare(right));
+        for (const key of sortedKeys) {
+            normalized[key] = normalizeForHash(record[key], depth + 1);
+        }
+        return normalized;
+    }
+    return String(value);
+}
+function hashTelemetryValue(installationId, value) {
+    return hashWithInstallationId(installationId, JSON.stringify(normalizeForHash(value)));
+}
+function hashCommandArgs(installationId, args) {
+    return {
+        hashes: args.map((arg) => hashWithInstallationId(installationId, arg)),
+        digest: hashWithInstallationId(installationId, args.join("\u0000")),
+    };
+}
+function hashTelemetryErrorFingerprint(installationId, command, errorCode, errorMessage) {
+    const normalizedMessage = sanitizeString(errorMessage ?? "", "redacted");
+    const fingerprintSource = `${command}\u0000${errorCode ?? "unknown_error"}\u0000${normalizedMessage}`;
+    return hashWithInstallationId(installationId, fingerprintSource);
+}
 function telemetryDisabledByEnvironment() {
     return PM_TELEMETRY_DISABLED_VALUES.has((process.env[PM_TELEMETRY_DISABLED_ENV] ?? "").trim().toLowerCase());
 }
@@ -305,6 +379,13 @@ async function exportLocalOtelSpan(activeCommand, outcome, finishedAtIso, durati
     }
     const serviceNameCandidate = sanitizeString((process.env[OTEL_SERVICE_NAME_ENV] ?? "").trim());
     const serviceName = serviceNameCandidate.length > 0 ? serviceNameCandidate : "pm-cli";
+    const normalizedExitCode = normalizeTelemetryExitCode(outcome.exit_code, outcome.ok);
+    const normalizedErrorCode = normalizeTelemetryErrorCode(outcome.error_code);
+    const normalizedErrorCategory = normalizeTelemetryErrorCategory({
+        ok: outcome.ok,
+        errorCode: normalizedErrorCode,
+        errorCategory: outcome.error_category,
+    });
     const attributes = [
         otlpStringAttribute("pm.command", sanitizeString(activeCommand.command)),
         otlpStringAttribute("pm.version", activeCommand.pm_version),
@@ -315,8 +396,15 @@ async function exportLocalOtelSpan(activeCommand, outcome, finishedAtIso, durati
         otlpStringAttribute("pm.pm_root_hash", activeCommand.pm_root_hash),
         otlpStringAttribute("pm.cwd_hash", activeCommand.cwd_hash),
         otlpBoolAttribute("pm.ok", outcome.ok),
+        otlpIntAttribute("pm.exit_code", normalizedExitCode),
         otlpIntAttribute("pm.duration_ms", durationMs),
     ];
+    if (typeof normalizedErrorCode === "string") {
+        attributes.push(otlpStringAttribute("pm.error_code", normalizedErrorCode));
+    }
+    if (typeof normalizedErrorCategory === "string") {
+        attributes.push(otlpStringAttribute("pm.error_category", normalizedErrorCategory));
+    }
     if (typeof outcome.error === "string" && outcome.error.trim().length > 0) {
         attributes.push(otlpStringAttribute("pm.error", sanitizeString(outcome.error)));
     }
@@ -407,21 +495,37 @@ function summarizeResult(result, captureLevel = "redacted") {
 }
 function buildCommandStartPayload(params) {
     const { captureLevel, context, pmVersion, sourceContext, pmRootHash, cwdHash, installationId } = params;
+    const commandTaxonomy = deriveTelemetryCommandTaxonomy(context.command);
+    const hashedArgs = hashCommandArgs(installationId, context.args);
+    const commandInvocationDigest = hashWithInstallationId(installationId, `${context.command}\u0000${context.args.join("\u0000")}`);
+    const commandOptionsDigest = hashTelemetryValue(installationId, context.options);
+    const globalOptionsDigest = hashTelemetryValue(installationId, context.global);
     if (captureLevel === "minimal") {
         return {
             capture_level: captureLevel,
             pm_version: pmVersion,
             source_context: sourceContext.source_context,
             source_context_source: sourceContext.source_context_source,
+            command_taxonomy: commandTaxonomy,
+            command_args_digest: hashedArgs.digest,
+            command_invocation_digest: commandInvocationDigest,
+            command_options_digest: commandOptionsDigest,
+            global_options_digest: globalOptionsDigest,
         };
     }
     return {
         pm_version: pmVersion,
         source_context: sourceContext.source_context,
         source_context_source: sourceContext.source_context_source,
+        command_taxonomy: commandTaxonomy,
         command_args: sanitizeCommandArgs(context.args, captureLevel),
+        command_args_hashes: hashedArgs.hashes,
+        command_args_digest: hashedArgs.digest,
+        command_invocation_digest: commandInvocationDigest,
         command_options: sanitizeValue(context.options, undefined, captureLevel),
+        command_options_digest: commandOptionsDigest,
         global_options: sanitizeValue(context.global, undefined, captureLevel),
+        global_options_digest: globalOptionsDigest,
         pm_root_hash: pmRootHash,
         cwd_hash: cwdHash,
         capture_level: captureLevel,
@@ -436,15 +540,25 @@ function buildCommandStartPayload(params) {
     };
 }
 function buildCommandFinishPayload(params) {
-    const { captureLevel, pmVersion, sourceContext, outcome, durationMs, startedAt } = params;
+    const { captureLevel, pmVersion, sourceContext, outcome, durationMs, startedAt, command, installationId, commandTaxonomy, exitCode, errorCode, errorCategory, commandResolution, resolutionStage, } = params;
+    const errorFingerprint = outcome.ok === false
+        ? hashTelemetryErrorFingerprint(installationId, command, errorCode, outcome.error)
+        : undefined;
     if (captureLevel === "minimal") {
         return {
             capture_level: captureLevel,
             pm_version: pmVersion,
             source_context: sourceContext.source_context,
             source_context_source: sourceContext.source_context_source,
+            command_taxonomy: commandTaxonomy,
+            command_resolution: commandResolution,
+            resolution_stage: resolutionStage,
             ok: outcome.ok,
+            exit_code: exitCode,
+            error_code: errorCode,
+            error_category: errorCategory,
             error: outcome.error ? sanitizeString(outcome.error, "redacted") : undefined,
+            error_fingerprint: errorFingerprint,
             duration_ms: durationMs,
         };
     }
@@ -453,13 +567,77 @@ function buildCommandFinishPayload(params) {
         pm_version: pmVersion,
         source_context: sourceContext.source_context,
         source_context_source: sourceContext.source_context_source,
+        command_taxonomy: commandTaxonomy,
+        command_resolution: commandResolution,
+        resolution_stage: resolutionStage,
         ok: outcome.ok,
+        exit_code: exitCode,
+        error_code: errorCode,
+        error_category: errorCategory,
         error: outcome.error ? sanitizeString(outcome.error, captureLevel) : undefined,
+        error_fingerprint: errorFingerprint,
         duration_ms: durationMs,
         started_at: startedAt,
         result_summary: summarizeResult(outcome.result, captureLevel),
     };
 }
+function buildCommandErrorPayload(params) {
+    const { captureLevel, pmVersion, sourceContext, command, commandTaxonomy, commandResolution, resolutionStage, args, options, pmRootHash, cwdHash, installationId, errorCode, errorMessage, errorCategory, exitCode, } = params;
+    const attemptedArgHashes = hashCommandArgs(installationId, args);
+    const attemptedCommandDigest = hashWithInstallationId(installationId, command);
+    const attemptedOptionsDigest = hashTelemetryValue(installationId, options);
+    const errorFingerprint = hashTelemetryErrorFingerprint(installationId, command, errorCode, errorMessage);
+    if (captureLevel === "minimal") {
+        return {
+            capture_level: captureLevel,
+            pm_version: pmVersion,
+            source_context: sourceContext.source_context,
+            source_context_source: sourceContext.source_context_source,
+            command_taxonomy: commandTaxonomy,
+            command_resolution: commandResolution,
+            resolution_stage: resolutionStage,
+            attempted_command_digest: attemptedCommandDigest,
+            attempted_args_digest: attemptedArgHashes.digest,
+            attempted_options_digest: attemptedOptionsDigest,
+            error_code: errorCode,
+            error_category: errorCategory,
+            exit_code: exitCode,
+            error: sanitizeString(errorMessage, "redacted"),
+            error_fingerprint: errorFingerprint,
+        };
+    }
+    return {
+        capture_level: captureLevel,
+        pm_version: pmVersion,
+        source_context: sourceContext.source_context,
+        source_context_source: sourceContext.source_context_source,
+        command_taxonomy: commandTaxonomy,
+        command_resolution: commandResolution,
+        resolution_stage: resolutionStage,
+        attempted_command: sanitizeString(command, captureLevel),
+        attempted_command_digest: attemptedCommandDigest,
+        attempted_args: sanitizeCommandArgs(args, captureLevel),
+        attempted_args_hashes: attemptedArgHashes.hashes,
+        attempted_args_digest: attemptedArgHashes.digest,
+        attempted_options: sanitizeValue(options, undefined, captureLevel),
+        attempted_options_digest: attemptedOptionsDigest,
+        error_code: errorCode,
+        error_category: errorCategory,
+        exit_code: exitCode,
+        error: sanitizeString(errorMessage, captureLevel),
+        error_fingerprint: errorFingerprint,
+        pm_root_hash: pmRootHash,
+        cwd_hash: cwdHash,
+        runtime: {
+            node: process.version,
+            platform: process.platform,
+            arch: process.arch,
+            hostname_hash: hashWithInstallationId(installationId, os.hostname()),
+            stdin_tty: process.stdin.isTTY === true,
+            stdout_tty: process.stdout.isTTY === true,
+        },
+    };
+}
 async function ensureInstallationId(globalPmRoot) {
     const settings = await readSettings(globalPmRoot);
     let changed = false;
@@ -605,12 +783,17 @@ async function flushQueue(globalPmRoot, endpoint, retentionDays) {
     }
     const dueIds = new Set(dueEntries.map((entry) => entry.event.event_id));
     const attemptTime = nowIso();
+    const requestHeaders = {
+        "content-type": "application/json",
+    };
+    const ingestKey = process.env.PM_TELEMETRY_INGEST_KEY?.trim();
+    if (ingestKey) {
+        requestHeaders["x-pm-telemetry-key"] = ingestKey;
+    }
     try {
         const response = await fetch(normalizedEndpoint, {
             method: "POST",
-            headers: {
-                "content-type": "application/json",
-            },
+            headers: requestHeaders,
             body: JSON.stringify({
                 schema_version: TELEMETRY_SCHEMA_VERSION,
                 events: dueEntries.map((entry) => entry.event),
@@ -698,10 +881,12 @@ export async function startTelemetryCommand(context) {
         };
         await enqueueTelemetryEvent(globalPmRoot, event);
         _lastFlushPromise = flushQueue(globalPmRoot, endpoint, retentionDays).catch(() => { });
+        const commandTaxonomy = deriveTelemetryCommandTaxonomy(context.command);
         return {
             started_at: occurredAt,
             started_at_ms: Date.now(),
             command: context.command,
+            command_taxonomy: commandTaxonomy,
             pm_version: pmVersion,
             source_context: sourceContext.source_context,
             source_context_source: sourceContext.source_context_source,
@@ -729,6 +914,25 @@ export async function finishTelemetryCommand(activeCommand, outcome) {
     try {
         const finishedAt = nowIso();
         const durationMs = Math.max(0, Date.now() - activeCommand.started_at_ms);
+        const normalizedErrorCode = normalizeTelemetryErrorCode(inferTelemetryErrorCode({
+            ok: outcome.ok,
+            errorCode: outcome.error_code,
+            errorMessage: outcome.error,
+            exitCode: outcome.exit_code,
+        }));
+        const normalizedErrorCategory = normalizeTelemetryErrorCategory({
+            ok: outcome.ok,
+            errorCode: normalizedErrorCode,
+            errorCategory: outcome.error_category,
+        });
+        const normalizedExitCode = normalizeTelemetryExitCode(outcome.exit_code, outcome.ok);
+        const commandResolution = outcome.command_resolution ??
+            deriveTelemetryCommandResolution({
+                ok: outcome.ok,
+                errorCode: normalizedErrorCode,
+                errorCategory: normalizedErrorCategory,
+            });
+        const resolutionStage = outcome.resolution_stage ?? "execute";
         const event = {
             schema_version: TELEMETRY_SCHEMA_VERSION,
             event_id: crypto.randomUUID(),
@@ -747,11 +951,92 @@ export async function finishTelemetryCommand(activeCommand, outcome) {
                 outcome,
                 durationMs,
                 startedAt: activeCommand.started_at,
+                command: activeCommand.command,
+                installationId: activeCommand.installation_id,
+                commandTaxonomy: activeCommand.command_taxonomy,
+                exitCode: normalizedExitCode,
+                errorCode: normalizedErrorCode,
+                errorCategory: normalizedErrorCategory,
+                commandResolution,
+                resolutionStage,
             }),
         };
         await enqueueTelemetryEvent(activeCommand.global_pm_root, event);
         _lastFlushPromise = flushQueue(activeCommand.global_pm_root, activeCommand.endpoint, activeCommand.retention_days).catch(() => { });
-        void exportLocalOtelSpan(activeCommand, outcome, finishedAt, durationMs).catch(() => { });
+        void exportLocalOtelSpan(activeCommand, {
+            ...outcome,
+            exit_code: normalizedExitCode,
+            error_code: normalizedErrorCode,
+            error_category: normalizedErrorCategory,
+        }, finishedAt, durationMs).catch(() => { });
+    }
+    catch {
+        // Telemetry must never block command execution.
+    }
+}
+export async function emitTelemetryErrorEvent(context) {
+    if (telemetryDisabledByEnvironment()) {
+        return;
+    }
+    try {
+        const globalPmRoot = resolveGlobalPmRoot(process.cwd());
+        const settings = await readSettings(globalPmRoot);
+        if (!settings.telemetry.enabled) {
+            return;
+        }
+        const captureLevel = normalizeCaptureLevel(settings.telemetry.capture_level);
+        const { installationId, endpoint, retentionDays } = await ensureInstallationId(globalPmRoot);
+        const pmVersion = normalizePmVersion(context.pm_version);
+        const sourceContext = resolveTelemetrySourceContext(context.global);
+        const pmRootHash = hashWithInstallationId(installationId, context.pm_root);
+        const cwdHash = hashWithInstallationId(installationId, process.cwd());
+        const occurredAt = nowIso();
+        const normalizedErrorCode = normalizeTelemetryErrorCode(inferTelemetryErrorCode({
+            ok: false,
+            errorCode: context.error_code,
+            errorMessage: context.error_message,
+            exitCode: context.exit_code,
+        })) ?? "unknown_error";
+        const normalizedErrorCategory = context.error_category ?? resolveTelemetryErrorCategory(normalizedErrorCode);
+        const normalizedExitCode = normalizeTelemetryExitCode(context.exit_code, false);
+        const normalizedCommand = context.command.trim().length > 0 ? context.command : "<unknown>";
+        const commandTaxonomy = deriveTelemetryCommandTaxonomy(normalizedCommand);
+        const commandResolution = context.command_resolution ??
+            deriveTelemetryCommandResolution({
+                ok: false,
+                errorCode: normalizedErrorCode,
+                errorCategory: normalizedErrorCategory,
+            });
+        const resolutionStage = context.resolution_stage ?? "unknown";
+        const event = {
+            schema_version: TELEMETRY_SCHEMA_VERSION,
+            event_id: crypto.randomUUID(),
+            event_type: "command_error",
+            occurred_at: occurredAt,
+            installation_id: installationId,
+            session_id: PROCESS_SESSION_ID,
+            command: sanitizeString(normalizedCommand, "redacted"),
+            payload: buildCommandErrorPayload({
+                captureLevel,
+                pmVersion,
+                sourceContext,
+                command: normalizedCommand,
+                commandTaxonomy,
+                commandResolution,
+                resolutionStage,
+                args: context.args,
+                options: context.options,
+                pmRootHash,
+                cwdHash,
+                installationId,
+                errorCode: normalizedErrorCode,
+                errorCategory: normalizedErrorCategory,
+                exitCode: normalizedExitCode,
+                errorMessage: context.error_message,
+            }),
+        };
+        await enqueueTelemetryEvent(globalPmRoot, event);
+        _lastFlushPromise = flushQueue(globalPmRoot, endpoint, retentionDays).catch(() => { });
     }
     catch {
         // Telemetry must never block command execution.