crumbtrail-node 0.1.0 → 0.2.0

package/dist/{chunk-EASSXKUJ.js → chunk-5HPWIOG3.js}

@@ -2702,6 +2702,7 @@ var SentryError = class extends Error {
     this.status = status;
     this.name = "SentryError";
   }
+  status;
 };
 function sanitizeUrl2(u) {
   try {
@@ -3115,6 +3116,8 @@ var CloudWatchError = class extends Error {
     this.target = target;
     this.name = "CloudWatchError";
   }
+  status;
+  target;
 };
 function isTransient2(error) {
   if (error instanceof CloudWatchError) {
@@ -3527,6 +3530,7 @@ var SplunkError = class extends Error {
     this.status = status;
     this.name = "SplunkError";
   }
+  status;
 };
 function sanitizeUrl3(u) {
   try {
@@ -3877,6 +3881,7 @@ var DatadogError = class extends Error {
     this.status = status;
     this.name = "DatadogError";
   }
+  status;
 };
 function sanitizeUrl4(u) {
   try {
@@ -4240,6 +4245,7 @@ var PostHogError = class extends Error {
     this.status = status;
     this.name = "PostHogError";
   }
+  status;
 };
 function sanitizeUrl5(u) {
   try {
@@ -4630,6 +4636,8 @@ var CloudflareError = class extends Error {
     this.op = op;
     this.name = "CloudflareError";
   }
+  status;
+  op;
 };
 function isTransient6(error) {
   if (error instanceof CloudflareError) {
@@ -10482,6 +10490,8 @@ var AudioProcessingError = class extends Error {
     this.cause = cause;
     this.name = "AudioProcessingError";
   }
+  phase;
+  cause;
 };
 var AudioTranscriptionUnavailableError = class extends Error {
   constructor() {
@@ -12964,12 +12974,12 @@ import fs10 from "fs";
 // package.json
 var package_default = {
   name: "crumbtrail-node",
-  version: "0.1.0",
+  version: "0.2.0",
   description: "Local Crumbtrail server, MCP evidence tools, Express middleware, and CLI for self-hosted debugging sessions.",
   license: "MIT",
   repository: {
     type: "git",
-    url: "https://github.com/oshabana/crumbtrail.git",
+    url: "git+https://github.com/crumbtrail-dev/crumbtrail-js.git",
     directory: "packages/node"
   },
   keywords: [
@@ -13022,6 +13032,10 @@ var package_default = {
     "@types/node": "^25.5.0",
     express: "^5.2.1",
     typescript: "^5.7.0"
+  },
+  homepage: "https://github.com/crumbtrail-dev/crumbtrail-js/tree/main/packages/node#readme",
+  bugs: {
+    url: "https://github.com/crumbtrail-dev/crumbtrail-js/issues"
   }
 };
 
@@ -13299,6 +13313,10 @@ var RequestValidationError = class extends Error {
     this.retryable = retryable;
     this.name = "RequestValidationError";
   }
+  status;
+  publicMessage;
+  code;
+  retryable;
 };
 function serveStatic(res, staticDir, urlPath) {
   const resolved = resolveStaticPath(staticDir, urlPath);
@@ -14028,6 +14046,7 @@ var BoundedTraceSessionCache = class {
   constructor(maxEntries) {
     this.maxEntries = maxEntries;
   }
+  maxEntries;
   entries = /* @__PURE__ */ new Map();
   get(traceId) {
     const existing = this.entries.get(traceId);
@@ -14726,6 +14745,20 @@ function createServer(config) {
     });
     server.on("close", () => sweeper.stop());
   }
+  if (config.ai?.enabled && config.ai.backfillOnStart) {
+    const sessionDirs = sessions.listSummaries().map((summary) => sessions.getExistingSessionDir(summary.id)).filter((dir) => dir !== void 0);
+    const timer = setTimeout(() => {
+      void backfillAiDiagnoses(
+        sessionDirs,
+        config.ai
+      ).then(
+        (result) => config.ai?.log?.(
+          `Crumbtrail AI diagnosis backfill complete: ${JSON.stringify(result)}`
+        )
+      );
+    }, 0);
+    server.on("close", () => clearTimeout(timer));
+  }
   if (fastFinalizer) {
     server.on("close", () => fastFinalizer.stop());
   }
@@ -14769,6 +14802,7 @@ var FixContextError = class extends Error {
     this.code = code;
     this.name = "FixContextError";
   }
+  code;
 };
 function buildFixContext(sessionDirOrId, opts = {}) {
   const sessionDir = resolveSessionDir(sessionDirOrId, opts);
@@ -15701,16 +15735,85 @@ function diffEnvironment(a, b, rules, disabled) {
       addSuppressedRules(rules, beforeRules, afterRules, disabled);
     return [];
   }
+  const envDelta = buildEnvDiff(a, b, disabled);
   return [
     {
       plane: "env",
       kind: "env.snapshot",
       before: a,
       after: b,
-      brief: "feature flag, config, release, or build snapshot changed between sessions"
+      brief: envBrief(envDelta),
+      envDelta
     }
   ];
 }
+function buildEnvDiff(a, b, disabled) {
+  const delta = {
+    flags: channelDelta(recordField(a.flags), recordField(b.flags), disabled),
+    config: channelDelta(
+      recordField(a.config),
+      recordField(b.config),
+      disabled
+    )
+  };
+  const releaseBefore = stringOrUndefined(a.release);
+  const releaseAfter = stringOrUndefined(b.release);
+  if (releaseBefore !== releaseAfter) {
+    delta.release = {
+      ...releaseBefore !== void 0 ? { before: releaseBefore } : {},
+      ...releaseAfter !== void 0 ? { after: releaseAfter } : {}
+    };
+  }
+  const buildBefore = stringOrUndefined(a.build);
+  const buildAfter = stringOrUndefined(b.build);
+  if (buildBefore !== buildAfter) {
+    delta.build = {
+      ...buildBefore !== void 0 ? { before: buildBefore } : {},
+      ...buildAfter !== void 0 ? { after: buildAfter } : {}
+    };
+  }
+  return delta;
+}
+function recordField(value) {
+  return isRecord14(value) ? value : {};
+}
+function channelDelta(a, b, disabled) {
+  const added = [];
+  const removed = [];
+  const changed = [];
+  for (const key of Object.keys(a).sort()) {
+    if (!(key in b)) {
+      removed.push({ key, before: a[key] });
+    } else if (envValuesDiffer(a[key], b[key], disabled)) {
+      changed.push({ key, before: a[key], after: b[key] });
+    }
+  }
+  for (const key of Object.keys(b).sort()) {
+    if (!(key in a)) added.push({ key, after: b[key] });
+  }
+  return { added, removed, changed };
+}
+function envValuesDiffer(before, after, disabled) {
+  const beforeRules = /* @__PURE__ */ new Set();
+  const afterRules = /* @__PURE__ */ new Set();
+  if (canonicalize(before, beforeRules) !== canonicalize(after, afterRules))
+    return true;
+  const rawDiffers = stableStringify(before) !== stableStringify(after);
+  return rawDiffers && hasDisabledRule(beforeRules, afterRules, disabled);
+}
+function envBrief(delta) {
+  const counts = delta.flags.added.length + delta.flags.removed.length + delta.flags.changed.length + delta.config.added.length + delta.config.removed.length + delta.config.changed.length + (delta.release ? 1 : 0) + (delta.build ? 1 : 0);
+  const parts = [];
+  const flagCount = delta.flags.added.length + delta.flags.removed.length + delta.flags.changed.length;
+  const configCount = delta.config.added.length + delta.config.removed.length + delta.config.changed.length;
+  if (flagCount > 0) parts.push(`${flagCount} flag(s)`);
+  if (configCount > 0) parts.push(`${configCount} config value(s)`);
+  if (delta.release) parts.push("release");
+  if (delta.build) parts.push("build");
+  if (counts === 0 || parts.length === 0)
+    return "feature flag, config, release, or build snapshot changed between sessions";
+  return `environment delta between sessions: ${parts.join(", ")} changed`;
+}
 function confidenceFor(divergences) {
   if (divergences.length === 0) return "high";
   if (divergences.some(
@@ -15737,6 +15840,9 @@ async function compareSessions(aDir, bDir, options = {}) {
     ...diffDb(a.dbWrites, b.dbWrites, rules, disabled),
     ...diffEnvironment(a.environment, b.environment, rules, disabled)
   ];
+  const envDelta = divergences.find(
+    (divergence) => divergence.kind === "env.snapshot"
+  )?.envDelta;
   return {
     schemaVersion: SESSION_COMPARE_SCHEMA_VERSION,
     verdict: divergences.length > 0 ? "regression" : "clean",
@@ -15759,20 +15865,185 @@ async function compareSessions(aDir, bDir, options = {}) {
     divergences,
     noise: { suppressedCount: rules.size, rules: [...rules].sort() },
     evidence: divergencesToEvidence(divergences),
-    intent: []
+    intent: [],
+    ...envDelta ? { envDelta } : {}
   };
 }
 
+// src/compare/report.ts
+var PLANE_ORDER = ["flow", "network", "db", "env"];
+var PLANE_LABELS = {
+  flow: "Flow steps",
+  network: "Network calls",
+  db: "Database rows",
+  env: "Environment and flags"
+};
+function renderCompareReport(comparison) {
+  const lines = [];
+  const regressed = comparison.verdict === "regression";
+  lines.push(
+    `# Session comparison - ${formatSessionRef(comparison.a)} vs ${formatSessionRef(comparison.b)}`
+  );
+  lines.push("");
+  lines.push(
+    regressed ? `> **Verdict: REGRESSION** (confidence: ${comparison.confidence}) - recorded behavior changed between these sessions.` : `> **Verdict: CLEAN** (confidence: ${comparison.confidence}) - the recorded sessions show no behavioral divergence.`
+  );
+  lines.push("");
+  lines.push(
+    "A is the baseline session; B is the candidate release/build. Every row below is grounded in the recorded evidence of both sessions."
+  );
+  lines.push("");
+  lines.push("## Aligned flow");
+  lines.push("");
+  const { matchedSteps, unmatchedA, unmatchedB } = comparison.alignment;
+  lines.push(
+    `${matchedSteps} step(s) matched by component identity \xB7 ${unmatchedA} only in A \xB7 ${unmatchedB} only in B`
+  );
+  lines.push("");
+  if (comparison.divergences.length > 0) {
+    lines.push("| Plane | Kind | Component | Divergence |");
+    lines.push("|---|---|---|---|");
+    for (const d of comparison.divergences) {
+      const component = d.sig ? `\`${escapeCell(d.sig)}\`` : "\u2014";
+      lines.push(
+        `| **${d.plane}** | \`${d.kind}\` | ${component} | ${escapeCell(d.brief)} |`
+      );
+    }
+    lines.push("");
+  }
+  for (const plane of PLANE_ORDER) {
+    const planeDivergences = comparison.divergences.filter(
+      (d) => d.plane === plane
+    );
+    if (planeDivergences.length === 0) continue;
+    lines.push(`## ${PLANE_LABELS[plane]}`);
+    lines.push("");
+    for (const d of planeDivergences) {
+      lines.push(`### \`${d.kind}\` - ${escapeCell(d.brief)}`);
+      lines.push("");
+      if (d.sig) lines.push(`- Component: \`${d.sig}\``);
+      if (d.requestId) lines.push(`- Request: \`${d.requestId}\``);
+      if (d.table)
+        lines.push(
+          `- Table: \`${d.table}\`${d.pk ? ` \xB7 pk \`${JSON.stringify(d.pk)}\`` : ""}`
+        );
+      lines.push("");
+      if (d.envDelta) {
+        lines.push(...renderEnvDelta(d.envDelta));
+      } else {
+        lines.push("```diff");
+        lines.push(`- before: ${JSON.stringify(d.before)}`);
+        lines.push(`+ after:  ${JSON.stringify(d.after)}`);
+        lines.push("```");
+      }
+      lines.push("");
+    }
+  }
+  lines.push("---");
+  lines.push("");
+  lines.push(
+    comparison.noise.suppressedCount > 0 ? `*${comparison.noise.suppressedCount} expected-variance difference(s) suppressed by the noise model (${comparison.noise.rules.join(", ")}).*` : "*No differences were suppressed by the noise model.*"
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+function formatComparisonSummary(comparison) {
+  const lines = [];
+  lines.push(
+    `crumbtrail-server compare - ${formatSessionRef(comparison.a)} vs ${formatSessionRef(comparison.b)}`
+  );
+  lines.push(`  Schema:      ${comparison.schemaVersion}`);
+  lines.push(
+    `  Verdict:     ${comparison.verdict.toUpperCase()} (confidence ${comparison.confidence})`
+  );
+  lines.push(
+    `  Alignment:   ${comparison.alignment.matchedSteps} matched \xB7 ${comparison.alignment.unmatchedA} only in A \xB7 ${comparison.alignment.unmatchedB} only in B`
+  );
+  lines.push(`  Divergences: ${comparison.divergences.length}`);
+  for (const d of comparison.divergences.slice(0, 5)) {
+    lines.push(`    [${d.plane}] ${d.kind} - ${d.brief}`);
+  }
+  if (comparison.divergences.length > 5) {
+    lines.push(
+      `    ... and ${comparison.divergences.length - 5} more (use --json or --report for the complete list)`
+    );
+  }
+  const rules = comparison.noise.rules.length > 0 ? ` (${comparison.noise.rules.join(", ")})` : "";
+  lines.push(
+    `  Noise:       ${comparison.noise.suppressedCount} suppressed${rules}`
+  );
+  return lines.join("\n");
+}
+function escapeCell(text2) {
+  return text2.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+function sessionRefLabel(ref) {
+  return ref.release ?? ref.sessionId;
+}
+function comparisonTitle(comparison) {
+  return `${sessionRefLabel(comparison.a)} vs ${sessionRefLabel(comparison.b)}`;
+}
+function renderEnvDelta(delta) {
+  const lines = ["```diff"];
+  renderEnvChannel(lines, "flags", delta.flags);
+  renderEnvChannel(lines, "config", delta.config);
+  if (delta.release) {
+    lines.push(
+      `~ release: ${JSON.stringify(delta.release.before ?? null)} -> ${JSON.stringify(delta.release.after ?? null)}`
+    );
+  }
+  if (delta.build) {
+    lines.push(
+      `~ build: ${JSON.stringify(delta.build.before ?? null)} -> ${JSON.stringify(delta.build.after ?? null)}`
+    );
+  }
+  if (lines.length === 1) lines.push("  (no field-level changes)");
+  lines.push("```");
+  return lines;
+}
+function renderEnvChannel(lines, channel, delta) {
+  for (const change of delta.added) {
+    lines.push(
+      `+ ${channel}.${change.key}: ${JSON.stringify(change.after ?? null)}`
+    );
+  }
+  for (const change of delta.removed) {
+    lines.push(
+      `- ${channel}.${change.key}: ${JSON.stringify(change.before ?? null)}`
+    );
+  }
+  for (const change of delta.changed) {
+    lines.push(
+      `~ ${channel}.${change.key}: ${JSON.stringify(change.before ?? null)} -> ${JSON.stringify(change.after ?? null)}`
+    );
+  }
+}
+function formatSessionRef(ref) {
+  if (ref.release) {
+    const detail = [
+      `session ${ref.sessionId}`,
+      ref.build ? `build ${ref.build}` : void 0
+    ].filter(Boolean);
+    return `${ref.release} (${detail.join(", ")})`;
+  }
+  return ref.build ? `${ref.sessionId} (build ${ref.build})` : ref.sessionId;
+}
+
 // src/compare/regression-context.ts
 import fs13 from "fs";
 import path13 from "path";
 var REGRESSION_CONTEXT_SCHEMA_VERSION = "regression-context.v1";
 function buildRegressionContext(comparison, bDir) {
-  const requestIds = unique(comparison.divergences.map((d) => d.requestId).filter(isString));
-  const times = requestIds.flatMap((requestId) => requestTimesFromIndex(bDir, requestId));
+  const requestIds = unique(
+    comparison.divergences.map((d) => d.requestId).filter(isString)
+  );
+  const times = requestIds.flatMap(
+    (requestId) => requestTimesFromIndex(bDir, requestId)
+  );
   const firstSig = comparison.divergences.map((d) => d.sig).find(isString);
   return {
     schemaVersion: REGRESSION_CONTEXT_SCHEMA_VERSION,
+    title: comparisonTitle(comparison),
     comparison,
     divergent_interaction: firstSig ? interactionForSig(bDir, firstSig) : null,
     causal_window: requestIds.length > 0 ? {
@@ -15790,6 +16061,7 @@ function buildRegressionContext(comparison, bDir) {
       before: d.before,
       after: d.after
     })),
+    env_delta: comparison.envDelta ?? null,
     repro_hint: reproHint(bDir)
   };
 }
@@ -15834,7 +16106,8 @@ function collectRefTimes(value, times) {
   const start = isRecord15(value.start) ? value.start : void 0;
   const end = isRecord15(value.end) ? value.end : void 0;
   for (const candidate of [ref, start, end]) {
-    if (typeof candidate?.t === "number" && Number.isFinite(candidate.t)) times.push(candidate.t);
+    if (typeof candidate?.t === "number" && Number.isFinite(candidate.t))
+      times.push(candidate.t);
   }
 }
 function reproHint(sessionDir) {
@@ -16892,12 +17165,29 @@ var McpServer = class {
           "sha"
         ]))
           continue;
-        sessions.push(meta);
+        sessions.push(this.withReleaseBuild(meta));
       } catch {
       }
     }
     return textResult(sessions);
   }
+  /**
+   * Surfaces release/build as first-class list-row fields regardless of which
+   * alias the app used (release/releaseId/version, build/buildId/commit/sha), so
+   * an agent can label and group sessions by release without re-reading each
+   * meta. Additive: the raw meta keys are preserved.
+   */
+  withReleaseBuild(meta) {
+    const release = stringField5(meta.release ?? meta.releaseId ?? meta.version);
+    const build = stringField5(
+      meta.build ?? meta.buildId ?? meta.commit ?? meta.sha
+    );
+    return {
+      ...meta,
+      ...release !== void 0 ? { release } : {},
+      ...build !== void 0 ? { build } : {}
+    };
+  }
   sessionMetadataMatches(meta, expected, keys) {
     return keys.some((key) => meta[key] === expected);
   }
@@ -18273,6 +18563,7 @@ var InspectError = class extends Error {
     this.code = code;
     this.name = "InspectError";
   }
+  code;
 };
 function inspectSession(sessionDirOrId, opts = {}) {
   const sessionDir = resolveSessionDir2(sessionDirOrId, opts);
@@ -18400,117 +18691,6 @@ function isRecord17(value) {
   return value != null && typeof value === "object" && !Array.isArray(value);
 }
 
-// src/compare/report.ts
-var PLANE_ORDER = ["flow", "network", "db", "env"];
-var PLANE_LABELS = {
-  flow: "Flow steps",
-  network: "Network calls",
-  db: "Database rows",
-  env: "Environment and flags"
-};
-function renderCompareReport(comparison) {
-  const lines = [];
-  const regressed = comparison.verdict === "regression";
-  lines.push(
-    `# Session comparison - ${formatSessionRef(comparison.a)} vs ${formatSessionRef(comparison.b)}`
-  );
-  lines.push("");
-  lines.push(
-    regressed ? `> **Verdict: REGRESSION** (confidence: ${comparison.confidence}) - recorded behavior changed between these sessions.` : `> **Verdict: CLEAN** (confidence: ${comparison.confidence}) - the recorded sessions show no behavioral divergence.`
-  );
-  lines.push("");
-  lines.push(
-    "A is the baseline session; B is the candidate release/build. Every row below is grounded in the recorded evidence of both sessions."
-  );
-  lines.push("");
-  lines.push("## Aligned flow");
-  lines.push("");
-  const { matchedSteps, unmatchedA, unmatchedB } = comparison.alignment;
-  lines.push(
-    `${matchedSteps} step(s) matched by component identity \xB7 ${unmatchedA} only in A \xB7 ${unmatchedB} only in B`
-  );
-  lines.push("");
-  if (comparison.divergences.length > 0) {
-    lines.push("| Plane | Kind | Component | Divergence |");
-    lines.push("|---|---|---|---|");
-    for (const d of comparison.divergences) {
-      const component = d.sig ? `\`${escapeCell(d.sig)}\`` : "\u2014";
-      lines.push(
-        `| **${d.plane}** | \`${d.kind}\` | ${component} | ${escapeCell(d.brief)} |`
-      );
-    }
-    lines.push("");
-  }
-  for (const plane of PLANE_ORDER) {
-    const planeDivergences = comparison.divergences.filter(
-      (d) => d.plane === plane
-    );
-    if (planeDivergences.length === 0) continue;
-    lines.push(`## ${PLANE_LABELS[plane]}`);
-    lines.push("");
-    for (const d of planeDivergences) {
-      lines.push(`### \`${d.kind}\` - ${escapeCell(d.brief)}`);
-      lines.push("");
-      if (d.sig) lines.push(`- Component: \`${d.sig}\``);
-      if (d.requestId) lines.push(`- Request: \`${d.requestId}\``);
-      if (d.table)
-        lines.push(
-          `- Table: \`${d.table}\`${d.pk ? ` \xB7 pk \`${JSON.stringify(d.pk)}\`` : ""}`
-        );
-      lines.push("");
-      lines.push("```diff");
-      lines.push(`- before: ${JSON.stringify(d.before)}`);
-      lines.push(`+ after:  ${JSON.stringify(d.after)}`);
-      lines.push("```");
-      lines.push("");
-    }
-  }
-  lines.push("---");
-  lines.push("");
-  lines.push(
-    comparison.noise.suppressedCount > 0 ? `*${comparison.noise.suppressedCount} expected-variance difference(s) suppressed by the noise model (${comparison.noise.rules.join(", ")}).*` : "*No differences were suppressed by the noise model.*"
-  );
-  lines.push("");
-  return lines.join("\n");
-}
-function formatComparisonSummary(comparison) {
-  const lines = [];
-  lines.push(
-    `crumbtrail-server compare - ${formatSessionRef(comparison.a)} vs ${formatSessionRef(comparison.b)}`
-  );
-  lines.push(`  Schema:      ${comparison.schemaVersion}`);
-  lines.push(
-    `  Verdict:     ${comparison.verdict.toUpperCase()} (confidence ${comparison.confidence})`
-  );
-  lines.push(
-    `  Alignment:   ${comparison.alignment.matchedSteps} matched \xB7 ${comparison.alignment.unmatchedA} only in A \xB7 ${comparison.alignment.unmatchedB} only in B`
-  );
-  lines.push(`  Divergences: ${comparison.divergences.length}`);
-  for (const d of comparison.divergences.slice(0, 5)) {
-    lines.push(`    [${d.plane}] ${d.kind} - ${d.brief}`);
-  }
-  if (comparison.divergences.length > 5) {
-    lines.push(
-      `    ... and ${comparison.divergences.length - 5} more (use --json or --report for the complete list)`
-    );
-  }
-  const rules = comparison.noise.rules.length > 0 ? ` (${comparison.noise.rules.join(", ")})` : "";
-  lines.push(
-    `  Noise:       ${comparison.noise.suppressedCount} suppressed${rules}`
-  );
-  return lines.join("\n");
-}
-function escapeCell(text2) {
-  return text2.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
-}
-function formatSessionRef(ref) {
-  const tags = [
-    ref.release ? `release ${ref.release}` : void 0,
-    ref.build ? `build ${ref.build}` : void 0
-  ].filter(Boolean);
-  return tags.length > 0 ? `${ref.sessionId} (${tags.join(", ")})` : ref.sessionId;
-}
-
 // src/version.ts
 import fs15 from "fs";
 import path16 from "path";
@@ -18895,6 +19075,10 @@ export {
   SESSION_COMPARE_SCHEMA_VERSION,
   CompareError,
   compareSessions,
+  renderCompareReport,
+  formatComparisonSummary,
+  sessionRefLabel,
+  comparisonTitle,
   REGRESSION_CONTEXT_SCHEMA_VERSION,
   buildRegressionContext,
   McpServer,
@@ -18914,7 +19098,5 @@ export {
   InspectError,
   inspectSession,
   formatInspection,
-  renderCompareReport,
-  formatComparisonSummary,
   readPackageVersion
 };