@arcreflex/agent-transcripts 0.1.2 → 0.1.4

package/README.md

@@ -15,6 +15,7 @@ src/
   cli.ts          # CLI entry point, subcommand routing
   parse.ts        # Source → intermediate JSON
   render.ts       # Intermediate JSON → markdown
+  sync.ts         # Batch sync sessions → markdown
   types.ts        # Core types (Transcript, Message, Adapter)
   adapters/       # Source format adapters (currently: claude-code)
   utils/          # Helpers (summary extraction)
@@ -43,7 +44,7 @@ Two-stage pipeline: Parse (source → JSON) → Render (JSON → markdown).
 
 - `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.2",
+  "version": "0.1.4",
   "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,9 +10,14 @@ 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";
+
+// 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({
@@ -51,8 +56,12 @@ const parseCmd = command({
     adapter: adapterOpt,
   },
   async handler({ input, output, adapter }) {
+    const naming = OPENROUTER_API_KEY
+      ? { apiKey: OPENROUTER_API_KEY }
+      : undefined;
+
     if (output) {
-      await parse({ input, output, adapter });
+      await parse({ input, output, adapter, naming });
     } else {
       // Print JSONL to stdout (one transcript per line)
       const { transcripts } = await parseToTranscripts({ input, adapter });
@@ -77,6 +86,38 @@ const renderCmd = command({
   },
 });
 
+// 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 (mirrors source structure)",
+    }),
+    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 }) {
+    await sync({ source, output, force, quiet });
+  },
+});
+
 // Default command: full pipeline (parse → render)
 const defaultCmd = command({
   name: "agent-transcripts",
@@ -88,9 +129,13 @@ 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 });
+      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 });
@@ -113,6 +158,7 @@ const cli = subcommands({
   cmds: {
     parse: parseCmd,
     render: renderCmd,
+    sync: syncCmd,
   },
   // Default command when no subcommand is specified
 });
@@ -121,7 +167,7 @@ const cli = subcommands({
 const args = process.argv.slice(2);
 
 // Check if first arg is a subcommand
-if (args[0] === "parse" || args[0] === "render") {
+if (args[0] === "parse" || args[0] === "render" || args[0] === "sync") {
   run(cli, args);
 } else {
   // Run default command for full pipeline

package/src/parse.ts

@@ -2,15 +2,17 @@
  * Parse command: source format → intermediate JSON
  */
 
-import { basename, dirname, join } from "path";
+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
   adapter?: string; // explicit adapter name
+  naming?: NamingOptions; // options for output file naming
 }
 
 /**
@@ -40,27 +42,24 @@ async function readInput(
 /**
  * Determine output file paths for transcripts.
  */
-function getOutputPaths(
+async function getOutputPaths(
   transcripts: Transcript[],
   inputPath: string,
   outputOption?: string,
-): string[] {
-  // Determine base name
-  let baseName: string;
-  if (inputPath === "<stdin>") {
-    baseName = "transcript";
-  } else {
-    const name = basename(inputPath);
-    baseName = name.replace(/\.jsonl?$/, "");
-  }
-
+  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
+    // If output looks like a file (has extension), use its directory and name
     if (outputOption.match(/\.\w+$/)) {
       outputDir = dirname(outputOption);
-      baseName = basename(outputOption).replace(/\.\w+$/, "");
+      explicitBaseName = outputOption
+        .split("/")
+        .pop()!
+        .replace(/\.\w+$/, "");
     } else {
       outputDir = outputOption;
     }
@@ -68,14 +67,33 @@ function getOutputPaths(
     outputDir = process.cwd();
   }
 
-  // Generate paths
-  if (transcripts.length === 1) {
-    return [join(outputDir, `${baseName}.json`)];
+  // 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 transcripts.map((_, i) =>
-    join(outputDir, `${baseName}_${i + 1}.json`),
-  );
+  return paths;
 }
 
 export interface ParseResult {
@@ -127,7 +145,12 @@ export async function parse(
   const { transcripts, inputPath } = await parseToTranscripts(options);
 
   // Write output files
-  const outputPaths = getOutputPaths(transcripts, inputPath, options.output);
+  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);

package/src/sync.ts

@@ -0,0 +1,175 @@
+/**
+ * Sync command: batch export sessions to markdown transcripts.
+ *
+ * Discovers session files in source directory, parses them,
+ * and writes rendered markdown to output directory.
+ * Output structure mirrors source structure with extension changed.
+ */
+
+import { Glob } from "bun";
+import { dirname, join, relative } 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";
+
+export interface SyncOptions {
+  source: string;
+  output: string;
+  force?: boolean;
+  quiet?: boolean;
+}
+
+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;
+}
+
+/**
+ * Compute output path for a session file.
+ * Mirrors input structure, changing extension to .md.
+ */
+function computeOutputPath(
+  relativePath: string,
+  outputDir: string,
+  suffix?: string,
+): string {
+  // Replace extension with .md
+  const mdPath = relativePath.replace(/\.[^.]+$/, ".md");
+  // Add suffix if provided (for multiple transcripts from same file)
+  const finalPath = suffix ? mdPath.replace(/\.md$/, `${suffix}.md`) : mdPath;
+  return join(outputDir, finalPath);
+}
+
+/**
+ * Check if output file needs to be re-rendered based on mtime.
+ */
+async function needsSync(
+  outputPath: string,
+  sourceMtime: number,
+  force: boolean,
+): Promise<boolean> {
+  if (force) return true;
+
+  try {
+    const outputStat = await stat(outputPath);
+    return outputStat.mtime.getTime() < sourceMtime;
+  } catch {
+    // Output doesn't exist, needs sync
+    return true;
+  }
+}
+
+/**
+ * Sync session files from source to output directory.
+ */
+export async function sync(options: SyncOptions): Promise<SyncResult> {
+  const { source, output, force = false, quiet = false } = options;
+
+  const result: SyncResult = { synced: 0, skipped: 0, errors: 0 };
+
+  // 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);
+
+      // Process each transcript (usually just one per file)
+      for (let i = 0; i < transcripts.length; i++) {
+        const transcript = transcripts[i];
+        const suffix = transcripts.length > 1 ? `_${i + 1}` : undefined;
+        const outputPath = computeOutputPath(
+          session.relativePath,
+          output,
+          suffix,
+        );
+
+        // Check if sync needed
+        if (!(await needsSync(outputPath, session.mtime, force))) {
+          if (!quiet) {
+            console.error(`Skip (up to date): ${outputPath}`);
+          }
+          result.skipped++;
+          continue;
+        }
+
+        // Ensure output directory exists
+        await mkdir(dirname(outputPath), { recursive: true });
+
+        // Render and write
+        const markdown = renderTranscript(transcript);
+        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/naming.ts

@@ -0,0 +1,173 @@
+/**
+ * Output file naming utilities.
+ *
+ * Generates descriptive filenames for transcripts:
+ * - With OpenRouter API key: yyyy-mm-dd-{llm-generated-slug}.{ext}
+ * - Without: yyyy-mm-dd-{input-filename-prefix}.{ext}
+ */
+
+import type { Transcript, UserMessage } from "../types.ts";
+import { basename } from "path";
+
+export interface NamingOptions {
+  apiKey?: string; // OpenRouter API key
+  model?: string; // Default: google/gemini-2.0-flash-001
+}
+
+const DEFAULT_MODEL = "google/gemini-2.0-flash-001";
+const SLUG_MAX_LENGTH = 40;
+
+/**
+ * Extract date from transcript's first message timestamp.
+ */
+function extractDate(transcript: Transcript): string {
+  const firstMessage = transcript.messages[0];
+  if (firstMessage?.timestamp) {
+    const date = new Date(firstMessage.timestamp);
+    if (!isNaN(date.getTime())) {
+      return date.toISOString().slice(0, 10); // yyyy-mm-dd
+    }
+  }
+  // Fallback to current date
+  return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * Extract context from transcript for LLM summarization.
+ * Uses first few user messages, truncated.
+ */
+function extractContext(transcript: Transcript): string {
+  const userMessages = transcript.messages.filter(
+    (m): m is UserMessage => m.type === "user",
+  );
+
+  const chunks: string[] = [];
+  let totalLength = 0;
+  const maxLength = 500;
+
+  for (const msg of userMessages.slice(0, 3)) {
+    const content = msg.content.slice(0, 200);
+    if (totalLength + content.length > maxLength) break;
+    chunks.push(content);
+    totalLength += content.length;
+  }
+
+  return chunks.join("\n\n");
+}
+
+/**
+ * Sanitize a string into a valid URL slug.
+ */
+function sanitizeSlug(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "") // remove special chars
+    .replace(/\s+/g, "-") // spaces to hyphens
+    .replace(/-+/g, "-") // collapse multiple hyphens
+    .replace(/^-|-$/g, "") // trim leading/trailing hyphens
+    .slice(0, SLUG_MAX_LENGTH);
+}
+
+/**
+ * Generate slug via OpenRouter API.
+ */
+async function generateSlugViaLLM(
+  context: string,
+  options: NamingOptions,
+): Promise<string | null> {
+  const { apiKey, model = DEFAULT_MODEL } = options;
+  if (!apiKey || !context.trim()) return null;
+
+  try {
+    const response = await fetch(
+      "https://openrouter.ai/api/v1/chat/completions",
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model,
+          messages: [
+            {
+              role: "user",
+              content: `Generate a 2-4 word URL slug (lowercase, hyphenated) summarizing this conversation topic. Reply with ONLY the slug, nothing else.\n\n${context}`,
+            },
+          ],
+          max_tokens: 20,
+        }),
+      },
+    );
+
+    if (!response.ok) {
+      console.error(
+        `OpenRouter API error: ${response.status} ${response.statusText}`,
+      );
+      return null;
+    }
+
+    const data = (await response.json()) as {
+      choices?: Array<{ message?: { content?: string } }>;
+    };
+    const content = data.choices?.[0]?.message?.content?.trim();
+
+    if (!content) return null;
+
+    const slug = sanitizeSlug(content);
+    return slug || null;
+  } catch (error) {
+    console.error(
+      `OpenRouter API call failed: ${error instanceof Error ? error.message : error}`,
+    );
+    return null;
+  }
+}
+
+/**
+ * Generate fallback slug from input filename.
+ */
+function generateFallbackSlug(inputPath: string): string {
+  return extractFileId(inputPath, 8) || "transcript";
+}
+
+/**
+ * Extract a short identifier from the input filename.
+ * Used as a suffix for traceability back to source.
+ */
+function extractFileId(inputPath: string, length = 6): string {
+  if (inputPath === "<stdin>") {
+    return "";
+  }
+
+  const name = basename(inputPath);
+  const base = name.replace(/\.jsonl?$/, "");
+  // Take first N chars, sanitize, and clean up any trailing hyphens
+  return sanitizeSlug(base.slice(0, length)).replace(/-+$/, "");
+}
+
+/**
+ * Generate output base name for a transcript.
+ * Returns string like "2024-01-15-implement-auth-flow-abc123"
+ */
+export async function generateOutputName(
+  transcript: Transcript,
+  inputPath: string,
+  options: NamingOptions = {},
+): Promise<string> {
+  const date = extractDate(transcript);
+  const fileId = extractFileId(inputPath);
+
+  // Try LLM-generated slug if API key available
+  if (options.apiKey) {
+    const context = extractContext(transcript);
+    const slug = await generateSlugViaLLM(context, options);
+    if (slug) {
+      return fileId ? `${date}-${slug}-${fileId}` : `${date}-${slug}`;
+    }
+  }
+
+  // Fallback to input filename prefix (no need for fileId suffix, it's already the slug)
+  const slug = generateFallbackSlug(inputPath);
+  return `${date}-${slug}`;
+}