@techdivision/opencode-time-tracking 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.7.1] - 2025-03-01
+
+### Fixed
+
+- Fix `agent_defaults` lookup to be tolerant of `@` prefix in agent names
+- Add `AgentMatcher` utility for consistent agent name normalization across the codebase
+
+## [0.7.0] - 2025-02-04
+
+### Added
+
+- Add `valid_projects` configuration for JIRA project whitelist
+- Restrict ticket detection to specific projects when configured
+
+### Changed
+
+- Default ticket pattern now requires at least 2 uppercase letters
+- Matches: `PROJ-123`, `SOSO-1`, `AB-99`
+- Does not match: `V-1`, `X-9` (single letter), `UTF-8` (false positive)
+
 ## [0.6.1] - 2025-02-02
 
 ### Fixed

package/README.md

@@ -100,6 +100,20 @@ Skip time tracking for specific agents:
 }
 ```
 
+#### Project Whitelist
+
+Restrict ticket detection to specific JIRA projects:
+
+```json
+{
+  "time_tracking": {
+    "csv_file": "...",
+    "global_default": { ... },
+    "valid_projects": ["PROJ", "SOSO", "FEAT"]
+  }
+}
+```
+
 ### Full Example
 
 ```json
@@ -120,11 +134,40 @@ Skip time tracking for specific agents:
         "issue_key": "PROJ-REVIEW"
       }
     },
-    "ignored_agents": ["@internal"]
+    "ignored_agents": ["@internal"],
+    "valid_projects": ["PROJ", "SOSO"]
   }
 }
 ```
 
+## Ticket Detection
+
+### Pattern
+
+By default, tickets must have at least 2 uppercase letters followed by a number:
+- Matches: `PROJ-123`, `SOSO-1`, `AB-99`
+- Does not match: `V-1`, `X-9` (single letter), `UTF-8` (common false positive)
+
+### Project Whitelist
+
+When `valid_projects` is configured, only tickets from those projects are recognized:
+
+```json
+{
+  "time_tracking": {
+    "valid_projects": ["PROJ", "SOSO", "FEAT"]
+  }
+}
+```
+
+With whitelist:
+- Matches: `PROJ-123`, `SOSO-1`, `FEAT-99`
+- Does not match: `UTF-8`, `ISO-9001`, `OTHER-123`
+
+Without whitelist (default):
+- Matches any pattern with 2+ uppercase letters: `PROJ-123`, `AB-1`
+- Does not match single-letter prefixes: `V-1`, `X-99`
+
 ## Fallback Hierarchy
 
 ### Ticket Resolution

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techdivision/opencode-time-tracking",
-  "version": "0.6.1",
+  "version": "0.7.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

@@ -61,7 +61,7 @@ export const plugin: Plugin = async ({
 
   const sessionManager = new SessionManager()
   const csvWriter = new CsvWriter(config, directory)
-  const ticketExtractor = new TicketExtractor(client)
+  const ticketExtractor = new TicketExtractor(client, config.valid_projects)
   const ticketResolver = new TicketResolver(config, ticketExtractor)
 
   const hooks: Hooks = {

package/src/hooks/EventHook.ts

@@ -12,6 +12,7 @@ import type { MessageWithParts } from "../types/MessageWithParts"
 import type { OpencodeClient } from "../types/OpencodeClient"
 import type { TimeTrackingConfig } from "../types/TimeTrackingConfig"
 
+import { AgentMatcher } from "../utils/AgentMatcher"
 import { DescriptionGenerator } from "../utils/DescriptionGenerator"
 
 /**
@@ -193,9 +194,11 @@ export function createEventHook(
       const agentString = session.agent?.name ?? null
 
       // Check if agent should be ignored (tolerant matching: with or without @ prefix)
-      const normalizedAgent = agentString?.replace(/^@/, "")
+      const normalizedAgent = agentString
+        ? AgentMatcher.normalize(agentString)
+        : null
       const isIgnoredAgent = config.ignored_agents?.some(
-        (ignored) => ignored.replace(/^@/, "") === normalizedAgent
+        (ignored) => AgentMatcher.normalize(ignored) === normalizedAgent
       )
 
       if (agentString && isIgnoredAgent) {

package/src/services/TicketExtractor.ts

@@ -7,10 +7,12 @@ 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".
+ * Default regular expression pattern for Jira ticket references.
+ * Requires at least 2 uppercase letters followed by a dash and digits.
+ * Matches patterns like "PROJ-123", "AB-1", "FEATURE-9999".
+ * Does not match single-letter prefixes like "V-1" or "X-99".
  */
-const TICKET_PATTERN = /([A-Z]+-\d+)/
+const DEFAULT_TICKET_PATTERN = /\b([A-Z]{2,}-\d+)\b/
 
 /**
  * Extracts Jira ticket references from user messages and todos.
@@ -22,18 +24,43 @@ const TICKET_PATTERN = /([A-Z]+-\d+)/
  *
  * Returns the first match found, allowing tickets to be updated
  * when mentioned in later messages.
+ *
+ * If `validProjects` is provided, only tickets from those projects
+ * are recognized. Otherwise, any ticket matching the default pattern
+ * (2+ uppercase letters) is accepted.
  */
 export class TicketExtractor {
   /** OpenCode SDK client */
   private client: OpencodeClient
 
+  /** Compiled regex pattern for ticket matching */
+  private ticketPattern: RegExp
+
   /**
    * Creates a new ticket extractor instance.
    *
    * @param client - The OpenCode SDK client
+   * @param validProjects - Optional whitelist of valid JIRA project keys
+   *
+   * @example
+   * ```typescript
+   * // Accept any ticket with 2+ letter prefix
+   * const extractor = new TicketExtractor(client)
+   *
+   * // Only accept PROJ and SOSO tickets
+   * const extractor = new TicketExtractor(client, ["PROJ", "SOSO"])
+   * ```
    */
-  constructor(client: OpencodeClient) {
+  constructor(client: OpencodeClient, validProjects?: string[]) {
     this.client = client
+
+    if (validProjects && validProjects.length > 0) {
+      // Build pattern that only matches specified projects
+      const projectsRegex = validProjects.join("|")
+      this.ticketPattern = new RegExp(`\\b((?:${projectsRegex})-\\d+)\\b`)
+    } else {
+      this.ticketPattern = DEFAULT_TICKET_PATTERN
+    }
   }
 
   /**
@@ -149,7 +176,7 @@ export class TicketExtractor {
    * @returns The first ticket match, or `null` if not found
    */
   private extractFromText(text: string): string | null {
-    const match = text.match(TICKET_PATTERN)
+    const match = text.match(this.ticketPattern)
 
     return match?.[1] ?? null
   }

package/src/services/TicketResolver.ts

@@ -6,6 +6,8 @@ import type { ResolvedTicketInfo } from "../types/ResolvedTicketInfo"
 import type { TimeTrackingConfig } from "../types/TimeTrackingConfig"
 import type { TicketExtractor } from "./TicketExtractor"
 
+import { AgentMatcher } from "../utils/AgentMatcher"
+
 /**
  * Resolves tickets and account keys using fallback hierarchy.
  *
@@ -65,11 +67,13 @@ export class TicketResolver {
       }
     }
 
-    // 2. Try agent default
-    if (agentName && this.config.agent_defaults?.[agentName]) {
+    // 2. Try agent default (tolerant matching: with or without @ prefix)
+    const agentKey = agentName ? this.findAgentKey(agentName) : null
+
+    if (agentKey) {
       return {
-        ticket: this.config.agent_defaults[agentName].issue_key,
-        accountKey: this.resolveAccountKey(agentName),
+        ticket: this.config.agent_defaults![agentKey].issue_key,
+        accountKey: this.resolveAccountKey(agentKey),
       }
     }
 
@@ -88,16 +92,41 @@ export class TicketResolver {
     }
   }
 
+  /**
+   * Finds the matching config key for an agent name.
+   *
+   * @param agentName - The agent name from the SDK
+   * @returns The matching config key, or `null` if not found
+   *
+   * @remarks
+   * Normalizes both the agent name and config keys to ensure
+   * matching works regardless of @ prefix.
+   */
+  private findAgentKey(agentName: string): string | null {
+    const defaults = this.config.agent_defaults
+
+    if (!defaults) {
+      return null
+    }
+
+    const normalized = AgentMatcher.normalize(agentName)
+    const key = Object.keys(defaults).find(
+      (k) => AgentMatcher.normalize(k) === normalized
+    )
+
+    return key ?? null
+  }
+
   /**
    * Resolves account key using fallback hierarchy.
    *
-   * @param agentName - The agent name, or `null`
+   * @param agentKey - The agent config key, or `null`
    * @returns Resolved Tempo account key
    */
-  private resolveAccountKey(agentName: string | null): string {
+  private resolveAccountKey(agentKey: string | null): string {
     // 1. Agent-specific account_key
-    if (agentName && this.config.agent_defaults?.[agentName]?.account_key) {
-      return this.config.agent_defaults[agentName].account_key!
+    if (agentKey && this.config.agent_defaults?.[agentKey]?.account_key) {
+      return this.config.agent_defaults[agentKey].account_key!
     }
 
     // 2. Global default account_key (required)

package/src/types/TimeTrackingConfig.ts

@@ -51,6 +51,16 @@ export interface TimeTrackingJsonConfig {
    * Agent names should include the "@" prefix (e.g., "@internal").
    */
   ignored_agents?: string[]
+
+  /**
+   * Whitelist of valid JIRA project keys.
+   *
+   * @remarks
+   * If set, only tickets from these projects are recognized.
+   * If not set, any ticket matching the default pattern is accepted.
+   * Project keys should be uppercase with at least 2 letters (e.g., "PROJ", "SOSO").
+   */
+  valid_projects?: string[]
 }
 
 /**

package/src/utils/AgentMatcher.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Utility for normalizing agent names.
+ */
+
+/**
+ * Normalizes agent names to a canonical form.
+ *
+ * @remarks
+ * Agent names can appear with or without the "@" prefix
+ * depending on the source (SDK, config, user input).
+ * This class ensures consistent comparison by normalizing
+ * all agent names to the "@<name>" format.
+ */
+export class AgentMatcher {
+  /**
+   * Normalizes an agent name to canonical form (with @ prefix).
+   *
+   * @param agentName - The agent name to normalize
+   * @returns The normalized agent name with @ prefix
+   *
+   * @example
+   * ```typescript
+   * AgentMatcher.normalize("developer")      // → "@developer"
+   * AgentMatcher.normalize("@developer")     // → "@developer"
+   * AgentMatcher.normalize("@time-tracking") // → "@time-tracking"
+   * ```
+   */
+  static normalize(agentName: string): string {
+    return agentName.startsWith("@") ? agentName : `@${agentName}`
+  }
+}