@techdivision/opencode-time-tracking 0.7.1 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.8.1] - 2025-03-01
+
+### Fixed
+
+- Fix `user_email` resolution to read from `.opencode/.env` instead of project root `.env`
+- Previously fell back to system username when `.env` was not found in project root
+
+## [0.8.0] - 2025-03-01
+
+### Added
+
+- Add detailed token columns to CSV: `tokens_input`, `tokens_output`, `tokens_reasoning`, `tokens_cache_read`, `tokens_cache_write`
+- Add `cost` column to CSV tracking session cost in USD (from OpenCode SDK)
+- Add `CsvWriter.ensureHeader()` for automatic CSV header management at plugin startup
+
+### Fixed
+
+- Fix CSV header migration: automatically upgrade old 17-column files to 23-column format
+- Fix ticket extraction: skip synthetic text parts (file contents, MCP resources) to avoid false positives from example patterns in docs
+- Fix empty CSV files created without headers
+
+### Changed
+
+- CSV header is now validated and repaired at plugin startup, not on each write
+
 ## [0.7.1] - 2025-03-01
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techdivision/opencode-time-tracking",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "Automatic time tracking plugin for OpenCode - tracks session duration and tool usage to CSV",
   "main": "src/Plugin.ts",
   "types": "src/Plugin.ts",

package/src/Plugin.ts

@@ -64,6 +64,9 @@ export const plugin: Plugin = async ({
   const ticketExtractor = new TicketExtractor(client, config.valid_projects)
   const ticketResolver = new TicketResolver(config, ticketExtractor)
 
+  // Ensure CSV file has a valid header at startup
+  await csvWriter.ensureHeader()
+
   const hooks: Hooks = {
     "tool.execute.after": createToolExecuteAfterHook(
       sessionManager,

package/src/hooks/EventHook.ts

@@ -140,6 +140,11 @@ export function createEventHook(
           cacheRead: part.tokens.cache.read,
           cacheWrite: part.tokens.cache.write,
         })
+
+        // Track cost from step-finish events
+        if (part.cost !== undefined) {
+          sessionManager.addCost(part.sessionID, part.cost)
+        }
       }
 
       return
@@ -224,6 +229,7 @@ export function createEventHook(
           description,
           notes: `Auto-tracked: ${toolSummary}`,
           tokenUsage: session.tokenUsage,
+          cost: session.cost,
           model: modelString,
           agent: agentString,
         })

package/src/services/ConfigLoader.ts

@@ -61,7 +61,7 @@ async function loadEnvValue(
  *
  * The `user_email` is resolved from (in order of priority):
  * 1. `OPENCODE_USER_EMAIL` system environment variable
- * 2. `OPENCODE_USER_EMAIL` from project `.env` file
+ * 2. `OPENCODE_USER_EMAIL` from `.opencode/.env` file
  * 3. System username (fallback)
  */
 export class ConfigLoader {
@@ -94,9 +94,9 @@ export class ConfigLoader {
 
           // Resolve user_email with fallback chain:
           // 1. System environment variable
-          // 2. Project .env file
+          // 2. .opencode/.env file
           // 3. System username
-          const envValue = await loadEnvValue(directory, ENV_USER_EMAIL)
+          const envValue = await loadEnvValue(`${directory}/.opencode`, ENV_USER_EMAIL)
           const userEmail =
             process.env[ENV_USER_EMAIL] || envValue || userInfo().username
 

package/src/services/CsvWriter.ts

@@ -16,9 +16,51 @@ import "../types/Bun"
 /**
  * CSV header row for the worklog export file.
  * Compatible with Jira/Tempo time tracking import.
+ *
+ * @remarks
+ * Columns 1-17: Original format (v0.5.0 - v0.7.x)
+ * Columns 18-23: Extended format (v0.8.0+) with token details and cost
  */
 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,model,agent"
+  "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,model,agent,tokens_input,tokens_output,tokens_reasoning,tokens_cache_read,tokens_cache_write,cost"
+
+/** Number of columns in the current CSV format */
+const CSV_COLUMN_COUNT = 23
+
+/**
+ * Checks if a line is a CSV header row.
+ *
+ * @param line - The line to check
+ * @returns `true` if the line appears to be a header
+ */
+function isHeaderLine(line: string): boolean {
+  return line.startsWith('"id"') || line.startsWith("id,")
+}
+
+/**
+ * Pads a CSV line with empty fields to match the expected column count.
+ *
+ * @param line - The CSV line to pad
+ * @param currentColumns - The current number of columns in the line
+ * @param targetColumns - The target number of columns
+ * @returns The padded line, or the original line if no padding needed
+ */
+function padCsvLine(
+  line: string,
+  currentColumns: number,
+  targetColumns: number
+): string {
+  if (currentColumns >= targetColumns) {
+    return line
+  }
+
+  const missingColumns = targetColumns - currentColumns
+  const padding = ',""\n'.repeat(missingColumns).slice(0, -1) // Remove trailing newline, keep commas
+  const emptyFields = Array(missingColumns).fill('""').join(",")
+
+  // Append empty fields to the line
+  return line + "," + emptyFields
+}
 
 /**
  * Writes time tracking entries to a CSV file.
@@ -68,15 +110,95 @@ export class CsvWriter {
     return csvPath
   }
 
+  /**
+   * Ensures the CSV file exists and has a valid, up-to-date header.
+   *
+   * @remarks
+   * Call this once at plugin startup. Handles these cases:
+   * - File doesn't exist: creates it with header
+   * - File is empty: writes header
+   * - File has data but no header: prepends header and pads rows if needed
+   * - File has outdated header (fewer columns): replaces header and pads all rows
+   * - File already has current header: no action needed
+   *
+   * @returns `true` if file was modified, `false` if already valid
+   */
+  async ensureHeader(): Promise<boolean> {
+    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()
+
+    if (!exists) {
+      // Create new file with header
+      await Bun.write(csvPath, CSV_HEADER + "\n")
+      return true
+    }
+
+    const content = await file.text()
+    const trimmedContent = content.trim()
+
+    if (trimmedContent.length === 0) {
+      // Empty file: write header
+      await Bun.write(csvPath, CSV_HEADER + "\n")
+      return true
+    }
+
+    const lines = trimmedContent.split("\n")
+    const firstLine = lines[0]
+    const hasHeader = isHeaderLine(firstLine)
+
+    // Determine column count from first data line
+    const dataLineIndex = hasHeader ? 1 : 0
+    if (dataLineIndex >= lines.length) {
+      // Only header, no data - ensure header is current
+      if (hasHeader && CsvFormatter.countColumns(firstLine) < CSV_COLUMN_COUNT) {
+        await Bun.write(csvPath, CSV_HEADER + "\n")
+        return true
+      }
+      return false
+    }
+
+    const firstDataLine = lines[dataLineIndex]
+    const columnCount = CsvFormatter.countColumns(firstDataLine)
+
+    // Check if migration is needed
+    if (columnCount >= CSV_COLUMN_COUNT) {
+      // Already has enough columns
+      if (!hasHeader) {
+        // Just prepend header
+        await Bun.write(csvPath, CSV_HEADER + "\n" + trimmedContent + "\n")
+        return true
+      }
+      return false
+    }
+
+    // Migration needed: pad all data rows to CSV_COLUMN_COUNT
+    const dataLines = hasHeader ? lines.slice(1) : lines
+    const paddedLines = dataLines.map((line) => {
+      const lineColumnCount = CsvFormatter.countColumns(line)
+      return padCsvLine(line, lineColumnCount, CSV_COLUMN_COUNT)
+    })
+
+    // Write new header + padded data
+    await Bun.write(csvPath, CSV_HEADER + "\n" + paddedLines.join("\n") + "\n")
+    return true
+  }
+
   /**
    * 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.
+   * Assumes `ensureHeader()` was called at startup.
+   * Simply appends the new entry to the file.
    *
    * @example
    * ```typescript
@@ -87,19 +209,13 @@ export class CsvWriter {
    *   durationSeconds: 3600,
    *   description: "Implemented feature X",
    *   notes: "Auto-tracked: read(5x), edit(3x)",
-   *   tokenUsage: { input: 1000, output: 500, reasoning: 0, cacheRead: 0, cacheWrite: 0 }
+   *   tokenUsage: { input: 1000, output: 500, reasoning: 0, cacheRead: 0, cacheWrite: 0 },
+   *   cost: 0.0234
    * })
    * ```
    */
   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()
 
@@ -124,11 +240,19 @@ export class CsvWriter {
       CsvFormatter.escape(data.notes),
       data.model ?? "",
       data.agent ?? "",
+      // Extended columns (v0.8.0+)
+      data.tokenUsage.input.toString(),
+      data.tokenUsage.output.toString(),
+      data.tokenUsage.reasoning.toString(),
+      data.tokenUsage.cacheRead.toString(),
+      data.tokenUsage.cacheWrite.toString(),
+      data.cost.toFixed(6),
     ]
 
     const csvLine = fields.map((f) => `"${f}"`).join(",")
 
     if (!exists) {
+      // Fallback: create file with header if ensureHeader() wasn't called
       await Bun.write(csvPath, CSV_HEADER + "\n" + csvLine + "\n")
     } else {
       const content = await file.text()

package/src/services/SessionManager.ts

@@ -63,6 +63,7 @@ export class SessionManager {
         cacheRead: 0,
         cacheWrite: 0,
       },
+      cost: 0,
       model: null,
       agent: null,
     }
@@ -134,6 +135,20 @@ export class SessionManager {
     }
   }
 
+  /**
+   * Adds cost to a session's cumulative total.
+   *
+   * @param sessionID - The OpenCode session identifier
+   * @param cost - The cost in USD to add
+   */
+  addCost(sessionID: string, cost: number): void {
+    const session = this.sessions.get(sessionID)
+
+    if (session) {
+      session.cost += cost
+    }
+  }
+
   /**
    * Updates the ticket reference for a session.
    *

package/src/services/TicketExtractor.ts

@@ -116,7 +116,9 @@ export class TicketExtractor {
         }
 
         for (const part of message.parts) {
-          if (part.type === "text" && part.text) {
+          // Skip synthetic parts (file contents, MCP resources, etc.)
+          // These may contain example ticket patterns from docs
+          if (part.type === "text" && part.text && !part.synthetic) {
             const ticket = this.extractFromText(part.text)
 
             if (ticket) {

package/src/types/CsvEntryData.ts

@@ -29,6 +29,9 @@ export interface CsvEntryData {
   /** Token consumption statistics */
   tokenUsage: TokenUsage
 
+  /** Total cost in USD */
+  cost: number
+
   /**
    * Model identifier in format `providerID/modelID`.
    *

package/src/types/MessagePart.ts

@@ -11,4 +11,14 @@ export interface MessagePart {
 
   /** Text content for text parts */
   text?: string
+
+  /**
+   * Whether this part was synthetically generated by OpenCode.
+   *
+   * @remarks
+   * OpenCode creates synthetic text parts for file contents, MCP resources,
+   * and other system-injected content. These should be excluded from
+   * ticket extraction as they may contain example patterns from docs.
+   */
+  synthetic?: boolean
 }

package/src/types/MessagePartUpdatedProperties.ts

@@ -16,6 +16,9 @@ export interface MessagePartUpdatedProperties {
     /** Session ID (present on step-finish and agent parts) */
     sessionID?: string
 
+    /** Cost in USD (present on step-finish parts) */
+    cost?: number
+
     /** Token usage (present on step-finish parts) */
     tokens?: StepFinishPart["tokens"]
 

package/src/types/SessionData.ts

@@ -23,6 +23,9 @@ export interface SessionData {
   /** Cumulative token usage for the session */
   tokenUsage: TokenUsage
 
+  /** Cumulative cost in USD for the session */
+  cost: number
+
   /** Model used in this session, or `null` if not detected */
   model: ModelInfo | null
 

package/src/types/StepFinishPart.ts

@@ -16,6 +16,9 @@ export interface StepFinishPart {
   /** The session this part belongs to */
   sessionID: string
 
+  /** Cost in USD for this step */
+  cost: number
+
   /** Token usage for this step */
   tokens: {
     /** Input tokens consumed */

package/src/utils/CsvFormatter.ts

@@ -54,4 +54,31 @@ export class CsvFormatter {
   static formatTime(timestamp: number): string {
     return new Date(timestamp).toTimeString().split(" ")[0]
   }
+
+  /**
+   * Counts the number of columns in a CSV line.
+   *
+   * @param csvLine - A single line from a CSV file (with quoted fields)
+   * @returns The number of columns
+   *
+   * @remarks
+   * Handles quoted fields correctly by counting occurrences of `","` pattern.
+   * Assumes all fields are double-quoted as our CSV writer produces.
+   *
+   * @example
+   * ```typescript
+   * CsvFormatter.countColumns('"a","b","c"')  // Returns: 3
+   * CsvFormatter.countColumns('"single"')     // Returns: 1
+   * ```
+   */
+  static countColumns(csvLine: string): number {
+    if (!csvLine || csvLine.trim().length === 0) {
+      return 0
+    }
+
+    // Count occurrences of "," which separates quoted fields
+    // Add 1 because n separators means n+1 fields
+    const matches = csvLine.match(/","/g)
+    return matches ? matches.length + 1 : 1
+  }
 }