teleportation-cli 1.1.5 → 1.2.1

package/lib/teleport/exporters/claude-exporter.js

@@ -0,0 +1,302 @@
+/**
+ * Claude Code Transcript Exporter
+ *
+ * Converts Timeline API events to Claude Code's native JSONL format.
+ * Claude Code stores transcripts in ~/.claude/projects/{slug}/{sessionId}.jsonl
+ *
+ * Claude JSONL Format:
+ * - Each line is a valid JSON object
+ * - Human messages: {type: "human", content: [{type: "text", text: "..."}]}
+ * - Assistant messages: {type: "assistant", content: [{type: "text", text: "..."}, {type: "tool_use", ...}]}
+ * - Tool results are embedded in subsequent human messages
+ *
+ * @module lib/teleport/exporters/claude-exporter
+ */
+
+import { homedir } from 'os';
+import { join } from 'path';
+import { TranscriptExporter } from './interface.js';
+
+/**
+ * Maps Timeline event types to Claude message types
+ * @type {Object.<string, string>}
+ */
+const EVENT_TYPE_MAP = {
+  user_message: 'human',
+  assistant_response: 'assistant',
+  tool_use: 'assistant',
+  tool_result: 'human',
+  thinking: 'assistant',
+  compact_summary: 'assistant',
+};
+
+/**
+ * Exporter for Claude Code's native JSONL transcript format.
+ *
+ * @extends TranscriptExporter
+ */
+export class ClaudeTranscriptExporter extends TranscriptExporter {
+  name = 'claude-code';
+  displayName = 'Claude Code';
+
+  /**
+   * Export timeline events to Claude Code JSONL format.
+   *
+   * @param {import('./interface.js').TimelineEvent[]} events - Timeline events
+   * @param {import('./interface.js').ExportOptions} [options={}] - Export options
+   * @returns {Promise<string>} JSONL content (newline-separated JSON objects)
+   */
+  async export(events, options = {}) {
+    const { includeThinking = true } = options;
+
+    // Validate and sort events
+    this.validateEvents(events);
+
+    if (events.length === 0) {
+      return '';
+    }
+
+    const sorted = this.sortEvents(events);
+    const messages = [];
+
+    // Group events into messages
+    // Claude expects alternating human/assistant messages
+    let pendingToolResults = [];
+
+    for (const event of sorted) {
+      const claudeMessage = this._convertEvent(event, { includeThinking });
+
+      if (!claudeMessage) {
+        continue;
+      }
+
+      // Tool results get batched and added to the next human message
+      if (event.event_type === 'tool_result') {
+        pendingToolResults.push(claudeMessage.content[0]);
+        continue;
+      }
+
+      // If we have pending tool results and this is a human message, add them
+      if (claudeMessage.type === 'human' && pendingToolResults.length > 0) {
+        claudeMessage.content = [...pendingToolResults, ...claudeMessage.content];
+        pendingToolResults = [];
+      }
+
+      // If we have pending tool results and this is an assistant message,
+      // create a synthetic human message with just the tool results first
+      if (claudeMessage.type === 'assistant' && pendingToolResults.length > 0) {
+        messages.push({
+          type: 'human',
+          content: pendingToolResults,
+        });
+        pendingToolResults = [];
+      }
+
+      messages.push(claudeMessage);
+    }
+
+    // If we still have pending tool results, add them as a final human message
+    if (pendingToolResults.length > 0) {
+      messages.push({
+        type: 'human',
+        content: pendingToolResults,
+      });
+    }
+
+    // Convert to JSONL (each message on its own line)
+    return messages.map((msg) => JSON.stringify(msg)).join('\n') + '\n';
+  }
+
+  /**
+   * Get the Claude Code transcript path.
+   *
+   * @param {string} sessionId - Session identifier (UUID)
+   * @param {string} projectSlug - Project slug from Claude Code
+   * @returns {string} Path like ~/.claude/projects/{slug}/{sessionId}.jsonl
+   */
+  getTranscriptPath(sessionId, projectSlug) {
+    const home = homedir();
+    const slug = this._normalizeSlug(projectSlug);
+    return join(home, '.claude', 'projects', slug, `${sessionId}.jsonl`);
+  }
+
+  /**
+   * Convert a timeline event to Claude message format.
+   *
+   * @private
+   * @param {import('./interface.js').TimelineEvent} event - Timeline event
+   * @param {Object} options - Conversion options
+   * @param {boolean} options.includeThinking - Include thinking blocks
+   * @returns {Object|null} Claude message object or null if skipped
+   */
+  _convertEvent(event, { includeThinking }) {
+    const { event_type, data } = event;
+
+    switch (event_type) {
+      case 'user_message':
+        return this._convertUserMessage(data);
+
+      case 'assistant_response':
+        return this._convertAssistantResponse(data);
+
+      case 'tool_use':
+        return this._convertToolUse(data);
+
+      case 'tool_result':
+        return this._convertToolResult(data);
+
+      case 'thinking':
+        if (!includeThinking) return null;
+        return this._convertThinking(data);
+
+      case 'compact_summary':
+        return this._convertCompactSummary(data);
+
+      default:
+        // Unknown event type - skip silently
+        return null;
+    }
+  }
+
+  /**
+   * Convert user_message event to Claude human message.
+   *
+   * @private
+   * @param {Object} data - Event data
+   * @returns {Object} Claude human message
+   */
+  _convertUserMessage(data) {
+    const content = data.content || data.text || data.message || '';
+    return {
+      type: 'human',
+      content: [{ type: 'text', text: String(content) }],
+    };
+  }
+
+  /**
+   * Convert assistant_response event to Claude assistant message.
+   *
+   * @private
+   * @param {Object} data - Event data
+   * @returns {Object} Claude assistant message
+   */
+  _convertAssistantResponse(data) {
+    const content = data.content || data.message || data.text || data.response || '';
+    return {
+      type: 'assistant',
+      content: [{ type: 'text', text: String(content) }],
+    };
+  }
+
+  /**
+   * Convert tool_use event to Claude assistant message with tool_use content.
+   *
+   * @private
+   * @param {Object} data - Event data
+   * @returns {Object} Claude assistant message with tool_use
+   */
+  _convertToolUse(data) {
+    const toolUse = {
+      type: 'tool_use',
+      id: data.tool_id || data.id || `tool_${Date.now()}`,
+      name: data.tool || data.tool_name || data.name || 'unknown',
+      input: data.input || data.parameters || data.args || {},
+    };
+
+    return {
+      type: 'assistant',
+      content: [toolUse],
+    };
+  }
+
+  /**
+   * Convert tool_result event to content block for human message.
+   *
+   * @private
+   * @param {Object} data - Event data
+   * @returns {Object} Claude human message with tool_result content
+   */
+  _convertToolResult(data) {
+    const toolResult = {
+      type: 'tool_result',
+      tool_use_id: data.tool_id || data.tool_use_id || data.id || 'unknown',
+      content: data.output || data.result || data.content || '',
+      is_error: data.is_error || data.error || false,
+    };
+
+    // If is_error is truthy but content is empty, use error message
+    if (toolResult.is_error && !toolResult.content && data.error_message) {
+      toolResult.content = data.error_message;
+    }
+
+    return {
+      type: 'human',
+      content: [toolResult],
+    };
+  }
+
+  /**
+   * Convert thinking event to Claude assistant message with thinking content.
+   *
+   * @private
+   * @param {Object} data - Event data
+   * @returns {Object} Claude assistant message with thinking
+   */
+  _convertThinking(data) {
+    const thinking = data.thinking || data.content || data.text || '';
+    return {
+      type: 'assistant',
+      content: [
+        {
+          type: 'thinking',
+          thinking: String(thinking),
+        },
+      ],
+    };
+  }
+
+  /**
+   * Convert compact_summary event to Claude assistant message.
+   *
+   * @private
+   * @param {Object} data - Event data
+   * @returns {Object} Claude assistant message with summary
+   */
+  _convertCompactSummary(data) {
+    const summary = data.summary || data.content || data.text || '';
+    return {
+      type: 'assistant',
+      content: [
+        {
+          type: 'text',
+          text: `[Session Summary]\n${String(summary)}`,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Normalize project slug for use in file paths.
+   * Claude Code uses hyphenated paths like "-Users-kefentse-dev-teleporter".
+   *
+   * @private
+   * @param {string} slug - Project slug or path
+   * @returns {string} Normalized slug
+   */
+  _normalizeSlug(slug) {
+    if (!slug) {
+      return 'default';
+    }
+
+    // If it's already a Claude-style slug, use it as-is
+    if (slug.startsWith('-')) {
+      return slug;
+    }
+
+    // Convert path-like slug to Claude format
+    // e.g., "/Users/kefentse/dev/project" -> "-Users-kefentse-dev-project"
+    return slug.replace(/\//g, '-').replace(/^-/, '');
+  }
+}
+
+export default ClaudeTranscriptExporter;

package/lib/teleport/exporters/gemini-exporter.js

@@ -0,0 +1,307 @@
+/**
+ * Gemini CLI Transcript Exporter
+ *
+ * Converts Timeline API events to Gemini CLI's native JSON format.
+ * Gemini CLI stores transcripts in ~/.gemini/tmp/{hash}/logs.json
+ *
+ * Gemini JSON Format:
+ * - Array of message objects
+ * - User messages: {role: "user", parts: [{text: "..."}]}
+ * - Model messages: {role: "model", parts: [{text: "..."}, {functionCall: {...}}]}
+ * - Function results: {role: "user", parts: [{functionResponse: {...}}]}
+ *
+ * @module lib/teleport/exporters/gemini-exporter
+ */
+
+import { createHash } from 'crypto';
+import { homedir } from 'os';
+import { join } from 'path';
+import { TranscriptExporter } from './interface.js';
+
+/**
+ * Tool name mapping from Claude/Timeline format to Gemini format.
+ * Gemini CLI uses snake_case tool names.
+ *
+ * @type {Object.<string, string>}
+ */
+const TOOL_NAME_MAP = {
+  Read: 'read_file',
+  Write: 'write_file',
+  Edit: 'edit_file',
+  Bash: 'run_terminal_command',
+  Glob: 'glob_files',
+  Grep: 'grep_search',
+  LS: 'list_directory',
+  WebSearch: 'web_search',
+  WebFetch: 'web_fetch',
+  Task: 'spawn_agent',
+  AskUser: 'ask_user',
+  AskUserQuestion: 'ask_user',
+  // Add more mappings as needed
+};
+
+/**
+ * Exporter for Gemini CLI's native JSON transcript format.
+ *
+ * @extends TranscriptExporter
+ */
+export class GeminiTranscriptExporter extends TranscriptExporter {
+  name = 'gemini-cli';
+  displayName = 'Gemini CLI';
+
+  /**
+   * Export timeline events to Gemini CLI JSON format.
+   *
+   * Note: Gemini CLI does not support thinking blocks, so they are omitted.
+   *
+   * @param {import('./interface.js').TimelineEvent[]} events - Timeline events
+   * @param {import('./interface.js').ExportOptions} [options={}] - Export options
+   * @returns {Promise<string>} JSON content (pretty-printed with 2-space indent)
+   */
+  async export(events, options = {}) {
+    const { prettyPrint = true } = options;
+
+    // Validate and sort events
+    this.validateEvents(events);
+
+    if (events.length === 0) {
+      return prettyPrint ? '[]' : '[]';
+    }
+
+    const sorted = this.sortEvents(events);
+    const messages = [];
+
+    for (const event of sorted) {
+      const geminiMessage = this._convertEvent(event);
+
+      if (!geminiMessage) {
+        continue;
+      }
+
+      // Try to merge consecutive messages of the same role
+      const lastMessage = messages[messages.length - 1];
+      if (lastMessage && lastMessage.role === geminiMessage.role) {
+        // Merge parts
+        lastMessage.parts = [...lastMessage.parts, ...geminiMessage.parts];
+      } else {
+        messages.push(geminiMessage);
+      }
+    }
+
+    // Format output
+    return prettyPrint ? JSON.stringify(messages, null, 2) : JSON.stringify(messages);
+  }
+
+  /**
+   * Get the Gemini CLI transcript path.
+   *
+   * Gemini uses MD5 hash of project slug for directory name.
+   *
+   * @param {string} sessionId - Session identifier
+   * @param {string} projectSlug - Project slug/path
+   * @returns {string} Path like ~/.gemini/tmp/{hash}/logs.json
+   */
+  getTranscriptPath(sessionId, projectSlug) {
+    const home = homedir();
+    const hash = this._hashSlug(projectSlug);
+    return join(home, '.gemini', 'tmp', hash, 'logs.json');
+  }
+
+  /**
+   * Convert a timeline event to Gemini message format.
+   *
+   * @private
+   * @param {import('./interface.js').TimelineEvent} event - Timeline event
+   * @returns {Object|null} Gemini message object or null if skipped
+   */
+  _convertEvent(event) {
+    const { event_type, data } = event;
+
+    switch (event_type) {
+      case 'user_message':
+        return this._convertUserMessage(data);
+
+      case 'assistant_response':
+        return this._convertAssistantResponse(data);
+
+      case 'tool_use':
+        return this._convertToolUse(data);
+
+      case 'tool_result':
+        return this._convertToolResult(data);
+
+      case 'compact_summary':
+        return this._convertCompactSummary(data);
+
+      case 'thinking':
+        // Gemini does not support thinking blocks - skip
+        return null;
+
+      default:
+        // Unknown event type - skip silently
+        return null;
+    }
+  }
+
+  /**
+   * Convert user_message event to Gemini user message.
+   *
+   * @private
+   * @param {Object} data - Event data
+   * @returns {Object} Gemini user message
+   */
+  _convertUserMessage(data) {
+    const text = data.content || data.text || data.message || '';
+    return {
+      role: 'user',
+      parts: [{ text: String(text) }],
+    };
+  }
+
+  /**
+   * Convert assistant_response event to Gemini model message.
+   *
+   * @private
+   * @param {Object} data - Event data
+   * @returns {Object} Gemini model message
+   */
+  _convertAssistantResponse(data) {
+    const text = data.content || data.message || data.text || data.response || '';
+    return {
+      role: 'model',
+      parts: [{ text: String(text) }],
+    };
+  }
+
+  /**
+   * Convert tool_use event to Gemini model message with functionCall.
+   *
+   * @private
+   * @param {Object} data - Event data
+   * @returns {Object} Gemini model message with functionCall
+   */
+  _convertToolUse(data) {
+    const toolName = data.tool || data.tool_name || data.name || 'unknown';
+    const geminiName = this._mapToolName(toolName);
+    const args = data.input || data.parameters || data.args || {};
+
+    return {
+      role: 'model',
+      parts: [
+        {
+          functionCall: {
+            name: geminiName,
+            args: this._convertToolArgs(toolName, args),
+          },
+        },
+      ],
+    };
+  }
+
+  /**
+   * Convert tool_result event to Gemini user message with functionResponse.
+   *
+   * @private
+   * @param {Object} data - Event data
+   * @returns {Object} Gemini user message with functionResponse
+   */
+  _convertToolResult(data) {
+    const toolName = data.tool || data.tool_name || data.name || 'unknown';
+    const geminiName = this._mapToolName(toolName);
+    const output = data.output || data.result || data.content || '';
+    const isError = data.is_error || data.error || false;
+
+    return {
+      role: 'user',
+      parts: [
+        {
+          functionResponse: {
+            name: geminiName,
+            response: {
+              success: !isError,
+              output: String(output),
+            },
+          },
+        },
+      ],
+    };
+  }
+
+  /**
+   * Convert compact_summary event to Gemini model message.
+   *
+   * @private
+   * @param {Object} data - Event data
+   * @returns {Object} Gemini model message
+   */
+  _convertCompactSummary(data) {
+    const summary = data.summary || data.content || data.text || '';
+    return {
+      role: 'model',
+      parts: [{ text: `[Session Summary]\n${String(summary)}` }],
+    };
+  }
+
+  /**
+   * Map Claude/Timeline tool name to Gemini tool name.
+   *
+   * @private
+   * @param {string} toolName - Original tool name
+   * @returns {string} Gemini-compatible tool name
+   */
+  _mapToolName(toolName) {
+    // Check direct mapping
+    if (TOOL_NAME_MAP[toolName]) {
+      return TOOL_NAME_MAP[toolName];
+    }
+
+    // Convert to snake_case if not in map
+    return toolName
+      .replace(/([A-Z])/g, '_$1')
+      .toLowerCase()
+      .replace(/^_/, '');
+  }
+
+  /**
+   * Convert tool arguments to Gemini format.
+   * Some tools have different argument names.
+   *
+   * @private
+   * @param {string} toolName - Original tool name
+   * @param {Object} args - Original arguments
+   * @returns {Object} Gemini-compatible arguments
+   */
+  _convertToolArgs(toolName, args) {
+    // Map common argument names
+    const argMap = {
+      file_path: 'path',
+      command: 'cmd',
+      pattern: 'query',
+    };
+
+    const converted = {};
+    for (const [key, value] of Object.entries(args)) {
+      const newKey = argMap[key] || key;
+      converted[newKey] = value;
+    }
+
+    return converted;
+  }
+
+  /**
+   * Generate MD5 hash of project slug for Gemini's directory naming.
+   *
+   * @private
+   * @param {string} slug - Project slug/path
+   * @returns {string} MD5 hash (16 characters)
+   */
+  _hashSlug(slug) {
+    if (!slug) {
+      return createHash('md5').update('default').digest('hex').substring(0, 16);
+    }
+
+    return createHash('md5').update(slug).digest('hex').substring(0, 16);
+  }
+}
+
+export default GeminiTranscriptExporter;

package/lib/teleport/exporters/index.js

@@ -0,0 +1,93 @@
+/**
+ * Transcript Exporters
+ *
+ * CLI-agnostic exporters that convert Timeline API events to native CLI formats.
+ *
+ * @module lib/teleport/exporters
+ */
+
+export { TranscriptExporter } from './interface.js';
+export { ClaudeTranscriptExporter } from './claude-exporter.js';
+export { GeminiTranscriptExporter } from './gemini-exporter.js';
+
+/**
+ * Coder name constants for exporter selection
+ * @type {Object.<string, string>}
+ */
+export const CODER_NAMES = {
+  CLAUDE_CODE: 'claude-code',
+  GEMINI_CLI: 'gemini-cli',
+};
+
+/**
+ * Registry of available exporters
+ * @type {Object.<string, typeof TranscriptExporter>}
+ */
+const EXPORTERS = {
+  [CODER_NAMES.CLAUDE_CODE]: () => import('./claude-exporter.js').then(m => m.ClaudeTranscriptExporter),
+  [CODER_NAMES.GEMINI_CLI]: () => import('./gemini-exporter.js').then(m => m.GeminiTranscriptExporter),
+};
+
+/**
+ * Get the appropriate exporter for a given coder name.
+ *
+ * @param {string} coderName - The coder name (e.g., 'claude-code', 'gemini-cli')
+ * @returns {Promise<import('./interface.js').TranscriptExporter>} Exporter instance
+ * @throws {Error} If coder name is not supported
+ *
+ * @example
+ * ```js
+ * const exporter = await getExporterForCoder('claude-code');
+ * const transcript = await exporter.export(events);
+ * ```
+ */
+export async function getExporterForCoder(coderName) {
+  // Normalize coder name
+  const normalized = coderName?.toLowerCase()?.trim();
+
+  // Direct match
+  if (EXPORTERS[normalized]) {
+    const ExporterClass = await EXPORTERS[normalized]();
+    return new ExporterClass();
+  }
+
+  // Alias matching
+  const aliases = {
+    'claude': CODER_NAMES.CLAUDE_CODE,
+    'claude-code': CODER_NAMES.CLAUDE_CODE,
+    'claudecode': CODER_NAMES.CLAUDE_CODE,
+    'gemini': CODER_NAMES.GEMINI_CLI,
+    'gemini-cli': CODER_NAMES.GEMINI_CLI,
+    'geminicli': CODER_NAMES.GEMINI_CLI,
+  };
+
+  const mappedName = aliases[normalized];
+  if (mappedName && EXPORTERS[mappedName]) {
+    const ExporterClass = await EXPORTERS[mappedName]();
+    return new ExporterClass();
+  }
+
+  throw new Error(
+    `Unsupported coder: '${coderName}'. Supported coders: ${Object.keys(EXPORTERS).join(', ')}`
+  );
+}
+
+/**
+ * Get list of supported coder names.
+ *
+ * @returns {string[]} Array of supported coder names
+ */
+export function getSupportedCoders() {
+  return Object.keys(EXPORTERS);
+}
+
+/**
+ * Check if a coder is supported.
+ *
+ * @param {string} coderName - The coder name to check
+ * @returns {boolean} True if supported
+ */
+export function isCoderSupported(coderName) {
+  const normalized = coderName?.toLowerCase()?.trim();
+  return Boolean(EXPORTERS[normalized]);
+}