@arcreflex/agent-transcripts 0.1.11 → 0.1.13

package/README.md

@@ -35,7 +35,9 @@ src/
 test/
   fixtures/       # Snapshot test inputs/outputs
   snapshots.test.ts
+  adapters.test.ts
   archive.test.ts
+  watch.test.ts
   tree.test.ts
   naming.test.ts
   summary.test.ts
@@ -57,8 +59,9 @@ agent-transcripts convert <file>              # Parse and render to stdout
 agent-transcripts convert <file> -o <dir>     # Parse and render to directory
 
 # Archive management
-agent-transcripts archive <source>            # Archive sessions from source dir
-agent-transcripts archive <source> --archive-dir ~/my-archive
+agent-transcripts archive                     # Auto-discover from adapter defaults (~/.claude)
+agent-transcripts archive /path --adapter claude-code  # Explicit source + adapter
+agent-transcripts archive --archive-dir ~/my-archive   # Custom archive location
 
 # Serving
 agent-transcripts serve                       # Serve from default archive
@@ -66,8 +69,9 @@ agent-transcripts serve --archive-dir <dir>   # Serve from custom archive
 agent-transcripts serve -p 8080               # Custom port
 
 # Watching
-agent-transcripts watch <source>              # Keep archive updated continuously
-agent-transcripts watch <source> --poll-interval 60000
+agent-transcripts watch                       # Auto-discover from adapter defaults
+agent-transcripts watch /path --adapter claude-code    # Explicit source + adapter
+agent-transcripts watch --poll-interval 60000
 
 # Title generation
 agent-transcripts title                       # Generate titles for archive entries
@@ -98,10 +102,10 @@ HTML (rendered on demand, in-memory LRU)
 
 ### Archive
 
-The archive is the central data store at `~/.local/share/agent-transcripts/archive/`:
+The archive is the central data store at `$XDG_DATA_HOME/agent-transcripts/archive/` (defaults to `~/.local/share/agent-transcripts/archive/`):
 
 ```
-~/.local/share/agent-transcripts/archive/
+$XDG_DATA_HOME/agent-transcripts/archive/
   {sessionId}.json  →  ArchiveEntry
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcreflex/agent-transcripts",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Transform AI coding agent session files into readable transcripts",
   "type": "module",
   "repository": {

package/src/adapters/claude-code.ts

@@ -6,6 +6,7 @@
 
 import { Glob } from "bun";
 import { basename, join, relative } from "path";
+import { homedir } from "os";
 import { stat } from "fs/promises";
 import type {
   Adapter,
@@ -816,6 +817,7 @@ async function discoverByGlob(source: string): Promise<DiscoveredSession[]> {
 export const claudeCodeAdapter: Adapter = {
   name: "claude-code",
   version: "claude-code:1",
+  defaultSource: process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"),
 
   async discover(source: string): Promise<DiscoveredSession[]> {
     // Try index-based discovery first, fall back to glob

package/src/adapters/index.ts

@@ -2,7 +2,7 @@
  * Adapter registry with path-based detection.
  */
 
-import type { Adapter } from "../types.ts";
+import type { Adapter, SourceSpec } from "../types.ts";
 import { claudeCodeAdapter } from "./claude-code.ts";
 
 const adapters: Record<string, Adapter> = {
@@ -39,8 +39,10 @@ export function listAdapters(): string[] {
 }
 
 /**
- * Get all registered adapters.
+ * Get default source specs from adapters that define a defaultSource.
  */
-export function getAdapters(): Adapter[] {
-  return Object.values(adapters);
+export function getDefaultSources(): SourceSpec[] {
+  return Object.values(adapters)
+    .filter((a): a is Adapter & { defaultSource: string } => !!a.defaultSource)
+    .map((a) => ({ adapter: a, source: a.defaultSource }));
 }

package/src/archive.ts

@@ -12,8 +12,8 @@ import type { Adapter, DiscoveredSession, Transcript } from "./types.ts";
 import { extractSessionId } from "./utils/naming.ts";
 
 export const DEFAULT_ARCHIVE_DIR = join(
-  homedir(),
-  ".local/share/agent-transcripts/archive",
+  process.env.XDG_DATA_HOME || join(homedir(), ".local/share"),
+  "agent-transcripts/archive",
 );
 
 const ARCHIVE_SCHEMA_VERSION = 1;

package/src/cli.ts

@@ -19,8 +19,9 @@ import { convertToDirectory } from "./convert.ts";
 import { generateTitles } from "./title.ts";
 import { serve } from "./serve.ts";
 import { archiveAll, DEFAULT_ARCHIVE_DIR } from "./archive.ts";
-import { getAdapters } from "./adapters/index.ts";
+import { getAdapter, getDefaultSources } from "./adapters/index.ts";
 import { ArchiveWatcher } from "./watch.ts";
+import type { SourceSpec } from "./types.ts";
 
 // Shared options
 const inputArg = positional({
@@ -55,16 +56,52 @@ const archiveDirOpt = option({
   description: `Archive directory (default: ${DEFAULT_ARCHIVE_DIR})`,
 });
 
+/**
+ * Resolve source specs from CLI args.
+ * - No source: use adapter defaults
+ * - Source + adapter: explicit pair
+ * - Source without adapter: error
+ */
+function resolveSourceSpecs(
+  source: string | undefined,
+  adapterName: string | undefined,
+): SourceSpec[] {
+  if (!source) {
+    const defaults = getDefaultSources();
+    if (defaults.length === 0) {
+      console.error("Error: no adapters have a default source directory.");
+      process.exit(1);
+    }
+    return defaults;
+  }
+
+  if (!adapterName) {
+    console.error(
+      "Error: --adapter is required when specifying a source directory.",
+    );
+    process.exit(1);
+  }
+
+  const adapter = getAdapter(adapterName);
+  if (!adapter) {
+    console.error(`Error: unknown adapter "${adapterName}".`);
+    process.exit(1);
+  }
+
+  return [{ adapter, source }];
+}
+
 // Archive subcommand
 const archiveCmd = command({
   name: "archive",
   description: "Archive session files from source directory",
   args: {
     source: positional({
-      type: string,
+      type: optional(string),
       displayName: "source",
-      description: "Source directory to scan for session files",
+      description: "Source directory to scan (omit to use adapter defaults)",
     }),
+    adapter: adapterOpt,
     archiveDir: archiveDirOpt,
     quiet: flag({
       long: "quiet",
@@ -72,13 +109,26 @@ const archiveCmd = command({
       description: "Suppress progress output",
     }),
   },
-  async handler({ source, archiveDir, quiet }) {
+  async handler({ source, adapter: adapterName, archiveDir, quiet }) {
     const dir = archiveDir ?? DEFAULT_ARCHIVE_DIR;
-    const result = await archiveAll(dir, source, getAdapters(), { quiet });
+    const specs = resolveSourceSpecs(source, adapterName);
+
+    let totalUpdated = 0;
+    let totalCurrent = 0;
+    let totalErrors = 0;
+
+    for (const spec of specs) {
+      const result = await archiveAll(dir, spec.source, [spec.adapter], {
+        quiet,
+      });
+      totalUpdated += result.updated.length;
+      totalCurrent += result.current.length;
+      totalErrors += result.errors.length;
+    }
 
     if (!quiet) {
       console.error(
-        `\nArchive complete: ${result.updated.length} updated, ${result.current.length} current, ${result.errors.length} errors`,
+        `\nArchive complete: ${totalUpdated} updated, ${totalCurrent} current, ${totalErrors} errors`,
       );
     }
   },
@@ -143,10 +193,11 @@ const watchCmd = command({
   description: "Watch source directories and keep archive updated",
   args: {
     source: positional({
-      type: string,
+      type: optional(string),
       displayName: "source",
-      description: "Source directory to watch for session files",
+      description: "Source directory to watch (omit to use adapter defaults)",
     }),
+    adapter: adapterOpt,
     archiveDir: archiveDirOpt,
     pollInterval: option({
       type: optional(number),
@@ -159,8 +210,16 @@ const watchCmd = command({
       description: "Suppress progress output",
     }),
   },
-  async handler({ source, archiveDir, pollInterval, quiet }) {
-    const watcher = new ArchiveWatcher([source], {
+  async handler({
+    source,
+    adapter: adapterName,
+    archiveDir,
+    pollInterval,
+    quiet,
+  }) {
+    const specs = resolveSourceSpecs(source, adapterName);
+
+    const watcher = new ArchiveWatcher(specs, {
       archiveDir: archiveDir ?? undefined,
       pollIntervalMs: pollInterval ?? undefined,
       quiet,
@@ -174,8 +233,9 @@ const watchCmd = command({
       },
     });
 
+    const dirs = [...new Set(specs.map((s) => s.source))].join(", ");
     if (!quiet) {
-      console.error(`Watching ${source}...`);
+      console.error(`Watching ${dirs}...`);
     }
 
     await watcher.start();

package/src/types.ts

@@ -91,8 +91,16 @@ export interface Adapter {
   name: string;
   /** Versioned identifier for cache invalidation (e.g. "claude-code:1") */
   version: string;
+  /** Default source directory for auto-discovery (if the adapter has one) */
+  defaultSource?: string;
   /** Discover session files in the given directory */
   discover(source: string): Promise<DiscoveredSession[]>;
   /** Parse source content into one or more transcripts (split by conversation) */
   parse(content: string, sourcePath: string): Transcript[];
 }
+
+/** An adapter paired with its source directory. */
+export interface SourceSpec {
+  adapter: Adapter;
+  source: string;
+}

package/src/watch.ts

@@ -2,13 +2,12 @@
  * Watch module: keep archive in sync with source directories.
  *
  * Uses fs.watch for change detection with periodic full scan as fallback.
- * Lockfile prevents concurrent watchers on the same archive.
+ * Multiple watchers can safely target the same archive — writes are atomic
+ * (tmp + rename) and archiving is idempotent.
  */
 
-import { watch, unlinkSync, type FSWatcher } from "fs";
-import { join } from "path";
-import { mkdir, writeFile, readFile } from "fs/promises";
-import { getAdapters } from "./adapters/index.ts";
+import { watch, type FSWatcher } from "fs";
+import type { SourceSpec } from "./types.ts";
 import {
   archiveAll,
   DEFAULT_ARCHIVE_DIR,
@@ -23,65 +22,8 @@ export interface WatchOptions {
   quiet?: boolean;
 }
 
-function lockPath(archiveDir: string): string {
-  return join(archiveDir, "archive.lock");
-}
-
-async function acquireLock(archiveDir: string): Promise<boolean> {
-  await mkdir(archiveDir, { recursive: true });
-  const lock = lockPath(archiveDir);
-  try {
-    await writeFile(lock, String(process.pid), { flag: "wx" });
-    return true;
-  } catch (err: unknown) {
-    if (
-      err &&
-      typeof err === "object" &&
-      "code" in err &&
-      err.code === "EEXIST"
-    ) {
-      // Lock file exists — check if the holding process is still alive
-      try {
-        const existing = await readFile(lock, "utf-8");
-        const pid = parseInt(existing, 10);
-        if (!isNaN(pid)) {
-          try {
-            process.kill(pid, 0);
-            return false; // Process is alive, lock is held
-          } catch {
-            // Process is dead, stale lock — reclaim
-          }
-        }
-        await writeFile(lock, String(process.pid), { flag: "w" });
-        return true;
-      } catch {
-        return false;
-      }
-    }
-    throw err;
-  }
-}
-
-function releaseLock(archiveDir: string): void {
-  try {
-    unlinkSync(lockPath(archiveDir));
-  } catch (err: unknown) {
-    if (
-      err &&
-      typeof err === "object" &&
-      "code" in err &&
-      err.code === "ENOENT"
-    ) {
-      return;
-    }
-    console.error(
-      `Warning: failed to release lock: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
-}
-
 export class ArchiveWatcher {
-  private sourceDirs: string[];
+  private sources: SourceSpec[];
   private archiveDir: string;
   private pollIntervalMs: number;
   private onUpdate?: (result: ArchiveResult) => void;
@@ -91,8 +33,8 @@ export class ArchiveWatcher {
   private pollTimer: ReturnType<typeof setInterval> | null = null;
   private scanning = false;
 
-  constructor(sourceDirs: string[], options: WatchOptions = {}) {
-    this.sourceDirs = sourceDirs;
+  constructor(sources: SourceSpec[], options: WatchOptions = {}) {
+    this.sources = sources;
     this.archiveDir = options.archiveDir ?? DEFAULT_ARCHIVE_DIR;
     this.pollIntervalMs = options.pollIntervalMs ?? 30_000;
     this.onUpdate = options.onUpdate;
@@ -101,29 +43,30 @@ export class ArchiveWatcher {
   }
 
   async start(): Promise<void> {
-    const locked = await acquireLock(this.archiveDir);
-    if (!locked) {
-      throw new Error(
-        `Another watcher is already running on ${this.archiveDir}`,
-      );
-    }
-
     // Initial scan
     await this.scan();
 
-    // Set up fs.watch on each source dir
-    for (const dir of this.sourceDirs) {
+    // Set up fs.watch on each unique source dir
+    const watchedDirs = new Set<string>();
+    for (const spec of this.sources) {
+      if (watchedDirs.has(spec.source)) continue;
+      watchedDirs.add(spec.source);
+
       try {
-        const watcher = watch(dir, { recursive: true }, (_event, filename) => {
-          if (filename && filename.endsWith(".jsonl")) {
-            this.debouncedScan();
-          }
-        });
+        const watcher = watch(
+          spec.source,
+          { 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)}`,
+            `Warning: could not watch ${spec.source}: ${err instanceof Error ? err.message : String(err)}`,
           );
         }
       }
@@ -143,8 +86,6 @@ export class ArchiveWatcher {
       clearInterval(this.pollTimer);
       this.pollTimer = null;
     }
-
-    releaseLock(this.archiveDir);
   }
 
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
@@ -159,11 +100,13 @@ export class ArchiveWatcher {
     this.scanning = true;
 
     try {
-      const adapters = getAdapters();
-      for (const dir of this.sourceDirs) {
-        const result = await archiveAll(this.archiveDir, dir, adapters, {
-          quiet: this.quiet,
-        });
+      for (const spec of this.sources) {
+        const result = await archiveAll(
+          this.archiveDir,
+          spec.source,
+          [spec.adapter],
+          { quiet: this.quiet },
+        );
         if (result.updated.length > 0 || result.errors.length > 0) {
           this.onUpdate?.(result);
         }

package/test/adapters.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "bun:test";
+import { getDefaultSources, getAdapter } from "../src/adapters/index.ts";
+import { claudeCodeAdapter } from "../src/adapters/claude-code.ts";
+
+describe("getDefaultSources", () => {
+  it("returns claude-code with its defaultSource", () => {
+    const specs = getDefaultSources();
+    expect(specs.length).toBeGreaterThanOrEqual(1);
+
+    const cc = specs.find((s) => s.adapter.name === "claude-code");
+    expect(cc).toBeDefined();
+    expect(cc?.adapter).toBe(claudeCodeAdapter);
+    expect(typeof cc?.source).toBe("string");
+    expect(cc?.source.length).toBeGreaterThan(0);
+  });
+
+  it("only includes adapters with defaultSource set", () => {
+    for (const spec of getDefaultSources()) {
+      expect(spec.source).toBeTruthy();
+    }
+  });
+});
+
+describe("getAdapter", () => {
+  it("returns adapter by name", () => {
+    expect(getAdapter("claude-code")).toBe(claudeCodeAdapter);
+  });
+
+  it("returns undefined for unknown adapter", () => {
+    expect(getAdapter("nonexistent")).toBeUndefined();
+  });
+});

package/test/watch.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it, beforeEach, afterEach } from "bun:test";
+import { join } from "path";
+import { mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { ArchiveWatcher } from "../src/watch.ts";
+import { claudeCodeAdapter } from "../src/adapters/claude-code.ts";
+import { listEntries } from "../src/archive.ts";
+
+const fixturesDir = join(import.meta.dir, "fixtures/claude");
+
+let archiveDir: string;
+let sourceDir: string;
+
+beforeEach(async () => {
+  archiveDir = await mkdtemp(join(tmpdir(), "watch-archive-"));
+  sourceDir = await mkdtemp(join(tmpdir(), "watch-source-"));
+});
+
+afterEach(async () => {
+  await rm(archiveDir, { recursive: true, force: true });
+  await rm(sourceDir, { recursive: true, force: true });
+});
+
+describe("ArchiveWatcher with SourceSpec[]", () => {
+  it("archives from a single source spec on initial scan", async () => {
+    // Copy a fixture into the source dir
+    const content = await Bun.file(
+      join(fixturesDir, "basic-conversation.input.jsonl"),
+    ).text();
+    await Bun.write(join(sourceDir, "session.jsonl"), content);
+
+    const updates: string[] = [];
+    const watcher = new ArchiveWatcher(
+      [{ adapter: claudeCodeAdapter, source: sourceDir }],
+      {
+        archiveDir,
+        quiet: true,
+        onUpdate(result) {
+          updates.push(...result.updated);
+        },
+      },
+    );
+
+    await watcher.start();
+    watcher.stop();
+
+    expect(updates.length).toBe(1);
+    const entries = await listEntries(archiveDir);
+    expect(entries.length).toBe(1);
+  });
+
+  it("archives from multiple source specs", async () => {
+    const sourceDir2 = await mkdtemp(join(tmpdir(), "watch-source2-"));
+
+    const content = await Bun.file(
+      join(fixturesDir, "basic-conversation.input.jsonl"),
+    ).text();
+    await Bun.write(join(sourceDir, "a.jsonl"), content);
+    await Bun.write(join(sourceDir2, "b.jsonl"), content);
+
+    const updates: string[] = [];
+    const watcher = new ArchiveWatcher(
+      [
+        { adapter: claudeCodeAdapter, source: sourceDir },
+        { adapter: claudeCodeAdapter, source: sourceDir2 },
+      ],
+      {
+        archiveDir,
+        quiet: true,
+        onUpdate(result) {
+          updates.push(...result.updated);
+        },
+      },
+    );
+
+    await watcher.start();
+    watcher.stop();
+
+    expect(updates.length).toBe(2);
+    const entries = await listEntries(archiveDir);
+    expect(entries.length).toBe(2);
+
+    await rm(sourceDir2, { recursive: true, force: true });
+  });
+});