trekoon 0.1.2 → 0.1.5

package/.agents/skills/trekoon/SKILL.md

@@ -7,9 +7,158 @@ description: Use Trekoon to create issues/tasks, plan backlog and sprints, creat
 
 Trekoon is a local-first issue tracker for epics, tasks, and subtasks.
 
-Use long flags (`--status`, `--description`, etc.) and ALWAYS prefer `--toon` for machine-readable output.
+## CRITICAL: Always Use --toon Flag
+
+**Every trekoon command MUST include `--toon` for machine-readable output.**
+
+The `--toon` flag outputs structured YAML-like data that is easy to parse. Never run trekoon commands without it.
+
+### TOON Output Format
+
+All `--toon` output follows this structure:
+
+```yaml
+ok: true
+command: task.list
+data:
+  tasks[0]:
+    id: abc-123
+    epicId: epic-456
+    title: Implement feature X
+    status: todo
+    createdAt: 1700000000000
+    updatedAt: 1700000000000
+  tasks[1]:
+    id: def-789
+    epicId: epic-456
+    title: Write tests
+    status: in_progress
+    createdAt: 1700000001000
+    updatedAt: 1700000001000
+```
+
+On error:
+
+```yaml
+ok: false
+command: task.show
+data: {}
+error:
+  code: not_found
+  message: task not found: invalid-id
+```
+
+### Key Fields
+
+| Field | Meaning |
+|-------|---------|
+| `ok` | `true` if command succeeded, `false` on error |
+| `command` | The command that was executed (e.g., `task.list`, `epic.create`) |
+| `data` | The response payload (tasks, epics, dependencies, etc.) |
+| `error` | Present only on failure, contains `code` and `message` |
+
+Use long flags (`--status`, `--description`, etc.) and ALWAYS append `--toon` to every command.
+
+## 1) Status Management
+
+### Status values
+
+Trekoon accepts any non-empty status string.
+
+Recommended statuses for consistent workflows:
+
+| Status | Meaning |
+|--------|---------|
+| `todo` | Work not started (default for new items) |
+| `in_progress` | Actively being worked on |
+| `done` | Completed successfully |
+
+Note: `in-progress` (hyphenated) is treated the same as `in_progress` for default list ordering/filtering.
+
+### When to Change Status
+
+| Transition | When to apply |
+|------------|---------------|
+| `todo → in_progress` | When you START working on a task/subtask/epic |
+| `in_progress → done` | When you COMPLETE the work and it is ready |
+
+### Status Change Commands
+
+```bash
+trekoon task update <task-id> --status in_progress --toon
+trekoon task update <task-id> --status done --toon
+trekoon subtask update <subtask-id> --status done --toon
+trekoon epic update <epic-id> --status done --toon
+```
+
+## 2) Dependency Management
+
+Dependencies define what must be completed before a task can start. A task/subtask can depend on other tasks/subtasks.
+
+### Commands
+
+```bash
+trekoon dep add <source-id> <depends-on-id> --toon
+trekoon dep list <source-id> --toon
+trekoon dep remove <source-id> <depends-on-id> --toon
+```
 
-## 1) Load existing work first
+- `<source-id>`: The task/subtask that has the dependency
+- `<depends-on-id>`: The task/subtask that must be completed first
+
+### Checking Dependencies
+
+Before starting any task, always check its dependencies:
+
+```bash
+trekoon dep list <task-id> --toon
+```
+
+The response `data.dependencies` array contains entries with:
+- `sourceId`: the task you're checking
+- `dependsOnId`: what must be done first
+- `dependsOnKind`: "task" or "subtask"
+
+### Dependency Rules
+
+1. A task with dependencies should only be marked `in_progress` when ALL dependencies have status `done`
+2. Dependencies can only exist between tasks and subtasks (not epics)
+3. Cycles are automatically detected and rejected
+
+## 3) Task Completion Flow
+
+### Before Starting a Task
+
+1. Check if task has unmet dependencies:
+   ```bash
+   trekoon dep list <task-id> --toon
+   ```
+
+2. If dependencies exist and are not `done`, complete those first
+
+3. Only mark `in_progress` when all dependencies are `done`
+
+### When Completing a Task
+
+1. Mark the task as done:
+   ```bash
+   trekoon task update <task-id> --status done --toon
+   ```
+
+2. To find the next task that was blocked by this one:
+   - List all tasks: `trekoon task list --all --toon`
+   - Check which tasks have dependencies on the completed task
+   - The task(s) with all dependencies now satisfied are ready to start
+
+### Finding Next Work
+
+```bash
+trekoon task list --status todo --limit 20 --toon
+```
+
+Tasks are sorted with `in_progress` first, then `todo`. Look for tasks with no dependencies or all dependencies satisfied.
+
+## 4) Load existing work first
 
 Before creating or changing anything, inspect current context:
 
@@ -20,7 +169,7 @@ trekoon epic show <id> --all --toon
 trekoon task show <id> --all --toon
 ```
 
-- `epic list` / `task list` defaults:
+- `epic list` / `task list` / `subtask list` defaults:
   - open work only (`in_progress`, `in-progress`, `todo`)
   - prioritized as `in_progress`/`in-progress` first, then `todo`
   - default limit `10`
@@ -36,7 +185,14 @@ trekoon task list --all --toon
 - `epic show <id> --all --toon`: full epic tree (tasks + subtasks)
 - `task show <id> --all --toon`: task plus its subtasks
 
-## 2) Create work (epic/task/subtask)
+### View Options
+
+| Command | `--view` options |
+|---------|------------------|
+| `list` | `table` (default), `compact` |
+| `show` | `table` (default), `compact`, `tree`, `detail` |
+
+## 5) Create work (epic/task/subtask)
 
 ```bash
 trekoon epic create --title "..." --description "..." --status todo --toon
@@ -47,8 +203,9 @@ trekoon subtask create --task <task-id> --title "..." --description "..." --stat
 Notes:
 - `description` is required for epic/task create and it must be well written.
 - `status` defaults to `todo` if omitted.
+- `description` is optional for subtask create.
 
-## 3) Update work
+## 6) Update work
 
 ### Single-item update
 
@@ -73,7 +230,7 @@ Rules:
 - In bulk mode, do not pass a positional ID.
 - Bulk update supports `--append` and/or `--status`.
 
-## 4) Setup/install/init (if `trekoon` is unavailable)
+## 7) Setup/install/init (if `trekoon` is unavailable)
 
 1. Install Trekoon (or make sure it is on `PATH`).
 2. In the target repository/worktree, initialize tracker state:
@@ -81,11 +238,12 @@ Rules:
 ```bash
 trekoon init
 ```
+
 3. You can always run `trekoon quickstart` or `trekoon --help` to get more information.
 
 If `.trekoon/trekoon.db` is missing, initialize before any create/update commands.
 
-## 5) Safety
+## 8) Safety
 
 - Never edit `.trekoon/trekoon.db` directly.
 - `trekoon wipe --yes` is prohibited unless the user explicitly confirms they want a destructive wipe.

package/README.md

@@ -77,10 +77,10 @@ Human view options:
 
 - List and show commands default to table output in human mode.
 - Use `--view compact` to restore compact pipe output.
-- `epic list` and `task list` support `--view table|compact`.
+- `epic list`, `task list`, and `subtask list` support `--view table|compact`.
 - `epic show` and `task show` support `--view table|compact|tree|detail`.
 
-List defaults and filters (`epic list`, `task list`):
+List defaults and filters (`epic list`, `task list`, `subtask list`):
 
 - Default scope: open work only (`in_progress`, `in-progress`, `todo`)
 - Default limit: `10`
@@ -89,7 +89,7 @@ List defaults and filters (`epic list`, `task list`):
 - All rows and statuses: `--all`
 - `--all` is mutually exclusive with `--status` and `--limit`
 
-Bulk updates (`epic update`, `task update`):
+Bulk updates (`epic update`, `task update`, `subtask update`):
 
 - Target all rows: `--all`
 - Target specific rows: `--ids <id1,id2,...>`
@@ -103,6 +103,8 @@ Examples:
 ```bash
 trekoon task update --all --status in_progress
 trekoon task update --ids <task-1>,<task-2> --append "\nFollow-up note"
+trekoon subtask update --all --status done
+trekoon subtask update --ids <subtask-1>,<subtask-2> --append "\nFollow-up note"
 trekoon epic update --ids <epic-1>,<epic-2> --status done
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "AI-first local issue tracker CLI.",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,8 @@
   "scripts": {
     "run": "bun run ./src/index.ts",
     "build": "bun build ./src/index.ts --outdir ./dist --target bun",
-    "test": "bun test ./tests"
+    "test": "bun test ./tests",
+    "lint": "bunx tsc --noEmit"
   },
   "devDependencies": {
     "@types/bun": "^1.3.9",

package/src/commands/events.ts

@@ -0,0 +1,88 @@
+import { hasFlag, parseArgs, parseStrictPositiveInt, readMissingOptionValue, readOption } from "./arg-parser";
+
+import { failResult, okResult } from "../io/output";
+import { type CliContext, type CliResult } from "../runtime/command-types";
+import { openTrekoonDatabase } from "../storage/database";
+import { DEFAULT_EVENT_RETENTION_DAYS, pruneEvents } from "../storage/events-retention";
+
+const EVENTS_USAGE = "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]";
+
+function usage(message: string): CliResult {
+  return failResult({
+    command: "events",
+    human: `${message}\n${EVENTS_USAGE}`,
+    data: { message },
+    error: {
+      code: "invalid_args",
+      message,
+    },
+  });
+}
+
+function invalidInput(command: string, message: string, option: string): CliResult {
+  return failResult({
+    command,
+    human: message,
+    data: {
+      option,
+    },
+    error: {
+      code: "invalid_input",
+      message,
+    },
+  });
+}
+
+export async function runEvents(context: CliContext): Promise<CliResult> {
+  const parsed = parseArgs(context.args);
+  const subcommand: string | undefined = parsed.positional[0];
+
+  if (!subcommand) {
+    return usage("Missing events subcommand.");
+  }
+
+  if (subcommand !== "prune") {
+    return usage(`Unknown events subcommand '${subcommand}'.`);
+  }
+
+  if (parsed.positional.length > 1) {
+    return usage("Unexpected positional arguments for events prune.");
+  }
+
+  const missingOption: string | undefined = readMissingOptionValue(parsed.missingOptionValues, "retention-days");
+  if (missingOption !== undefined) {
+    return invalidInput("events.prune", `Option --${missingOption} requires a value.`, missingOption);
+  }
+
+  const parsedRetentionDays: number | undefined = parseStrictPositiveInt(readOption(parsed.options, "retention-days"));
+  if (Number.isNaN(parsedRetentionDays)) {
+    return invalidInput("events.prune", "--retention-days must be a positive integer.", "retention-days");
+  }
+
+  const retentionDays: number = parsedRetentionDays ?? DEFAULT_EVENT_RETENTION_DAYS;
+  const dryRun: boolean = hasFlag(parsed.flags, "dry-run");
+  const archive: boolean = hasFlag(parsed.flags, "archive");
+  const storage = openTrekoonDatabase(context.cwd);
+
+  try {
+    const summary = pruneEvents(storage.db, {
+      retentionDays,
+      dryRun,
+      archive,
+    });
+
+    return okResult({
+      command: "events.prune",
+      human: [
+        dryRun ? "Dry run complete." : "Prune complete.",
+        `Retention days: ${summary.retentionDays}`,
+        `Candidates: ${summary.candidateCount}`,
+        `Archived: ${summary.archivedCount}`,
+        `Deleted: ${summary.deletedCount}`,
+      ].join("\n"),
+      data: summary,
+    });
+  } finally {
+    storage.close();
+  }
+}

package/src/commands/help.ts

@@ -21,6 +21,8 @@ const ROOT_HELP = [
   "  task         Task lifecycle commands",
   "  subtask      Subtask lifecycle commands",
   "  dep          Dependency graph commands",
+  "  events       Event retention and cleanup commands",
+  "  migrate      Migration status and rollback commands",
   "  sync         Cross-branch sync commands",
   "  skills       Project-local skill install/link commands",
 ].join("\n");
@@ -33,8 +35,11 @@ const COMMAND_HELP: Record<string, string> = {
     "Usage: trekoon epic <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --status <csv> | --limit <n> | --all | --view table|compact; show: compact=epic summary, tree=hierarchy, detail=descriptions, and --all defaults to detail in machine modes; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
   task:
     "Usage: trekoon task <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --status <csv> | --limit <n> | --all | --view table|compact; show: compact=task summary, tree=hierarchy, detail=descriptions, and --all defaults to detail in machine modes; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
-  subtask: "Usage: trekoon subtask <subcommand> [options] (list supports --view table|compact)",
+  subtask:
+    "Usage: trekoon subtask <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --task <id> | --status <csv> | --limit <n> | --all | --view table|compact; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
   dep: "Usage: trekoon dep <subcommand> [options]",
+  events: "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]",
+  migrate: "Usage: trekoon migrate <status|rollback> [--to-version <n>]",
   sync: "Usage: trekoon sync <subcommand> [options]",
   skills:
     "Usage: trekoon skills install [--link --editor opencode|claude] [--to <path>] (--to sets symlink root for --link only; install path always <cwd>/.agents/skills/trekoon/SKILL.md)",

package/src/commands/migrate.ts

@@ -0,0 +1,123 @@
+import { parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
+
+import { failResult, okResult } from "../io/output";
+import { type CliContext, type CliResult } from "../runtime/command-types";
+import { openTrekoonDatabase } from "../storage/database";
+import { describeMigrations, rollbackDatabase } from "../storage/migrations";
+
+const MIGRATE_USAGE = "Usage: trekoon migrate <status|rollback> [--to-version <n>]";
+
+function usage(message: string): CliResult {
+  return failResult({
+    command: "migrate",
+    human: `${message}\n${MIGRATE_USAGE}`,
+    data: { message },
+    error: {
+      code: "invalid_args",
+      message,
+    },
+  });
+}
+
+function parseVersion(rawValue: string | undefined): number | null {
+  if (rawValue === undefined) {
+    return null;
+  }
+
+  if (!/^\d+$/.test(rawValue)) {
+    return Number.NaN;
+  }
+
+  return Number.parseInt(rawValue, 10);
+}
+
+export async function runMigrate(context: CliContext): Promise<CliResult> {
+  const parsed = parseArgs(context.args);
+  const subcommand: string | undefined = parsed.positional[0];
+
+  if (!subcommand) {
+    return usage("Missing migrate subcommand.");
+  }
+
+  const missingOption = readMissingOptionValue(parsed.missingOptionValues, "to-version");
+  if (missingOption !== undefined) {
+    return failResult({
+      command: "migrate",
+      human: `Option --${missingOption} requires a value.`,
+      data: {
+        option: missingOption,
+      },
+      error: {
+        code: "invalid_input",
+        message: `Option --${missingOption} requires a value.`,
+      },
+    });
+  }
+
+  const storage = openTrekoonDatabase(context.cwd, { autoMigrate: false });
+
+  try {
+    if (subcommand === "status") {
+      const status = describeMigrations(storage.db);
+
+      return okResult({
+        command: "migrate.status",
+        human: [
+          `Current version: ${status.currentVersion}`,
+          `Latest version: ${status.latestVersion}`,
+          `Pending migrations: ${status.pending.length}`,
+        ].join("\n"),
+        data: status,
+      });
+    }
+
+    if (subcommand === "rollback") {
+      const status = describeMigrations(storage.db);
+      const parsedVersion: number | null = parseVersion(readOption(parsed.options, "to-version"));
+
+      if (Number.isNaN(parsedVersion)) {
+        return failResult({
+          command: "migrate.rollback",
+          human: "--to-version must be a non-negative integer.",
+          data: {
+            option: "to-version",
+          },
+          error: {
+            code: "invalid_input",
+            message: "--to-version must be a non-negative integer.",
+          },
+        });
+      }
+
+      const targetVersion: number = parsedVersion ?? Math.max(0, status.currentVersion - 1);
+      const summary = rollbackDatabase(storage.db, targetVersion);
+
+      return okResult({
+        command: "migrate.rollback",
+        human: [
+          `Rolled back ${summary.rolledBack} migration(s).`,
+          `From version ${summary.fromVersion} to ${summary.toVersion}.`,
+        ].join("\n"),
+        data: summary,
+      });
+    }
+
+    return usage(`Unknown migrate subcommand '${subcommand}'.`);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : "Unknown migration failure.";
+
+    return failResult({
+      command: "migrate",
+      human: message,
+      data: {
+        reason: "migrate_failed",
+      },
+      error: {
+        code: "migrate_failed",
+        message,
+      },
+    });
+  } finally {
+    storage.close();
+  }
+}

package/src/commands/quickstart.ts

@@ -17,7 +17,7 @@ const QUICKSTART_TEXT = [
   "3) Task details and description",
   "- Human list and show views default to table format.",
   "- Alternate list view: add --view compact.",
-  "- task/epic list defaults: open work only (in_progress/in-progress, todo), max 10.",
+  "- task/epic/subtask list defaults: open work only (in_progress/in-progress, todo), max 10.",
   "- Filter list by status: --status in_progress,todo (CSV).",
   "- Change page size: --limit <n>. Show all statuses and all rows with --all.",
   "- --all cannot be combined with --status or --limit.",