@nickmeriano/task 0.5.0 → 0.7.0

package/src/cli.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 // The `task` CLI — tasks that live in your repo. Zero dependencies: hand-rolled
-// flag parsing, node:sqlite for storage, plain text out (--json for agents).
+// flag parsing, plain-text tickets in .task/tickets/ for storage (node:sqlite
+// still reads boards from before `task migrate`), plain text out (--json for
+// agents).
 //
 //   task init
 //   task add "Wire up webhooks" --tags api,infra --milestone launch
@@ -13,11 +15,22 @@ import { readFileSync } from "node:fs"
 import type { Server } from "node:http"
 import { basename, join } from "node:path"
 import process from "node:process"
-import { resolveAuthor } from "./author.js"
-import { detectRepo, parseSlug, publish, resolveHost } from "./publish.js"
-import { createTaskServer } from "./server.js"
-import { CONFIG_FILE, TASK_DIR, TaskStore, findBoards, findRoot, initProject } from "./store.js"
-import { STATUSES, isStatus, type Status, type Task, type TaskPatch } from "./types.js"
+import { resolveAuthor } from "./author.ts"
+import { ClaimError, claim, claimableTasks, release } from "./claim.ts"
+import { detectRepo, parseSlug, publish, resolveHost } from "./publish.ts"
+import { createTaskServer } from "./server.ts"
+import { initProject, migrateBoard, openBoard } from "./file-store.ts"
+import {
+  CONFIG_FILE,
+  TASK_DIR,
+  boardConfig,
+  findBoards,
+  findBoardsByPrefix,
+  findRoot,
+  findScopeRoot,
+  type Store,
+} from "./store.ts"
+import { STATUSES, isStatus, type Status, type Task, type TaskPatch } from "./types.ts"
 
 // node:sqlite still emits an ExperimentalWarning on Node 22 — noise in a CLI
 // that runs it on every invocation. Filter that one warning, keep the rest.
@@ -62,6 +75,9 @@ const BOOLEAN_FLAGS = new Set([
   "yes",
   "needs-human",
   "no-needs-human",
+  "archived",
+  "claimable",
+  "release",
   "open",
   "no-open",
   "strict-port",
@@ -102,10 +118,68 @@ function fail(message: string): never {
   process.exit(1)
 }
 
-function openStore(): TaskStore {
+function openStore(): Store {
   const root = findRoot(process.cwd())
   if (!root) fail("no .task directory found in this directory or any parent — run `task init` first")
-  return new TaskStore(root)
+  return openBoard(root)
+}
+
+/** The prefix a ref carries, if any: "TAS-12" → "TAS", "12" → null. */
+function refPrefix(ref: string): string | null {
+  const match = /^([A-Za-z0-9]+)-\d+$/.exec(ref.trim())
+  return match ? match[1].toUpperCase() : null
+}
+
+/**
+ * The board a ref belongs to. A bare number means the nearest board, as ever —
+ * but a prefixed id is an address, and it routes: if the prefix isn't the
+ * nearest board's, every board in the repo (walking up to the outermost board
+ * root, then down) is searched for it, so `task show TAS-12` works from
+ * anywhere in a monorepo. What this must never do is what it used to: silently
+ * strip a foreign prefix and act on the nearest board's ticket of that number.
+ */
+function openStoreFor(ref: string | undefined): Store {
+  const prefix = ref ? refPrefix(ref) : null
+  if (!prefix) return openStore()
+
+  const nearest = findRoot(process.cwd())
+  if (nearest) {
+    const store = openBoard(nearest)
+    if (store.config.prefix.toUpperCase() === prefix) return store
+    store.close()
+  }
+
+  const scope = findScopeRoot(process.cwd())
+  const matches = findBoardsByPrefix(scope, prefix)
+  if (matches.length === 1) return openBoard(matches[0].root)
+  if (matches.length > 1) {
+    fail(`prefix ${prefix} is ambiguous — boards at: ${matches.map((m) => m.id).join(", ")}`)
+  }
+  const known = findBoards(scope)
+    .map((b) => {
+      try {
+        return `${boardConfig(b.root).prefix} (${b.id})`
+      } catch {
+        return null
+      }
+    })
+    .filter(Boolean)
+  fail(
+    `no board with prefix ${prefix} in this repo${known.length ? ` — boards here: ${known.join(", ")}` : ""}`,
+  )
+}
+
+/**
+ * Parse a ref against an already-chosen board, refusing a foreign prefix
+ * instead of reinterpreting it — this guards the second id in `task link`,
+ * where the board was picked by the first.
+ */
+function parseRefOn(store: Store, ref: string): number {
+  const prefix = refPrefix(ref)
+  if (prefix && prefix !== store.config.prefix.toUpperCase()) {
+    fail(`${ref} is not on the ${store.config.prefix} board — links can't cross boards`)
+  }
+  return store.parseId(ref)
 }
 
 // ── Input normalization ──────────────────────────────────────────────────────
@@ -213,10 +287,29 @@ function cmdAdd(args: Args): void {
 
 function cmdList(args: Args): void {
   const store = openStore()
+  if (args.flags.claimable) {
+    // The dispatcher's queue view (TAS-21): claimable already pins the status
+    // set and consults origin, so the board-shaping flags don't compose.
+    for (const flag of ["status", "all", "archived"]) {
+      if (args.flags[flag] !== undefined) fail(`--claimable can't be combined with --${flag}`)
+    }
+    const tasks = claimableTasks(store)
+    if (args.flags.json) {
+      console.log(JSON.stringify({ tasks }, null, 2))
+    } else if (tasks.length === 0) {
+      console.log("nothing claimable — no unblocked, unclaimed todo tickets")
+    } else {
+      table(tasks.map(taskRow))
+    }
+    return
+  }
+  const archived = Boolean(args.flags.archived)
   const statusFlag = str(args.flags, "status")
   const statuses = statusFlag
     ? statusFlag.split(",").map(parseStatus)
-    : args.flags.all
+    : // The archive is all done/canceled, and --all already means everything —
+      // the open-tickets default only applies to the plain board listing.
+      args.flags.all || archived
       ? undefined
       : (["backlog", "todo", "in_progress"] as Status[])
   const tagFlag = str(args.flags, "tags") ?? str(args.flags, "tag")
@@ -225,6 +318,7 @@ function cmdList(args: Args): void {
     tags: tagFlag ? parseTags(tagFlag) : undefined,
     milestone: str(args.flags, "milestone"),
     needsHuman: args.flags["needs-human"] ? true : undefined,
+    archived: archived || undefined,
   })
   // Present in board order: grouped by status column, then position.
   const order = new Map(STATUSES.map((s, i) => [s, i]))
@@ -232,16 +326,109 @@ function cmdList(args: Args): void {
   if (args.flags.json) {
     console.log(JSON.stringify({ tasks }, null, 2))
   } else if (tasks.length === 0) {
-    console.log(args.flags.all ? "no tasks" : "no open tasks (--all includes done/canceled)")
+    console.log(
+      archived
+        ? "no archived tasks"
+        : args.flags.all
+          ? "no tasks"
+          : "no open tasks (--all includes done/canceled)",
+    )
   } else {
     table(tasks.map(taskRow))
   }
 }
 
+/**
+ * `task boards` — every board in this repo, found the way `task serve` finds
+ * them but anchored at the *outermost* board root, so it answers from anywhere
+ * in a monorepo. The `*` marks the board the other commands would target from
+ * here.
+ */
+function cmdBoards(args: Args): void {
+  const cwd = process.cwd()
+  const scope = findScopeRoot(cwd)
+  const boards = findBoards(scope)
+  if (boards.length === 0) {
+    fail("no .task directory found in this directory, any parent, or below — run `task init` first")
+  }
+  const nearest = findRoot(cwd)
+  const rows = boards.map((ref) => {
+    const store = openBoard(ref.root)
+    const open = store.list({ statuses: ["backlog", "todo", "in_progress"] }).length
+    store.close()
+    return {
+      id: ref.id,
+      name: store.config.name,
+      prefix: store.config.prefix,
+      open,
+      current: ref.root === nearest,
+    }
+  })
+  if (args.flags.json) {
+    console.log(JSON.stringify({ boards: rows }, null, 2))
+  } else {
+    table(
+      rows.map((b) => [
+        b.current ? "*" : "",
+        b.prefix,
+        b.name,
+        b.id,
+        `${b.open} open`,
+      ]),
+    )
+  }
+}
+
+/**
+ * `task archive <id>` / `task archive --all` — move finished tickets to
+ * `.task/archive/`, out of the board and off every hot path. History, not a
+ * hiding place: only done/canceled tickets qualify, everything stays readable
+ * via `show` and `list --archived`, and `task unarchive` puts one back.
+ */
+function cmdArchive(args: Args): void {
+  const ref = args.positional[0]
+  if (args.flags.all && ref) fail("pass an id or --all, not both")
+  if (!args.flags.all && !ref) fail("usage: task archive <id> | task archive --all")
+
+  if (ref) {
+    const store = openStoreFor(ref)
+    const task = store.archive(store.parseId(ref))
+    if (args.flags.json) {
+      console.log(JSON.stringify({ task }, null, 2))
+    } else {
+      console.log(`archived ${task.id}  ${task.title}`)
+    }
+    return
+  }
+
+  const store = openStore()
+  const finished = store.list({ statuses: ["done", "canceled"] })
+  const archived = finished.map((t) => store.archive(t.number))
+  if (args.flags.json) {
+    console.log(JSON.stringify({ archived }, null, 2))
+  } else if (archived.length === 0) {
+    console.log("nothing to archive — no done or canceled tasks on the board")
+  } else {
+    for (const task of archived) console.log(`archived ${task.id}  ${task.title}`)
+  }
+}
+
+function cmdUnarchive(args: Args): void {
+  const ref = args.positional[0]
+  if (!ref) fail("usage: task unarchive <id>")
+  const store = openStoreFor(ref)
+  const task = store.unarchive(store.parseId(ref))
+  if (args.flags.json) {
+    console.log(JSON.stringify({ task }, null, 2))
+  } else {
+    printTask(task)
+  }
+}
+
 function cmdShow(args: Args): void {
   const ref = args.positional[0]
   if (!ref) fail("usage: task show <id>")
-  const store = openStore()
+  const store = openStoreFor(ref)
   const number = store.parseId(ref)
   const task = store.get(number)
   if (!task) fail(`no such task: ${store.displayId(number)}`)
@@ -260,6 +447,7 @@ function cmdShow(args: Args): void {
       .join(", ")
   console.log(`${task.id}  ${task.title}`)
   console.log(`status    ${task.status}`)
+  if (task.archived) console.log(`archived  yes — \`task unarchive ${task.id}\` to edit`)
   if (task.needsHuman) console.log(`needs     a human`)
   if (task.tags.length) console.log(`tags      ${task.tags.join(", ")}`)
   if (task.milestone) console.log(`milestone ${task.milestone}`)
@@ -281,7 +469,7 @@ function cmdShow(args: Args): void {
 function cmdUpdate(args: Args, forcedStatus?: Status): void {
   const ref = args.positional[0]
   if (!ref) fail("usage: task update <id> [--status …] [--title …] …")
-  const store = openStore()
+  const store = openStoreFor(ref)
   const number = store.parseId(ref)
   const patch = patchFromFlags(args.flags)
   if (forcedStatus) patch.status = forcedStatus
@@ -310,7 +498,7 @@ function cmdComment(args: Args): void {
   const [ref, ...rest] = args.positional
   const body = rest.join(" ").trim()
   if (!ref || !body) fail(`usage: task comment <id> <text> [--author <who>]`)
-  const store = openStore()
+  const store = openStoreFor(ref)
   const author = resolveAuthor(str(args.flags, "author")).name
   const comment = store.addComment(store.parseId(ref), body, author)
   if (args.flags.json) {
@@ -332,9 +520,9 @@ function cmdLink(args: Args, action: "link" | "unlink"): void {
   if (!ref || (blocks ? blockedBy : !blockedBy)) {
     fail(`usage: task ${action} <id> (--blocks <id> | --blocked-by <id>)`)
   }
-  const store = openStore()
+  const store = openStoreFor(ref)
   const relation = blocks ? "blocks" : "blocked_by"
-  const target = store.parseId((blocks ?? blockedBy)!)
+  const target = parseRefOn(store, (blocks ?? blockedBy)!)
   const number = store.parseId(ref)
   const task =
     action === "link" ? store.link(number, relation, target) : store.unlink(number, relation, target)
@@ -350,6 +538,44 @@ function cmdLink(args: Args, action: "link" | "unlink"): void {
   }
 }
 
+/**
+ * `task claim <id>` / `task claim --release <id>` — see claim.ts for the
+ * mechanics. Exit codes are the contract callers script against: 0 claimed,
+ * 1 already claimed (pick the next ticket), 2 not claimable (fix something).
+ */
+function cmdClaim(args: Args): void {
+  const ref = args.positional[0]
+  if (!ref) fail("usage: task claim <id> | task claim --release <id>")
+  const store = openStoreFor(ref)
+  const number = store.parseId(ref)
+  try {
+    if (args.flags.release) {
+      const result = release(store, number)
+      if (args.flags.json) {
+        console.log(JSON.stringify({ released: result }, null, 2))
+      } else if (!result.remote && !result.local) {
+        console.log(`${store.displayId(number)} wasn't claimed — no ${result.branch} to delete`)
+      } else {
+        const where = [result.remote && "origin", result.local && "local"].filter(Boolean)
+        console.log(`released ${store.displayId(number)} — deleted ${result.branch} (${where.join(" and ")})`)
+      }
+      return
+    }
+    const result = claim(store, number)
+    if (args.flags.json) {
+      console.log(JSON.stringify({ task: result.task, branch: result.branch }, null, 2))
+    } else {
+      console.log(`claimed ${result.task.id} — on ${result.branch} (from ${result.base}), status in_progress`)
+    }
+  } catch (error) {
+    if (error instanceof ClaimError) {
+      console.error(`error: ${error.message}`)
+      process.exit(error.kind === "claimed" ? 1 : 2)
+    }
+    throw error
+  }
+}
+
 const AUTHOR_SOURCE: Record<string, string> = {
   flag: "--author",
   env: "$TASK_AUTHOR",
@@ -367,10 +593,34 @@ function cmdWhoami(args: Args): void {
   }
 }
 
+/**
+ * `task migrate` — from the legacy committed SQLite database to text-canonical
+ * storage: one markdown file per ticket and per comment under .task/tickets/,
+ * with the database left on disk as an ignored backup. Additive and safe to
+ * re-run planning-wise: it refuses to run twice.
+ */
+function cmdMigrate(args: Args): void {
+  const root = findRoot(process.cwd())
+  if (!root) fail("no .task directory found in this directory or any parent — run `task init` first")
+  const result = migrateBoard(root)
+  if (args.flags.json) {
+    console.log(JSON.stringify({ migrated: result }, null, 2))
+    return
+  }
+  console.log(
+    `Migrated ${result.tasks} task${result.tasks === 1 ? "" : "s"} and ${result.comments} comment${result.comments === 1 ? "" : "s"} to .task/tickets/`,
+  )
+  console.log(`tasks.db stays on disk as a backup, but it's ignored now — the files are the state.`)
+  console.log(``)
+  console.log(`Next:`)
+  console.log(`  git rm --cached ${join(TASK_DIR, "tasks.db")}     stop tracking the database`)
+  console.log(`  git add ${TASK_DIR}                       commit the tickets`)
+}
+
 function cmdDelete(args: Args): void {
   const ref = args.positional[0]
   if (!ref) fail("usage: task delete <id>")
-  const store = openStore()
+  const store = openStoreFor(ref)
   const number = store.parseId(ref)
   store.delete(number)
   console.log(`deleted ${store.displayId(number)}`)
@@ -560,8 +810,10 @@ function runPublishFlow(
 
 const HELP = `task — a task manager that lives in your repo
 
-State is a SQLite database in .task/ at the project root. Commit it: tasks and
-their status travel with the code they describe. Any command works from any
+State is plain text in .task/ at the project root — one markdown file per
+ticket and per comment under .task/tickets/. Commit it: tasks travel with the
+code they describe, ticket changes show up as readable diffs in PRs, and two
+branches editing different tickets merge cleanly. Any command works from any
 subdirectory (it walks up to find .task/, like git).
 
 Usage
@@ -569,7 +821,7 @@ Usage
   task add <title> [--description <text>] [--status <s>] [--tags <a,b>]
                    [--milestone <m>] [--needs-human]
   task list [--status <s1,s2>] [--tag <a,b>] [--milestone <m>]
-            [--needs-human] [--all]
+            [--needs-human] [--all] [--archived] [--claimable]
   task show <id>
   task update <id> [--title <t>] [--description <text>] [--status <s>]
                    [--tags <a,b>] [--milestone <m>]
@@ -582,8 +834,34 @@ Usage
   task link <id> --blocks <id>  mark a dependency — one relation, visible from
                                 both tasks (A blocked by B ⇔ B blocks A)
   task unlink <id> (--blocks <id> | --blocked-by <id>)
+  task claim <id>               claim a ticket before working it: branch
+                                <claimPrefix><prefix>-<n> off origin's default
+                                branch, ticket → in_progress as its first
+                                commit, pushed. The namespace defaults to
+                                task/claim/ — set "claimPrefix" in
+                                .task/config.json to change it (e.g.
+                                "claude/task/", which Claude cloud sessions
+                                can push). Branch on origin = claimed —
+                                git's atomic ref creation is the lock, so two
+                                concurrent claimers can't both win. Exit codes:
+                                0 claimed, 1 already claimed, 2 not claimable
+                                (not todo, blocked, needs-human, dirty tree)
+  task claim --release <id>     abandon a claim: delete the branch on origin
+                                and locally — the status flip only lived on
+                                the branch, so deleting it is the revert
+  task list --claimable         the claim queue: todo tickets in position
+                                order, minus blocked / needs-human / already
+                                claimed on origin. Top entry is next up
   task comment <id> <text> [--author <who>]
   task delete <id>
+  task boards                   every board in this repo — prefix, name, path,
+                                open count; * marks the one commands target here
+  task archive <id>             move a done/canceled ticket to .task/archive/,
+                                out of the board and off the hot path — still
+                                readable via show and list --archived, and its
+                                number stays reserved
+  task archive --all            archive everything done or canceled
+  task unarchive <id>           put an archived ticket back on the board
   task whoami                   who your comments are attributed to
   task serve [--port <n>] [--no-open] [--strict-port]
                                 board + table UI with live updates, opened in
@@ -602,9 +880,14 @@ Usage
   task unpublish [--repo <owner/name>]
                                 take that URL down. Removes the board, not the
                                 tasks — those are in .task/ either way
+  task migrate                  move a pre-0.6 board off its committed SQLite
+                                database and onto text files in .task/tickets/.
+                                The database stays on disk as an ignored backup
 
 Values
-  <id>          TAS-12, or just 12
+  <id>          TAS-12, or just 12. A bare number means the nearest board; a
+                prefixed id routes to whichever board in the repo owns that
+                prefix, so TAS-12 works from anywhere in a monorepo
   status        ${STATUSES.join("  ")}
   --tag a,b     matches a task carrying *either* tag
   --needs-human this can't be finished by an agent alone
@@ -654,12 +937,22 @@ function main(): void | Promise<void> {
       return cmdLink(args, "link")
     case "unlink":
       return cmdLink(args, "unlink")
+    case "claim":
+      return cmdClaim(args)
     case "comment":
       return cmdComment(args)
     case "whoami":
       return cmdWhoami(args)
     case "delete":
       return cmdDelete(args)
+    case "boards":
+      return cmdBoards(args)
+    case "archive":
+      return cmdArchive(args)
+    case "unarchive":
+      return cmdUnarchive(args)
+    case "migrate":
+      return cmdMigrate(args)
     case "serve":
       return cmdServe(args)
     case "publish":