@arcreflex/agent-transcripts 0.1.4 → 0.1.8

package/.github/workflows/publish.yml

@@ -9,10 +9,15 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
+      contents: read
       id-token: write
     steps:
       - uses: actions/checkout@v4
 
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
       - uses: oven-sh/setup-bun@v2
 
       - run: bun install

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

@@ -13,12 +13,16 @@ CLI tool that transforms AI coding agent session files into readable transcripts
 ```
 src/
   cli.ts          # CLI entry point, subcommand routing
-  parse.ts        # Source → intermediate JSON
-  render.ts       # Intermediate JSON → markdown
+  parse.ts        # Source → intermediate format
+  render.ts       # Intermediate format → 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     # Deterministic output file naming
+    provenance.ts # Source tracking via transcripts.json + YAML front matter
+    summary.ts    # Tool call summary extraction
 test/
   fixtures/       # Snapshot test inputs/outputs
   snapshots.test.ts
@@ -32,19 +36,54 @@ bun run test         # snapshot tests
 bun run format       # auto-format
 ```
 
+## CLI Usage
+
+```bash
+# Subcommands (convert is default if omitted)
+agent-transcripts convert <file>              # Parse and render to stdout
+agent-transcripts convert <file> -o <dir>     # Parse and render to directory
+agent-transcripts sync <dir> -o <out>         # Batch sync sessions
+
+# Use "-" for stdin
+cat session.jsonl | agent-transcripts -
+```
+
 ## Architecture
 
-Two-stage pipeline: Parse (source → JSON) → Render (JSON → markdown).
+Two-stage pipeline: Parse (source → intermediate) → Render (intermediate → 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 via `transcripts.json` index + YAML front matter
+- Deterministic naming: `{datetime}-{sessionId}.md`
+- Sync uses sessions-index.json for discovery (claude-code), skipping subagent files
+- Sync uses mtime via index to skip unchanged sources
+
+### transcripts.json
+
+The index file tracks the relationship between source files and outputs:
+
+```typescript
+interface TranscriptsIndex {
+  version: 1;
+  entries: {
+    [outputFilename: string]: {
+      source: string; // absolute path to source
+      sourceMtime: number; // ms since epoch
+      sessionId: string; // full session ID from filename
+      segmentIndex?: number; // for multi-transcript sources (1-indexed)
+      syncedAt: string; // ISO timestamp
+    };
+  };
+}
+```
 
 ## Key Types
 
 - `Transcript`: source info, warnings, messages array
 - `Message`: union of UserMessage | AssistantMessage | SystemMessage | ToolCallGroup | ErrorMessage
-- `Adapter`: name, file patterns, parse function
+- `Adapter`: name, discover function, parse function
 
 ## Adding an Adapter
 

package/package.json

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

package/src/adapters/claude-code.ts

@@ -4,8 +4,12 @@
  * Parses session files from ~/.claude/projects/{project}/sessions/{session}.jsonl
  */
 
+import { Glob } from "bun";
+import { basename, join, relative } from "path";
+import { stat } from "fs/promises";
 import type {
   Adapter,
+  DiscoveredSession,
   Transcript,
   Message,
   Warning,
@@ -13,6 +17,21 @@ import type {
 } from "../types.ts";
 import { extractToolSummary } from "../utils/summary.ts";
 
+/**
+ * Claude Code sessions-index.json structure.
+ */
+interface SessionsIndex {
+  version: number;
+  entries: SessionIndexEntry[];
+}
+
+interface SessionIndexEntry {
+  sessionId: string;
+  fullPath: string;
+  fileMtime: number;
+  isSidechain: boolean;
+}
+
 // Claude Code JSONL record types
 interface ClaudeRecord {
   type: string;
@@ -333,9 +352,86 @@ function transformConversation(
   };
 }
 
+/**
+ * Discover sessions from sessions-index.json.
+ * Returns undefined if index doesn't exist or is invalid.
+ */
+async function discoverFromIndex(
+  source: string,
+): Promise<DiscoveredSession[] | undefined> {
+  const indexPath = join(source, "sessions-index.json");
+
+  try {
+    const content = await Bun.file(indexPath).text();
+    const index: SessionsIndex = JSON.parse(content);
+
+    if (index.version !== 1 || !Array.isArray(index.entries)) {
+      return undefined;
+    }
+
+    const sessions: DiscoveredSession[] = [];
+
+    for (const entry of index.entries) {
+      // Skip sidechains (subagents)
+      if (entry.isSidechain) continue;
+
+      // Verify the file exists and get current mtime
+      try {
+        const fileStat = await stat(entry.fullPath);
+        sessions.push({
+          path: entry.fullPath,
+          relativePath:
+            relative(source, entry.fullPath) || basename(entry.fullPath),
+          mtime: fileStat.mtime.getTime(),
+        });
+      } catch {
+        // Skip files that no longer exist
+      }
+    }
+
+    return sessions;
+  } catch {
+    // Index doesn't exist or is invalid
+    return undefined;
+  }
+}
+
+/**
+ * Discover sessions via glob pattern fallback.
+ */
+async function discoverByGlob(source: string): Promise<DiscoveredSession[]> {
+  const sessions: DiscoveredSession[] = [];
+  const glob = new Glob("**/*.jsonl");
+
+  for await (const file of glob.scan({ cwd: source, absolute: false })) {
+    // Skip files in subagents directories
+    if (file.includes("/subagents/")) continue;
+
+    const fullPath = join(source, file);
+
+    try {
+      const fileStat = await stat(fullPath);
+      sessions.push({
+        path: fullPath,
+        relativePath: file,
+        mtime: fileStat.mtime.getTime(),
+      });
+    } catch {
+      // Skip files we can't stat
+    }
+  }
+
+  return sessions;
+}
+
 export const claudeCodeAdapter: Adapter = {
   name: "claude-code",
-  filePatterns: ["*.jsonl"],
+
+  async discover(source: string): Promise<DiscoveredSession[]> {
+    // Try index-based discovery first, fall back to glob
+    const fromIndex = await discoverFromIndex(source);
+    return fromIndex ?? (await discoverByGlob(source));
+  },
 
   parse(content: string, sourcePath: string): Transcript[] {
     const { records, warnings } = parseJsonl(content);

package/src/cli.ts

@@ -12,25 +12,23 @@ import {
   positional,
   flag,
 } from "cmd-ts";
-import { parse, parseToTranscripts } from "./parse.ts";
-import { render, renderTranscript } from "./render.ts";
+import { parseToTranscripts } from "./parse.ts";
+import { renderTranscript } from "./render.ts";
 import { sync } from "./sync.ts";
-
-// Read OpenRouter API key from environment for LLM-based slug generation
-const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY;
+import { convertToDirectory } from "./convert.ts";
 
 // 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({
   type: optional(string),
   long: "output",
   short: "o",
-  description: "Output path (prints to stdout if not specified)",
+  description: "Output directory (prints to stdout if not specified)",
 });
 
 const adapterOpt = option({
@@ -46,46 +44,6 @@ const headOpt = option({
   description: "Render branch ending at this message ID (default: latest)",
 });
 
-// Parse subcommand
-const parseCmd = command({
-  name: "parse",
-  description: "Parse source format to intermediate JSON",
-  args: {
-    input: inputArg,
-    output: outputOpt,
-    adapter: adapterOpt,
-  },
-  async handler({ input, output, adapter }) {
-    const naming = OPENROUTER_API_KEY
-      ? { apiKey: OPENROUTER_API_KEY }
-      : undefined;
-
-    if (output) {
-      await parse({ input, output, adapter, naming });
-    } else {
-      // Print JSONL to stdout (one transcript per line)
-      const { transcripts } = await parseToTranscripts({ input, adapter });
-      for (const transcript of transcripts) {
-        console.log(JSON.stringify(transcript));
-      }
-    }
-  },
-});
-
-// Render subcommand
-const renderCmd = command({
-  name: "render",
-  description: "Render intermediate JSON to markdown",
-  args: {
-    input: inputArg,
-    output: outputOpt,
-    head: headOpt,
-  },
-  async handler({ input, output, head }) {
-    await render({ input, output, head });
-  },
-});
-
 // Sync subcommand
 const syncCmd = command({
   name: "sync",
@@ -100,7 +58,7 @@ const syncCmd = command({
       type: string,
       long: "output",
       short: "o",
-      description: "Output directory (mirrors source structure)",
+      description: "Output directory for transcripts",
     }),
     force: flag({
       long: "force",
@@ -118,10 +76,17 @@ const syncCmd = command({
   },
 });
 
-// Default command: full pipeline (parse → render)
-const defaultCmd = command({
-  name: "agent-transcripts",
-  description: "Transform agent session files to readable transcripts",
+/**
+ * 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,
@@ -129,19 +94,22 @@ const defaultCmd = command({
     head: headOpt,
   },
   async handler({ input, output, adapter, head }) {
-    const naming = OPENROUTER_API_KEY
-      ? { apiKey: OPENROUTER_API_KEY }
-      : undefined;
-
-    if (output) {
-      // Write intermediate JSON and markdown files
-      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 });
-      }
+    if (output && isDirectoryOutput(output)) {
+      // Directory output: use provenance tracking
+      await convertToDirectory({
+        input,
+        outputDir: output,
+        adapter,
+        head,
+      });
+    } else if (output) {
+      // Explicit file output: not supported anymore (use directory)
+      console.error(
+        "Error: Explicit file output not supported. Use a directory path instead.",
+      );
+      process.exit(1);
     } 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
@@ -151,25 +119,27 @@ const defaultCmd = command({
   },
 });
 
+const SUBCOMMANDS = ["convert", "sync"] as const;
+
 // Main CLI with subcommands
 const cli = subcommands({
   name: "agent-transcripts",
   description: "Transform agent session files to readable transcripts",
   cmds: {
-    parse: parseCmd,
-    render: renderCmd,
+    convert: convertCmd,
     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" || args[0] === "sync") {
-  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,126 @@
+/**
+ * Convert command: full pipeline with provenance tracking.
+ *
+ * When output is a directory, uses provenance tracking via transcripts.json
+ * index to manage output files.
+ */
+
+import { join } from "path";
+import { mkdir } from "fs/promises";
+import { parseToTranscripts } from "./parse.ts";
+import { renderTranscript } from "./render.ts";
+import { generateOutputName, extractSessionId } from "./utils/naming.ts";
+import {
+  loadIndex,
+  saveIndex,
+  removeEntriesForSource,
+  restoreEntries,
+  deleteOutputFiles,
+  setEntry,
+  normalizeSourcePath,
+} from "./utils/provenance.ts";
+
+export interface ConvertToDirectoryOptions {
+  input: string;
+  outputDir: string;
+  adapter?: string;
+  head?: string;
+}
+
+/**
+ * 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 } = options;
+
+  // Ensure output directory exists
+  await mkdir(outputDir, { recursive: true });
+
+  // Parse input to transcripts
+  const { transcripts, inputPath } = await parseToTranscripts({
+    input,
+    adapter,
+  });
+
+  // Normalize source path for consistent index keys
+  const sourcePath = normalizeSourcePath(inputPath);
+
+  // Load index and handle existing outputs
+  const index = await loadIndex(outputDir);
+
+  // Remove old entries (save for restoration on error)
+  const removedEntries =
+    sourcePath !== "<stdin>" ? removeEntriesForSource(index, sourcePath) : [];
+
+  // Get source mtime for index entry
+  let sourceMtime = Date.now();
+  if (sourcePath !== "<stdin>") {
+    try {
+      const stat = await Bun.file(sourcePath).stat();
+      if (stat) {
+        sourceMtime = stat.mtime.getTime();
+      }
+    } catch {
+      // Use current time as fallback
+    }
+  }
+
+  const sessionId = extractSessionId(inputPath);
+  const newOutputs: string[] = [];
+
+  try {
+    // Generate fresh outputs
+    for (let i = 0; i < transcripts.length; i++) {
+      const transcript = transcripts[i];
+      const segmentIndex = transcripts.length > 1 ? i + 1 : undefined;
+
+      // Generate deterministic name
+      const baseName = generateOutputName(transcript, inputPath);
+      const suffix = segmentIndex ? `_${segmentIndex}` : "";
+      const relativePath = `${baseName}${suffix}.md`;
+      const outputPath = join(outputDir, relativePath);
+
+      // Render with provenance front matter
+      const markdown = renderTranscript(transcript, {
+        head,
+        sourcePath: sourcePath !== "<stdin>" ? sourcePath : undefined,
+      });
+      await Bun.write(outputPath, markdown);
+      newOutputs.push(relativePath);
+
+      // Update index (only for non-stdin sources)
+      if (sourcePath !== "<stdin>") {
+        setEntry(index, relativePath, {
+          source: sourcePath,
+          sourceMtime,
+          sessionId,
+          segmentIndex,
+          syncedAt: new Date().toISOString(),
+        });
+      }
+
+      console.error(`Wrote: ${outputPath}`);
+    }
+
+    // Success: delete old output files (after new ones are written)
+    const oldFilenames = removedEntries.map((e) => e.filename);
+    const toDelete = oldFilenames.filter((f) => !newOutputs.includes(f));
+    if (toDelete.length > 0) {
+      await deleteOutputFiles(outputDir, toDelete);
+    }
+  } catch (error) {
+    // Clean up any newly written files before restoring old entries
+    if (newOutputs.length > 0) {
+      await deleteOutputFiles(outputDir, newOutputs);
+    }
+    // Restore old entries on error to preserve provenance
+    restoreEntries(index, removedEntries);
+    throw error;
+  }
+
+  // Save index
+  await saveIndex(outputDir, index);
+}

package/src/parse.ts

@@ -1,32 +1,32 @@
 /**
- * Parse command: source format → intermediate JSON
+ * Parse: source format → intermediate transcript format
  */
 
-import { dirname, join } from "path";
-import { mkdir } from "fs/promises";
 import type { Transcript } from "./types.ts";
 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
-  output?: string; // output path/dir
+  input: string; // file path, or "-" for stdin
   adapter?: string; // explicit adapter name
-  naming?: NamingOptions; // options for output file naming
+}
+
+export interface ParseResult {
+  transcripts: Transcript[];
+  inputPath: string;
 }
 
 /**
  * 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();
 
@@ -40,73 +40,7 @@ async function readInput(
 }
 
 /**
- * Determine output file paths for transcripts.
- */
-async function getOutputPaths(
-  transcripts: Transcript[],
-  inputPath: string,
-  outputOption?: string,
-  namingOptions?: NamingOptions,
-): Promise<string[]> {
-  // Determine output directory
-  let outputDir: string;
-  let explicitBaseName: string | undefined;
-
-  if (outputOption) {
-    // If output looks like a file (has extension), use its directory and name
-    if (outputOption.match(/\.\w+$/)) {
-      outputDir = dirname(outputOption);
-      explicitBaseName = outputOption
-        .split("/")
-        .pop()!
-        .replace(/\.\w+$/, "");
-    } else {
-      outputDir = outputOption;
-    }
-  } else {
-    outputDir = process.cwd();
-  }
-
-  // Generate paths with descriptive names
-  const paths: string[] = [];
-
-  for (let i = 0; i < transcripts.length; i++) {
-    let baseName: string;
-
-    if (explicitBaseName) {
-      // User provided explicit filename
-      baseName = explicitBaseName;
-    } else {
-      // Generate descriptive name
-      baseName = await generateOutputName(
-        transcripts[i],
-        inputPath,
-        namingOptions || {},
-      );
-    }
-
-    // Add suffix for multiple transcripts
-    if (transcripts.length > 1) {
-      baseName = `${baseName}_${i + 1}`;
-    }
-
-    paths.push(join(outputDir, `${baseName}.json`));
-  }
-
-  return paths;
-}
-
-export interface ParseResult {
-  transcripts: Transcript[];
-  inputPath: string;
-}
-
-export interface ParseAndWriteResult extends ParseResult {
-  outputPaths: string[];
-}
-
-/**
- * Parse source file(s) to transcripts (no file I/O beyond reading input).
+ * Parse source file(s) to transcripts.
  */
 export async function parseToTranscripts(
   options: ParseOptions,
@@ -115,7 +49,7 @@ export async function parseToTranscripts(
 
   // Determine adapter
   let adapterName = options.adapter;
-  if (!adapterName && options.input) {
+  if (!adapterName && options.input !== "-") {
     adapterName = detectAdapter(options.input);
   }
 
@@ -135,31 +69,3 @@ export async function parseToTranscripts(
   const transcripts = adapter.parse(content, inputPath);
   return { transcripts, inputPath };
 }
-
-/**
- * Parse source file(s) to intermediate JSON and write to files.
- */
-export async function parse(
-  options: ParseOptions,
-): Promise<ParseAndWriteResult> {
-  const { transcripts, inputPath } = await parseToTranscripts(options);
-
-  // Write output files
-  const outputPaths = await getOutputPaths(
-    transcripts,
-    inputPath,
-    options.output,
-    options.naming,
-  );
-
-  for (let i = 0; i < transcripts.length; i++) {
-    const json = JSON.stringify(transcripts[i], null, 2);
-    // Ensure directory exists
-    const dir = dirname(outputPaths[i]);
-    await mkdir(dir, { recursive: true });
-    await Bun.write(outputPaths[i], json);
-    console.error(`Wrote: ${outputPaths[i]}`);
-  }
-
-  return { transcripts, inputPath, outputPaths };
-}