@nickmeriano/task 0.4.2 → 0.6.0

package/src/cli.ts

@@ -1,11 +1,13 @@
 #!/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
 //   task list --status todo,in_progress
-//   task start TASK-3 && task done TASK-3
+//   task start TAS-3 && task done TAS-3
 //   task serve
 
 import { spawn } from "node:child_process"
@@ -13,11 +15,21 @@ 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 { 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 +74,7 @@ const BOOLEAN_FLAGS = new Set([
   "yes",
   "needs-human",
   "no-needs-human",
+  "archived",
   "open",
   "no-open",
   "strict-port",
@@ -102,10 +115,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 ──────────────────────────────────────────────────────
@@ -134,6 +205,10 @@ function patchFromFlags(flags: Args["flags"]): TaskPatch {
   if (milestone !== undefined) patch.milestone = milestone.trim() || null
   if (flags["needs-human"]) patch.needsHuman = true
   if (flags["no-needs-human"]) patch.needsHuman = false
+  // Replace semantics like --tags; `--pr` (append one) is handled per-command
+  // because appending needs the task's current list.
+  const prs = str(flags, "prs")
+  if (prs !== undefined) patch.prs = prs.split(",").map((p) => p.trim()).filter(Boolean)
   return patch
 }
 
@@ -196,7 +271,10 @@ function cmdAdd(args: Args): void {
   const title = args.positional.join(" ").trim()
   if (!title) fail(`usage: task add <title> [--description …] [--status …] [--tags a,b] [--milestone …] [--needs-human]`)
   const store = openStore()
-  const task = store.create({ title, ...patchFromFlags(args.flags) })
+  const patch = patchFromFlags(args.flags)
+  const pr = str(args.flags, "pr")
+  if (pr) patch.prs = [...(patch.prs ?? []), pr]
+  const task = store.create({ title, ...patch })
   if (args.flags.json) {
     console.log(JSON.stringify({ task }, null, 2))
   } else {
@@ -206,10 +284,13 @@ function cmdAdd(args: Args): void {
 
 function cmdList(args: Args): void {
   const store = openStore()
+  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")
@@ -218,6 +299,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]))
@@ -225,16 +307,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)}`)
@@ -243,11 +418,23 @@ function cmdShow(args: Args): void {
     console.log(JSON.stringify({ task, comments }, null, 2))
     return
   }
+  // A linked task is only as useful as knowing whether it's still in the way.
+  const describeLinks = (numbers: number[]): string =>
+    numbers
+      .map((n) => {
+        const other = store.get(n)
+        return other ? `${other.id} (${other.status})` : store.displayId(n)
+      })
+      .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}`)
+  if (task.blockedBy.length) console.log(`blocked   by ${describeLinks(task.blockedBy)}`)
+  if (task.blocks.length) console.log(`blocks    ${describeLinks(task.blocks)}`)
+  for (const pr of task.prs) console.log(`pr        ${pr}`)
   console.log(`created   ${task.createdAt}`)
   console.log(`updated   ${task.updatedAt}`)
   if (task.description) console.log(`\n${task.description}`)
@@ -263,11 +450,18 @@ 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
+  const pr = str(args.flags, "pr")
+  if (pr) {
+    // Append, dedup — `--pr <url>` is "attach this PR", not "replace the list".
+    const current = patch.prs ?? store.get(number)?.prs ?? []
+    patch.prs = current.includes(pr) ? current : [...current, pr]
+  }
   if (Object.keys(patch).length === 0) fail("nothing to update — pass at least one flag")
-  const task = store.update(store.parseId(ref), patch)
+  const task = store.update(number, patch)
   if (args.flags.json) {
     console.log(JSON.stringify({ task }, null, 2))
   } else {
@@ -285,7 +479,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) {
@@ -295,6 +489,36 @@ function cmdComment(args: Args): void {
   }
 }
 
+/**
+ * `task link TAS-3 --blocked-by TAS-5` / `task unlink TAS-3 --blocks TAS-9`.
+ * One relation with two spellings: either flag writes the same (blocker,
+ * blocked) row, so the other task's `task show` reflects it immediately.
+ */
+function cmdLink(args: Args, action: "link" | "unlink"): void {
+  const ref = args.positional[0]
+  const blocks = str(args.flags, "blocks")
+  const blockedBy = str(args.flags, "blocked-by")
+  if (!ref || (blocks ? blockedBy : !blockedBy)) {
+    fail(`usage: task ${action} <id> (--blocks <id> | --blocked-by <id>)`)
+  }
+  const store = openStoreFor(ref)
+  const relation = blocks ? "blocks" : "blocked_by"
+  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)
+  if (args.flags.json) {
+    console.log(JSON.stringify({ task }, null, 2))
+  } else {
+    const verb = action === "link" ? "now" : "no longer"
+    const [subject, object] =
+      relation === "blocks"
+        ? [task.id, store.displayId(target)]
+        : [store.displayId(target), task.id]
+    console.log(`${subject} ${verb} blocks ${object}`)
+  }
+}
+
 const AUTHOR_SOURCE: Record<string, string> = {
   flag: "--author",
   env: "$TASK_AUTHOR",
@@ -312,10 +536,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)}`)
@@ -505,8 +753,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
@@ -514,16 +764,29 @@ 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]
   task show <id>
   task update <id> [--title <t>] [--description <text>] [--status <s>]
                    [--tags <a,b>] [--milestone <m>]
                    [--needs-human | --no-needs-human]
+                   [--pr <url>] [--prs <url1,url2>]
   task move <id> <status>       shorthand for update --status
   task start <id>               → in_progress
   task done <id>                → done
+  task link <id> --blocked-by <id>
+  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 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
@@ -542,13 +805,20 @@ 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>          TASK-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
-  clearing      --tags "" drops all tags, --milestone "" clears it
+  --pr <url>    attach a pull request (appends); --prs replaces the whole list
+  clearing      --tags "" drops all tags, --milestone "" clears it, --prs ""
+                detaches all PRs
 
 Comment authors resolve --author → $TASK_AUTHOR → git config user.name →
 anonymous, so there is nothing to set up. \`task whoami\` shows which one won.
@@ -588,12 +858,24 @@ function main(): void | Promise<void> {
       return cmdUpdate(args, "in_progress")
     case "done":
       return cmdUpdate(args, "done")
+    case "link":
+      return cmdLink(args, "link")
+    case "unlink":
+      return cmdLink(args, "unlink")
     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":