@comfanion/usethis_todo 0.1.16-dev.1 → 0.1.16-dev.2

package/index.ts

@@ -2,7 +2,7 @@ import type { Plugin } from "@opencode-ai/plugin"
 import path from "path"
 import fs from "fs/promises"
 
-import { write, read, read_five, read_by_id, update, setNativeStorageBase } from "./tools"
+import { write, read, read_five, read_by_id, setNativeStorageBase } from "./tools"
 
 interface TodoPruneState {
   lastToolCallId: string | null
@@ -37,13 +37,10 @@ const UsethisTodoPlugin: Plugin = async ({ directory, client }) => {
       if (!state?.lastToolCallId) return
 
       const prunedToolNames = new Set([
-        "usethis_todo_write",
-        "usethis_todo_update",
-        "usethis_todo_read",
-        "usethis_todo_read_five",
-        "usethis_todo_read_by_id",
         "todowrite",
         "todoread",
+        "usethis_todo_read_five",
+        "usethis_todo_read_by_id",
       ])
 
       // Collect all TODO-related tool parts
@@ -69,18 +66,19 @@ const UsethisTodoPlugin: Plugin = async ({ directory, client }) => {
     },
 
     tool: {
-      // Enhanced tools only — NO native overrides
-      // Native todowrite/todoread stay untouched → Bus.publish fires → sidebar works
-      usethis_todo_write: write,
-      usethis_todo_read: read,
+      // Native overrides → tool named "todowrite"/"todoread" completing
+      // triggers Bus.publish("todo.updated") → sidebar refresh
+      todowrite: write,
+      todoread: read,
+      // Extra tools (no native equivalent)
       usethis_todo_read_five: read_five,
       usethis_todo_read_by_id: read_by_id,
-      usethis_todo_update: update,
     },
 
-    // Set nicer titles in TUI + track prune state (enhanced tools only)
+    // Set nicer titles in TUI + track prune state
     "tool.execute.after": async (input, output) => {
-      if (!input.tool.startsWith("usethis_todo_")) return
+      const ourTools = new Set(["todowrite", "todoread", "usethis_todo_read_five", "usethis_todo_read_by_id"])
+      if (!ourTools.has(input.tool)) return
 
       // Update prune state with latest call ID
       const sessionID = input.sessionID
@@ -93,13 +91,10 @@ const UsethisTodoPlugin: Plugin = async ({ directory, client }) => {
       const out = output.output || ""
 
       // Set a nicer title in TUI
-      if (input.tool === "usethis_todo_write") {
+      if (input.tool === "todowrite") {
         const match = out.match(/\[(\d+)\/(\d+) done/)
         output.title = match ? `TODO: ${match[2]} tasks` : "TODO updated"
-      } else if (input.tool === "usethis_todo_update") {
-        const match = out.match(/^✅ (.+)$/m)
-        output.title = match ? match[1] : "Task updated"
-      } else if (input.tool === "usethis_todo_read") {
+      } else if (input.tool === "todoread") {
         const match = out.match(/\[(\d+)\/(\d+) done, (\d+) in progress\]/)
         output.title = match ? `TODO [${match[1]}/${match[2]} done]` : "TODO list"
       } else if (input.tool === "usethis_todo_read_five") {
@@ -107,24 +102,6 @@ const UsethisTodoPlugin: Plugin = async ({ directory, client }) => {
       } else if (input.tool === "usethis_todo_read_by_id") {
         output.title = "Task details"
       }
-
-      // Publish TODO snapshot into chat for write/update ops
-      const isWriteOp = input.tool === "usethis_todo_write"
-        || input.tool === "usethis_todo_update"
-      if (!isWriteOp) return
-
-      const text = ["## TODO", "", out].join("\n")
-      try {
-        await client?.session?.prompt?.({
-          path: { id: input.sessionID },
-          body: {
-            noReply: true,
-            parts: [{ type: "text", text }],
-          },
-        })
-      } catch {
-        // non-fatal
-      }
     },
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/usethis_todo",
-  "version": "0.1.16-dev.1",
+  "version": "0.1.16-dev.2",
   "description": "OpenCode plugin: enhanced TODO tools (dual storage + dependency graph)",
   "type": "module",
   "main": "./index.ts",

package/tools.ts

@@ -1,12 +1,11 @@
 /**
- * TODO Tool with Dependencies & Priority — v3 (unified storage)
+ * TODO Tool with Dependencies & Priority — v4 (unified storage)
  *
- * 4 commands:
- *   usethis_todo_write({ todos: [...] })    - create/update TODO list
- *   usethis_todo_read()                     - read TODO with graph analysis
- *   usethis_todo_read_five()           - read next 5 tasks with their blockers
- *   usethis_todo_read_by_id()           - read task by id with its blockers
- *   usethis_todo_update(id, field, value)   - update any task field
+ * 4 tools:
+ *   todowrite({ todos: [...], merge? })  - create/update TODO list (upsert by default)
+ *   todoread()                           - read TODO with graph analysis
+ *   todoread_five()                      - read next 5 tasks with their blockers
+ *   todoread_by_id({ id })               - read task by id with its blockers
  *
  * Storage:
  *   Unified: Native OpenCode storage (TUI compatible)
@@ -16,6 +15,7 @@
  *   - Stores FULL enhanced schema (blockedBy, priority, etc) in the native file
  *   - Maps statuses to native values (pending/completed) for Sidebar compatibility
  *   - Preserves original statuses in `usethisStatus` field
+ *   - merge (default: true) = upsert; merge: false = replace entire list
  */
 
 import { tool } from "@opencode-ai/plugin"
@@ -71,14 +71,14 @@ interface Todo {
   content: string         // Short task summary
   description?: string    // Full task description (optional)
   releases?: string[]     // Release identifiers (optional)
-  status: string          // todo | in_progress | ready | done
+  status: string          // pending | in_progress | ready | completed | cancelled
   priority: string        // CRIT | HIGH | MED | LOW
   blockedBy?: string[]    // IDs of blocking tasks
   createdAt?: number
   updatedAt?: number
   
   // Shadow fields for native compatibility
-  usethisStatus?: string    // The REAL status (todo, ready, etc)
+  usethisStatus?: string    // The REAL status (pending, ready, etc)
   usethisPriority?: string  // The REAL priority (CRIT, HIGH, etc)
 
   // Mind extensions (backward compatible - optional)
@@ -132,22 +132,28 @@ async function logAction(directory: string, action: string, details: string): Pr
 }
 
 async function getNativeDataDirs(): Promise<string[]> {
-  const dirs = new Set<string>()
-
-  // 1) xdg-basedir (what OpenCode itself uses)
-  // Removed dynamic import to avoid "chunk not found" errors in some environments
-  // relying on standard env vars and paths instead
+  const dirs: string[] = []
+  const seen = new Set<string>()
 
-  // 2) explicit XDG override
+  // 1) explicit XDG override (highest priority)
   if (process.env.XDG_DATA_HOME) {
-    dirs.add(process.env.XDG_DATA_HOME)
+    dirs.push(process.env.XDG_DATA_HOME)
+    seen.add(process.env.XDG_DATA_HOME)
   }
 
-  // 3) common fallbacks
-  dirs.add(path.join(os.homedir(), ".local", "share"))
-  dirs.add(path.join(os.homedir(), "Library", "Application Support"))
+  // 2) common fallbacks
+  const fallbacks = [
+    path.join(os.homedir(), ".local", "share"),
+    path.join(os.homedir(), "Library", "Application Support"),
+  ]
+  for (const dir of fallbacks) {
+    if (!seen.has(dir)) {
+      dirs.push(dir)
+      seen.add(dir)
+    }
+  }
 
-  return [...dirs]
+  return dirs
 }
 
 async function getStoragePaths(sid: string): Promise<string[]> {
@@ -172,30 +178,7 @@ async function getStoragePaths(sid: string): Promise<string[]> {
 // Mapping Logic (Enhanced <-> Native)
 // ============================================================================
 
-function toNativeStatus(status: string): string {
-  switch (status) {
-    case "todo": return "pending"
-    case "in_progress": return "in_progress"
-    case "ready": return "in_progress" // Sidebar has no 'ready'
-    case "done": return "completed"
-    case "cancelled": return "cancelled"
-    default: return "pending"
-  }
-}
 
-function fromNativeStatus(nativeStatus: string, originalStatus?: string): string {
-  // If we have the original status stored, prefer it
-  if (originalStatus) return originalStatus
-
-  // Otherwise map back (lossy for ready/todo distinction)
-  switch (nativeStatus) {
-    case "pending": return "todo"
-    case "in_progress": return "in_progress"
-    case "completed": return "done"
-    case "cancelled": return "cancelled"
-    default: return "todo"
-  }
-}
 
 function toNativePriority(priority: string): string {
   switch (priority) {
@@ -214,13 +197,13 @@ function toNativePriority(priority: string): string {
 async function readTodos(sid: string, directory?: string): Promise<Todo[]> {
   try {
     const storagePaths = await getStoragePaths(sid)
-    // Try to read from any available path, starting with authoritative
     for (const storagePath of storagePaths) {
       try {
         const raw = JSON.parse(await fs.readFile(storagePath, "utf-8"))
         if (Array.isArray(raw)) {
           return raw.map((t: any) => {
-            const realStatus = fromNativeStatus(t.status, t.usethisStatus)
+            // Restore "ready" status if it was saved
+            const realStatus = t.usethisStatus || t.status
             const realPriority = t.usethisPriority || t.priority
             return normalizeTodo({ ...t, status: realStatus, priority: realPriority })
           })
@@ -243,15 +226,17 @@ async function writeTodos(todos: Todo[], sid: string, directory?: string): Promi
   const enhancedPath = getEnhancedPath(sid, directory)
   
   const storageTodos = todos.map(t => {
-    const nativeStatus = toNativeStatus(t.status)
+    // Status is already native — map "ready" to "in_progress" for native storage
+    const nativeStatus = t.status === "ready" ? "in_progress" : t.status
     const nativePriority = toNativePriority(t.priority)
     
     return {
       ...t,
       status: nativeStatus,
       priority: nativePriority,
-      usethisStatus: t.status,
-      usethisPriority: t.priority
+      usethisPriority: t.priority,
+      // Keep "ready" status in a field so we can restore it on read
+      ...(t.status === "ready" ? { usethisStatus: "ready" } : {}),
     }
   })
 
@@ -289,11 +274,11 @@ function analyzeGraph(todos: Todo[]): TodoGraph {
   const availableTodos: Todo[] = []
 
   for (const todo of todos) {
-    if (normalizeStatus(todo.status) !== "todo") continue
+    if (normalizeStatus(todo.status) !== "pending") continue
     const activeBlockers = (todo.blockedBy || []).filter(id => {
       const b = todos.find(t => t.id === id)
       const bs = normalizeStatus(b?.status)
-      return b && bs !== "done" && bs !== "cancelled"
+      return b && bs !== "completed" && bs !== "cancelled"
     })
     if (activeBlockers.length === 0) {
       availableTodos.push(todo)
@@ -333,24 +318,24 @@ function analyzeGraph(todos: Todo[]): TodoGraph {
 // ============================================================================
 
 const PE = (p?: string) => p === "CRIT" ? "🔴" : p === "HIGH" ? "🟠" : p === "LOW" ? "🟢" : "🟡"
-const SI = (s: string) => s === "done" ? "✓" : s === "in_progress" ? "⚙" : s === "ready" ? "⏳" : s === "cancelled" ? "✗" : s === "todo" ? "○" : "·"
+const SI = (s: string) => s === "completed" ? "✓" : s === "in_progress" ? "⚙" : s === "ready" ? "⏳" : s === "cancelled" ? "✗" : s === "pending" ? "○" : "·"
 
 function normalizeStatus(input: unknown): string {
   const s = String(input || "").trim()
 
-  // New canonical set
-  if (s === "todo" || s === "in_progress" || s === "ready" || s === "done") return s
+  // Canonical set (aligned with native OpenCode)
+  if (s === "pending" || s === "in_progress" || s === "completed" || s === "cancelled") return s
 
-  // Back-compat (older versions)
-  if (s === "pending") return "todo"
-  if (s === "waiting_review" || s === "finished") return "ready"
-  if (s === "completed") return "done"
+  // Our extension
+  if (s === "ready") return "ready"
 
-  // Keep cancelled if it appears (native supports it)
-  if (s === "cancelled") return "cancelled"
+  // Back-compat (older versions used different names)
+  if (s === "todo") return "pending"
+  if (s === "done" || s === "finished") return "completed"
+  if (s === "waiting_review") return "ready"
 
   // Default
-  return "todo"
+  return "pending"
 }
 
 function normalizeReleases(input: unknown): string[] | undefined {
@@ -365,8 +350,8 @@ function normalizeTodo(input: any): Todo {
   const status = normalizeStatus(input?.status)
   const releases = normalizeReleases(input?.releases)
 
-  // Auto transition: ready -> done when releases exist
-  const promotedStatus = status === "ready" && releases?.length ? "done" : status
+  // Auto transition: ready -> completed when releases exist
+  const promotedStatus = status === "ready" && releases?.length ? "completed" : status
 
   // Initialize Mind extensions if provided (backward compatible)
   const normalized: Todo = {
@@ -401,13 +386,13 @@ function sortTodosForList(todos: Todo[]): Todo[] {
 
 function isBlocked(todo: Todo, byId: Map<string, Todo>): boolean {
   const s = normalizeStatus(todo.status)
-  if (s !== "todo") return false
+  if (s !== "pending") return false
   if (!todo.blockedBy?.length) return false
   for (const id of todo.blockedBy) {
     const b = byId.get(id)
     const bs = normalizeStatus(b?.status)
     if (!b) return true
-    if (bs !== "done" && bs !== "cancelled") return true
+    if (bs !== "completed" && bs !== "cancelled") return true
   }
   return false
 }
@@ -508,7 +493,7 @@ function resolveBlockers(todos: Todo[], rootIds: string[]): { blockers: Todo[];
 function formatGraph(graph: TodoGraph): string {
   const { todos } = graph
   const total = todos.length
-  const done = todos.filter(t => normalizeStatus(t.status) === "done").length
+  const done = todos.filter(t => normalizeStatus(t.status) === "completed").length
   const wip = todos.filter(t => normalizeStatus(t.status) === "in_progress").length
 
   const availableTodos = graph.available
@@ -538,37 +523,76 @@ function formatGraph(graph: TodoGraph): string {
 // ============================================================================
 
 export const write = tool({
-  description: "Create or update TODO list. Use this for TODO. For better performance use ID for task relation",
+  description: `Create or update TODO list. Use this for TODO. For better performance use ID for task relation.
+
+By default (merge: true) this upserts — only specified tasks are created/updated, all others are preserved.
+Set merge: false to replace the entire list.`,
   args: {
     todos: tool.schema.array(
       tool.schema.object({
         id: tool.schema.string().describe("Task ID in concat format: E01-S01-T01(for graph dependency)"),
         content: tool.schema.string().describe("Short task summary or title"),
         description: tool.schema.string().optional().describe("Full task description. Helps to remember what should be done"),
-        releases: tool.schema.array(tool.schema.string()).optional().describe("Task IDs that auto-promote this task from ready → done when set (e.g. subtask IDs that were completed)"),
-        status: tool.schema.string().describe("todo | in_progress | ready | done"),
+        releases: tool.schema.array(tool.schema.string()).optional().describe("Task IDs that auto-promote this task from ready → completed when set"),
+        status: tool.schema.string().describe("pending | in_progress | ready | completed | cancelled"),
         priority: tool.schema.string().describe("CRIT | HIGH | MED | LOW"),
         blockedBy: tool.schema.array(tool.schema.string()).optional().describe("IDs of blocking tasks. this help you understand scope better"),
       }),
     ).describe("Array of todos"),
+    merge: tool.schema.boolean().optional().default(true).describe("When true (default): merge/upsert — only updates specified tasks, preserves others. When false: replaces entire list."),
   },
   async execute(args, context) {
     const now = Date.now()
-    const todos = args.todos.map((t: any) => normalizeTodo({ ...t, createdAt: t.createdAt || now, updatedAt: now }))
-    await writeTodos(todos, context.sessionID, context.directory)
-    await logAction(context.directory, "write", `Created/Updated ${todos.length} tasks in session ${context.sessionID}`)
-    return formatGraph(analyzeGraph(todos))
+    
+    if (args.merge !== false) {
+      // MERGE mode (default): read existing, merge incoming
+      const existing = await readTodos(context.sessionID, context.directory)
+      const byId = new Map(existing.map(t => [t.id, t]))
+      
+      for (const incoming of args.todos) {
+        const normalizedIncoming: any = normalizeTodo(incoming)
+        const existingTodo = byId.get(normalizedIncoming.id)
+        if (existingTodo) {
+          Object.assign(existingTodo, normalizedIncoming)
+          existingTodo.updatedAt = now
+          existingTodo.status = normalizeTodo(existingTodo).status
+          existingTodo.releases = normalizeTodo(existingTodo).releases
+        } else {
+          byId.set(normalizedIncoming.id, normalizeTodo({ ...normalizedIncoming, createdAt: now, updatedAt: now }))
+        }
+      }
+      
+      const merged = [...byId.values()]
+      await writeTodos(merged, context.sessionID, context.directory)
+      await logAction(context.directory, "write-merge", `Merged ${args.todos.length} task(s) in session ${context.sessionID}`)
+      return formatGraph(analyzeGraph(merged))
+    } else {
+      // REPLACE mode: replace entire list
+      const todos = args.todos.map((t: any) => normalizeTodo({ ...t, createdAt: t.createdAt || now, updatedAt: now }))
+      await writeTodos(todos, context.sessionID, context.directory)
+      await logAction(context.directory, "write", `Created/Updated ${todos.length} tasks in session ${context.sessionID}`)
+      return formatGraph(analyzeGraph(todos))
+    }
   },
 })
 
 export const read_five = tool({
-  description: "Read current TODO list. Shows Next 5 tasks.",
+  description: `Read the next 5 actionable tasks — unblocked, sorted by priority.
+
+Returns:
+- Next 5: the top-priority unblocked tasks you can work on right now
+- Blocked By (resolved): full dependency chain for those tasks
+- Count of remaining tasks beyond the top 5
+
+Use this as your primary "what should I do next?" tool. More focused than usethis_todo_read() — shows only actionable items without the full list.
+
+Call this after completing a task to see what's next.`,
   args: {},
   async execute(_args, context) {
     const todos = await readTodos(context.sessionID, context.directory)
-    const ready = sortTodosForList(todos.filter(t => normalizeStatus(t.status) === "todo"))
+    const ready = sortTodosForList(todos.filter(t => normalizeStatus(t.status) === "pending"))
     await logAction(context.directory, "read_five", `Read next 5 tasks (total ready: ${ready.length})`)
-    if (ready.length === 0) return "No tasks in todo."
+    if (ready.length === 0) return "No tasks in pending."
 
     const items = ready.slice(0, 5)
 
@@ -598,7 +622,20 @@ export const read_five = tool({
 })
 
 export const read = tool({
-  description: "Read current TODO list. Shows all tasks.",
+  description: `Read the full TODO list with dependency graph analysis.
+
+Returns:
+- All Tasks: complete list grouped by epic/story hierarchy with status icons
+- Available Now: unblocked tasks ready to work on, sorted by priority
+- Blocked: tasks waiting on dependencies, showing what blocks them
+- Progress summary: [done/total done, N in progress]
+
+Use this to:
+- Review overall progress and plan next steps
+- Understand which tasks are blocked and why
+- Get the full picture before making decisions
+
+For a quick view of just the next actionable tasks, use usethis_todo_read_five() instead.`,
   args: {},
   async execute(_args, context) {
     const todos = await readTodos(context.sessionID, context.directory)
@@ -609,7 +646,14 @@ export const read = tool({
 })
 
 export const read_by_id = tool({
-  description: "Read task by id.",
+  description: `Read a single task by ID with its full dependency chain.
+
+Returns:
+- Task details: status, priority, description, content
+- Blocked By (resolved): complete chain of blockers (recursive — shows blockers of blockers)
+- Missing dependencies: IDs referenced in blockedBy that don't exist
+
+Use this to inspect a specific task's details and understand what's blocking it before starting work.`,
   args: {
     id: tool.schema.string().describe("Task ID"),
   },
@@ -641,43 +685,4 @@ export const read_by_id = tool({
   },
 })
 
-export const update = tool({
-  description: "Update task(s). Send 1 or many for update",
-  args: {
-    todos: tool.schema.array(
-      tool.schema.object({
-        id: tool.schema.string().describe("Task ID in concat format: E01-S01-T01"),
-        content: tool.schema.string().describe("Short task summary"),
-        description: tool.schema.string().optional().describe("Full task description"),
-        releases: tool.schema.array(tool.schema.string()).optional().describe("Task IDs that auto-promote this task from ready → done when set (e.g. subtask IDs that were completed)"),
-        status: tool.schema.string().describe("todo | in_progress | ready | done"),
-        priority: tool.schema.string().describe("CRIT | HIGH | MED | LOW"),
-        blockedBy: tool.schema.array(tool.schema.string()).optional().describe("IDs of blocking tasks(from todo -> blocked)"),
-      }),
-    ).describe("Array of todos to update"),
-  },
-  async execute(args, context) {
-    const todos = await readTodos(context.sessionID, context.directory)
-    const now = Date.now()
-    const byId = new Map(todos.map(t => [t.id, t]))
-
-    for (const incoming of args.todos) {
-      const normalizedIncoming: any = normalizeTodo(incoming)
-      const existing = byId.get(normalizedIncoming.id)
-      if (existing) {
-        Object.assign(existing, normalizedIncoming)
-        existing.updatedAt = now
-        // Ensure auto transition is applied after merge
-        existing.status = normalizeTodo(existing).status
-        existing.releases = normalizeTodo(existing).releases
-      } else {
-        byId.set(normalizedIncoming.id, normalizeTodo({ ...normalizedIncoming, createdAt: now, updatedAt: now }))
-      }
-    }
 
-    const merged = [...byId.values()]
-    await writeTodos(merged, context.sessionID, context.directory)
-    await logAction(context.directory, "update", `Updated ${args.todos.length} task(s) in session ${context.sessionID}`)
-    return `✅ Updated ${args.todos.length} task(s)\n\n${formatGraph(analyzeGraph(merged))}`
-  },
-})