@raquezha/notrace 0.0.6 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @raquezha/notrace
 
+## 0.1.0
+
+### Minor Changes
+
+- a2fc3cb: Implement machine-global observability dashboard and Mistral-style timeline parser.
+  - Storage migrated from `.notrace/` in the local working directory to a machine-wide `~/.notrace/` directory to prevent repository pollution and enable global insights.
+  - Dashboard updated with a new `Project` column for multi-repo tracking.
+  - Timeline parser overhauled to render LLM arrays, tool execution cards, and code blocks beautifully instead of raw JSON dumps.
+
+### Patch Changes
+
+- 8f31379: fix(noheadroom): match lowercase footer casing
+  feat(notrace): add session export to HTML retrospective
+
+## 0.0.7
+
+### Patch Changes
+
+- 5a3e563: Improve session reports by rendering the session ID as a copyable chip under the notrace logo.
+- 5a3e563: Enhance the trace header to include the active git branch alongside the repository name, and clarify the capture setting label.
+- 7664e50: Polish notrace reliability and installed-package ergonomics: add review/compare package CLIs, validate run records before writing, atomically write private artifacts, recover from corrupt index JSON, and verify capture modes.
+
 ## 0.0.6
 
 ### Patch Changes

package/README.md

@@ -103,10 +103,12 @@ Mode meanings:
 - `redacted`: captured payloads with common secret-like values redacted
 - `metadata`: minimal capture, no prompt/tool bodies
 
-**Security warning:** even redacted reports can contain sensitive prompts, tool payloads, local paths, and outputs. Do not publish generated reports.
+**Security warning:** `full` reports can contain prompts, tool arguments, tool outputs, local paths, model payloads, and secrets returned by tools. `redacted` mode removes common secret-shaped values and sensitive keys, but redaction is best-effort and can miss project-specific secrets. `metadata` mode is safest for sharing because prompt/tool bodies are omitted, but reports can still reveal repository names, paths, timing, models, providers, and workflow metadata. Do not publish generated reports without review.
 
 ## Review
 
+From this monorepo:
+
 ```bash
 npm run review:notrace -- \
   .notrace/sessions/<id>/notrace.json \
@@ -116,6 +118,17 @@ npm run review:notrace -- \
   --next-change "Try same task with RepoScry enabled."
 ```
 
+From an installed package:
+
+```bash
+npx -p @raquezha/notrace notrace-review \
+  .notrace/sessions/<id>/notrace.json \
+  --outcome partial \
+  --friction high \
+  --lesson "Headroom reduced tokens but needed manual steering." \
+  --next-change "Try same task with RepoScry enabled."
+```
+
 Review fields:
 - `outcome`: `success`, `partial`, `failed`, `abandoned`, `inconclusive`
 - `friction`: `low`, `medium`, `high`
@@ -124,12 +137,22 @@ Review fields:
 
 ## Compare
 
+From this monorepo:
+
 ```bash
 npm run compare:notrace -- \
   .notrace/sessions/<baseline-id>/notrace.json \
   .notrace/sessions/<candidate-id>/notrace.json
 ```
 
+From an installed package:
+
+```bash
+npx -p @raquezha/notrace notrace-compare \
+  .notrace/sessions/<baseline-id>/notrace.json \
+  .notrace/sessions/<candidate-id>/notrace.json
+```
+
 ## Templates
 
 HTML source-of-truth lives in `templates/`:

package/bin/notrace-compare.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { resolve, relative, dirname, basename, extname, join } from "node:path";
+
+function usage() {
+  console.error("Usage: notrace-compare <baseline-notrace.json> <candidate-notrace.json>");
+  process.exit(1);
+}
+
+const [, , baselineArg, candidateArg] = process.argv;
+if (!baselineArg || !candidateArg) usage();
+
+function loadReview(runPath) {
+  const reviewPath = join(dirname(runPath), `${basename(runPath, extname(runPath))}.review.json`);
+  try {
+    const data = JSON.parse(readFileSync(reviewPath, "utf8"));
+    if (data?.kind !== "notrace-review") return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+function loadRun(filePath) {
+  const absolutePath = resolve(filePath);
+  const data = JSON.parse(readFileSync(absolutePath, "utf8"));
+  if (data?.kind !== "notrace-run") {
+    throw new Error(`${filePath} is not a notrace run record`);
+  }
+  return { path: absolutePath, data, review: loadReview(absolutePath) };
+}
+
+function fmtNumber(value) {
+  return Number(value || 0).toLocaleString();
+}
+
+function fmtUsd(value) {
+  return `$${Number(value || 0).toFixed(5)}`;
+}
+
+function fmtMs(value) {
+  const ms = Number(value || 0);
+  if (ms < 1000) return `${ms}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
+function fmtDelta(delta, formatter = fmtNumber, invertGood = false) {
+  const good = invertGood ? delta > 0 : delta < 0;
+  const bad = invertGood ? delta < 0 : delta > 0;
+  const sign = delta > 0 ? "+" : "";
+  const text = `${sign}${formatter(delta)}`;
+  if (good) return `${text} better`;
+  if (bad) return `${text} worse`;
+  return `${text} same`;
+}
+
+function list(value) {
+  return Array.isArray(value) && value.length ? value.join(", ") : "-";
+}
+
+const baseline = loadRun(baselineArg);
+const candidate = loadRun(candidateArg);
+
+const a = baseline.data;
+const b = candidate.data;
+const aReview = baseline.review;
+const bReview = candidate.review;
+const aActivity = a.activity || {};
+const bActivity = b.activity || {};
+const aTotals = aActivity.totals || {};
+const bTotals = bActivity.totals || {};
+
+const rows = [
+  {
+    label: "Total tokens",
+    baseline: fmtNumber(aTotals.totalTokens),
+    candidate: fmtNumber(bTotals.totalTokens),
+    delta: fmtDelta((bTotals.totalTokens || 0) - (aTotals.totalTokens || 0))
+  },
+  {
+    label: "Input tokens",
+    baseline: fmtNumber(aTotals.inputTokens),
+    candidate: fmtNumber(bTotals.inputTokens),
+    delta: fmtDelta((bTotals.inputTokens || 0) - (aTotals.inputTokens || 0))
+  },
+  {
+    label: "Output tokens",
+    baseline: fmtNumber(aTotals.outputTokens),
+    candidate: fmtNumber(bTotals.outputTokens),
+    delta: fmtDelta((bTotals.outputTokens || 0) - (aTotals.outputTokens || 0))
+  },
+  {
+    label: "Duration",
+    baseline: fmtMs(aActivity.durationMs),
+    candidate: fmtMs(bActivity.durationMs),
+    delta: fmtDelta((bActivity.durationMs || 0) - (aActivity.durationMs || 0), fmtMs)
+  },
+  {
+    label: "LLM calls",
+    baseline: fmtNumber(aActivity.llmCallCount),
+    candidate: fmtNumber(bActivity.llmCallCount),
+    delta: fmtDelta((bActivity.llmCallCount || 0) - (aActivity.llmCallCount || 0))
+  },
+  {
+    label: "Tool calls",
+    baseline: fmtNumber(aActivity.toolCallCount),
+    candidate: fmtNumber(bActivity.toolCallCount),
+    delta: fmtDelta((bActivity.toolCallCount || 0) - (aActivity.toolCallCount || 0))
+  },
+  {
+    label: "Tool errors",
+    baseline: fmtNumber(aActivity.toolErrorCount),
+    candidate: fmtNumber(bActivity.toolErrorCount),
+    delta: fmtDelta((bActivity.toolErrorCount || 0) - (aActivity.toolErrorCount || 0))
+  },
+  {
+    label: "Cost (USD)",
+    baseline: fmtUsd(aTotals.totalCostUsd),
+    candidate: fmtUsd(bTotals.totalCostUsd),
+    delta: fmtDelta((bTotals.totalCostUsd || 0) - (aTotals.totalCostUsd || 0), fmtUsd)
+  }
+];
+
+const labelWidth = Math.max(...rows.map((row) => row.label.length));
+const baselineWidth = Math.max("Baseline".length, ...rows.map((row) => row.baseline.length));
+const candidateWidth = Math.max("Candidate".length, ...rows.map((row) => row.candidate.length));
+
+function pad(value, width) {
+  return String(value).padEnd(width);
+}
+
+console.log("notrace compare\n");
+console.log(`Baseline : ${relative(process.cwd(), baseline.path) || baseline.path}`);
+console.log(`Candidate: ${relative(process.cwd(), candidate.path) || candidate.path}`);
+console.log("");
+console.log(`Task      : ${b.task?.id || a.task?.id || "(none)"}`);
+console.log(`Capture   : ${a.captureMode} -> ${b.captureMode}`);
+console.log(`Models    : ${list(a.conditions?.models)} -> ${list(b.conditions?.models)}`);
+console.log(`Providers : ${list(a.conditions?.providers)} -> ${list(b.conditions?.providers)}`);
+console.log("");
+console.log(`Review    : ${(aReview?.outcome || "-")}/${(aReview?.friction || "-")} -> ${(bReview?.outcome || "-")}/${(bReview?.friction || "-")}`);
+if (aReview?.lesson || bReview?.lesson) {
+  console.log(`Lessons   : ${(aReview?.lesson || "-")} -> ${(bReview?.lesson || "-")}`);
+}
+if (aReview?.nextChange || bReview?.nextChange) {
+  console.log(`Next      : ${(aReview?.nextChange || "-")} -> ${(bReview?.nextChange || "-")}`);
+}
+console.log("");
+console.log(`${pad("Metric", labelWidth)} | ${pad("Baseline", baselineWidth)} | ${pad("Candidate", candidateWidth)} | Delta`);
+console.log(`${"-".repeat(labelWidth)}-+-${"-".repeat(baselineWidth)}-+-${"-".repeat(candidateWidth)}-+-${"-".repeat(24)}`);
+for (const row of rows) {
+  console.log(`${pad(row.label, labelWidth)} | ${pad(row.baseline, baselineWidth)} | ${pad(row.candidate, candidateWidth)} | ${row.delta}`);
+}

package/bin/notrace-review.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve, relative, dirname, basename, extname, join } from "node:path";
+
+const VALID_OUTCOMES = new Set(["success", "partial", "failed", "abandoned", "inconclusive"]);
+const VALID_FRICTION = new Set(["low", "medium", "high"]);
+
+function appendWorkLogEntry(taskDir, message) {
+  const workMd = join(taskDir, "WORK.md");
+  if (!existsSync(workMd)) return;
+
+  const text = readFileSync(workMd, "utf8");
+  const entry = `- ${new Date().toISOString()}: ${message}`;
+
+  if (!/^(## )?\[LOG\]\s*$/m.test(text)) {
+    writeFileSync(workMd, `${text.trimEnd()}\n\n## [LOG]\n${entry}\n`, { encoding: "utf8" });
+    return;
+  }
+
+  const lines = text.split("\n");
+  const logIndex = lines.findIndex((line) => /^(## )?\[LOG\]\s*$/.test(line));
+  if (logIndex === -1) return;
+
+  let nextSectionIndex = lines.length;
+  for (let i = logIndex + 1; i < lines.length; i++) {
+    if (/^(## )?\[[A-Z0-9_-]+\]\s*$/.test(lines[i])) {
+      nextSectionIndex = i;
+      break;
+    }
+  }
+
+  const before = lines.slice(0, nextSectionIndex);
+  const after = lines.slice(nextSectionIndex);
+  while (before.length > logIndex + 1 && before[before.length - 1]?.trim() === "") {
+    before.pop();
+  }
+  before.push(entry);
+
+  writeFileSync(workMd, `${[...before, ...after].join("\n").replace(/\n*$/, "\n")}`, { encoding: "utf8" });
+}
+
+function usage() {
+  console.error("Usage: notrace-review <notrace.json> [--outcome value] [--friction value] [--lesson text] [--next-change text]");
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+if (!args.length) usage();
+
+const runPath = resolve(args[0]);
+const flags = args.slice(1);
+
+function takeFlag(name) {
+  const index = flags.indexOf(name);
+  if (index === -1) return undefined;
+  const value = flags[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`Missing value for ${name}`);
+  }
+  return value;
+}
+
+const outcome = takeFlag("--outcome");
+const friction = takeFlag("--friction");
+const lesson = takeFlag("--lesson");
+const nextChange = takeFlag("--next-change");
+
+if (!existsSync(runPath)) {
+  throw new Error(`Run record not found: ${runPath}`);
+}
+
+const run = JSON.parse(readFileSync(runPath, "utf8"));
+if (run?.kind !== "notrace-run") {
+  throw new Error(`Not a notrace run record: ${runPath}`);
+}
+
+if (outcome && !VALID_OUTCOMES.has(outcome)) {
+  throw new Error(`Invalid outcome: ${outcome}`);
+}
+if (friction && !VALID_FRICTION.has(friction)) {
+  throw new Error(`Invalid friction: ${friction}`);
+}
+
+const reviewPath = join(dirname(runPath), `${basename(runPath, extname(runPath))}.review.json`);
+const existing = existsSync(reviewPath)
+  ? JSON.parse(readFileSync(reviewPath, "utf8"))
+  : {
+      schemaVersion: 1,
+      kind: "notrace-review",
+      traceId: run.traceId,
+      runRecord: basename(runPath),
+      outcome: null,
+      friction: null,
+      lesson: "",
+      nextChange: ""
+    };
+
+const review = {
+  ...existing,
+  traceId: run.traceId,
+  runRecord: basename(runPath),
+  outcome: outcome ?? existing.outcome ?? null,
+  friction: friction ?? existing.friction ?? null,
+  lesson: lesson ?? existing.lesson ?? "",
+  nextChange: nextChange ?? existing.nextChange ?? ""
+};
+
+writeFileSync(reviewPath, `${JSON.stringify(review, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+
+if (run.repository?.cwd && (run.task?.dir || run.task?.path)) {
+  const taskDir = run.task?.dir
+    ? resolve(run.task.dir)
+    : resolve(run.repository.cwd, run.task.path);
+  appendWorkLogEntry(taskDir, `notrace review recorded: outcome=${review.outcome ?? "-"}, friction=${review.friction ?? "-"}, review=${relative(taskDir, reviewPath)}`);
+} else {
+  appendWorkLogEntry(dirname(runPath), `notrace review recorded: outcome=${review.outcome ?? "-"}, friction=${review.friction ?? "-"}, review=${basename(reviewPath)}`);
+}
+
+console.log(`notrace review ✓ ${reviewPath}`);
+console.log(`  outcome   : ${review.outcome ?? "-"}`);
+console.log(`  friction  : ${review.friction ?? "-"}`);
+console.log(`  lesson    : ${review.lesson || "-"}`);
+console.log(`  nextChange: ${review.nextChange || "-"}`);

package/dist/notrace/adapters.js

@@ -22,8 +22,11 @@ function appendWorkLogEntry(taskDir, message) {
         }
         const before = lines.slice(0, nextSection);
         const after = lines.slice(nextSection);
+        while (before.length > logIndex + 1 && before[before.length - 1]?.trim() === "") {
+            before.pop();
+        }
         before.push(entry);
-        writeFileSync(workMd, `${before.join("\n")}\n${after.join("\n")}`);
+        writeFileSync(workMd, `${[...before, ...after].join("\n").replace(/\n*$/, "\n")}`);
     }
     catch { }
 }

package/dist/notrace/index.js

@@ -1,5 +1,7 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, chmodSync } from "node:fs";
 import * as path from "node:path";
+import * as os from "node:os";
+import { execSync } from "node:child_process";
 import { getActiveAdapter } from "./adapters.js";
 import { generateHtmlReport, generateDashboardHtml } from "./renderer.js";
 const REDACTED = "[REDACTED by notrace]";
@@ -21,6 +23,8 @@ function isSensitiveKey(key) {
     return SENSITIVE_KEY_RE.test(normalized);
 }
 function sanitizeTraceValue(value) {
+    if (currentMode === "metadata")
+        return { omitted: true, reason: "metadata-capture" };
     if (currentMode === "full")
         return value;
     if (value == null || typeof value !== "object") {
@@ -47,6 +51,34 @@ function normalizeUsage(raw) {
         totalCostUsd: asNumber(usage.cost?.total),
     };
 }
+function readJsonFile(filePath, fallback) {
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+function writePrivateFileAtomic(filePath, content) {
+    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
+    chmodSync(tmpPath, 0o600);
+    renameSync(tmpPath, filePath);
+}
+function validateRunRecord(record) {
+    if (record.kind !== "notrace-run")
+        throw new Error("notrace record validation failed: invalid kind");
+    if (record.schemaVersion !== SCHEMA_VERSION)
+        throw new Error("notrace record validation failed: invalid schemaVersion");
+    if (!record.traceId || !record.session?.id)
+        throw new Error("notrace record validation failed: missing session id");
+    if (!record.repository?.cwd)
+        throw new Error("notrace record validation failed: missing repository cwd");
+    if (!record.activity?.totals)
+        throw new Error("notrace record validation failed: missing activity totals");
+    if (!Array.isArray(record.events))
+        throw new Error("notrace record validation failed: events must be an array");
+}
 function collectActivity(events, startedAt, endedAt) {
     const activity = {
         turnCount: 0,
@@ -116,9 +148,10 @@ function toTaskInfo(context) {
         dir: context.taskDir,
     };
 }
-function createIndexEntry(record, cwd, htmlPath, recordPath) {
+function createIndexEntry(record, htmlPath, recordPath) {
     return {
         sessionId: record.traceId,
+        repositoryName: record.repository.name,
         startedAt: record.session.startedAt,
         endedAt: record.session.endedAt,
         captureMode: record.captureMode,
@@ -126,8 +159,8 @@ function createIndexEntry(record, cwd, htmlPath, recordPath) {
         conditions: record.conditions,
         activity: record.activity,
         artifacts: {
-            html: path.relative(cwd, htmlPath),
-            record: path.relative(cwd, recordPath),
+            html: htmlPath,
+            record: recordPath,
         },
     };
 }
@@ -220,17 +253,24 @@ export default function (pi) {
         const endedAt = Date.now();
         const adapter = getActiveAdapter(ctx.cwd);
         const context = adapter.getContext(ctx.cwd);
-        const notraceDir = path.resolve(ctx.cwd, ".notrace");
+        const notraceDir = process.env.NOTRACE_DIR || path.join(os.homedir(), ".notrace");
         const finalTraceId = ctx.sessionManager?.getSessionId?.() || traceId;
         const outputDir = path.join(notraceDir, "sessions", finalTraceId.replace(/[^a-z0-9]/gi, "-"));
         const repositoryName = path.basename(ctx.cwd);
+        let branchName = null;
+        try {
+            branchName = execSync("git branch --show-current", { cwd: ctx.cwd, stdio: ["ignore", "pipe", "ignore"], encoding: "utf8", timeout: 1000 }).trim() || null;
+        }
+        catch {
+            // not a git repo or no commits yet
+        }
         const recordPath = path.join(outputDir, "notrace.json");
         let mergedEvents = events;
         let originalStartedAt = startTime;
         let originalTask = null;
         if (existsSync(recordPath)) {
             try {
-                const oldRecord = JSON.parse(readFileSync(recordPath, "utf-8"));
+                const oldRecord = readJsonFile(recordPath, null);
                 if (Array.isArray(oldRecord.events)) {
                     mergedEvents = [...oldRecord.events, ...events];
                 }
@@ -256,6 +296,7 @@ export default function (pi) {
             repository: {
                 name: repositoryName,
                 cwd: ctx.cwd,
+                branch: branchName,
             },
             session: {
                 id: finalTraceId,
@@ -271,23 +312,50 @@ export default function (pi) {
             telemetry: { extensions: telemetry },
             events: mergedEvents,
         };
+        validateRunRecord(record);
         const html = generateHtmlReport(record);
         mkdirSync(outputDir, { recursive: true });
         const htmlPath = path.join(outputDir, "notrace.html");
-        writeFileSync(htmlPath, html);
-        writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`);
+        writePrivateFileAtomic(htmlPath, html);
+        writePrivateFileAtomic(recordPath, `${JSON.stringify(record, null, 2)}\n`);
         const indexPath = path.join(notraceDir, "index.json");
-        const existing = existsSync(indexPath) ? JSON.parse(readFileSync(indexPath, "utf-8")) : { repositoryName, sessions: [] };
-        let sessions = Array.isArray(existing.sessions) ? existing.sessions.filter((s) => s.sessionId !== finalTraceId) : [];
-        if (!isGhostSession) {
-            sessions.push(createIndexEntry(record, ctx.cwd, htmlPath, recordPath));
+        const lockPath = `${indexPath}.lock`;
+        let lockAcquired = false;
+        for (let i = 0; i < 20; i++) {
+            try {
+                writeFileSync(lockPath, `${process.pid}`, { flag: "wx" });
+                lockAcquired = true;
+                break;
+            }
+            catch {
+                const t = Date.now();
+                while (Date.now() - t < 50) { } // busy wait 50ms
+            }
+        }
+        try {
+            const existing = readJsonFile(indexPath, { sessions: [] });
+            let sessions = Array.isArray(existing.sessions) ? existing.sessions.filter((s) => s.sessionId !== finalTraceId) : [];
+            if (!isGhostSession) {
+                sessions.push(createIndexEntry(record, htmlPath, recordPath));
+            }
+            writePrivateFileAtomic(indexPath, `${JSON.stringify({ sessions }, null, 2)}\n`);
+            writePrivateFileAtomic(path.join(notraceDir, "index.html"), generateDashboardHtml(sessions, {}));
+        }
+        finally {
+            if (lockAcquired && existsSync(lockPath)) {
+                try {
+                    import("node:fs").then(fs => fs.rmSync ? fs.rmSync(lockPath) : fs.unlinkSync(lockPath));
+                }
+                catch { }
+            }
         }
-        writeFileSync(indexPath, `${JSON.stringify({ repositoryName, sessions }, null, 2)}\n`);
-        writeFileSync(path.join(notraceDir, "index.html"), generateDashboardHtml(sessions, { repositoryName }));
         if (context) {
+            const displayPath = htmlPath.startsWith(os.homedir())
+                ? `~${htmlPath.slice(os.homedir().length)}`
+                : htmlPath;
             adapter.attach(context, {
-                html: path.relative(ctx.cwd, htmlPath),
-                record: path.relative(ctx.cwd, recordPath)
+                html: displayPath,
+                record: recordPath
             });
         }
         console.log(`\n\x1b[1m\x1b[38;5;208m[notrace] Session Retrospective: file://${htmlPath}\x1b[0m\n`);