@comfanion/usethis_todo 0.1.4 → 0.1.6

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/index.ts

@@ -2,7 +2,15 @@ import type { Plugin } from "@opencode-ai/plugin"
 
 import { write, read, read_five, read_by_id, update } from "./tools"
 
-const UsethisTodoPlugin: Plugin = async ({ client }) => {
+const UsethisTodoPlugin: Plugin = async ({ directory, client }) => {
+  // Ensure storage directory exists on init
+  try {
+    const todoDir = path.join(directory, ".opencode", "session-todo")
+    await fs.mkdir(todoDir, { recursive: true })
+  } catch {
+    // ignore
+  }
+
   return {
     tool: {
       usethis_todo_write: write,

package/package.json

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