opencode-time-tracking 0.1.5

package/src/services/CsvWriter.ts

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview CSV writer for exporting time tracking data.
+ */
+
+import { randomUUID } from "crypto"
+import { mkdir } from "fs/promises"
+import { dirname } from "path"
+
+import type { CsvEntryData } from "../types/CsvEntryData"
+import type { TimeTrackingConfig } from "../types/TimeTrackingConfig"
+
+import { CsvFormatter } from "../utils/CsvFormatter"
+
+import "../types/Bun"
+
+/**
+ * CSV header row for the worklog export file.
+ * Compatible with Jira/Tempo time tracking import.
+ */
+const CSV_HEADER =
+  "id,start_date,end_date,user,ticket_name,issue_key,account_key,start_time,end_time,duration_seconds,tokens_used,tokens_remaining,story_points,description,notes"
+
+/**
+ * Writes time tracking entries to a CSV file.
+ *
+ * @remarks
+ * The CSV format is compatible with Jira/Tempo worklog imports.
+ * The file path can be absolute, relative to the project, or use `~/` for home directory.
+ */
+export class CsvWriter {
+  /** Plugin configuration */
+  private config: TimeTrackingConfig
+
+  /** Project directory path */
+  private directory: string
+
+  /**
+   * Creates a new CSV writer instance.
+   *
+   * @param config - The plugin configuration
+   * @param directory - The project directory path
+   */
+  constructor(config: TimeTrackingConfig, directory: string) {
+    this.config = config
+    this.directory = directory
+  }
+
+  /**
+   * Resolves the CSV file path from configuration.
+   *
+   * @returns The absolute path to the CSV file
+   *
+   * @remarks
+   * Handles three path formats:
+   * - `~/path` - Expands to home directory
+   * - `/absolute/path` - Used as-is
+   * - `relative/path` - Relative to project directory
+   */
+  private resolvePath(): string {
+    let csvPath = this.config.csv_file
+
+    if (csvPath.startsWith("~/")) {
+      csvPath = csvPath.replace("~", process.env.HOME || "")
+    } else if (!csvPath.startsWith("/")) {
+      csvPath = `${this.directory}/${csvPath}`
+    }
+
+    return csvPath
+  }
+
+  /**
+   * Writes a time tracking entry to the CSV file.
+   *
+   * @param data - The entry data to write
+   *
+   * @remarks
+   * Creates the CSV file with headers if it doesn't exist.
+   * Appends to existing file if it exists.
+   * Creates parent directories as needed.
+   *
+   * @example
+   * ```typescript
+   * await csvWriter.write({
+   *   ticket: "PROJ-123",
+   *   startTime: Date.now() - 3600000,
+   *   endTime: Date.now(),
+   *   durationSeconds: 3600,
+   *   description: "Implemented feature X",
+   *   notes: "Auto-tracked: read(5x), edit(3x)",
+   *   tokenUsage: { input: 1000, output: 500, reasoning: 0, cacheRead: 0, cacheWrite: 0 }
+   * })
+   * ```
+   */
+  async write(data: CsvEntryData): Promise<void> {
+    const csvPath = this.resolvePath()
+
+    try {
+      await mkdir(dirname(csvPath), { recursive: true })
+    } catch {
+      // Directory may already exist
+    }
+
+    const file = Bun.file(csvPath)
+    const exists = await file.exists()
+
+    const totalTokens =
+      data.tokenUsage.input + data.tokenUsage.output + data.tokenUsage.reasoning
+
+    const fields = [
+      randomUUID(),
+      CsvFormatter.formatDate(data.startTime),
+      CsvFormatter.formatDate(data.endTime),
+      this.config.user_email,
+      "",
+      data.ticket ?? "",
+      this.config.default_account_key,
+      CsvFormatter.formatTime(data.startTime),
+      CsvFormatter.formatTime(data.endTime),
+      data.durationSeconds.toString(),
+      totalTokens.toString(),
+      "",
+      "",
+      CsvFormatter.escape(data.description),
+      CsvFormatter.escape(data.notes),
+    ]
+
+    const csvLine = fields.map((f) => `"${f}"`).join(",")
+
+    if (!exists) {
+      await Bun.write(csvPath, CSV_HEADER + "\n" + csvLine + "\n")
+    } else {
+      const content = await file.text()
+      await Bun.write(csvPath, content + csvLine + "\n")
+    }
+  }
+}

package/src/services/SessionManager.ts

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Session state management for time tracking.
+ */
+
+import type { ActivityData } from "../types/ActivityData"
+import type { SessionData } from "../types/SessionData"
+import type { TokenUsage } from "../types/TokenUsage"
+
+/**
+ * Manages active session state for time tracking.
+ *
+ * @remarks
+ * Each OpenCode session is tracked separately with its own:
+ * - Start time
+ * - Ticket reference
+ * - Tool activities
+ * - Token usage statistics
+ *
+ * Sessions are stored in memory and cleaned up when completed.
+ */
+export class SessionManager {
+  /** Map of session ID to session data */
+  private sessions = new Map<string, SessionData>()
+
+  /**
+   * Retrieves session data by ID.
+   *
+   * @param sessionID - The OpenCode session identifier
+   * @returns The session data, or `undefined` if not found
+   */
+  get(sessionID: string): SessionData | undefined {
+    return this.sessions.get(sessionID)
+  }
+
+  /**
+   * Checks if a session exists.
+   *
+   * @param sessionID - The OpenCode session identifier
+   * @returns `true` if the session exists, `false` otherwise
+   */
+  has(sessionID: string): boolean {
+    return this.sessions.has(sessionID)
+  }
+
+  /**
+   * Creates a new session.
+   *
+   * @param sessionID - The OpenCode session identifier
+   * @param ticket - Optional Jira ticket reference (e.g., "PROJ-123")
+   * @returns The newly created session data
+   */
+  create(sessionID: string, ticket: string | null): SessionData {
+    const session: SessionData = {
+      ticket,
+      startTime: Date.now(),
+      activities: [],
+      tokenUsage: {
+        input: 0,
+        output: 0,
+        reasoning: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+      },
+    }
+
+    this.sessions.set(sessionID, session)
+
+    return session
+  }
+
+  /**
+   * Deletes a session.
+   *
+   * @param sessionID - The OpenCode session identifier
+   */
+  delete(sessionID: string): void {
+    this.sessions.delete(sessionID)
+  }
+
+  /**
+   * Adds a tool activity to a session.
+   *
+   * @param sessionID - The OpenCode session identifier
+   * @param activity - The activity data to add
+   */
+  addActivity(sessionID: string, activity: ActivityData): void {
+    const session = this.sessions.get(sessionID)
+
+    if (session) {
+      session.activities.push(activity)
+    }
+  }
+
+  /**
+   * Adds token usage to a session's cumulative totals.
+   *
+   * @param sessionID - The OpenCode session identifier
+   * @param tokens - The token usage to add
+   */
+  addTokenUsage(sessionID: string, tokens: TokenUsage): void {
+    const session = this.sessions.get(sessionID)
+
+    if (session) {
+      session.tokenUsage.input += tokens.input
+      session.tokenUsage.output += tokens.output
+      session.tokenUsage.reasoning += tokens.reasoning
+      session.tokenUsage.cacheRead += tokens.cacheRead
+      session.tokenUsage.cacheWrite += tokens.cacheWrite
+    }
+  }
+
+  /**
+   * Updates the ticket reference for a session.
+   *
+   * @param sessionID - The OpenCode session identifier
+   * @param ticket - The new ticket reference, or `null` to keep existing
+   *
+   * @remarks
+   * Only updates if a non-null ticket is provided.
+   * This allows the ticket to be updated when found in later messages.
+   */
+  updateTicket(sessionID: string, ticket: string | null): void {
+    const session = this.sessions.get(sessionID)
+
+    if (session && ticket) {
+      session.ticket = ticket
+    }
+  }
+}

package/src/services/TicketExtractor.ts

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview Extracts Jira ticket references from session context.
+ */
+
+import type { MessageWithParts } from "../types/MessageWithParts"
+import type { OpencodeClient } from "../types/OpencodeClient"
+import type { Todo } from "../types/Todo"
+
+/**
+ * Regular expression pattern for Jira ticket references.
+ * Matches patterns like "PROJ-123", "ABC-1", "FEATURE-9999".
+ */
+const TICKET_PATTERN = /([A-Z]+-\d+)/
+
+/**
+ * Extracts Jira ticket references from user messages and todos.
+ *
+ * @remarks
+ * Scans the session context for ticket patterns in this priority:
+ * 1. User messages (newest first)
+ * 2. Todo items (newest first)
+ *
+ * Returns the first match found, allowing tickets to be updated
+ * when mentioned in later messages.
+ */
+export class TicketExtractor {
+  /** OpenCode SDK client */
+  private client: OpencodeClient
+
+  /**
+   * Creates a new ticket extractor instance.
+   *
+   * @param client - The OpenCode SDK client
+   */
+  constructor(client: OpencodeClient) {
+    this.client = client
+  }
+
+  /**
+   * Extracts a ticket reference from the session context.
+   *
+   * @param sessionID - The OpenCode session identifier
+   * @returns The ticket reference (e.g., "PROJ-123"), or `null` if not found
+   *
+   * @example
+   * ```typescript
+   * const ticket = await ticketExtractor.extract("session-123")
+   * // Returns "PROJ-456" if user mentioned it in a message
+   * ```
+   */
+  async extract(sessionID: string): Promise<string | null> {
+    const ticketFromMessages = await this.extractFromMessages(sessionID)
+
+    if (ticketFromMessages) {
+      return ticketFromMessages
+    }
+
+    const ticketFromTodos = await this.extractFromTodos(sessionID)
+
+    return ticketFromTodos
+  }
+
+  /**
+   * Extracts a ticket from user messages.
+   *
+   * @param sessionID - The OpenCode session identifier
+   * @returns The ticket reference, or `null` if not found
+   */
+  private async extractFromMessages(
+    sessionID: string
+  ): Promise<string | null> {
+    try {
+      const result = await this.client.session.messages({
+        path: { id: sessionID },
+      } as Parameters<typeof this.client.session.messages>[0])
+
+      if (!result.data) {
+        return null
+      }
+
+      const messages = result.data as MessageWithParts[]
+
+      // Scan user messages for ticket pattern (newest first)
+      for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i]
+
+        if (message.info.role !== "user") {
+          continue
+        }
+
+        for (const part of message.parts) {
+          if (part.type === "text" && part.text) {
+            const ticket = this.extractFromText(part.text)
+
+            if (ticket) {
+              return ticket
+            }
+          }
+        }
+      }
+
+      return null
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Extracts a ticket from todo items.
+   *
+   * @param sessionID - The OpenCode session identifier
+   * @returns The ticket reference, or `null` if not found
+   */
+  private async extractFromTodos(sessionID: string): Promise<string | null> {
+    try {
+      const result = await this.client.session.todo({
+        path: { id: sessionID },
+      } as Parameters<typeof this.client.session.todo>[0])
+
+      if (!result.data) {
+        return null
+      }
+
+      const todos = result.data as Todo[]
+
+      // Scan todos for ticket pattern (newest first)
+      for (let i = todos.length - 1; i >= 0; i--) {
+        const todo = todos[i]
+
+        if (todo.content) {
+          const ticket = this.extractFromText(todo.content)
+
+          if (ticket) {
+            return ticket
+          }
+        }
+      }
+
+      return null
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Extracts a ticket pattern from text.
+   *
+   * @param text - The text to search
+   * @returns The first ticket match, or `null` if not found
+   */
+  private extractFromText(text: string): string | null {
+    const match = text.match(TICKET_PATTERN)
+
+    return match?.[1] ?? null
+  }
+}

package/src/types/ActivityData.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Activity data type for tracking tool executions.
+ */
+
+/**
+ * Represents a single tool activity within a session.
+ */
+export interface ActivityData {
+  /** The name of the tool that was executed (e.g., "read", "edit", "bash") */
+  tool: string
+
+  /** Unix timestamp in milliseconds when the activity occurred */
+  timestamp: number
+
+  /** Optional file path associated with the activity */
+  file?: string
+}

package/src/types/Bun.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Global Bun type declarations.
+ *
+ * @remarks
+ * This file declares the Bun global object for TypeScript.
+ * The actual Bun runtime is provided by OpenCode at plugin load time.
+ */
+
+declare global {
+  /** Bun runtime file system API */
+  const Bun: {
+    /**
+     * Creates a file handle for the given path.
+     *
+     * @param path - The file path
+     * @returns A file handle object
+     */
+    file(path: string): {
+      /** Checks if the file exists */
+      exists(): Promise<boolean>
+
+      /** Parses the file as JSON */
+      json(): Promise<unknown>
+
+      /** Reads the file as text */
+      text(): Promise<string>
+    }
+
+    /**
+     * Writes content to a file.
+     *
+     * @param path - The file path
+     * @param content - The content to write
+     * @returns The number of bytes written
+     */
+    write(path: string, content: string): Promise<number>
+  }
+}
+
+export {}

package/src/types/CsvEntryData.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview CSV entry data type for worklog exports.
+ */
+
+import type { TokenUsage } from "./TokenUsage"
+
+/**
+ * Data structure for a single CSV worklog entry.
+ */
+export interface CsvEntryData {
+  /** Jira ticket reference (e.g., "PROJ-123"), or `null` if not found */
+  ticket: string | null
+
+  /** Session start time as Unix timestamp in milliseconds */
+  startTime: number
+
+  /** Session end time as Unix timestamp in milliseconds */
+  endTime: number
+
+  /** Duration of the session in seconds */
+  durationSeconds: number
+
+  /** Human-readable description of the work performed */
+  description: string
+
+  /** Additional notes (e.g., tool usage summary) */
+  notes: string
+
+  /** Token consumption statistics */
+  tokenUsage: TokenUsage
+}

package/src/types/MessageInfo.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Message info type from OpenCode SDK.
+ */
+
+import type { MessageSummary } from "./MessageSummary"
+
+/**
+ * Information about a message in the conversation.
+ */
+export interface MessageInfo {
+  /** The role of the message sender */
+  role: "user" | "assistant"
+
+  /** Optional summary generated by the LLM */
+  summary?: MessageSummary
+}

package/src/types/MessagePart.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Message part type from OpenCode SDK.
+ */
+
+/**
+ * A part of a message (text, file, tool call, etc.).
+ */
+export interface MessagePart {
+  /** The type of the part (e.g., "text", "tool", "file") */
+  type: string
+
+  /** Text content for text parts */
+  text?: string
+}

package/src/types/MessagePartUpdatedProperties.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Properties for message.part.updated events.
+ */
+
+import type { StepFinishPart } from "./StepFinishPart"
+
+/**
+ * Properties received with message.part.updated events.
+ */
+export interface MessagePartUpdatedProperties {
+  /** The updated message part */
+  part: {
+    /** The type of the part */
+    type: string
+
+    /** Session ID (present on step-finish parts) */
+    sessionID?: string
+
+    /** Token usage (present on step-finish parts) */
+    tokens?: StepFinishPart["tokens"]
+  }
+}

package/src/types/MessageSummary.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Message summary type from OpenCode SDK.
+ */
+
+/**
+ * LLM-generated summary of a message's changes.
+ */
+export interface MessageSummary {
+  /** Short title describing the changes */
+  title?: string
+
+  /** Longer description of the changes */
+  body?: string
+}

package/src/types/MessageWithParts.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Message with parts type from OpenCode SDK.
+ */
+
+import type { MessageInfo } from "./MessageInfo"
+import type { MessagePart } from "./MessagePart"
+
+/**
+ * A message with its associated parts.
+ */
+export interface MessageWithParts {
+  /** Message metadata */
+  info: MessageInfo
+
+  /** Array of message parts (text, tools, files, etc.) */
+  parts: MessagePart[]
+}

package/src/types/OpencodeClient.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview OpenCode SDK client type.
+ */
+
+import type { createOpencodeClient } from "@opencode-ai/sdk"
+
+/**
+ * The OpenCode SDK client type.
+ *
+ * @remarks
+ * Derived from the return type of `createOpencodeClient`.
+ * Provides access to session, TUI, and other OpenCode APIs.
+ */
+export type OpencodeClient = ReturnType<typeof createOpencodeClient>

package/src/types/SessionData.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Session data type for time tracking state.
+ */
+
+import type { ActivityData } from "./ActivityData"
+import type { TokenUsage } from "./TokenUsage"
+
+/**
+ * State data for a tracked session.
+ */
+export interface SessionData {
+  /** Jira ticket reference, or `null` if not found */
+  ticket: string | null
+
+  /** Session start time as Unix timestamp in milliseconds */
+  startTime: number
+
+  /** Array of tool activities recorded during the session */
+  activities: ActivityData[]
+
+  /** Cumulative token usage for the session */
+  tokenUsage: TokenUsage
+}

package/src/types/StepFinishPart.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Step finish part type from OpenCode SDK.
+ */
+
+/**
+ * A step-finish message part containing token usage.
+ *
+ * @remarks
+ * Emitted when a model completes a reasoning step.
+ * Contains detailed token consumption statistics.
+ */
+export interface StepFinishPart {
+  /** Part type identifier */
+  type: "step-finish"
+
+  /** The session this part belongs to */
+  sessionID: string
+
+  /** Token usage for this step */
+  tokens: {
+    /** Input tokens consumed */
+    input: number
+
+    /** Output tokens generated */
+    output: number
+
+    /** Reasoning tokens used (for o1-style models) */
+    reasoning: number
+
+    /** Cache statistics */
+    cache: {
+      /** Tokens read from cache */
+      read: number
+
+      /** Tokens written to cache */
+      write: number
+    }
+  }
+}