octie-cli 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. package/README.md +523 -0
  2. package/dist/cli/commands/approve.d.ts +27 -0
  3. package/dist/cli/commands/approve.d.ts.map +1 -0
  4. package/dist/cli/commands/approve.js +119 -0
  5. package/dist/cli/commands/approve.js.map +1 -0
  6. package/dist/cli/commands/batch.d.ts +15 -0
  7. package/dist/cli/commands/batch.d.ts.map +1 -0
  8. package/dist/cli/commands/batch.js +521 -0
  9. package/dist/cli/commands/batch.js.map +1 -0
  10. package/dist/cli/commands/create.d.ts +9 -0
  11. package/dist/cli/commands/create.d.ts.map +1 -0
  12. package/dist/cli/commands/create.js +321 -0
  13. package/dist/cli/commands/create.js.map +1 -0
  14. package/dist/cli/commands/delete.d.ts +9 -0
  15. package/dist/cli/commands/delete.d.ts.map +1 -0
  16. package/dist/cli/commands/delete.js +143 -0
  17. package/dist/cli/commands/delete.js.map +1 -0
  18. package/dist/cli/commands/export.d.ts +9 -0
  19. package/dist/cli/commands/export.d.ts.map +1 -0
  20. package/dist/cli/commands/export.js +66 -0
  21. package/dist/cli/commands/export.js.map +1 -0
  22. package/dist/cli/commands/find.d.ts +16 -0
  23. package/dist/cli/commands/find.d.ts.map +1 -0
  24. package/dist/cli/commands/find.js +252 -0
  25. package/dist/cli/commands/find.js.map +1 -0
  26. package/dist/cli/commands/get.d.ts +9 -0
  27. package/dist/cli/commands/get.d.ts.map +1 -0
  28. package/dist/cli/commands/get.js +74 -0
  29. package/dist/cli/commands/get.js.map +1 -0
  30. package/dist/cli/commands/graph.d.ts +9 -0
  31. package/dist/cli/commands/graph.d.ts.map +1 -0
  32. package/dist/cli/commands/graph.js +200 -0
  33. package/dist/cli/commands/graph.js.map +1 -0
  34. package/dist/cli/commands/import.d.ts +9 -0
  35. package/dist/cli/commands/import.d.ts.map +1 -0
  36. package/dist/cli/commands/import.js +807 -0
  37. package/dist/cli/commands/import.js.map +1 -0
  38. package/dist/cli/commands/init.d.ts +9 -0
  39. package/dist/cli/commands/init.d.ts.map +1 -0
  40. package/dist/cli/commands/init.js +57 -0
  41. package/dist/cli/commands/init.js.map +1 -0
  42. package/dist/cli/commands/list.d.ts +9 -0
  43. package/dist/cli/commands/list.d.ts.map +1 -0
  44. package/dist/cli/commands/list.js +175 -0
  45. package/dist/cli/commands/list.js.map +1 -0
  46. package/dist/cli/commands/merge.d.ts +9 -0
  47. package/dist/cli/commands/merge.d.ts.map +1 -0
  48. package/dist/cli/commands/merge.js +113 -0
  49. package/dist/cli/commands/merge.js.map +1 -0
  50. package/dist/cli/commands/serve.d.ts +9 -0
  51. package/dist/cli/commands/serve.d.ts.map +1 -0
  52. package/dist/cli/commands/serve.js +94 -0
  53. package/dist/cli/commands/serve.js.map +1 -0
  54. package/dist/cli/commands/update.d.ts +9 -0
  55. package/dist/cli/commands/update.d.ts.map +1 -0
  56. package/dist/cli/commands/update.js +423 -0
  57. package/dist/cli/commands/update.js.map +1 -0
  58. package/dist/cli/commands/wire.d.ts +15 -0
  59. package/dist/cli/commands/wire.d.ts.map +1 -0
  60. package/dist/cli/commands/wire.js +164 -0
  61. package/dist/cli/commands/wire.js.map +1 -0
  62. package/dist/cli/index.d.ts +7 -0
  63. package/dist/cli/index.d.ts.map +1 -0
  64. package/dist/cli/index.js +100 -0
  65. package/dist/cli/index.js.map +1 -0
  66. package/dist/cli/output/json.d.ts +16 -0
  67. package/dist/cli/output/json.d.ts.map +1 -0
  68. package/dist/cli/output/json.js +29 -0
  69. package/dist/cli/output/json.js.map +1 -0
  70. package/dist/cli/output/markdown.d.ts +15 -0
  71. package/dist/cli/output/markdown.d.ts.map +1 -0
  72. package/dist/cli/output/markdown.js +206 -0
  73. package/dist/cli/output/markdown.js.map +1 -0
  74. package/dist/cli/output/table.d.ts +23 -0
  75. package/dist/cli/output/table.d.ts.map +1 -0
  76. package/dist/cli/output/table.js +150 -0
  77. package/dist/cli/output/table.js.map +1 -0
  78. package/dist/cli/utils/helpers.d.ts +126 -0
  79. package/dist/cli/utils/helpers.d.ts.map +1 -0
  80. package/dist/cli/utils/helpers.js +325 -0
  81. package/dist/cli/utils/helpers.js.map +1 -0
  82. package/dist/core/graph/algorithms.d.ts +11 -0
  83. package/dist/core/graph/algorithms.d.ts.map +1 -0
  84. package/dist/core/graph/algorithms.js +14 -0
  85. package/dist/core/graph/algorithms.js.map +1 -0
  86. package/dist/core/graph/cycle.d.ts +155 -0
  87. package/dist/core/graph/cycle.d.ts.map +1 -0
  88. package/dist/core/graph/cycle.js +297 -0
  89. package/dist/core/graph/cycle.js.map +1 -0
  90. package/dist/core/graph/index.d.ts +223 -0
  91. package/dist/core/graph/index.d.ts.map +1 -0
  92. package/dist/core/graph/index.js +475 -0
  93. package/dist/core/graph/index.js.map +1 -0
  94. package/dist/core/graph/operations.d.ts +240 -0
  95. package/dist/core/graph/operations.d.ts.map +1 -0
  96. package/dist/core/graph/operations.js +503 -0
  97. package/dist/core/graph/operations.js.map +1 -0
  98. package/dist/core/graph/sort.d.ts +76 -0
  99. package/dist/core/graph/sort.d.ts.map +1 -0
  100. package/dist/core/graph/sort.js +254 -0
  101. package/dist/core/graph/sort.js.map +1 -0
  102. package/dist/core/graph/traversal.d.ts +122 -0
  103. package/dist/core/graph/traversal.d.ts.map +1 -0
  104. package/dist/core/graph/traversal.js +336 -0
  105. package/dist/core/graph/traversal.js.map +1 -0
  106. package/dist/core/models/task-node.d.ts +328 -0
  107. package/dist/core/models/task-node.d.ts.map +1 -0
  108. package/dist/core/models/task-node.js +1090 -0
  109. package/dist/core/models/task-node.js.map +1 -0
  110. package/dist/core/registry/index.d.ts +102 -0
  111. package/dist/core/registry/index.d.ts.map +1 -0
  112. package/dist/core/registry/index.js +249 -0
  113. package/dist/core/registry/index.js.map +1 -0
  114. package/dist/core/registry/root-guard.d.ts +19 -0
  115. package/dist/core/registry/root-guard.d.ts.map +1 -0
  116. package/dist/core/registry/root-guard.js +28 -0
  117. package/dist/core/registry/root-guard.js.map +1 -0
  118. package/dist/core/storage/atomic-write.d.ts +181 -0
  119. package/dist/core/storage/atomic-write.d.ts.map +1 -0
  120. package/dist/core/storage/atomic-write.js +379 -0
  121. package/dist/core/storage/atomic-write.js.map +1 -0
  122. package/dist/core/storage/file-store.d.ts +148 -0
  123. package/dist/core/storage/file-store.d.ts.map +1 -0
  124. package/dist/core/storage/file-store.js +423 -0
  125. package/dist/core/storage/file-store.js.map +1 -0
  126. package/dist/core/storage/indexer.d.ts +138 -0
  127. package/dist/core/storage/indexer.d.ts.map +1 -0
  128. package/dist/core/storage/indexer.js +350 -0
  129. package/dist/core/storage/indexer.js.map +1 -0
  130. package/dist/core/utils/status-helpers.d.ts +59 -0
  131. package/dist/core/utils/status-helpers.d.ts.map +1 -0
  132. package/dist/core/utils/status-helpers.js +149 -0
  133. package/dist/core/utils/status-helpers.js.map +1 -0
  134. package/dist/index.d.ts +10 -0
  135. package/dist/index.d.ts.map +1 -0
  136. package/dist/index.js +10 -0
  137. package/dist/index.js.map +1 -0
  138. package/dist/types/index.d.ts +504 -0
  139. package/dist/types/index.d.ts.map +1 -0
  140. package/dist/types/index.js +182 -0
  141. package/dist/types/index.js.map +1 -0
  142. package/dist/web/routes/graph.d.ts +17 -0
  143. package/dist/web/routes/graph.d.ts.map +1 -0
  144. package/dist/web/routes/graph.js +277 -0
  145. package/dist/web/routes/graph.js.map +1 -0
  146. package/dist/web/routes/projects.d.ts +14 -0
  147. package/dist/web/routes/projects.d.ts.map +1 -0
  148. package/dist/web/routes/projects.js +102 -0
  149. package/dist/web/routes/projects.js.map +1 -0
  150. package/dist/web/routes/tasks.d.ts +17 -0
  151. package/dist/web/routes/tasks.d.ts.map +1 -0
  152. package/dist/web/routes/tasks.js +538 -0
  153. package/dist/web/routes/tasks.js.map +1 -0
  154. package/dist/web/server.d.ts +121 -0
  155. package/dist/web/server.d.ts.map +1 -0
  156. package/dist/web/server.js +389 -0
  157. package/dist/web/server.js.map +1 -0
  158. package/dist/web-ui/assets/index-BB0qvF1y.css +1 -0
  159. package/dist/web-ui/assets/index-Vmm72oKY.js +34 -0
  160. package/dist/web-ui/index.html +14 -0
  161. package/dist/web-ui/vite.svg +1 -0
  162. package/package.json +94 -0
package/README.md ADDED
@@ -0,0 +1,523 @@
1
+ # Octie
2
+
3
+ A graph-based task management system with CLI and web UI.
4
+
5
+ ## Overview
6
+
7
+ Octie is a project-oriented task management tool that uses directed graphs to represent task dependencies. It provides both a command-line interface for power users and a web interface for visualization.
8
+
9
+ ## Features
10
+
11
+ - **Graph-based task structure**: Tasks are nodes in a directed graph (DAG with optional loops)
12
+ - **Atomic task definitions**: Each task has comprehensive context including:
13
+ - Success criteria (quantitative, measurable)
14
+ - Deliverables (specific outputs)
15
+ - Blockers and dependencies
16
+ - Related files and notes
17
+ - Auto-managed timestamps (created_at, updated_at, completed_at)
18
+ - **Fast retrieval**: JSON-based storage with indexing for O(1) lookups
19
+ - **Dual output formats**: Markdown for AI consumption, JSON for visualization
20
+ - **CLI + Web UI**: Command-line tool with web-based visualization
21
+ - **Graph operations**: Add, remove, reconnect edges; cut, insert, merge tasks
22
+ - **Topological sorting**: Validated task ordering with cycle detection
23
+
24
+ ## Installation
25
+
26
+ ```bash
27
+ npm install -g octie
28
+ ```
29
+
30
+ ## Quick Start
31
+
32
+ ```bash
33
+ # Initialize a new project
34
+ octie init
35
+
36
+ # Create a task (interactive mode recommended)
37
+ octie create --interactive
38
+
39
+ # Create with flags
40
+ octie create \
41
+ --title "Setup database" \
42
+ --description "Create PostgreSQL database with migrations" \
43
+ --priority top \
44
+ --success-criterion "Database accepts connections" \
45
+ --success-criterion "Migrations run successfully" \
46
+ --deliverable "src/db/schema.sql"
47
+
48
+ # List tasks
49
+ octie list --status pending --priority top
50
+
51
+ # Get task details (multiple formats)
52
+ octie get <task-id> # Default table format
53
+ octie get <task-id> --format md # Markdown for AI
54
+ octie get <task-id> --format json # JSON for parsing
55
+
56
+ # Update task
57
+ octie update <task-id> --status in_progress
58
+
59
+ # Delete task
60
+ octie delete <task-id> --reconnect --force
61
+
62
+ # Start web UI
63
+ octie serve
64
+ ```
65
+
66
+ ## Development
67
+
68
+ ```bash
69
+ # Clone repository
70
+ git clone <repo-url>
71
+ cd task-driver/octie
72
+
73
+ # Install dependencies
74
+ npm install
75
+
76
+ # Build TypeScript
77
+ npm run build
78
+
79
+ # Run tests
80
+ npm test
81
+
82
+ # Run CLI in development mode
83
+ node dist/cli/index.js --help
84
+
85
+ # Start web UI server
86
+ npm run serve
87
+ ```
88
+
89
+ ## Project Structure
90
+
91
+ ```
92
+ octie/
93
+ ├── src/ # Source files
94
+ │ ├── cli/ # CLI interface
95
+ │ │ ├── commands/ # CLI commands (init, create, list, get, update, delete, merge, export, import, graph, serve)
96
+ │ │ └── utils/ # CLI helpers
97
+ │ ├── core/ # Core functionality
98
+ │ │ ├── graph/ # Graph data structures and algorithms
99
+ │ │ ├── models/ # Task node model
100
+ │ │ └── storage/ # File I/O and atomic writes
101
+ │ └── types/ # TypeScript type definitions
102
+ ├── tests/ # Test files
103
+ │ └── unit/cli/commands/ # CLI command tests
104
+ ├── web-ui/ # Web UI (React + Vite)
105
+ ├── dist/ # Compiled JavaScript
106
+ ├── cli.js # CLI entry point
107
+ ├── server.js # Web UI server
108
+ └── package.json
109
+ ```
110
+
111
+ ## CLI Commands Reference
112
+
113
+ ### Global Options
114
+
115
+ These options apply to all commands:
116
+
117
+ | Option | Description |
118
+ |--------|-------------|
119
+ | `--project <path>` | Specify project directory (default: current directory) |
120
+ | `--format <type>` | Output format: `table`, `json`, `md` |
121
+ | `--verbose` | Show detailed output |
122
+ | `--quiet` | Suppress non-essential output |
123
+
124
+ ### `octie init`
125
+
126
+ Initialize a new Octie project in the current or specified directory.
127
+
128
+ ```bash
129
+ octie init # Initialize in current directory
130
+ octie init --project ./my-project # Initialize in specific directory
131
+ ```
132
+
133
+ **Options:**
134
+ | Flag | Description |
135
+ |------|-------------|
136
+ | `--project <path>` | Directory to initialize (default: current) |
137
+
138
+ ### `octie create`
139
+
140
+ Create a new atomic task. All required fields must be provided.
141
+
142
+ ```bash
143
+ # Interactive mode (recommended)
144
+ octie create --interactive
145
+
146
+ # Command-line mode (all required fields)
147
+ octie create \
148
+ --title "Implement user authentication" \
149
+ --description "Create JWT-based authentication system with login, logout, and token refresh endpoints" \
150
+ --success-criterion "Login returns valid JWT on correct credentials" \
151
+ --success-criterion "Token refresh works correctly" \
152
+ --deliverable "src/auth/login.ts" \
153
+ --deliverable "tests/auth/login.test.ts" \
154
+ --priority top
155
+ ```
156
+
157
+ **Required Options:**
158
+ | Flag | Description | Validation |
159
+ |------|-------------|------------|
160
+ | `--title <string>` | Task title | 1-200 chars, must contain action verb |
161
+ | `--description <string>` | Detailed description | 50-10000 chars |
162
+ | `--success-criterion <text>` | Quantitative success criterion (repeatable) | Min 1, Max 10 |
163
+ | `--deliverable <text>` | Expected output (repeatable) | Min 1, Max 5 |
164
+
165
+ **Optional Options:**
166
+ | Flag | Description |
167
+ |------|-------------|
168
+ | `--priority <level>` | `top`, `second`, or `later` (default: `second`) |
169
+ | `--blockers <ids>` | Comma-separated task IDs that block this task |
170
+ | `--dependencies <ids>` | Comma-separated soft dependency task IDs |
171
+ | `--related-files <paths>` | Comma-separated file paths |
172
+ | `--notes <text>` | Additional context |
173
+ | `--interactive` | Use interactive prompts |
174
+
175
+ **Atomic Task Validation:**
176
+ Tasks must be specific, executable, and verifiable. The CLI will reject:
177
+ - Titles without action verbs (implement, create, fix, etc.)
178
+ - Vague titles ("fix stuff", "do things")
179
+ - Descriptions under 50 characters
180
+ - More than 10 success criteria (suggests non-atomic)
181
+ - More than 5 deliverables (suggests non-atomic)
182
+ - Subjective criteria ("make it better", "good performance")
183
+
184
+ ### `octie list`
185
+
186
+ List all tasks with optional filtering.
187
+
188
+ ```bash
189
+ octie list # List all tasks
190
+ octie list --status pending # Filter by status
191
+ octie list --priority top # Filter by priority
192
+ octie list --tree # Show as tree view
193
+ octie list --graph # Show graph structure
194
+ octie list --format json # JSON output
195
+ ```
196
+
197
+ **Options:**
198
+ | Flag | Description |
199
+ |------|-------------|
200
+ | `--status <status>` | Filter by: `not_started`, `pending`, `in_progress`, `completed`, `blocked` |
201
+ | `--priority <level>` | Filter by: `top`, `second`, `later` |
202
+ | `--format <type>` | Output format: `table`, `json`, `md` |
203
+ | `--tree` | Display as hierarchical tree |
204
+ | `--graph` | Display graph structure |
205
+
206
+ ### `octie get`
207
+
208
+ Get detailed information about a specific task.
209
+
210
+ ```bash
211
+ octie get <task-id> # Table format (default)
212
+ octie get <task-id> --format md # Markdown format
213
+ octie get <task-id> --format json # JSON format
214
+ ```
215
+
216
+ **Options:**
217
+ | Flag | Description |
218
+ |------|-------------|
219
+ | `--format <type>` | Output format: `table`, `json`, `md` |
220
+
221
+ ### `octie update`
222
+
223
+ Update an existing task.
224
+
225
+ ```bash
226
+ octie update <task-id> --status in_progress
227
+ octie update <task-id> --priority top
228
+ octie update <task-id> --complete-criterion <criterion-id>
229
+ octie update <task-id> --complete-deliverable <deliverable-id>
230
+ octie update <task-id> --notes "Additional context"
231
+ ```
232
+
233
+ **Options:**
234
+ | Flag | Description |
235
+ |------|-------------|
236
+ | `--status <status>` | Set status: `not_started`, `pending`, `in_progress`, `completed`, `blocked` |
237
+ | `--priority <level>` | Set priority: `top`, `second`, `later` |
238
+ | `--add-success-criterion <text>` | Add a new success criterion |
239
+ | `--complete-criterion <id>` | Mark criterion as complete |
240
+ | `--add-deliverable <text>` | Add a new deliverable |
241
+ | `--complete-deliverable <id>` | Mark deliverable as complete |
242
+ | `--block <task-id>` | Add blocker |
243
+ | `--unblock <task-id>` | Remove blocker |
244
+ | `--add-dependency <task-id>` | Add dependency |
245
+ | `--notes <text>` | Append to notes |
246
+
247
+ **Auto-managed Timestamps:**
248
+ - `updated_at` is automatically updated on any field change
249
+ - `completed_at` is automatically set when ALL success criteria AND deliverables are complete
250
+
251
+ ### `octie delete`
252
+
253
+ Delete a task with optional edge reconnection.
254
+
255
+ ```bash
256
+ octie delete <task-id> # Interactive deletion
257
+ octie delete <task-id> --force # Skip confirmation
258
+ octie delete <task-id> --reconnect # Reconnect edges (A→B→C becomes A→C)
259
+ octie delete <task-id> --cascade # Delete all dependent tasks
260
+ ```
261
+
262
+ **Options:**
263
+ | Flag | Description |
264
+ |------|-------------|
265
+ | `--reconnect` | Reconnect incoming to outgoing edges after deletion |
266
+ | `--cascade` | Delete all tasks that depend on this task |
267
+ | `--force` | Skip confirmation prompt |
268
+
269
+ ### `octie merge`
270
+
271
+ Merge two tasks into one.
272
+
273
+ ```bash
274
+ octie merge <source-id> <target-id> # Merge source into target
275
+ ```
276
+
277
+ The merge combines:
278
+ - Description (concatenated)
279
+ - Success criteria (deduplicated by ID)
280
+ - Deliverables (deduplicated by ID)
281
+ - Related files (deduplicated)
282
+ - Notes (concatenated)
283
+
284
+ Edges are reconnected from source to target.
285
+
286
+ ### `octie export`
287
+
288
+ Export project data to file.
289
+
290
+ ```bash
291
+ octie export # Export to stdout
292
+ octie export --type json --output backup.json
293
+ octie export --type md --output tasks.md
294
+ ```
295
+
296
+ **Options:**
297
+ | Flag | Description |
298
+ |------|-------------|
299
+ | `--type <format>` | Export format: `json`, `md` (default: `json`) |
300
+ | `--output <path>` | Output file path |
301
+
302
+ ### `octie import`
303
+
304
+ Import tasks from file.
305
+
306
+ ```bash
307
+ octie import backup.json # Import from JSON file
308
+ octie import tasks.md --format md # Import from Markdown
309
+ octie import backup.json --merge # Merge with existing tasks
310
+ ```
311
+
312
+ **Options:**
313
+ | Flag | Description |
314
+ |------|-------------|
315
+ | `--file <path>` | Input file path (required) |
316
+ | `--format <type>` | Input format: `json`, `md` (auto-detected from extension) |
317
+ | `--merge` | Merge with existing tasks instead of replacing |
318
+
319
+ ### `octie graph`
320
+
321
+ Graph analysis and validation commands.
322
+
323
+ ```bash
324
+ octie graph validate # Check graph integrity
325
+ octie graph cycles # Detect and display cycles
326
+ octie graph topology # Show topological order
327
+ octie graph critical-path # Show longest dependency path
328
+ octie graph orphans # Show disconnected tasks
329
+ octie graph stats # Display graph statistics
330
+ ```
331
+
332
+ ### `octie serve`
333
+
334
+ Start the web UI server.
335
+
336
+ ```bash
337
+ octie serve # Default: localhost:3000
338
+ octie serve --port 8080 # Custom port
339
+ octie serve --host 0.0.0.0 # Listen on all interfaces
340
+ ```
341
+
342
+ **Options:**
343
+ | Flag | Description |
344
+ |------|-------------|
345
+ | `--port <number>` | Server port (default: 3000) |
346
+ | `--host <address>` | Host address (default: localhost) |
347
+ | `--no-cors` | Disable CORS headers |
348
+
349
+ ### `octie wire`
350
+
351
+ Insert an existing task between two connected tasks on a blocker chain.
352
+
353
+ ```bash
354
+ # Wire task B between A and C
355
+ octie wire <task-b-id> \
356
+ --after <task-a-id> \
357
+ --before <task-c-id> \
358
+ --dep-on-after "Why B depends on A" \
359
+ --dep-on-before "Why C depends on B"
360
+ ```
361
+
362
+ **Visual Example:**
363
+ ```
364
+ Before: A → C (A blocks C)
365
+ After: A → B → C (A blocks B, B blocks C)
366
+ ```
367
+
368
+ **Workflow:**
369
+ 1. Create the intermediate task first (using `octie create`)
370
+ 2. Wire it into the chain using `octie wire`
371
+
372
+ **Required Options:**
373
+ | Flag | Description |
374
+ |------|-------------|
375
+ | `--after <id>` | Source task ID - will become the inserted task's blocker |
376
+ | `--before <id>` | Target task ID - will block on the inserted task instead |
377
+ | `--dep-on-after <text>` | Why the inserted task depends on the --after task (twin validation) |
378
+ | `--dep-on-before <text>` | Why the --before task depends on the inserted task |
379
+
380
+ **Example:**
381
+ ```bash
382
+ # Step 1: Create the intermediate task
383
+ octie create --title "Review API spec" --description "..." \
384
+ --success-criterion "..." --deliverable "..."
385
+
386
+ # Step 2: Wire it between two connected tasks
387
+ octie wire xyz789 \
388
+ --after abc123 \
389
+ --before def456 \
390
+ --dep-on-after "Needs API spec to create TypeScript models" \
391
+ --dep-on-before "Frontend needs TypeScript models for implementation"
392
+ ```
393
+
394
+ ## Web API Reference
395
+
396
+ When the server is running, the following REST API endpoints are available.
397
+
398
+ > **Full API documentation**: See [openapi.yaml](./openapi.yaml) for the complete OpenAPI 3.0 specification.
399
+
400
+ ### Task Endpoints
401
+
402
+ | Method | Endpoint | Description |
403
+ |--------|----------|-------------|
404
+ | `GET` | `/api/tasks` | List all tasks (supports `?status=`, `?priority=`, `?search=`) |
405
+ | `GET` | `/api/tasks/:id` | Get task by ID |
406
+ | `POST` | `/api/tasks` | Create new task |
407
+ | `PUT` | `/api/tasks/:id` | Update task |
408
+ | `DELETE` | `/api/tasks/:id` | Delete task (supports `?reconnect=true`) |
409
+ | `POST` | `/api/tasks/:id/merge` | Merge tasks (body: `{ "targetId": "uuid" }`) |
410
+
411
+ ### Graph Endpoints
412
+
413
+ | Method | Endpoint | Description |
414
+ |--------|----------|-------------|
415
+ | `GET` | `/api/graph` | Get full graph structure |
416
+ | `GET` | `/api/graph/topology` | Get topological order |
417
+ | `POST` | `/api/graph/validate` | Validate graph structure |
418
+ | `GET` | `/api/graph/cycles` | Detect cycles |
419
+ | `GET` | `/api/graph/critical-path` | Get critical path |
420
+ | `GET` | `/api/stats` | Get project statistics |
421
+
422
+ ### Health Endpoints
423
+
424
+ | Method | Endpoint | Description |
425
+ |--------|----------|-------------|
426
+ | `GET` | `/health` | Health check |
427
+ | `GET` | `/api` | API info |
428
+ | `GET` | `/api/project` | Project metadata |
429
+
430
+ ## Data Format
431
+
432
+ Tasks are stored in `.octie/project.json` with the following structure:
433
+
434
+ ```json
435
+ {
436
+ "version": "1.0.0",
437
+ "format": "octie-project",
438
+ "metadata": {
439
+ "project_name": "my-project",
440
+ "version": "1.0.0",
441
+ "created_at": "2026-02-16T12:00:00Z",
442
+ "updated_at": "2026-02-16T14:30:00Z",
443
+ "task_count": 5
444
+ },
445
+ "tasks": {
446
+ "task-id": {
447
+ "id": "uuid",
448
+ "title": "Task title",
449
+ "description": "Detailed description",
450
+ "status": "not_started|pending|in_progress|completed|blocked",
451
+ "priority": "top|second|later",
452
+ "success_criteria": [...],
453
+ "deliverables": [...],
454
+ "blockers": [],
455
+ "dependencies": [],
456
+ "edges": [],
457
+ "related_files": [],
458
+ "notes": "",
459
+ "created_at": "ISO-8601",
460
+ "updated_at": "ISO-8601",
461
+ "completed_at": "ISO-8601|null"
462
+ }
463
+ },
464
+ "edges": [
465
+ {"from": "task-id-1", "to": "task-id-2", "type": "blocks"}
466
+ ],
467
+ "indexes": {
468
+ "byStatus": {...},
469
+ "byPriority": {...},
470
+ "rootTasks": [...],
471
+ "orphans": []
472
+ }
473
+ }
474
+ ```
475
+
476
+ ## Testing
477
+
478
+ ```bash
479
+ # Run all tests
480
+ npm test
481
+
482
+ # Run specific test file
483
+ npx vitest run tests/unit/cli/commands/create.test.ts
484
+
485
+ # Run with coverage
486
+ npm run test:coverage
487
+
488
+ # Run benchmarks
489
+ npm run bench
490
+ ```
491
+
492
+ **Test Coverage**:
493
+ - Unit tests: 388 passed (8 skipped for unimplemented features)
494
+ - Integration tests: Full CLI workflow, concurrent access, file corruption recovery
495
+ - Web API tests: 48 comprehensive endpoint tests
496
+ - Performance benchmarks: All operations under target thresholds
497
+
498
+ ## Project Status
499
+
500
+ **Current Version**: 1.0.0
501
+
502
+ **Completed Features**:
503
+ - ✅ Core data structures (TaskNode, TaskGraphStore with O(1) lookup)
504
+ - ✅ Storage layer with atomic writes and backup rotation
505
+ - ✅ Graph algorithms (topological sort, cycle detection, traversal, operations)
506
+ - ✅ CLI commands (init, create, list, get, update, delete, merge, export, import, graph, serve)
507
+ - ✅ Output formatters (Markdown, JSON, Table)
508
+ - ✅ Web API server with RESTful endpoints (Express.js)
509
+ - ✅ Web UI (React + ReactFlow + Zustand + Tailwind CSS)
510
+ - ✅ Unit tests (388 passing)
511
+ - ✅ Integration tests (CLI workflow, concurrent access, recovery)
512
+ - ✅ Web API tests (48 comprehensive tests)
513
+ - ✅ Performance benchmarks (all under target thresholds)
514
+
515
+ **Future Enhancements** (post-v1.0.0):
516
+ - 📋 Real-time collaboration (WebSocket)
517
+ - 📋 Task templates
518
+ - 📋 Advanced filtering and search
519
+ - 📋 Export to other formats (PDF, CSV)
520
+
521
+ ## License
522
+
523
+ MIT
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Approve Command
3
+ *
4
+ * Manually approve a task that is in review.
5
+ * This is the ONLY manual status transition in the new system:
6
+ * in_review → completed
7
+ *
8
+ * @module cli/commands/approve
9
+ */
10
+ import { Command } from 'commander';
11
+ /**
12
+ * Approve a task in review
13
+ *
14
+ * This command transitions a task from 'in_review' to 'completed' status.
15
+ * This is the ONLY manual status transition in the new automatic status system.
16
+ *
17
+ * @param taskId - Task ID or prefix to approve
18
+ * @param options - Command options
19
+ */
20
+ export declare function approveCommand(taskId: string, options: {
21
+ project?: string;
22
+ }): Promise<void>;
23
+ /**
24
+ * Register the approve command with the CLI
25
+ */
26
+ export declare function registerApproveCommand(program: Command): void;
27
+ //# sourceMappingURL=approve.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"approve.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/approve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5B,OAAO,CAAC,IAAI,CAAC,CA8Df;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6C7D"}
@@ -0,0 +1,119 @@
1
+ /**
2
+ * Approve Command
3
+ *
4
+ * Manually approve a task that is in review.
5
+ * This is the ONLY manual status transition in the new system:
6
+ * in_review → completed
7
+ *
8
+ * @module cli/commands/approve
9
+ */
10
+ import { Command } from 'commander';
11
+ import { ValidationError } from '../../types/index.js';
12
+ import { getProjectPath, loadGraph, saveGraph } from '../utils/helpers.js';
13
+ import { recalculateDependentStatuses } from '../../core/utils/status-helpers.js';
14
+ import chalk from 'chalk';
15
+ /**
16
+ * Approve a task in review
17
+ *
18
+ * This command transitions a task from 'in_review' to 'completed' status.
19
+ * This is the ONLY manual status transition in the new automatic status system.
20
+ *
21
+ * @param taskId - Task ID or prefix to approve
22
+ * @param options - Command options
23
+ */
24
+ export async function approveCommand(taskId, options) {
25
+ try {
26
+ // Find project path
27
+ const projectPath = await getProjectPath(options.project);
28
+ // Load the graph
29
+ const graph = await loadGraph(projectPath);
30
+ // Find the task by ID or prefix
31
+ const task = graph.getNodeByIdOrPrefix(taskId);
32
+ if (!task) {
33
+ console.error(chalk.red(`Error: Task with ID '${taskId}' not found.`));
34
+ process.exit(1);
35
+ }
36
+ // Check if task is in review status
37
+ if (task.status !== 'in_review') {
38
+ console.error(chalk.red(`Error: Cannot approve task in '${task.status}' status.`));
39
+ console.error(chalk.yellow('Task must be in \'in_review\' status to be approved.'));
40
+ console.error(chalk.gray('Tip: Complete all success criteria, deliverables, and need_fix items to transition to in_review.'));
41
+ process.exit(1);
42
+ }
43
+ // Approve the task
44
+ task.approve();
45
+ // Recalculate status of all tasks that were blocked by this task
46
+ const updatedTaskIds = recalculateDependentStatuses(task.id, graph);
47
+ // Save the graph
48
+ await saveGraph(projectPath, graph);
49
+ // Output success message
50
+ console.log(chalk.green(`✓ Task approved: ${task.id}`));
51
+ console.log(chalk.gray(` Title: ${task.title}`));
52
+ console.log(chalk.gray(` Status: ${task.status}`));
53
+ if (task.completed_at) {
54
+ console.log(chalk.gray(` Completed: ${task.completed_at}`));
55
+ }
56
+ // Report if any dependent tasks were unblocked
57
+ if (updatedTaskIds.length > 0) {
58
+ console.log(chalk.cyan(` Unblocked tasks: ${updatedTaskIds.length}`));
59
+ }
60
+ }
61
+ catch (error) {
62
+ if (error instanceof ValidationError) {
63
+ console.error(chalk.red(`Validation Error: ${error.message}`));
64
+ if (error.suggestion) {
65
+ console.error(chalk.yellow(`Suggestion: ${error.suggestion}`));
66
+ }
67
+ process.exit(1);
68
+ }
69
+ throw error;
70
+ }
71
+ }
72
+ /**
73
+ * Register the approve command with the CLI
74
+ */
75
+ export function registerApproveCommand(program) {
76
+ program
77
+ .command('approve')
78
+ .description('Approve a task in review (in_review → completed). This is the only manual status transition.')
79
+ .argument('<task-id>', 'Task ID (full UUID or first 7-8 characters)')
80
+ .option('-p, --project <path>', 'Project directory path')
81
+ .addHelpText('after', `
82
+ Status System:
83
+ This is the ONLY manual status transition in the automatic status system.
84
+ All other status transitions happen automatically based on task state.
85
+
86
+ Automatic Transitions:
87
+ ready → in_progress When any criterion/deliverable is checked
88
+ in_progress → in_review When all items are complete
89
+ any → blocked When a blocker is added
90
+ blocked → in_progress When all blockers completed AND items already checked
91
+ blocked → ready When all blockers completed AND no items checked yet
92
+
93
+ Manual Transition (this command):
94
+ in_review → completed Approve after review
95
+
96
+ Note: blocked → in_progress (not ready) when items are already checked.
97
+ This preserves work state and is the intended behavior.
98
+
99
+ Prerequisites for Approval:
100
+ • Task must be in 'in_review' status
101
+ • All success criteria must be complete
102
+ • All deliverables must be complete
103
+ • All need_fix items must be resolved
104
+
105
+ Side Effects:
106
+ • Tasks blocked by this task will have their status recalculated
107
+ • Unblocked tasks transition based on their item state (not forced to ready)
108
+
109
+ Examples:
110
+ $ octie approve abc12345
111
+ $ octie approve abc12345 --project /path/to/project
112
+
113
+ Error Cases:
114
+ • Task not found → Error
115
+ • Task not in 'in_review' status → Error with guidance
116
+ `)
117
+ .action(approveCommand);
118
+ }
119
+ //# sourceMappingURL=approve.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"approve.js","sourceRoot":"","sources":["../../../src/cli/commands/approve.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Batch command - Perform bulk operations on multiple tasks
3
+ *
4
+ * Provides atomic batch operations with safety features:
5
+ * - Preview mode with --dry-run
6
+ * - Atomic operations (all succeed or all fail)
7
+ * - Progress indicators for large batches
8
+ * - Safety confirmation for destructive operations
9
+ */
10
+ import { Command } from 'commander';
11
+ /**
12
+ * Create the batch command with subcommands
13
+ */
14
+ export declare const batchCommand: Command;
15
+ //# sourceMappingURL=batch.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8ZpC;;GAEG;AACH,eAAO,MAAM,YAAY,SAiCvB,CAAC"}