@unbrained/pm-cli 2026.5.2 → 2026.5.3-5

package/dist/core/telemetry/observability.js

@@ -0,0 +1,185 @@
+import { EXIT_CODE } from "../shared/constants.js";
+const SETUP_ROOT_COMMANDS = new Set(["init", "config", "completion", "completion-tags"]);
+const QUERY_ROOT_COMMANDS = new Set([
+    "list",
+    "list-all",
+    "list-open",
+    "list-in-progress",
+    "list-blocked",
+    "list-closed",
+    "list-canceled",
+    "list-draft",
+    "search",
+    "get",
+    "context",
+    "calendar",
+    "history",
+    "activity",
+    "aggregate",
+    "deps",
+    "contracts",
+    "stats",
+    "dedupe-audit",
+]);
+const MUTATION_ROOT_COMMANDS = new Set([
+    "create",
+    "update",
+    "update-many",
+    "append",
+    "close",
+    "delete",
+    "restore",
+    "claim",
+    "release",
+    "comments",
+    "notes",
+    "learnings",
+    "files",
+    "docs",
+    "start-task",
+    "pause-task",
+    "close-task",
+]);
+const TESTING_ROOT_COMMANDS = new Set(["test", "test-all", "test-runs", "test-verify", "trace-test", "test-ping"]);
+const DIAGNOSTICS_ROOT_COMMANDS = new Set(["health", "validate", "normalize", "reindex", "gc", "extension-doctor"]);
+function normalizeCommandPath(commandPath) {
+    return commandPath
+        .trim()
+        .replaceAll(/\s+/g, " ")
+        .toLowerCase();
+}
+function normalizeErrorCode(errorCode) {
+    const normalized = errorCode?.trim().toLowerCase();
+    return normalized && normalized.length > 0 ? normalized : undefined;
+}
+export function deriveTelemetryCommandTaxonomy(commandPath) {
+    const normalizedPath = normalizeCommandPath(commandPath);
+    const tokens = normalizedPath.length > 0 ? normalizedPath.split(" ") : ["<unknown>"];
+    const root = tokens[0] ?? "<unknown>";
+    const leaf = tokens[tokens.length - 1] ?? root;
+    let family = "other";
+    if (SETUP_ROOT_COMMANDS.has(root)) {
+        family = "setup";
+    }
+    else if (QUERY_ROOT_COMMANDS.has(root)) {
+        family = "query";
+    }
+    else if (MUTATION_ROOT_COMMANDS.has(root)) {
+        family = "mutation";
+    }
+    else if (TESTING_ROOT_COMMANDS.has(root)) {
+        family = "testing";
+    }
+    else if (root === "extension") {
+        family = "extension";
+    }
+    else if (DIAGNOSTICS_ROOT_COMMANDS.has(root)) {
+        family = "diagnostics";
+    }
+    return {
+        command_path: normalizedPath.length > 0 ? normalizedPath : "<unknown>",
+        command_root: root,
+        command_leaf: leaf,
+        command_depth: tokens.length,
+        command_family: family,
+    };
+}
+export function inferTelemetryErrorCode(params) {
+    if (params.ok) {
+        return undefined;
+    }
+    const explicit = normalizeErrorCode(params.errorCode);
+    if (explicit) {
+        return explicit;
+    }
+    const message = (params.errorMessage ?? "").trim().toLowerCase();
+    if (message.includes("unknown command")) {
+        return "unknown_command";
+    }
+    if (message.includes("unknown option")) {
+        return "unknown_option";
+    }
+    if (message.includes("missing required options") || message.includes("missing required option")) {
+        return "missing_required_option";
+    }
+    if (message.includes("missing required argument")) {
+        return "missing_required_argument";
+    }
+    if (message.includes("no update flags provided")) {
+        return "no_update_fields";
+    }
+    if (message.includes("is assigned to") && message.includes("use --force")) {
+        return "ownership_conflict";
+    }
+    if (message.includes("is locked")) {
+        return "lock_conflict";
+    }
+    if (message.includes("already terminal") && message.includes("use --force")) {
+        return "terminal_state_conflict";
+    }
+    if (message.includes("tracker is not initialized")) {
+        return "tracker_not_initialized";
+    }
+    if (message.includes(" not found")) {
+        return "item_not_found";
+    }
+    if (message.includes("use \"pm close <id> <text>\" to close an item") ||
+        (message.includes("invalid --status value") && message.includes("\"closed\""))) {
+        return "close_through_update";
+    }
+    if (message.startsWith("invalid ") || message.includes(" must be ")) {
+        return "invalid_argument_value";
+    }
+    if (message.includes("strict create mode requires concrete values for --")) {
+        return "missing_required_option";
+    }
+    if (message.includes("either as positional") && message.includes("not both")) {
+        return "invalid_command_usage";
+    }
+    const exitCode = Number.isFinite(params.exitCode) ? Math.max(0, Math.trunc(params.exitCode ?? 0)) : 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";
+}
+export function deriveTelemetryCommandResolution(params) {
+    if (params.ok) {
+        return "success";
+    }
+    const normalizedCode = normalizeErrorCode(params.errorCode);
+    if (normalizedCode === "unknown_command") {
+        return "nonexistent_command";
+    }
+    if (normalizedCode === "unknown_option") {
+        return "invalid_option";
+    }
+    if (normalizedCode === "missing_required_option") {
+        return "missing_required_option";
+    }
+    if (normalizedCode === "missing_required_argument") {
+        return "missing_required_argument";
+    }
+    if (params.errorCategory === "usage") {
+        return "invalid_usage";
+    }
+    if (params.errorCategory === "validation") {
+        return "validation_failed";
+    }
+    if (params.errorCategory === "conflict") {
+        return "conflict";
+    }
+    if (params.errorCategory === "runtime") {
+        return "runtime_failed";
+    }
+    return "unknown_failed";
+}
+//# sourceMappingURL=observability.js.map

package/dist/core/telemetry/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"/","sources":["core/telemetry/observability.ts"],"names":[],"mappings":"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","sourcesContent":["import { EXIT_CODE, type TelemetryErrorCategory } from \"../shared/constants.js\";\n\nexport type TelemetryResolutionStage = \"parse\" | \"preflight\" | \"execute\" | \"unknown\";\n\nexport type TelemetryCommandResolution =\n  | \"success\"\n  | \"nonexistent_command\"\n  | \"invalid_option\"\n  | \"missing_required_option\"\n  | \"missing_required_argument\"\n  | \"invalid_usage\"\n  | \"validation_failed\"\n  | \"conflict\"\n  | \"runtime_failed\"\n  | \"unknown_failed\";\n\nexport interface TelemetryCommandTaxonomy {\n  command_path: string;\n  command_root: string;\n  command_leaf: string;\n  command_depth: number;\n  command_family: \"setup\" | \"query\" | \"mutation\" | \"testing\" | \"extension\" | \"diagnostics\" | \"other\";\n}\n\ninterface InferTelemetryErrorCodeParams {\n  ok: boolean;\n  errorCode?: string;\n  errorMessage?: string;\n  exitCode?: number;\n}\n\nconst SETUP_ROOT_COMMANDS = new Set([\"init\", \"config\", \"completion\", \"completion-tags\"]);\nconst QUERY_ROOT_COMMANDS = new Set([\n  \"list\",\n  \"list-all\",\n  \"list-open\",\n  \"list-in-progress\",\n  \"list-blocked\",\n  \"list-closed\",\n  \"list-canceled\",\n  \"list-draft\",\n  \"search\",\n  \"get\",\n  \"context\",\n  \"calendar\",\n  \"history\",\n  \"activity\",\n  \"aggregate\",\n  \"deps\",\n  \"contracts\",\n  \"stats\",\n  \"dedupe-audit\",\n]);\nconst MUTATION_ROOT_COMMANDS = new Set([\n  \"create\",\n  \"update\",\n  \"update-many\",\n  \"append\",\n  \"close\",\n  \"delete\",\n  \"restore\",\n  \"claim\",\n  \"release\",\n  \"comments\",\n  \"notes\",\n  \"learnings\",\n  \"files\",\n  \"docs\",\n  \"start-task\",\n  \"pause-task\",\n  \"close-task\",\n]);\nconst TESTING_ROOT_COMMANDS = new Set([\"test\", \"test-all\", \"test-runs\", \"test-verify\", \"trace-test\", \"test-ping\"]);\nconst DIAGNOSTICS_ROOT_COMMANDS = new Set([\"health\", \"validate\", \"normalize\", \"reindex\", \"gc\", \"extension-doctor\"]);\n\nfunction normalizeCommandPath(commandPath: string): string {\n  return commandPath\n    .trim()\n    .replaceAll(/\\s+/g, \" \")\n    .toLowerCase();\n}\n\nfunction normalizeErrorCode(errorCode: string | undefined): string | undefined {\n  const normalized = errorCode?.trim().toLowerCase();\n  return normalized && normalized.length > 0 ? normalized : undefined;\n}\n\nexport function deriveTelemetryCommandTaxonomy(commandPath: string): TelemetryCommandTaxonomy {\n  const normalizedPath = normalizeCommandPath(commandPath);\n  const tokens = normalizedPath.length > 0 ? normalizedPath.split(\" \") : [\"<unknown>\"];\n  const root = tokens[0] ?? \"<unknown>\";\n  const leaf = tokens[tokens.length - 1] ?? root;\n\n  let family: TelemetryCommandTaxonomy[\"command_family\"] = \"other\";\n  if (SETUP_ROOT_COMMANDS.has(root)) {\n    family = \"setup\";\n  } else if (QUERY_ROOT_COMMANDS.has(root)) {\n    family = \"query\";\n  } else if (MUTATION_ROOT_COMMANDS.has(root)) {\n    family = \"mutation\";\n  } else if (TESTING_ROOT_COMMANDS.has(root)) {\n    family = \"testing\";\n  } else if (root === \"extension\") {\n    family = \"extension\";\n  } else if (DIAGNOSTICS_ROOT_COMMANDS.has(root)) {\n    family = \"diagnostics\";\n  }\n\n  return {\n    command_path: normalizedPath.length > 0 ? normalizedPath : \"<unknown>\",\n    command_root: root,\n    command_leaf: leaf,\n    command_depth: tokens.length,\n    command_family: family,\n  };\n}\n\nexport function inferTelemetryErrorCode(params: InferTelemetryErrorCodeParams): string | undefined {\n  if (params.ok) {\n    return undefined;\n  }\n\n  const explicit = normalizeErrorCode(params.errorCode);\n  if (explicit) {\n    return explicit;\n  }\n\n  const message = (params.errorMessage ?? \"\").trim().toLowerCase();\n  if (message.includes(\"unknown command\")) {\n    return \"unknown_command\";\n  }\n  if (message.includes(\"unknown option\")) {\n    return \"unknown_option\";\n  }\n  if (message.includes(\"missing required options\") || message.includes(\"missing required option\")) {\n    return \"missing_required_option\";\n  }\n  if (message.includes(\"missing required argument\")) {\n    return \"missing_required_argument\";\n  }\n  if (message.includes(\"no update flags provided\")) {\n    return \"no_update_fields\";\n  }\n  if (message.includes(\"is assigned to\") && message.includes(\"use --force\")) {\n    return \"ownership_conflict\";\n  }\n  if (message.includes(\"is locked\")) {\n    return \"lock_conflict\";\n  }\n  if (message.includes(\"already terminal\") && message.includes(\"use --force\")) {\n    return \"terminal_state_conflict\";\n  }\n  if (message.includes(\"tracker is not initialized\")) {\n    return \"tracker_not_initialized\";\n  }\n  if (message.includes(\" not found\")) {\n    return \"item_not_found\";\n  }\n  if (\n    message.includes(\"use \\\"pm close <id> <text>\\\" to close an item\") ||\n    (message.includes(\"invalid --status value\") && message.includes(\"\\\"closed\\\"\"))\n  ) {\n    return \"close_through_update\";\n  }\n  if (message.startsWith(\"invalid \") || message.includes(\" must be \")) {\n    return \"invalid_argument_value\";\n  }\n  if (message.includes(\"strict create mode requires concrete values for --\")) {\n    return \"missing_required_option\";\n  }\n  if (message.includes(\"either as positional\") && message.includes(\"not both\")) {\n    return \"invalid_command_usage\";\n  }\n\n  const exitCode = Number.isFinite(params.exitCode) ? Math.max(0, Math.trunc(params.exitCode ?? 0)) : undefined;\n  if (exitCode === EXIT_CODE.USAGE) {\n    return \"invalid_command_usage\";\n  }\n  if (exitCode === EXIT_CODE.NOT_FOUND) {\n    return \"item_not_found\";\n  }\n  if (exitCode === EXIT_CODE.CONFLICT) {\n    return \"lock_conflict\";\n  }\n  if (exitCode === EXIT_CODE.DEPENDENCY_FAILED) {\n    return \"dependency_failed\";\n  }\n  return \"command_failed\";\n}\n\nexport function deriveTelemetryCommandResolution(params: {\n  ok: boolean;\n  errorCode?: string;\n  errorCategory?: TelemetryErrorCategory;\n}): TelemetryCommandResolution {\n  if (params.ok) {\n    return \"success\";\n  }\n\n  const normalizedCode = normalizeErrorCode(params.errorCode);\n  if (normalizedCode === \"unknown_command\") {\n    return \"nonexistent_command\";\n  }\n  if (normalizedCode === \"unknown_option\") {\n    return \"invalid_option\";\n  }\n  if (normalizedCode === \"missing_required_option\") {\n    return \"missing_required_option\";\n  }\n  if (normalizedCode === \"missing_required_argument\") {\n    return \"missing_required_argument\";\n  }\n\n  if (params.errorCategory === \"usage\") {\n    return \"invalid_usage\";\n  }\n  if (params.errorCategory === \"validation\") {\n    return \"validation_failed\";\n  }\n  if (params.errorCategory === \"conflict\") {\n    return \"conflict\";\n  }\n  if (params.errorCategory === \"runtime\") {\n    return \"runtime_failed\";\n  }\n  return \"unknown_failed\";\n}\n"]}

package/dist/core/telemetry/runtime.d.ts

@@ -1,4 +1,6 @@
 import type { GlobalOptions } from "../shared/command-types.js";
+import { type TelemetryErrorCategory } from "../shared/constants.js";
+import { type TelemetryCommandResolution, type TelemetryCommandTaxonomy, type TelemetryResolutionStage } from "./observability.js";
 declare const PM_TELEMETRY_SOURCE_CONTEXT_VALUES: readonly ["user", "automation", "test", "dogfood", "audit_smoke"];
 /** Wait for the most recent background flush to settle. Test-only helper. */
 export declare function waitForPendingFlush(): Promise<void>;
@@ -9,6 +11,7 @@ export interface ActiveTelemetryCommand {
     started_at: string;
     started_at_ms: number;
     command: string;
+    command_taxonomy: TelemetryCommandTaxonomy;
     pm_version: string;
     source_context: TelemetrySourceContext;
     source_context_source: TelemetrySourceContextSource;
@@ -31,10 +34,31 @@ export interface TelemetryCommandContext {
     global: GlobalOptions;
     pm_root: string;
 }
-export declare function startTelemetryCommand(context: TelemetryCommandContext): Promise<ActiveTelemetryCommand | null>;
-export declare function finishTelemetryCommand(activeCommand: ActiveTelemetryCommand | null, outcome: {
+export interface TelemetryCommandOutcome {
     ok: boolean;
     error?: string;
     result?: unknown;
-}): Promise<void>;
+    exit_code?: number;
+    error_code?: string;
+    error_category?: TelemetryErrorCategory;
+    command_resolution?: TelemetryCommandResolution;
+    resolution_stage?: TelemetryResolutionStage;
+}
+export interface TelemetryErrorEventContext {
+    command: string;
+    args: string[];
+    options: Record<string, unknown>;
+    global: GlobalOptions;
+    pm_version: string;
+    pm_root: string;
+    error_code: string;
+    error_message: string;
+    exit_code: number;
+    error_category?: TelemetryErrorCategory;
+    command_resolution?: TelemetryCommandResolution;
+    resolution_stage?: TelemetryResolutionStage;
+}
+export declare function startTelemetryCommand(context: TelemetryCommandContext): Promise<ActiveTelemetryCommand | null>;
+export declare function finishTelemetryCommand(activeCommand: ActiveTelemetryCommand | null, outcome: TelemetryCommandOutcome): Promise<void>;
+export declare function emitTelemetryErrorEvent(context: TelemetryErrorEventContext): Promise<void>;
 export {};