@nickmeriano/task 0.5.0 → 0.6.0

package/skill/SKILL.md

@@ -2,7 +2,7 @@
 name: tasks
 description: >-
   Work with this repository's built-in task manager (the `task` CLI — a .task/
-  directory with a SQLite database, from @nickmeriano/task). Use this
+  directory of plain-text tickets, from @nickmeriano/task). Use this
   skill whenever the user mentions tasks, tickets, issues, todos, backlog,
   kanban, board, "what's next", "what should I work on", or asks you to plan,
   track, or report progress on work — and also on your own initiative: when you
@@ -13,11 +13,14 @@ description: >-
 
 # tasks — the repo's task manager
 
-This repository tracks its work in `.task/` at the project root: a SQLite
-database driven by the `task` CLI. Tasks live in the repo, next to the code
-they describe — when you update a task, the user sees it instantly (the board
-UI at `task serve` updates in realtime), and the state is committed with the
-code, so it survives sessions and travels with branches.
+This repository tracks its work in `.task/` at the project root: one markdown
+file per ticket under `.task/tickets/`, driven by the `task` CLI. Tasks live in
+the repo, next to the code they describe — when you update a task, the user
+sees it instantly (the board UI at `task serve` updates in realtime), and the
+state is committed with the code, so it survives sessions, travels with
+branches, and shows up as readable diffs in PRs. Always write through the CLI
+rather than editing ticket files by hand — it keeps numbering, positions and
+relations consistent.
 
 Run `task` from anywhere in the repo; it walks up to find `.task/` like git
 finds `.git`. If the CLI isn't on PATH, use `npx @nickmeriano/task` instead.
@@ -45,6 +48,10 @@ task unlink <id> --blocked-by <id>     # remove one (or --blocks)
 task update <id> --pr <url>            # attach a pull request (appends)
 task comment <id> "text" --author claude
 task delete <id>
+task boards --json                     # every board in the repo, with prefixes
+task archive <id> --json               # done/canceled ticket -> .task/archive/
+task archive --all --json              # archive everything done or canceled
+task unarchive <id> --json             # put one back on the board
 task whoami                            # who comments are attributed to
 ```
 
@@ -53,11 +60,19 @@ the user can read it from a phone, and take it away again. Both open a browser
 and wait for a human, so **never run either on your own initiative**; suggest
 `task publish` if the user wants to see the board remotely.
 
-- `<id>` is `PREFIX-12` or just `12`.
+- `<id>` is `PREFIX-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 any directory. `task boards --json` lists them all.
 - Statuses: `backlog` `todo` `in_progress` `done` `canceled`.
 - `--tag a,b` matches a task carrying *either* tag, not both.
 - Clear a field by passing it empty: `--tags ""`, `--milestone ""`, `--prs ""`.
-- `task list` hides done/canceled by default; `--all` shows everything.
+- `task list` hides done/canceled by default; `--all` shows everything, and
+  `--archived` lists the archive instead of the board.
+- Archiving is history, not deletion: only done/canceled tickets qualify,
+  their numbers stay reserved, and `task show` still reads them. Archived
+  tickets refuse edits until unarchived. Don't archive on your own
+  initiative — suggest `task archive --all` when finished work is piling up,
+  and let the user decide.
 
 **Dependencies.** `task link A --blocked-by B` and `task link B --blocks A`
 write the same relation — each task's `task show` lists both its `blocked`

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,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 ──────────────────────────────────────────────────────
@@ -213,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")
@@ -225,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]))
@@ -232,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)}`)
@@ -260,6 +428,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 +450,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 +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) {
@@ -332,9 +501,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)
@@ -367,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)}`)
@@ -560,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
@@ -569,7 +764,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]
   task show <id>
   task update <id> [--title <t>] [--description <text>] [--status <s>]
                    [--tags <a,b>] [--milestone <m>]
@@ -584,6 +779,14 @@ Usage
   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
@@ -602,9 +805,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
@@ -660,6 +868,14 @@ function main(): void | Promise<void> {
       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":