@arcreflex/agent-transcripts 0.1.3 → 0.1.5

package/CLAUDE.md

@@ -0,0 +1,10 @@
+# agent-transcripts
+
+@README.md
+
+## Verification
+
+Before committing:
+1. `bun run check` (typecheck + prettier)
+2. `bun run test` (snapshot tests)
+3. Check for documentation drift in README.md

package/README.md

@@ -15,9 +15,14 @@ src/
   cli.ts          # CLI entry point, subcommand routing
   parse.ts        # Source → intermediate JSON
   render.ts       # Intermediate JSON → markdown
+  convert.ts      # Full pipeline with provenance tracking
+  sync.ts         # Batch sync sessions → markdown
   types.ts        # Core types (Transcript, Message, Adapter)
   adapters/       # Source format adapters (currently: claude-code)
-  utils/          # Helpers (summary extraction)
+  utils/
+    naming.ts     # Descriptive output file naming
+    provenance.ts # Source tracking via YAML front matter
+    summary.ts    # Summary extraction
 test/
   fixtures/       # Snapshot test inputs/outputs
   snapshots.test.ts
@@ -31,6 +36,22 @@ bun run test         # snapshot tests
 bun run format       # auto-format
 ```
 
+## CLI Usage
+
+```bash
+# Subcommands (convert is default if omitted)
+agent-transcripts convert <file>    # Full pipeline: parse → render
+agent-transcripts parse <file>      # Source → intermediate JSON
+agent-transcripts render <file>     # JSON → markdown
+agent-transcripts sync <dir> -o <out>  # Batch sync sessions
+
+# Use "-" for stdin
+cat session.jsonl | agent-transcripts -
+
+# Environment variables
+OPENROUTER_API_KEY=...   # Enables LLM-based descriptive output naming
+```
+
 ## Architecture
 
 Two-stage pipeline: Parse (source → JSON) → Render (JSON → markdown).
@@ -38,12 +59,15 @@ Two-stage pipeline: Parse (source → JSON) → Render (JSON → markdown).
 - Adapters handle source formats (see `src/adapters/index.ts` for registry)
 - Auto-detection: paths containing `.claude/` → claude-code adapter
 - Branching conversations preserved via `parentMessageRef` on messages
+- Provenance tracking: rendered markdown includes YAML front matter with source path
+- Descriptive naming: output files named by date + summary (LLM-enhanced if API key set)
+- Sync uses mtime to skip unchanged sources
 
 ## Key Types
 
 - `Transcript`: source info, warnings, messages array
 - `Message`: union of UserMessage | AssistantMessage | SystemMessage | ToolCallGroup | ErrorMessage
-- `Adapter`: `{ name: string, parse(content, sourcePath): Transcript[] }`
+- `Adapter`: name, file patterns, parse function
 
 ## Adding an Adapter
 

package/package.json

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

package/src/adapters/claude-code.ts

@@ -335,6 +335,7 @@ function transformConversation(
 
 export const claudeCodeAdapter: Adapter = {
   name: "claude-code",
+  filePatterns: ["*.jsonl"],
 
   parse(content: string, sourcePath: string): Transcript[] {
     const { records, warnings } = parseJsonl(content);

package/src/adapters/index.ts

@@ -43,3 +43,10 @@ export function getAdapter(name: string): Adapter | undefined {
 export function listAdapters(): string[] {
   return Object.keys(adapters);
 }
+
+/**
+ * Get all registered adapters.
+ */
+export function getAdapters(): Adapter[] {
+  return Object.values(adapters);
+}

package/src/cli.ts

@@ -10,18 +10,21 @@ import {
   option,
   optional,
   positional,
+  flag,
 } from "cmd-ts";
 import { parse, parseToTranscripts } from "./parse.ts";
 import { render, renderTranscript } from "./render.ts";
+import { sync } from "./sync.ts";
+import { convertToDirectory } from "./convert.ts";
 
 // Read OpenRouter API key from environment for LLM-based slug generation
 const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY;
 
 // Shared options
 const inputArg = positional({
-  type: optional(string),
+  type: string,
   displayName: "file",
-  description: "Input file (reads from stdin if not provided)",
+  description: "Input file (use - for stdin)",
 });
 
 const outputOpt = option({
@@ -84,10 +87,52 @@ const renderCmd = command({
   },
 });
 
-// Default command: full pipeline (parse → render)
-const defaultCmd = command({
-  name: "agent-transcripts",
-  description: "Transform agent session files to readable transcripts",
+// Sync subcommand
+const syncCmd = command({
+  name: "sync",
+  description: "Sync session files to markdown transcripts",
+  args: {
+    source: positional({
+      type: string,
+      displayName: "source",
+      description: "Source directory to scan for session files",
+    }),
+    output: option({
+      type: string,
+      long: "output",
+      short: "o",
+      description: "Output directory for transcripts",
+    }),
+    force: flag({
+      long: "force",
+      short: "f",
+      description: "Re-render all sessions, ignoring mtime",
+    }),
+    quiet: flag({
+      long: "quiet",
+      short: "q",
+      description: "Suppress progress output",
+    }),
+  },
+  async handler({ source, output, force, quiet }) {
+    const naming = OPENROUTER_API_KEY
+      ? { apiKey: OPENROUTER_API_KEY }
+      : undefined;
+    await sync({ source, output, force, quiet, naming });
+  },
+});
+
+/**
+ * Check if output looks like a directory (no extension) vs a specific file.
+ */
+function isDirectoryOutput(output: string): boolean {
+  return !output.match(/\.\w+$/);
+}
+
+// Convert subcommand: full pipeline (parse → render) - the default
+const convertCmd = command({
+  name: "convert",
+  description: "Full pipeline: parse source and render to markdown (default)",
   args: {
     input: inputArg,
     output: outputOpt,
@@ -99,15 +144,24 @@ const defaultCmd = command({
       ? { apiKey: OPENROUTER_API_KEY }
       : undefined;
 
-    if (output) {
-      // Write intermediate JSON and markdown files
+    if (output && isDirectoryOutput(output)) {
+      // Directory output: use sync-like behavior with provenance tracking
+      await convertToDirectory({
+        input,
+        outputDir: output,
+        adapter,
+        head,
+        naming,
+      });
+    } else if (output) {
+      // Explicit file output: write intermediate JSON and markdown
       const { outputPaths } = await parse({ input, output, adapter, naming });
       for (const jsonPath of outputPaths) {
         const mdPath = jsonPath.replace(/\.json$/, ".md");
         await render({ input: jsonPath, output: mdPath, head });
       }
     } else {
-      // Stream to stdout - no intermediate files
+      // No output: stream to stdout
       const { transcripts } = await parseToTranscripts({ input, adapter });
       for (let i = 0; i < transcripts.length; i++) {
         if (i > 0) console.log(); // blank line between transcripts
@@ -117,24 +171,29 @@ const defaultCmd = command({
   },
 });
 
+const SUBCOMMANDS = ["convert", "parse", "render", "sync"] as const;
+
 // Main CLI with subcommands
 const cli = subcommands({
   name: "agent-transcripts",
   description: "Transform agent session files to readable transcripts",
   cmds: {
+    convert: convertCmd,
     parse: parseCmd,
     render: renderCmd,
+    sync: syncCmd,
   },
-  // Default command when no subcommand is specified
 });
 
 // Run CLI
 const args = process.argv.slice(2);
 
-// Check if first arg is a subcommand
-if (args[0] === "parse" || args[0] === "render") {
-  run(cli, args);
-} else {
-  // Run default command for full pipeline
-  run(defaultCmd, args);
-}
+// If first arg isn't a subcommand (and isn't a help flag), prepend "convert" as the default
+const isSubcommand =
+  args.length > 0 &&
+  SUBCOMMANDS.includes(args[0] as (typeof SUBCOMMANDS)[number]);
+const isHelpFlag =
+  args.length === 0 || args[0] === "--help" || args[0] === "-h";
+const effectiveArgs = isSubcommand || isHelpFlag ? args : ["convert", ...args];
+
+run(cli, effectiveArgs);

package/src/convert.ts

@@ -0,0 +1,78 @@
+/**
+ * Convert command: full pipeline with provenance tracking.
+ *
+ * When output is a directory, uses the same replace-existing behavior
+ * as sync: scans for existing outputs by provenance and replaces them.
+ */
+
+import { dirname, join, resolve } from "path";
+import { mkdir, stat } from "fs/promises";
+import { parseToTranscripts } from "./parse.ts";
+import { renderTranscript } from "./render.ts";
+import { generateOutputName, type NamingOptions } from "./utils/naming.ts";
+import {
+  findExistingOutputs,
+  deleteExistingOutputs,
+} from "./utils/provenance.ts";
+
+export interface ConvertToDirectoryOptions {
+  input: string;
+  outputDir: string;
+  adapter?: string;
+  head?: string;
+  naming?: NamingOptions;
+}
+
+/**
+ * Convert source file to markdown in output directory.
+ * Uses provenance tracking to replace existing outputs.
+ */
+export async function convertToDirectory(
+  options: ConvertToDirectoryOptions,
+): Promise<void> {
+  const { input, outputDir, adapter, head, naming } = options;
+
+  // Parse input to transcripts
+  const { transcripts, inputPath } = await parseToTranscripts({
+    input,
+    adapter,
+  });
+
+  // Resolve absolute source path for provenance tracking
+  const sourcePath = inputPath === "<stdin>" ? "<stdin>" : resolve(inputPath);
+
+  // Find and delete existing outputs for this source
+  if (sourcePath !== "<stdin>") {
+    const existingOutputs = await findExistingOutputs(outputDir, sourcePath);
+    if (existingOutputs.length > 0) {
+      await deleteExistingOutputs(existingOutputs);
+    }
+  }
+
+  // Generate fresh outputs
+  for (let i = 0; i < transcripts.length; i++) {
+    const transcript = transcripts[i];
+    const suffix = transcripts.length > 1 ? `_${i + 1}` : undefined;
+
+    // Generate descriptive name
+    const baseName = await generateOutputName(
+      transcript,
+      inputPath,
+      naming || {},
+    );
+    const finalName = suffix ? `${baseName}${suffix}` : baseName;
+    const outputPath = join(outputDir, `${finalName}.md`);
+
+    // Ensure output directory exists
+    await mkdir(dirname(outputPath), { recursive: true });
+
+    // Render with provenance front matter
+    const markdown = renderTranscript(transcript, {
+      head,
+      sourcePath: sourcePath !== "<stdin>" ? sourcePath : undefined,
+    });
+    await Bun.write(outputPath, markdown);
+
+    console.error(`Wrote: ${outputPath}`);
+  }
+}

package/src/parse.ts

@@ -9,7 +9,7 @@ import { detectAdapter, getAdapter, listAdapters } from "./adapters/index.ts";
 import { generateOutputName, type NamingOptions } from "./utils/naming.ts";
 
 export interface ParseOptions {
-  input?: string; // file path, undefined for stdin
+  input: string; // file path, or "-" for stdin
   output?: string; // output path/dir
   adapter?: string; // explicit adapter name
   naming?: NamingOptions; // options for output file naming
@@ -19,14 +19,14 @@ export interface ParseOptions {
  * Read input content from file or stdin.
  */
 async function readInput(
-  input?: string,
+  input: string,
 ): Promise<{ content: string; path: string }> {
-  if (input) {
+  if (input !== "-") {
     const content = await Bun.file(input).text();
     return { content, path: input };
   }
 
-  // Read from stdin
+  // Read from stdin (when input is "-")
   const chunks: string[] = [];
   const reader = Bun.stdin.stream().getReader();
 
@@ -115,7 +115,7 @@ export async function parseToTranscripts(
 
   // Determine adapter
   let adapterName = options.adapter;
-  if (!adapterName && options.input) {
+  if (!adapterName && options.input !== "-") {
     adapterName = detectAdapter(options.input);
   }
 

package/src/render.ts

@@ -7,7 +7,7 @@ import { mkdir } from "fs/promises";
 import type { Transcript, Message, ToolCall } from "./types.ts";
 
 export interface RenderOptions {
-  input?: string; // file path, undefined for stdin
+  input: string; // file path, or "-" for stdin
   output?: string; // output path
   head?: string; // render branch ending at this message ID
 }
@@ -16,12 +16,12 @@ export interface RenderOptions {
  * Read transcript from file or stdin.
  */
 async function readTranscript(
-  input?: string,
+  input: string,
 ): Promise<{ transcript: Transcript; path: string }> {
   let content: string;
   let path: string;
 
-  if (input) {
+  if (input !== "-") {
     content = await Bun.file(input).text();
     path = input;
   } else {
@@ -213,15 +213,33 @@ function tracePath(target: string, parents: Map<string, string>): string[] {
   return path;
 }
 
+export interface RenderTranscriptOptions {
+  head?: string; // render branch ending at this message ID
+  sourcePath?: string; // absolute source path for front matter provenance
+}
+
 /**
  * Render transcript to markdown with branch awareness.
  */
 export function renderTranscript(
   transcript: Transcript,
-  head?: string,
+  options: RenderTranscriptOptions | string = {},
 ): string {
+  // Support legacy signature: renderTranscript(transcript, head?: string)
+  const opts: RenderTranscriptOptions =
+    typeof options === "string" ? { head: options } : options;
+  const { head, sourcePath } = opts;
+
   const lines: string[] = [];
 
+  // YAML front matter (for provenance tracking)
+  if (sourcePath) {
+    lines.push("---");
+    lines.push(`source: ${sourcePath}`);
+    lines.push("---");
+    lines.push("");
+  }
+
   // Header
   lines.push("# Transcript");
   lines.push("");

package/src/sync.ts

@@ -0,0 +1,181 @@
+/**
+ * Sync command: batch export sessions to markdown transcripts.
+ *
+ * Discovers session files in source directory, parses them,
+ * and writes rendered markdown to output directory.
+ * Uses LLM-generated descriptive names when API key is available.
+ * Tracks provenance via YAML front matter to correlate updates.
+ */
+
+import { Glob } from "bun";
+import { dirname, join } from "path";
+import { mkdir, stat } from "fs/promises";
+import { getAdapters } from "./adapters/index.ts";
+import type { Adapter } from "./types.ts";
+import { renderTranscript } from "./render.ts";
+import { generateOutputName, type NamingOptions } from "./utils/naming.ts";
+import {
+  scanOutputDirectory,
+  deleteExistingOutputs,
+  hasStaleOutputs,
+} from "./utils/provenance.ts";
+
+export interface SyncOptions {
+  source: string;
+  output: string;
+  force?: boolean;
+  quiet?: boolean;
+  naming?: NamingOptions;
+}
+
+export interface SyncResult {
+  synced: number;
+  skipped: number;
+  errors: number;
+}
+
+interface SessionFile {
+  path: string;
+  relativePath: string;
+  mtime: number;
+  adapter: Adapter;
+}
+
+/**
+ * Discover session files for a specific adapter.
+ */
+async function discoverForAdapter(
+  source: string,
+  adapter: Adapter,
+): Promise<SessionFile[]> {
+  const sessions: SessionFile[] = [];
+
+  for (const pattern of adapter.filePatterns) {
+    const glob = new Glob(`**/${pattern}`);
+
+    for await (const file of glob.scan({ cwd: source, absolute: false })) {
+      const fullPath = join(source, file);
+
+      try {
+        const fileStat = await stat(fullPath);
+        sessions.push({
+          path: fullPath,
+          relativePath: file,
+          mtime: fileStat.mtime.getTime(),
+          adapter,
+        });
+      } catch {
+        // Skip files we can't stat
+      }
+    }
+  }
+
+  return sessions;
+}
+
+/**
+ * Sync session files from source to output directory.
+ */
+export async function sync(options: SyncOptions): Promise<SyncResult> {
+  const { source, output, force = false, quiet = false, naming } = options;
+
+  const result: SyncResult = { synced: 0, skipped: 0, errors: 0 };
+
+  // Scan output directory for existing transcripts (source → output paths)
+  const existingOutputs = await scanOutputDirectory(output);
+  if (!quiet && existingOutputs.size > 0) {
+    const totalFiles = [...existingOutputs.values()].reduce(
+      (sum, paths) => sum + paths.length,
+      0,
+    );
+    console.error(
+      `Found ${totalFiles} existing transcript(s) from ${existingOutputs.size} source(s)`,
+    );
+  }
+
+  // Discover sessions for each adapter
+  const sessions: SessionFile[] = [];
+  for (const adapter of getAdapters()) {
+    const adapterSessions = await discoverForAdapter(source, adapter);
+    sessions.push(...adapterSessions);
+  }
+
+  if (!quiet) {
+    console.error(`Found ${sessions.length} session file(s)`);
+  }
+
+  // Process each session
+  for (const session of sessions) {
+    try {
+      // Read and parse using the adapter that discovered this file
+      const content = await Bun.file(session.path).text();
+      const transcripts = session.adapter.parse(content, session.path);
+
+      // Get all existing outputs for this source
+      const existingPaths = existingOutputs.get(session.path) || [];
+
+      // Check if sync needed (force, count mismatch, or any stale)
+      const needsUpdate =
+        force ||
+        (await hasStaleOutputs(
+          existingPaths,
+          transcripts.length,
+          session.mtime,
+        ));
+      if (!needsUpdate) {
+        if (!quiet) {
+          console.error(`Skip (up to date): ${session.relativePath}`);
+        }
+        result.skipped++;
+        continue;
+      }
+
+      // Delete existing outputs before regenerating
+      await deleteExistingOutputs(existingPaths, quiet);
+
+      // Generate fresh outputs for all transcripts
+      for (let i = 0; i < transcripts.length; i++) {
+        const transcript = transcripts[i];
+        const suffix = transcripts.length > 1 ? `_${i + 1}` : undefined;
+
+        // Generate descriptive name, preserving directory structure
+        const baseName = await generateOutputName(
+          transcript,
+          session.path,
+          naming || {},
+        );
+        const finalName = suffix ? `${baseName}${suffix}` : baseName;
+        const relativeDir = dirname(session.relativePath);
+        const outputPath = join(output, relativeDir, `${finalName}.md`);
+
+        // Ensure output directory exists
+        await mkdir(dirname(outputPath), { recursive: true });
+
+        // Render with provenance front matter and write
+        const markdown = renderTranscript(transcript, {
+          sourcePath: session.path,
+        });
+        await Bun.write(outputPath, markdown);
+
+        if (!quiet) {
+          console.error(`Synced: ${outputPath}`);
+        }
+      }
+
+      result.synced++;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Error: ${session.relativePath}: ${message}`);
+      result.errors++;
+    }
+  }
+
+  // Summary
+  if (!quiet) {
+    console.error(
+      `\nSync complete: ${result.synced} synced, ${result.skipped} skipped, ${result.errors} errors`,
+    );
+  }
+
+  return result;
+}

package/src/types.ts

@@ -70,6 +70,8 @@ export interface ErrorMessage extends BaseMessage {
  */
 export interface Adapter {
   name: string;
+  /** Glob patterns for discovering session files (e.g., ["*.jsonl"]) */
+  filePatterns: string[];
   /** Parse source content into one or more transcripts (split by conversation) */
   parse(content: string, sourcePath: string): Transcript[];
 }

package/src/utils/provenance.ts

@@ -0,0 +1,114 @@
+/**
+ * Provenance tracking utilities.
+ *
+ * Tracks the relationship between source files and output transcripts
+ * via YAML front matter, enabling update-in-place behavior.
+ */
+
+import { Glob } from "bun";
+import { join } from "path";
+import { stat, unlink } from "fs/promises";
+
+/**
+ * Extract source path from YAML front matter.
+ * Returns null if no front matter or no source field.
+ */
+export function extractSourceFromFrontMatter(content: string): string | null {
+  // Match YAML front matter at start of file
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  // Extract source field (simple line-based parsing)
+  const frontMatter = match[1];
+  const sourceLine = frontMatter
+    .split("\n")
+    .find((line) => line.startsWith("source:"));
+  if (!sourceLine) return null;
+
+  return sourceLine.replace(/^source:\s*/, "").trim();
+}
+
+/**
+ * Scan output directory for existing transcripts.
+ * Returns map from absolute source path → all output file paths for that source.
+ */
+export async function scanOutputDirectory(
+  outputDir: string,
+): Promise<Map<string, string[]>> {
+  const sourceToOutputs = new Map<string, string[]>();
+  const glob = new Glob("**/*.md");
+
+  for await (const file of glob.scan({ cwd: outputDir, absolute: false })) {
+    const fullPath = join(outputDir, file);
+    try {
+      const content = await Bun.file(fullPath).text();
+      const sourcePath = extractSourceFromFrontMatter(content);
+      if (sourcePath) {
+        const existing = sourceToOutputs.get(sourcePath) || [];
+        existing.push(fullPath);
+        sourceToOutputs.set(sourcePath, existing);
+      }
+    } catch {
+      // Skip files we can't read
+    }
+  }
+
+  return sourceToOutputs;
+}
+
+/**
+ * Find existing outputs for a specific source path.
+ */
+export async function findExistingOutputs(
+  outputDir: string,
+  sourcePath: string,
+): Promise<string[]> {
+  const allOutputs = await scanOutputDirectory(outputDir);
+  return allOutputs.get(sourcePath) || [];
+}
+
+/**
+ * Delete existing output files, with warnings on failure.
+ */
+export async function deleteExistingOutputs(
+  paths: string[],
+  quiet = false,
+): Promise<void> {
+  for (const oldPath of paths) {
+    try {
+      await unlink(oldPath);
+      if (!quiet) {
+        console.error(`Deleted: ${oldPath}`);
+      }
+    } catch (err) {
+      // Warn but continue - file may already be gone or have permission issues
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`Warning: could not delete ${oldPath}: ${msg}`);
+    }
+  }
+}
+
+/**
+ * Check if any outputs are stale relative to source mtime.
+ */
+export async function hasStaleOutputs(
+  existingOutputs: string[],
+  expectedCount: number,
+  sourceMtime: number,
+): Promise<boolean> {
+  if (existingOutputs.length !== expectedCount) return true;
+
+  for (const outputPath of existingOutputs) {
+    try {
+      const outputStat = await stat(outputPath);
+      if (outputStat.mtime.getTime() < sourceMtime) {
+        return true;
+      }
+    } catch {
+      // Output doesn't exist
+      return true;
+    }
+  }
+
+  return false;
+}