fleetlens 0.3.0 → 0.4.0

package/app/apps/web/components/sidebar.tsx

@@ -13,6 +13,7 @@ import {
   Search,
   Activity,
   Gauge,
+  Lightbulb,
 } from "lucide-react";
 import { formatRelative, prettyProjectName } from "@/lib/format";
 import { ThemeToggle } from "@/components/theme-toggle";
@@ -193,6 +194,13 @@ export function Sidebar({
         >
           Usage
         </NavLink>
+        <NavLink
+          href="/insights"
+          active={pathname === "/insights"}
+          icon={<Lightbulb size={15} />}
+        >
+          Insights
+        </NavLink>
       </nav>
 
       {/* Projects search + list */}

package/app/apps/web/eslint.config.mjs

@@ -0,0 +1,2 @@
+import root from "../../eslint.config.mjs";
+export default root;

package/app/apps/web/lib/ai/chrome-pdf.ts

@@ -0,0 +1,64 @@
+/**
+ * Thin wrapper around system Chrome/Chromium headless for PDF rendering.
+ *
+ * We detect the browser binary at known paths (macOS / Linux / Windows);
+ * override via CHROME_BIN env var. No node dependency on Puppeteer —
+ * Fleetlens is a local-only tool so we assume the user has a browser
+ * installed anyway.
+ */
+import { existsSync } from "node:fs";
+import { readFile, unlink } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const CANDIDATES: string[] = [
+  process.env.CHROME_BIN ?? "",
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+  "/usr/bin/google-chrome",
+  "/usr/bin/google-chrome-stable",
+  "/usr/bin/chromium-browser",
+  "/usr/bin/chromium",
+  "/snap/bin/chromium",
+  "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+  "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+].filter(Boolean);
+
+let cached: string | null | undefined;
+
+export function findChrome(): string | null {
+  if (cached !== undefined) return cached;
+  for (const p of CANDIDATES) {
+    if (existsSync(p)) { cached = p; return p; }
+  }
+  cached = null;
+  return null;
+}
+
+export async function renderPdf(url: string, outName: string): Promise<Buffer> {
+  const chrome = findChrome();
+  if (!chrome) {
+    throw new Error("Chrome/Chromium binary not found. Install Chrome or set CHROME_BIN.");
+  }
+  const safeName = outName.replace(/[^a-z0-9-]/gi, "_");
+  const outPath = join(tmpdir(), `fleetlens-${safeName}-${Date.now()}.pdf`);
+  await new Promise<void>((resolve, reject) => {
+    const proc = spawn(chrome, [
+      "--headless=new",
+      "--disable-gpu",
+      "--no-sandbox",
+      "--hide-scrollbars",
+      "--no-pdf-header-footer",
+      "--virtual-time-budget=5000",
+      `--print-to-pdf=${outPath}`,
+      url,
+    ], { stdio: "ignore" });
+    proc.on("close", (code) => code === 0 ? resolve() : reject(new Error(`chrome exited ${code}`)));
+    proc.on("error", reject);
+  });
+  const bytes = await readFile(outPath);
+  void unlink(outPath).catch(() => {});
+  return bytes;
+}

package/app/apps/web/lib/ai/insights-prompt.ts

@@ -0,0 +1,71 @@
+/**
+ * System prompt for the Insights analyst.
+ *
+ * Input it receives:
+ *   - period:      { start, end, label, range_type }
+ *   - aggregates:  PeriodBundle from @claude-lens/parser (all deterministic numbers)
+ *   - capsules:    SessionCapsule[] — intent material + behavioural flags
+ *   - prior:       PriorWeek[] — last 4 reports (archetype + stats). Empty if this
+ *                  is the first run. When non-empty, populate archetype.vs_usual.
+ *
+ * Output MUST be a single JSON object inside a ```json fence, matching
+ * the schema below. No prose outside the fence. No markdown outside.
+ */
+export const INSIGHTS_SYSTEM_PROMPT = `You are the Insights analyst for Fleetlens, a dashboard for Claude Code sessions.
+
+You receive a JSON payload summarising one calendar period (week or 4-weeks). The numbers are already computed — you do NOT do arithmetic, you interpret and name patterns.
+
+## Your output
+
+Return EXACTLY ONE JSON object inside a \`\`\`json fenced code block. No prose before or after. Schema:
+
+{
+  "archetype": {
+    "label": "Orchestration Conductor" | "Deep-dive Conversationalist" | "Fire-and-go Operator" | "Solo Builder" | "Context Switcher" | "Research Explorer",
+    "icon":  "Network" | "BrainCircuit" | "Zap" | "Compass" | "Layers3" | "Sparkles",
+    "tagline": "… short phrase, ≤ 70 chars, describing working style …",
+    "why":     "… 1-2 sentences grounded in aggregate numbers (e.g. 'You ran X subagent dispatches across Y turns…') …",
+    "vs_usual": "… OPTIONAL: only populate if \`prior\` is non-empty. 1 sentence contrasting this week's archetype + behaviour with the baseline (e.g. 'More orchestrated than the last 4 weeks (usual: Solo Builder)'). Omit the key entirely otherwise."
+  },
+  "theme_headline": "3-7 words capturing the period's dominant theme",
+  "shipped_summaries": {
+    "<session_id>": "1-sentence characterisation of the shipped work"
+  },
+  "patterns": [
+    { "icon": "Repeat" | "ClipboardList" | "GitCommit" | "Network" | "BrainCircuit" | "Zap" | "TrendingUp" | "TrendingDown",
+      "title": "…",
+      "stat": "…",
+      "note": "1 short sentence" }
+    // 2-4 patterns total
+  ],
+  "concurrency_insight": "1-2 sentences about parallelism shape. Empty string if no concurrency data.",
+  "concurrency_suggestion": "1 sentence, actionable. Empty string if nothing useful.",
+  "outlier_notes": {
+    "longest_run":  "1 line takeaway",
+    "fastest_ship": "…",
+    "most_errors":  "…",
+    "wandered":     "…"
+  },
+  "suggestion_headline": "bold, imperative, ≤ 70 chars",
+  "suggestion_body":     "2-3 sentences. Grounded in what you saw. Actionable."
+}
+
+## Archetype guide
+
+- **Orchestration Conductor** — heavy subagent_calls, long unsupervised turns, planning unfolds in-session.
+- **Deep-dive Conversationalist** — high turn_count per session, rapid user↔agent ping-pong, low subagent use.
+- **Fire-and-go Operator** — few user turns per session, long autonomous runs, minimal interruption.
+- **Solo Builder** — mid-length sessions, steady cadence, low subagent use, high direct edit/bash ratio.
+- **Context Switcher** — many short sessions across many projects, high cross-project count.
+- **Research Explorer** — Grep/Read/WebFetch heavy, low commits, exploratory outcomes.
+
+Pick exactly one. If borderline, pick the closer fit and say so in the \`why\`.
+
+## Rules
+
+1. **Ground every claim** — every sentence you write must reference a number or fact in the data. Never invent. Never include unreferenced general advice.
+2. **No vanity metrics** — don't quote total tokens, total cost, total sessions as headline claims. Use behavioural signals (subagent_calls, session length distribution, plan mode use, interrupt rate, concurrency peak).
+3. **Short and concrete** — no filler words. "You ran X this week" not "This past week saw the user running X."
+4. **Valid JSON** — strict. No trailing commas. No comments in the output. No text outside the fence.
+5. **Shipped summaries** — if capsules have pr_titles, write one summary per session_id that shipped. Use capsule first_user / final_agent / flags for texture.
+6. **Pattern selection** — pick 2-4 patterns where the signal is strongest. Don't pad. If plan_mode usage is zero and it's a busy week, say so. If loop_suspected flags correlate with shipping, call that out.`;

package/app/apps/web/lib/ai/saved-reports.ts

@@ -0,0 +1,83 @@
+/**
+ * Persistence for generated insight reports.
+ *
+ * Reports are keyed by their window start date + range_type:
+ *   week-2026-04-13.json        — week of Apr 13 – Apr 19
+ *   4weeks-2026-03-23.json      — 4-week rollup Mar 23 – Apr 19
+ *
+ * Pruning is lazy — we don't delete; this is ~2 KB/report so a year of
+ * weekly reports is ~100 KB.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { ReportData } from "@/components/insight-report";
+
+const DIR = join(homedir(), ".cclens", "insights");
+
+export type SavedReportMeta = {
+  key: string;
+  period_label: string;
+  period_sublabel: string;
+  range_type: ReportData["range_type"];
+  archetype_label: string;
+  archetype_icon: string;
+  saved_at: string;
+  sessions_used: number;
+  prs: number;
+};
+
+type SavedFile = { saved_at: string; report: ReportData };
+
+export function keyForRange(range_type: ReportData["range_type"], startIso: string): string {
+  const yyyymmdd = startIso.slice(0, 10);
+  return `${range_type}-${yyyymmdd}`;
+}
+
+export async function saveReport(key: string, report: ReportData): Promise<void> {
+  await fs.mkdir(DIR, { recursive: true });
+  const payload: SavedFile = { saved_at: new Date().toISOString(), report };
+  await fs.writeFile(join(DIR, `${key}.json`), JSON.stringify(payload, null, 2));
+}
+
+export async function listSavedReports(): Promise<SavedReportMeta[]> {
+  try {
+    const files = await fs.readdir(DIR);
+    const out: SavedReportMeta[] = [];
+    for (const f of files) {
+      if (!f.endsWith(".json")) continue;
+      try {
+        const raw = await fs.readFile(join(DIR, f), "utf8");
+        const parsed = JSON.parse(raw) as SavedFile;
+        const r = parsed.report;
+        out.push({
+          key: f.replace(/\.json$/, ""),
+          period_label: r.period_label,
+          period_sublabel: r.period_sublabel,
+          range_type: r.range_type,
+          archetype_label: r.archetype.label,
+          archetype_icon: r.archetype.icon,
+          saved_at: parsed.saved_at,
+          sessions_used: r.meta.sessions_used,
+          prs: r.shipped.length,
+        });
+      } catch { /* skip corrupt */ }
+    }
+    // Newest first (keys sort lexicographically by start date since YYYY-MM-DD)
+    out.sort((a, b) => b.key.localeCompare(a.key));
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+export async function getSavedReport(key: string): Promise<ReportData | null> {
+  if (!/^[a-z0-9-]+$/i.test(key)) return null; // no path traversal
+  try {
+    const raw = await fs.readFile(join(DIR, `${key}.json`), "utf8");
+    const parsed = JSON.parse(raw) as SavedFile;
+    return parsed.report;
+  } catch {
+    return null;
+  }
+}

package/app/apps/web/lib/date-range.ts

@@ -14,9 +14,18 @@ export function parseRange(value: string | string[] | undefined): RangeKey {
   return "all";
 }
 
-/** Return the cutoff ms for a given range, or undefined for "all". */
+/**
+ * Return the cutoff ms for a given range, or undefined for "all".
+ * Calendar-day semantics: "30d" means the last 30 local calendar days
+ * (today + 29 prior), not a rolling 30×24h window. Keeps the daily-bucket
+ * bars and the filter boundary aligned, and keeps the answer stable
+ * across page refreshes within the same day.
+ */
 export function cutoffMs(range: RangeKey, now = Date.now()): number | undefined {
   if (range === "all") return undefined;
   const days = range === "7d" ? 7 : range === "30d" ? 30 : 90;
-  return now - days * 24 * 60 * 60 * 1000;
+  const d = new Date(now);
+  d.setHours(0, 0, 0, 0);
+  d.setDate(d.getDate() - (days - 1));
+  return d.getTime();
 }

package/app/apps/web/lib/use-live-events.ts

@@ -34,7 +34,11 @@ export type LiveUpdate = LiveSessionUpdate | LiveUsageUpdate;
 
 type LiveEvent = LiveUpdate | { type: "heartbeat"; tsMs: number } | { type: "ready" };
 
-export function useLiveEvents(onUpdate: (update: LiveUpdate) => void): void {
+export function useLiveEvents(
+  onUpdate: (update: LiveUpdate) => void,
+  options: { enabled?: boolean } = {},
+): void {
+  const { enabled = true } = options;
   // Keep the latest handler in a ref so the EventSource effect doesn't
   // re-open every time the parent re-renders with a new closure.
   const handlerRef = useRef(onUpdate);
@@ -43,6 +47,7 @@ export function useLiveEvents(onUpdate: (update: LiveUpdate) => void): void {
   }, [onUpdate]);
 
   useEffect(() => {
+    if (!enabled) return;
     const es = new EventSource("/api/events");
     es.onmessage = (e) => {
       try {
@@ -61,5 +66,5 @@ export function useLiveEvents(onUpdate: (update: LiveUpdate) => void): void {
     return () => {
       es.close();
     };
-  }, []);
+  }, [enabled]);
 }

package/app/apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-lens/web",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": true,
   "description": "Local-only dashboard for Claude Code sessions. Reads ~/.claude/projects/*.jsonl and visualizes agent activity.",
   "license": "MIT",
@@ -11,7 +11,8 @@
     "lint": "eslint",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",
-    "clean": "rm -rf .next .turbo dist *.tsbuildinfo"
+    "clean": "rm -rf .next .turbo dist *.tsbuildinfo",
+    "test:coverage": "vitest run --passWithNoTests --coverage"
   },
   "dependencies": {
     "@claude-lens/parser": "workspace:*",