@arcreflex/agent-transcripts 0.1.5 → 0.1.9

package/src/cli.ts

@@ -7,18 +7,28 @@ import {
   subcommands,
   run,
   string,
+  number,
   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 { parseToTranscripts } from "./parse.ts";
+import { renderTranscript } from "./render.ts";
+import { sync, type OutputFormat } 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;
+import { generateTitles } from "./title.ts";
+import { serve } from "./serve.ts";
+
+// Custom type for format option
+const formatType = {
+  async from(value: string): Promise<OutputFormat> {
+    if (value !== "md" && value !== "html") {
+      throw new Error(`Invalid format: ${value}. Must be "md" or "html".`);
+    }
+    return value;
+  },
+};
 
 // Shared options
 const inputArg = positional({
@@ -31,7 +41,7 @@ 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({
@@ -47,50 +57,10 @@ 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",
-  description: "Sync session files to markdown transcripts",
+  description: "Sync session files to transcripts (markdown or HTML)",
   args: {
     source: positional({
       type: string,
@@ -103,6 +73,15 @@ const syncCmd = command({
       short: "o",
       description: "Output directory for transcripts",
     }),
+    format: option({
+      type: optional(formatType),
+      long: "format",
+      description: "Output format: md (default) or html",
+    }),
+    noTitle: flag({
+      long: "no-title",
+      description: "Skip LLM title generation (for HTML format)",
+    }),
     force: flag({
       long: "force",
       short: "f",
@@ -114,11 +93,65 @@ const syncCmd = command({
       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 });
+  async handler({ source, output, format, noTitle, force, quiet }) {
+    await sync({ source, output, format, noTitle, force, quiet });
+  },
+});
+
+// Title subcommand
+const titleCmd = command({
+  name: "title",
+  description: "Generate LLM titles for transcripts.json entries",
+  args: {
+    output: positional({
+      type: string,
+      displayName: "output",
+      description: "Output directory containing transcripts.json",
+    }),
+    force: flag({
+      long: "force",
+      short: "f",
+      description: "Regenerate all titles, not just missing ones",
+    }),
+    quiet: flag({
+      long: "quiet",
+      short: "q",
+      description: "Suppress progress output",
+    }),
+  },
+  async handler({ output, force, quiet }) {
+    await generateTitles({ outputDir: output, force, quiet });
+  },
+});
+
+// Serve subcommand
+const serveCmd = command({
+  name: "serve",
+  description: "Serve transcripts via HTTP (dynamic rendering with caching)",
+  args: {
+    source: positional({
+      type: string,
+      displayName: "source",
+      description: "Source directory to scan for session files",
+    }),
+    port: option({
+      type: optional(number),
+      long: "port",
+      short: "p",
+      description: "Port to listen on (default: 3000)",
+    }),
+    quiet: flag({
+      long: "quiet",
+      short: "q",
+      description: "Suppress request logging",
+    }),
+    noCache: flag({
+      long: "no-cache",
+      description: "Bypass HTML cache (for development)",
+    }),
+  },
+  async handler({ source, port, quiet, noCache }) {
+    await serve({ source, port: port ?? 3000, quiet, noCache });
   },
 });
 
@@ -140,26 +173,20 @@ const convertCmd = command({
     head: headOpt,
   },
   async handler({ input, output, adapter, head }) {
-    const naming = OPENROUTER_API_KEY
-      ? { apiKey: OPENROUTER_API_KEY }
-      : undefined;
-
     if (output && isDirectoryOutput(output)) {
-      // Directory output: use sync-like behavior with provenance tracking
+      // Directory output: use 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 });
-      }
+      // 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 {
       // No output: stream to stdout
       const { transcripts } = await parseToTranscripts({ input, adapter });
@@ -171,7 +198,7 @@ const convertCmd = command({
   },
 });
 
-const SUBCOMMANDS = ["convert", "parse", "render", "sync"] as const;
+const SUBCOMMANDS = ["convert", "sync", "title", "serve"] as const;
 
 // Main CLI with subcommands
 const cli = subcommands({
@@ -179,9 +206,9 @@ const cli = subcommands({
   description: "Transform agent session files to readable transcripts",
   cmds: {
     convert: convertCmd,
-    parse: parseCmd,
-    render: renderCmd,
     sync: syncCmd,
+    title: titleCmd,
+    serve: serveCmd,
   },
 });
 

package/src/convert.ts

@@ -1,18 +1,24 @@
 /**
  * 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.
+ * When output is a directory, uses provenance tracking via transcripts.json
+ * index to manage output files.
  */
 
-import { dirname, join, resolve } from "path";
-import { mkdir, stat } from "fs/promises";
+import { join } from "path";
+import { mkdir } from "fs/promises";
 import { parseToTranscripts } from "./parse.ts";
 import { renderTranscript } from "./render.ts";
-import { generateOutputName, type NamingOptions } from "./utils/naming.ts";
+import { generateOutputName, extractSessionId } from "./utils/naming.ts";
 import {
-  findExistingOutputs,
-  deleteExistingOutputs,
+  loadIndex,
+  saveIndex,
+  removeEntriesForSource,
+  restoreEntries,
+  deleteOutputFiles,
+  setEntry,
+  normalizeSourcePath,
+  extractFirstUserMessage,
 } from "./utils/provenance.ts";
 
 export interface ConvertToDirectoryOptions {
@@ -20,7 +26,6 @@ export interface ConvertToDirectoryOptions {
   outputDir: string;
   adapter?: string;
   head?: string;
-  naming?: NamingOptions;
 }
 
 /**
@@ -30,7 +35,10 @@ export interface ConvertToDirectoryOptions {
 export async function convertToDirectory(
   options: ConvertToDirectoryOptions,
 ): Promise<void> {
-  const { input, outputDir, adapter, head, naming } = options;
+  const { input, outputDir, adapter, head } = options;
+
+  // Ensure output directory exists
+  await mkdir(outputDir, { recursive: true });
 
   // Parse input to transcripts
   const { transcripts, inputPath } = await parseToTranscripts({
@@ -38,41 +46,73 @@ export async function convertToDirectory(
     adapter,
   });
 
-  // Resolve absolute source path for provenance tracking
-  const sourcePath = inputPath === "<stdin>" ? "<stdin>" : resolve(inputPath);
+  // 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) : [];
+
+  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);
 
-  // Find and delete existing outputs for this source
-  if (sourcePath !== "<stdin>") {
-    const existingOutputs = await findExistingOutputs(outputDir, sourcePath);
-    if (existingOutputs.length > 0) {
-      await deleteExistingOutputs(existingOutputs);
+      // 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,
+          sessionId,
+          segmentIndex,
+          syncedAt: new Date().toISOString(),
+          firstUserMessage: extractFirstUserMessage(transcript),
+          messageCount: transcript.metadata.messageCount,
+          startTime: transcript.metadata.startTime,
+          endTime: transcript.metadata.endTime,
+          cwd: transcript.metadata.cwd,
+        });
+      }
+
+      console.error(`Wrote: ${outputPath}`);
     }
-  }
 
-  // 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}`);
+    // 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,18 +1,18 @@
 /**
- * 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, or "-" for stdin
-  output?: string; // output path/dir
   adapter?: string; // explicit adapter name
-  naming?: NamingOptions; // options for output file naming
+}
+
+export interface ParseResult {
+  transcripts: Transcript[];
+  inputPath: string;
 }
 
 /**
@@ -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,
@@ -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 };
-}