@comfanion/usethis_todo 0.1.5 → 0.1.7-dev.0

package/README.md

@@ -1,16 +1,33 @@
-# @comfanion/usethis_todo
+# 📋 @comfanion/usethis_todo
 
-OpenCode plugin that provides enhanced TODO tools (dual storage + dependency graph).
+**Smart TODO management with dependency graphs and priority tracking**
 
-## Tools
+Stop juggling tasks in your head — let the graph show you what to do next!
 
-- `usethis_todo_write`
-- `usethis_todo_read`
-- `usethis_todo_read_five`
-- `usethis_todo_read_by_id`
-- `usethis_todo_update`
+---
 
-## Install (OpenCode)
+## ✨ What is this?
+
+An OpenCode plugin that transforms TODO lists into **intelligent task graphs**:
+
+- 🎯 **Dependency tracking** — tasks know what blocks them
+- 📊 **Visual graph analysis** — see available, blocked, and parallel tasks
+- 🔥 **Priority system** — CRIT | HIGH | MED | LOW with auto-sorting
+- 🏗️ **Hierarchical IDs** — E01-S01-T01 (Epic → Story → Task)
+- 💾 **Dual storage** — enhanced features + native TUI integration
+- 🚀 **Smart transitions** — auto-promote tasks when conditions are met
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install @comfanion/usethis_todo
+```
+
+### Configuration
 
 Add to `opencode.json`:
 
@@ -19,3 +36,575 @@ Add to `opencode.json`:
   "plugin": ["@comfanion/usethis_todo"]
 }
 ```
+
+### First TODO
+
+```javascript
+usethis_todo_write({
+  todos: [
+    {
+      id: "E01-S01-T01",
+      content: "Setup database schema",
+      status: "todo",
+      priority: "HIGH"
+    },
+    {
+      id: "E01-S01-T02",
+      content: "Create API endpoints",
+      status: "todo",
+      priority: "HIGH",
+      blockedBy: ["E01-S01-T01"]  // Waits for T01
+    }
+  ]
+})
+```
+
+**Output:**
+```
+TODO Graph [0/2 done, 0 in progress]
+
+All Tasks:
+- E01
+  - E01-S01
+    - ○ 🟠 E01-S01-T01: Setup database schema
+    - ⊗ 🟠 E01-S01-T02: Create API endpoints ← E01-S01-T01
+
+Available Now:
+- E01
+  - E01-S01
+    - ○ 🟠 E01-S01-T01: Setup database schema
+
+Blocked:
+- E01
+  - E01-S01
+    - ⊗ 🟠 E01-S01-T02: Create API endpoints ← E01-S01-T01
+```
+
+---
+
+## 🎯 Core Features
+
+### 1. Dependency Graph
+
+Tasks can depend on other tasks. The plugin automatically:
+- ✅ Shows which tasks are **available** (no blockers)
+- ⊗ Shows which tasks are **blocked** (waiting on others)
+- 🔗 Resolves **transitive dependencies** (A → B → C)
+- ⚡ Identifies **parallel tasks** (can work on simultaneously)
+
+**Example:**
+```javascript
+usethis_todo_write({
+  todos: [
+    { id: "T01", content: "Design API", status: "done", priority: "HIGH" },
+    { id: "T02", content: "Implement API", status: "todo", priority: "HIGH", blockedBy: ["T01"] },
+    { id: "T03", content: "Write tests", status: "todo", priority: "MED", blockedBy: ["T02"] },
+    { id: "T04", content: "Setup CI/CD", status: "todo", priority: "MED" }  // Parallel!
+  ]
+})
+```
+
+**Graph shows:**
+- **Available:** T02 (T01 done), T04 (no blockers)
+- **Blocked:** T03 (waits for T02)
+- **Parallel:** T02 and T04 can be done simultaneously
+
+### 2. Priority System
+
+Four priority levels with visual indicators:
+
+| Priority | Icon | Use Case |
+|----------|------|----------|
+| `CRIT` | 🔴 | Production down, security issue |
+| `HIGH` | 🟠 | Sprint goal, blocking others |
+| `MED` | 🟡 | Normal work (default) |
+| `LOW` | 🟢 | Nice to have, refactoring |
+
+Tasks are **auto-sorted** by priority in all views.
+
+### 3. Hierarchical IDs
+
+Organize tasks in 3 levels:
+
+```
+E01-S01-T01
+│   │   └── Task 01
+│   └────── Story 01
+└────────── Epic 01
+```
+
+**Benefits:**
+- 📁 Nested display (epics → stories → tasks)
+- 🔍 Easy filtering (all tasks in E01-S01)
+- 📊 Progress tracking per epic/story
+
+### 4. Status Lifecycle
+
+```
+todo → in_progress → ready → done
+  ↓         ↓          ↓       ↓
+  ○         ⚙          ⏳      ✓
+```
+
+**Auto-transitions:**
+- `ready` → `done` when `releases` field is set
+- Blocked tasks show `⊗` icon (even if status is `todo`)
+
+### 5. Release Tracking
+
+Mark tasks as part of releases:
+
+```javascript
+usethis_todo_update({
+  todos: [{
+    id: "E01-S01-T01",
+    status: "ready",
+    releases: ["v1.2.0"]  // Auto-promotes to "done"
+  }]
+})
+```
+
+---
+
+## 🛠️ Tools Reference
+
+### `usethis_todo_write`
+
+Create or replace entire TODO list.
+
+```javascript
+usethis_todo_write({
+  todos: [
+    {
+      id: "E01-S01-T01",              // Required: Hierarchical ID
+      content: "Task summary",         // Required: Short description
+      description: "Full details...",  // Optional: Long description
+      status: "todo",                  // Required: todo | in_progress | ready | done
+      priority: "HIGH",                // Required: CRIT | HIGH | MED | LOW
+      blockedBy: ["E01-S01-T02"],     // Optional: Dependency IDs
+      releases: ["v1.0.0"]            // Optional: Release tags
+    }
+  ]
+})
+```
+
+**Returns:** Full graph analysis
+
+### `usethis_todo_read`
+
+Read all tasks with graph analysis.
+
+```javascript
+usethis_todo_read()
+```
+
+**Returns:**
+- All tasks (nested by epic/story)
+- Available tasks (ready to work on)
+- Blocked tasks (waiting on dependencies)
+- Progress stats (X/Y done, Z in progress)
+
+### `usethis_todo_read_five`
+
+Get next 5 available tasks (smart view).
+
+```javascript
+usethis_todo_read_five()
+```
+
+**Returns:**
+- Top 5 tasks by priority
+- Resolved blockers (what they depend on)
+- Missing dependencies (if any)
+
+**Perfect for:** "What should I work on next?"
+
+### `usethis_todo_read_by_id`
+
+Get details for specific task.
+
+```javascript
+usethis_todo_read_by_id({ id: "E01-S01-T01" })
+```
+
+**Returns:**
+- Task details
+- Full dependency chain
+- Missing dependencies
+
+### `usethis_todo_update`
+
+Update one or more tasks (merge mode).
+
+```javascript
+usethis_todo_update({
+  todos: [
+    {
+      id: "E01-S01-T01",
+      status: "done"  // Only update status, keep other fields
+    },
+    {
+      id: "E01-S01-T02",
+      status: "in_progress",
+      priority: "CRIT"  // Update multiple fields
+    }
+  ]
+})
+```
+
+**Returns:** Updated graph
+
+---
+
+## 🎨 Usage Examples
+
+### Example 1: Sprint Planning
+
+```javascript
+// Create sprint tasks
+usethis_todo_write({
+  todos: [
+    // Epic 01: User Authentication
+    { id: "E01-S01-T01", content: "Design auth API", status: "done", priority: "HIGH" },
+    { id: "E01-S01-T02", content: "Implement JWT", status: "in_progress", priority: "HIGH", blockedBy: ["E01-S01-T01"] },
+    { id: "E01-S01-T03", content: "Add refresh tokens", status: "todo", priority: "MED", blockedBy: ["E01-S01-T02"] },
+    
+    // Epic 02: User Profile (parallel work)
+    { id: "E02-S01-T01", content: "Design profile schema", status: "todo", priority: "MED" },
+    { id: "E02-S01-T02", content: "Create profile API", status: "todo", priority: "MED", blockedBy: ["E02-S01-T01"] }
+  ]
+})
+```
+
+**Graph shows:**
+- **Available:** E01-S01-T02 (in progress), E02-S01-T01 (can start)
+- **Blocked:** E01-S01-T03, E02-S01-T02
+- **Parallel:** E01 and E02 can progress simultaneously
+
+### Example 2: Daily Workflow
+
+```javascript
+// Morning: What's next?
+usethis_todo_read_five()
+// → Shows top 5 tasks by priority
+
+// Start working
+usethis_todo_update({
+  todos: [{ id: "E01-S01-T02", status: "in_progress" }]
+})
+
+// Finish task
+usethis_todo_update({
+  todos: [{ id: "E01-S01-T02", status: "done" }]
+})
+
+// Check what unblocked
+usethis_todo_read_five()
+// → E01-S01-T03 now available!
+```
+
+### Example 3: Bug Triage
+
+```javascript
+// Critical bug found!
+usethis_todo_update({
+  todos: [{
+    id: "BUG-001",
+    content: "Fix login crash",
+    status: "todo",
+    priority: "CRIT"  // Jumps to top of queue
+  }]
+})
+
+usethis_todo_read_five()
+// → BUG-001 is first (CRIT priority)
+```
+
+### Example 4: Release Management
+
+```javascript
+// Mark tasks for release
+usethis_todo_update({
+  todos: [
+    { id: "E01-S01-T01", status: "ready", releases: ["v1.0.0"] },
+    { id: "E01-S01-T02", status: "ready", releases: ["v1.0.0"] }
+  ]
+})
+// → Auto-promotes to "done" when releases set
+
+// Check release progress
+usethis_todo_read()
+// → See all tasks tagged with v1.0.0
+```
+
+### Example 5: Complex Dependencies
+
+```javascript
+usethis_todo_write({
+  todos: [
+    { id: "T01", content: "Database schema", status: "done", priority: "HIGH" },
+    { id: "T02", content: "API layer", status: "done", priority: "HIGH", blockedBy: ["T01"] },
+    { id: "T03", content: "Business logic", status: "todo", priority: "HIGH", blockedBy: ["T02"] },
+    { id: "T04", content: "UI components", status: "todo", priority: "MED", blockedBy: ["T03"] },
+    { id: "T05", content: "Integration tests", status: "todo", priority: "MED", blockedBy: ["T04"] }
+  ]
+})
+
+// Check specific task
+usethis_todo_read_by_id({ id: "T05" })
+// → Shows full chain: T05 ← T04 ← T03 ← T02 ← T01
+```
+
+---
+
+## 📦 Storage
+
+### Dual Storage System
+
+The plugin writes to **two locations**:
+
+#### 1. Enhanced Storage (Project-local)
+```
+.opencode/
+  session-todo/
+    {session-id}.json    # Full data with dependencies
+  todo.log               # Action log
+```
+
+**Contains:**
+- Full task data (description, blockedBy, releases)
+- Timestamps (createdAt, updatedAt)
+- All custom fields
+
+#### 2. Native Storage (TUI Integration)
+```
+~/.local/share/opencode/storage/todo/{session-id}.json
+# or
+~/Library/Application Support/opencode/storage/todo/{session-id}.json
+```
+
+**Contains:**
+- Simplified format for OpenCode TUI
+- Status/priority mapped to native values
+- Dependencies shown in content field
+
+**Why dual storage?**
+- ✅ Enhanced features (graph, dependencies)
+- ✅ Native TUI display (sidebar integration)
+- ✅ Best of both worlds!
+
+---
+
+## 🎨 Visual Indicators
+
+### Status Icons
+
+| Icon | Status | Meaning |
+|------|--------|---------|
+| ○ | `todo` | Not started |
+| ⚙ | `in_progress` | Working on it |
+| ⏳ | `ready` | Done, awaiting release |
+| ✓ | `done` | Completed |
+| ✗ | `cancelled` | Abandoned |
+| ⊗ | (blocked) | Has active blockers |
+
+### Priority Icons
+
+| Icon | Priority | Color |
+|------|----------|-------|
+| 🔴 | CRIT | Red |
+| 🟠 | HIGH | Orange |
+| 🟡 | MED | Yellow |
+| 🟢 | LOW | Green |
+
+---
+
+## 🧠 Smart Features
+
+### 1. Auto-Promotion
+
+Tasks automatically transition when conditions are met:
+
+```javascript
+// Task in "ready" status
+{ id: "T01", status: "ready", releases: [] }
+
+// Add release tag
+usethis_todo_update({
+  todos: [{ id: "T01", releases: ["v1.0.0"] }]
+})
+
+// → Auto-promotes to "done"!
+```
+
+### 2. Transitive Dependencies
+
+The plugin resolves entire dependency chains:
+
+```javascript
+// T03 depends on T02, T02 depends on T01
+usethis_todo_read_by_id({ id: "T03" })
+
+// Shows full chain:
+// Blocked By (resolved):
+// - T02 (in_progress)
+// - T01 (done)
+```
+
+### 3. Parallel Detection
+
+Identifies tasks that can be worked on simultaneously:
+
+```javascript
+// Graph analysis shows:
+// Parallel groups:
+// - [T02, T04, T05]  ← Can all start now
+// - [T03, T06]       ← Can start after T02 done
+```
+
+### 4. Missing Dependency Detection
+
+Warns about broken references:
+
+```javascript
+{ id: "T01", blockedBy: ["T99"] }  // T99 doesn't exist
+
+usethis_todo_read_by_id({ id: "T01" })
+// → Blocked By missing: T99
+```
+
+---
+
+## 🔧 Advanced Usage
+
+### Custom ID Schemes
+
+While hierarchical IDs are recommended, you can use any format:
+
+```javascript
+// Hierarchical (recommended)
+{ id: "E01-S01-T01" }  // Epic-Story-Task
+
+// Flat
+{ id: "TASK-001" }
+
+// Custom
+{ id: "AUTH-LOGIN-JWT" }
+```
+
+**Note:** Hierarchical IDs get nested display, others show flat.
+
+### Filtering by Status
+
+```javascript
+// Get all in-progress tasks
+const todos = await usethis_todo_read()
+const wip = todos.filter(t => t.status === "in_progress")
+```
+
+### Progress Tracking
+
+```javascript
+// Track epic progress
+const todos = await usethis_todo_read()
+const epic01 = todos.filter(t => t.id.startsWith("E01-"))
+const done = epic01.filter(t => t.status === "done").length
+const total = epic01.length
+console.log(`Epic 01: ${done}/${total} done`)
+```
+
+---
+
+## 🐛 Debugging
+
+### Enable Logging
+
+All operations are logged to `.opencode/todo.log`:
+
+```
+[2024-01-15T10:30:00.000Z] WRITE: Created/Updated 5 tasks in session abc123
+[2024-01-15T10:31:00.000Z] UPDATE: Updated 1 task(s) in session abc123
+[2024-01-15T10:32:00.000Z] READ_FIVE: Read next 5 tasks (total ready: 12)
+```
+
+### Check Storage
+
+```bash
+# Enhanced storage
+cat .opencode/session-todo/{session-id}.json
+
+# Native storage (macOS)
+cat ~/Library/Application\ Support/opencode/storage/todo/{session-id}.json
+
+# Native storage (Linux)
+cat ~/.local/share/opencode/storage/todo/{session-id}.json
+```
+
+### Validate Dependencies
+
+```javascript
+// Check for circular dependencies
+usethis_todo_read()
+// → Graph analysis will show if tasks are mutually blocked
+```
+
+---
+
+## 🌟 Advantages
+
+### Compared to Simple TODO Lists
+
+| Feature | Simple TODO | usethis_todo |
+|---------|-------------|--------------|
+| Task list | ✅ | ✅ |
+| Dependencies | ❌ | ✅ |
+| Priority sorting | ❌ | ✅ |
+| Graph analysis | ❌ | ✅ |
+| Parallel detection | ❌ | ✅ |
+| Hierarchical IDs | ❌ | ✅ |
+| Auto-transitions | ❌ | ✅ |
+| Release tracking | ❌ | ✅ |
+
+### Compared to Project Management Tools
+
+| Feature | Jira/Asana | usethis_todo |
+|---------|------------|--------------|
+| In your editor | ❌ | ✅ |
+| Offline | ❌ | ✅ |
+| Free | ❌ | ✅ |
+| Fast | 🐌 | ⚡ |
+| No context switch | ❌ | ✅ |
+| Version controlled | ❌ | ✅ (project-local) |
+
+---
+
+## 📊 Technical Details
+
+- **Storage format:** JSON
+- **Session isolation:** Tasks are per-session (multi-session support)
+- **Dependency resolution:** Recursive graph traversal
+- **Priority sorting:** Stable sort (CRIT → HIGH → MED → LOW → ID)
+- **Status normalization:** Backward-compatible with old formats
+- **TUI integration:** Automatic sync to native storage
+
+---
+
+## 🤝 Contributing
+
+Found a bug? Have an idea? Open an issue or PR!
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 🎉 Authors
+
+Made with ❤️ by the **Comfanion** team
+
+---
+
+**Work smart, not hard — let the graph guide you!** 🚀

package/package.json

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

package/tools.ts

@@ -29,6 +29,45 @@ import fs from "fs/promises"
 // Types
 // ============================================================================
 
+interface TodoFile {
+  path: string                      // File path (relative to project root)
+  role: "input" | "output" | "test" | "doc" | "config" | "main" | "graph"
+  addedAt: string                   // ISO timestamp when linked
+  addedBy: "manual" | "auto"       // How it was added
+  lastAccessed?: string             // Last read/write timestamp
+  toolIds?: number[]                // Tool call IDs that touched this file
+  preserve?: boolean                // Don't prune even on TODO complete
+}
+
+interface TodoTool {
+  toolName: string                  // Tool name (read, write, search, etc.)
+  callId: number                    // Tool call ID in session history
+  timestamp: string                 // ISO timestamp
+  filePath?: string                 // If tool operated on file
+  status: "success" | "error"       // Tool execution status
+  tokens?: number                   // Tokens used by this tool result
+}
+
+interface TodoSearch {
+  query: string                     // Search query text
+  toolId: number                    // search() tool call ID
+  resultsCount: number              // Number of results returned
+  timestamp: string                 // ISO timestamp
+  topResults?: string[]             // Top file paths found
+}
+
+interface TodoContext {
+  totalTokens: number               // Total tokens in all linked tools
+  createdAt: string                 // Task creation timestamp
+  startedAt?: string                // When status → in_progress
+  completedAt?: string              // When status → completed
+  estimatedCleanup: number          // Estimated tokens prunable on complete
+  
+  // Tracking
+  activeTracking: boolean           // Is Mind currently tracking this TODO?
+  lastSync: string                  // Last time Mind synced metadata
+}
+
 interface Todo {
   id: string              // E01-S01-T01
   content: string         // Short task summary
@@ -39,6 +78,19 @@ interface Todo {
   blockedBy?: string[]    // IDs of blocking tasks
   createdAt?: number
   updatedAt?: number
+  
+  // Mind extensions (backward compatible - optional)
+  files?: TodoFile[]                // Associated files
+  tools?: TodoTool[]                // Associated tool calls
+  searches?: TodoSearch[]           // Associated searches
+  context?: TodoContext             // Context metadata
+  
+  // Cleanup configuration (optional)
+  cleanup?: {
+    onComplete?: "auto" | "manual" | "extract"
+    preserveFiles?: string[]        // Glob patterns to preserve
+    preserveTools?: string[]        // Tool names to preserve
+  }
 }
 
 interface NativeTodo {
@@ -260,11 +312,21 @@ function normalizeTodo(input: any): Todo {
   // Auto transition: ready -> done when releases exist
   const promotedStatus = status === "ready" && releases?.length ? "done" : status
 
-  return {
+  // Initialize Mind extensions if provided (backward compatible)
+  const normalized: Todo = {
     ...input,
     status: promotedStatus,
     releases,
   }
+
+  // Preserve existing Mind extensions if they exist
+  if (input.files) normalized.files = input.files
+  if (input.tools) normalized.tools = input.tools
+  if (input.searches) normalized.searches = input.searches
+  if (input.context) normalized.context = input.context
+  if (input.cleanup) normalized.cleanup = input.cleanup
+
+  return normalized
 }
 
 function prioRank(p?: string): number {
@@ -294,9 +356,14 @@ function todoLine(todo: Todo, byId: Map<string, Todo>): string {
   const desc = todo.description?.trim() ? ` — ${todo.description.trim()}` : ""
   const rel = todo.releases?.length ? ` [rel: ${todo.releases.join(", ")}]` : ""
   const deps = todo.blockedBy?.length ? ` ← ${todo.blockedBy.join(", ")}` : ""
+  
+  // Mind extensions
+  const files = todo.files?.length ? ` 📄${todo.files.length}` : ""
+  const tokens = todo.context?.totalTokens ? ` (${todo.context.totalTokens}t)` : ""
+  
   const ns = normalizeStatus(todo.status)
   const icon = isBlocked(todo, byId) ? "⊗" : SI(ns)
-  return `${icon} ${PE(todo.priority)} ${todo.id}: ${todo.content}${desc}${rel}${deps}`
+  return `${icon} ${PE(todo.priority)} ${todo.id}: ${todo.content}${desc}${rel}${files}${tokens}${deps}`
 }
 
 function renderNestedTodoList(todos: Todo[], allTodos?: Todo[]): string {
@@ -411,17 +478,17 @@ function formatGraph(graph: TodoGraph): string {
 // ============================================================================
 
 export const write = tool({
-  description: "Create or update TODO list. TODOv2 (Prefer this instead of TODO)",
+  description: "Create or update TODO list. Use this for TODO. For better performance use ID for task relation",
   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("Release identifiers"),
+        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("Set IDs for AUTO Release task from ready -> done(after review)"),
         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"),
+        blockedBy: tool.schema.array(tool.schema.string()).optional().describe("IDs of blocking tasks. this help you understand scope better"),
       }),
     ).describe("Array of todos"),
   },