@arcreflex/agent-transcripts 0.1.10 → 0.1.12

package/src/title.ts

@@ -1,27 +1,19 @@
 /**
- * Title generation command.
- *
- * Adds LLM-generated titles to transcripts.json entries that don't have them.
- * Can be run standalone or called from sync.
+ * Title generation: add LLM-generated titles to archive entries.
  */
 
-import { join } from "path";
-import { loadIndex, saveIndex } from "./utils/provenance.ts";
-import { getAdapters } from "./adapters/index.ts";
+import {
+  listEntries,
+  saveEntry,
+  DEFAULT_ARCHIVE_DIR,
+  type ArchiveEntry,
+} from "./archive.ts";
 import { renderTranscript } from "./render.ts";
-import { renderTranscriptHtml } from "./render-html.ts";
 import { generateTitle } from "./utils/openrouter.ts";
-import {
-  computeContentHash,
-  loadCache,
-  saveCache,
-  getCachedTitle,
-  type CacheEntry,
-} from "./cache.ts";
 
 export interface TitleOptions {
-  outputDir: string;
-  force?: boolean; // regenerate all titles, not just missing ones
+  archiveDir?: string;
+  force?: boolean;
   quiet?: boolean;
 }
 
@@ -31,13 +23,14 @@ export interface TitleResult {
   errors: number;
 }
 
-/**
- * Generate titles for transcripts.json entries that don't have them.
- */
 export async function generateTitles(
   options: TitleOptions,
 ): Promise<TitleResult> {
-  const { outputDir, force = false, quiet = false } = options;
+  const {
+    archiveDir = DEFAULT_ARCHIVE_DIR,
+    force = false,
+    quiet = false,
+  } = options;
 
   const result: TitleResult = { generated: 0, skipped: 0, errors: 0 };
 
@@ -48,123 +41,52 @@ export async function generateTitles(
     return result;
   }
 
-  const index = await loadIndex(outputDir);
-  const entries = Object.entries(index.entries);
+  const entries = await listEntries(archiveDir);
 
   if (entries.length === 0) {
     if (!quiet) {
-      console.error("No entries in transcripts.json");
+      console.error("No entries in archive");
     }
     return result;
   }
 
-  const adapters = getAdapters();
-  const adapterMap = new Map(adapters.map((a) => [a.name, a]));
-
-  // Process entries that need titles
-  for (const [filename, entry] of entries) {
-    // Skip if already has title (unless force)
+  for (const entry of entries) {
     if (entry.title && !force) {
       result.skipped++;
       continue;
     }
 
     try {
-      // Read source and compute content hash
-      const content = await Bun.file(entry.source).text();
-      const contentHash = computeContentHash(content);
-
-      // Check cache for existing title
-      const cached = await loadCache(entry.source);
-      const segmentIndex = entry.segmentIndex ? entry.segmentIndex - 1 : 0;
-      const cachedTitle = getCachedTitle(cached, contentHash, segmentIndex);
-
-      if (cachedTitle && !force) {
-        entry.title = cachedTitle;
+      // Use the first transcript for title generation
+      const transcript = entry.transcripts[0];
+      if (!transcript || transcript.metadata.messageCount === 0) {
         result.skipped++;
         continue;
       }
 
-      // Determine adapter from filename pattern (HTML files were synced with an adapter)
-      // We need to find which adapter was used - check the source path
-      let adapter = adapterMap.get("claude-code"); // default
-      for (const a of adapters) {
-        if (entry.source.includes(".claude/")) {
-          adapter = a;
-          break;
-        }
-      }
-
-      if (!adapter) {
-        console.error(`Warning: No adapter found for ${entry.source}`);
-        result.errors++;
-        continue;
-      }
-
-      const transcripts = adapter.parse(content, entry.source);
-
-      // Find the right transcript (by segment index if applicable)
-      const transcript = transcripts[segmentIndex];
-
-      if (!transcript) {
-        console.error(`Warning: Transcript not found for ${filename}`);
-        result.errors++;
-        continue;
-      }
-
       const markdown = renderTranscript(transcript);
       const title = await generateTitle(markdown);
 
       if (title) {
         entry.title = title;
+        await saveEntry(archiveDir, entry);
         result.generated++;
         if (!quiet) {
-          console.error(`Title: ${filename} → ${title}`);
-        }
-
-        // Update cache with new title
-        // Start fresh if content changed to avoid stale md/html
-        // Deep copy segments to avoid mutating cached object
-        const newCache: CacheEntry = {
-          contentHash,
-          segments:
-            cached?.contentHash === contentHash
-              ? cached.segments.map((s) => ({ ...s }))
-              : [],
-        };
-        // Ensure segment array is long enough
-        while (newCache.segments.length <= segmentIndex) {
-          newCache.segments.push({});
+          console.error(`Title: ${entry.sessionId} → ${title}`);
         }
-        newCache.segments[segmentIndex].title = title;
-
-        // Re-render HTML with title if this is an HTML file
-        if (filename.endsWith(".html")) {
-          const html = await renderTranscriptHtml(transcript, { title });
-          const outputPath = join(outputDir, filename);
-          await Bun.write(outputPath, html);
-          newCache.segments[segmentIndex].html = html;
-        }
-
-        await saveCache(entry.source, newCache);
       } else {
         result.skipped++;
-        if (!quiet) {
-          console.error(`Skip (no title generated): ${filename}`);
-        }
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      console.error(`Error: ${filename}: ${message}`);
+      console.error(`Error: ${entry.sessionId}: ${message}`);
       result.errors++;
     }
   }
 
-  await saveIndex(outputDir, index);
-
   if (!quiet) {
     console.error(
-      `\nTitle generation complete: ${result.generated} generated, ${result.skipped} skipped, ${result.errors} errors`,
+      `\nTitle generation: ${result.generated} generated, ${result.skipped} skipped, ${result.errors} errors`,
     );
   }
 

package/src/types.ts

@@ -76,6 +76,7 @@ export interface ErrorMessage extends BaseMessage {
  * A session file discovered by an adapter.
  */
 export interface DiscoveredSession {
+  /** Absolute path to the session file. Must be absolute for archive traceability. */
   path: string;
   relativePath: string;
   mtime: number;
@@ -88,6 +89,8 @@ export interface DiscoveredSession {
  */
 export interface Adapter {
   name: string;
+  /** Versioned identifier for cache invalidation (e.g. "claude-code:1") */
+  version: string;
   /** Discover session files in the given directory */
   discover(source: string): Promise<DiscoveredSession[]>;
   /** Parse source content into one or more transcripts (split by conversation) */

package/src/utils/naming.ts

@@ -7,22 +7,17 @@
 import type { Transcript } from "../types.ts";
 import { basename } from "path";
 
-/**
- * Extract date and time from transcript's first message timestamp.
- * Returns format: yyyy-mm-dd-hhmm (24-hour, local time)
- */
-function extractDateTime(transcript: Transcript): string {
-  const firstMessage = transcript.messages[0];
-  const date = firstMessage?.timestamp
-    ? new Date(firstMessage.timestamp)
-    : new Date();
-
-  if (isNaN(date.getTime())) {
-    return formatDateTime(new Date());
-  }
+/** Format a timestamp as yyyy-mm-dd-hhmm (24-hour, local time). */
+export function formatDateTimePrefix(timestamp: string): string {
+  const date = timestamp ? new Date(timestamp) : new Date();
+  if (isNaN(date.getTime())) return formatDateTime(new Date());
   return formatDateTime(date);
 }
 
+function extractDateTime(transcript: Transcript): string {
+  return formatDateTimePrefix(transcript.messages[0]?.timestamp ?? "");
+}
+
 function formatDateTime(date: Date): string {
   const year = date.getFullYear();
   const month = String(date.getMonth() + 1).padStart(2, "0");

package/src/utils/summary.ts

@@ -2,10 +2,7 @@
  * Extract one-line summaries from tool call inputs.
  */
 
-function truncate(str: string, maxLen: number): string {
-  if (str.length <= maxLen) return str;
-  return str.slice(0, maxLen - 3) + "...";
-}
+import { truncate } from "./text.ts";
 
 type ToolInput = Record<string, unknown>;
 

package/src/utils/text.ts

@@ -0,0 +1,5 @@
+/** Truncate a string, appending "..." if it exceeds maxLen. */
+export function truncate(str: string, maxLen: number): string {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 3) + "...";
+}

package/src/utils/theme.ts

@@ -0,0 +1,152 @@
+/**
+ * Shared CSS theme tokens and base styles used by both
+ * render-html.ts (transcript pages) and render-index.ts (index page).
+ */
+
+export const THEME_VARS = `
+@import url('https://fonts.googleapis.com/css2?family=Berkeley+Mono:wght@400;500&family=IBM+Plex+Mono:wght@400;500;600&family=Inter:wght@400;500&display=swap');
+
+:root {
+  /* Typography */
+  --font-mono: 'Berkeley Mono', 'IBM Plex Mono', 'JetBrains Mono', 'SF Mono', Consolas, monospace;
+  --font-body: 'Inter', -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+
+  /* Dark theme */
+  --bg: #0d0d0d;
+  --bg-elevated: #141414;
+  --bg-surface: #1a1a1a;
+  --fg: #e4e4e4;
+  --fg-secondary: #a3a3a3;
+  --muted: #666666;
+  --border: #2a2a2a;
+  --border-subtle: #222222;
+
+  /* Accent */
+  --accent: #f59e0b;
+  --accent-dim: #b45309;
+  --accent-glow: rgba(245, 158, 11, 0.15);
+
+  /* Links */
+  --link: #60a5fa;
+  --link-hover: #93c5fd;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3);
+  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.4);
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    --bg: #fafafa;
+    --bg-elevated: #ffffff;
+    --bg-surface: #f5f5f5;
+    --fg: #171717;
+    --fg-secondary: #525252;
+    --muted: #a3a3a3;
+    --border: #e5e5e5;
+    --border-subtle: #f0f0f0;
+
+    --accent: #d97706;
+    --accent-dim: #92400e;
+    --accent-glow: rgba(217, 119, 6, 0.1);
+
+    --link: #2563eb;
+    --link-hover: #1d4ed8;
+
+    --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+    --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.08);
+  }
+}`;
+
+export const BASE_RESET = `
+*, *::before, *::after { box-sizing: border-box; }
+
+html {
+  font-size: 15px;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+  font-family: var(--font-body);
+  background: var(--bg);
+  color: var(--fg);
+  line-height: 1.65;
+  margin: 0;
+  padding: 0;
+  min-height: 100vh;
+}
+
+a {
+  color: var(--link);
+  text-decoration: none;
+  transition: color 0.15s ease;
+}
+
+a:hover {
+  color: var(--link-hover);
+}`;
+
+export const SCROLLBAR_STYLES = `
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+
+::-webkit-scrollbar-track {
+  background: var(--border-subtle);
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--muted);
+  border-radius: 3px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: var(--fg-secondary);
+}`;
+
+/**
+ * Accent bar on the left edge of the page, parameterized by container class.
+ */
+export function accentBar(containerClass: string): string {
+  return `
+.${containerClass}::before {
+  content: '';
+  position: fixed;
+  left: 0;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background: linear-gradient(
+    180deg,
+    transparent 0%,
+    var(--accent-dim) 15%,
+    var(--accent) 50%,
+    var(--accent-dim) 85%,
+    transparent 100%
+  );
+  opacity: 0.6;
+}`;
+}
+
+/**
+ * Responsive breakpoint hiding the accent bar and shrinking fonts.
+ * containerClass: the wrapper class to adjust padding on.
+ */
+export function responsiveBase(containerClass: string): string {
+  return `
+@media (max-width: 640px) {
+  html {
+    font-size: 14px;
+  }
+
+  .${containerClass} {
+    padding: 1.5rem 1rem 3rem;
+  }
+
+  .${containerClass}::before {
+    display: none;
+  }
+}`;
+}

package/src/utils/tree.ts

@@ -2,7 +2,7 @@
  * Tree/branch navigation utilities for transcript messages.
  */
 
-import type { Message } from "../types.ts";
+import type { Transcript, Message } from "../types.ts";
 
 export interface MessageTree {
   bySourceRef: Map<string, Message[]>;
@@ -114,3 +114,87 @@ export function getFirstLine(msg: Message): string {
     ? firstLine.slice(0, maxLen) + "..."
     : firstLine;
 }
+
+// ============================================================================
+// Tree walk: yields events as it walks the primary branch of a transcript.
+// ============================================================================
+
+export type TreeEvent =
+  | { type: "messages"; messages: Message[] }
+  | { type: "branch_note"; branches: BranchInfo[] }
+  | { type: "head_not_found"; head: string }
+  | { type: "empty" };
+
+export interface BranchInfo {
+  sourceRef: string;
+  firstLine: string;
+}
+
+export interface WalkOptions {
+  head?: string;
+}
+
+/**
+ * Walk the primary branch of a transcript, yielding render events.
+ * Handles tree construction, target resolution, path tracing, and branch detection.
+ */
+export function* walkTranscriptTree(
+  transcript: Transcript,
+  options: WalkOptions = {},
+): Generator<TreeEvent> {
+  if (transcript.messages.length === 0) {
+    yield { type: "empty" };
+    return;
+  }
+
+  const { head } = options;
+  const { bySourceRef, children, parents } = buildTree(transcript.messages);
+
+  let target: string | undefined;
+  if (head) {
+    if (!bySourceRef.has(head)) {
+      yield { type: "head_not_found", head };
+      return;
+    }
+    target = head;
+  } else {
+    target = findLatestLeaf(bySourceRef, children);
+  }
+
+  if (!target) {
+    // Fallback: yield all messages in order
+    yield { type: "messages", messages: transcript.messages };
+    return;
+  }
+
+  const path = tracePath(target, parents);
+  const pathSet = new Set(path);
+
+  for (const sourceRef of path) {
+    const msgs = bySourceRef.get(sourceRef);
+    if (!msgs) continue;
+
+    yield { type: "messages", messages: msgs };
+
+    // Branch notes (only when not using explicit head)
+    if (!head) {
+      const childSet = children.get(sourceRef);
+      if (childSet && childSet.size > 1) {
+        const branches: BranchInfo[] = [];
+        for (const childRef of childSet) {
+          if (pathSet.has(childRef)) continue;
+          const branchMsgs = bySourceRef.get(childRef);
+          if (branchMsgs && branchMsgs.length > 0) {
+            branches.push({
+              sourceRef: childRef,
+              firstLine: getFirstLine(branchMsgs[0]),
+            });
+          }
+        }
+        if (branches.length > 0) {
+          yield { type: "branch_note", branches };
+        }
+      }
+    }
+  }
+}

package/src/watch.ts

@@ -0,0 +1,111 @@
+/**
+ * Watch module: keep archive in sync with source directories.
+ *
+ * Uses fs.watch for change detection with periodic full scan as fallback.
+ * Multiple watchers can safely target the same archive — writes are atomic
+ * (tmp + rename) and archiving is idempotent.
+ */
+
+import { watch, type FSWatcher } from "fs";
+import { getAdapters } from "./adapters/index.ts";
+import {
+  archiveAll,
+  DEFAULT_ARCHIVE_DIR,
+  type ArchiveResult,
+} from "./archive.ts";
+
+export interface WatchOptions {
+  archiveDir?: string;
+  pollIntervalMs?: number;
+  onUpdate?: (result: ArchiveResult) => void;
+  onError?: (error: Error) => void;
+  quiet?: boolean;
+}
+
+export class ArchiveWatcher {
+  private sourceDirs: string[];
+  private archiveDir: string;
+  private pollIntervalMs: number;
+  private onUpdate?: (result: ArchiveResult) => void;
+  private onError?: (error: Error) => void;
+  private quiet: boolean;
+  private watchers: FSWatcher[] = [];
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private scanning = false;
+
+  constructor(sourceDirs: string[], options: WatchOptions = {}) {
+    this.sourceDirs = sourceDirs;
+    this.archiveDir = options.archiveDir ?? DEFAULT_ARCHIVE_DIR;
+    this.pollIntervalMs = options.pollIntervalMs ?? 30_000;
+    this.onUpdate = options.onUpdate;
+    this.onError = options.onError;
+    this.quiet = options.quiet ?? false;
+  }
+
+  async start(): Promise<void> {
+    // Initial scan
+    await this.scan();
+
+    // Set up fs.watch on each source dir
+    for (const dir of this.sourceDirs) {
+      try {
+        const watcher = watch(dir, { recursive: true }, (_event, filename) => {
+          if (filename && filename.endsWith(".jsonl")) {
+            this.debouncedScan();
+          }
+        });
+        this.watchers.push(watcher);
+      } catch (err) {
+        if (!this.quiet) {
+          console.error(
+            `Warning: could not watch ${dir}: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      }
+    }
+
+    // Periodic fallback scan
+    this.pollTimer = setInterval(() => this.scan(), this.pollIntervalMs);
+  }
+
+  stop(): void {
+    for (const w of this.watchers) {
+      w.close();
+    }
+    this.watchers = [];
+
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  private debouncedScan(): void {
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => this.scan(), 500);
+  }
+
+  private async scan(): Promise<void> {
+    if (this.scanning) return;
+    this.scanning = true;
+
+    try {
+      const adapters = getAdapters();
+      for (const dir of this.sourceDirs) {
+        const result = await archiveAll(this.archiveDir, dir, adapters, {
+          quiet: this.quiet,
+        });
+        if (result.updated.length > 0 || result.errors.length > 0) {
+          this.onUpdate?.(result);
+        }
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.onError?.(error);
+    } finally {
+      this.scanning = false;
+    }
+  }
+}