@nickmeriano/task 0.4.2 → 0.6.0

package/src/index.ts

@@ -1,6 +1,32 @@
 // Programmatic access to the same store the CLI and `task serve` use — for
 // scripts that want to read or write .task/ without shelling out.
-export { TaskStore, findRoot, findBoards, initProject, derivePrefix, type BoardRef } from "./store.js"
-export { createTaskServer } from "./server.js"
-export { resolveAuthor, ANONYMOUS, type Author, type AuthorSource } from "./author.js"
-export * from "./types.js"
+export {
+  TaskStore,
+  boardConfig,
+  derivePrefix,
+  findBoards,
+  findBoardsByPrefix,
+  findRoot,
+  findScopeRoot,
+  type BoardRef,
+  type Store,
+} from "./store.ts"
+export {
+  ARCHIVE_DIR,
+  FileStore,
+  TICKETS_DIR,
+  initProject,
+  migrateBoard,
+  openBoard,
+} from "./file-store.ts"
+export {
+  parseTicket,
+  serializeTicket,
+  parseComment,
+  serializeComment,
+  type TicketDoc,
+  type CommentDoc,
+} from "./ticket-doc.ts"
+export { createTaskServer } from "./server.ts"
+export { resolveAuthor, ANONYMOUS, type Author, type AuthorSource } from "./author.ts"
+export * from "./types.ts"

package/src/server.ts

@@ -2,9 +2,10 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 import { watch, existsSync, readFileSync, statSync, type FSWatcher } from "node:fs"
 import { extname, join, normalize } from "node:path"
 import { fileURLToPath } from "node:url"
-import { resolveAuthor } from "./author.js"
-import { findBoards, TaskStore, type BoardRef } from "./store.js"
-import { STATUSES, isStatus, type TaskPatch } from "./types.js"
+import { resolveAuthor } from "./author.ts"
+import { openBoard } from "./file-store.ts"
+import { findBoards, type BoardRef, type Store } from "./store.ts"
+import { STATUSES, isStatus, type TaskPatch } from "./types.ts"
 
 /** The prebuilt SPA, shipped inside the package next to dist/. */
 const UI_DIR = fileURLToPath(new URL("../ui/dist", import.meta.url))
@@ -48,10 +49,26 @@ function parsePatch(body: Record<string, unknown>): TaskPatch {
     patch.milestone = body.milestone === "" ? null : body.milestone
   }
   if (typeof body.needsHuman === "boolean") patch.needsHuman = body.needsHuman
+  if (Array.isArray(body.blocks)) patch.blocks = body.blocks.map(taskNumber)
+  if (Array.isArray(body.blockedBy)) patch.blockedBy = body.blockedBy.map(taskNumber)
+  if (Array.isArray(body.prs)) {
+    patch.prs = body.prs.map((pr) => {
+      const url = String(pr).trim()
+      // Anything the UI would render as a clickable link has to be a link.
+      if (!/^https?:\/\//.test(url)) throw new Error(`not a PR url: ${url}`)
+      return url
+    })
+  }
   if (typeof body.position === "number") patch.position = body.position
   return patch
 }
 
+function taskNumber(value: unknown): number {
+  const n = Number(value)
+  if (!Number.isInteger(n) || n <= 0) throw new Error(`invalid task number: ${String(value)}`)
+  return n
+}
+
 /**
  * `task serve` — one plain node:http server for the static UI, the JSON API,
  * and an SSE stream that pings whenever anything writes to a `.task/` (the UI
@@ -89,15 +106,18 @@ export function createTaskServer(serveRoot: string): Server {
   }
 
   interface Board {
-    store: TaskStore
+    store: Store
     watcher: FSWatcher
   }
   const boards = new Map<string, Board>()
   let ordered: string[] = []
 
-  const openBoard = (ref: BoardRef): void => {
-    const store = new TaskStore(ref.root)
-    const watcher = watch(store.taskDir, () => noteChange(ref.id))
+  const attachBoard = (ref: BoardRef): void => {
+    const store = openBoard(ref.root)
+    // Recursive: text-canonical state is a tree (tickets/<n>/comments/…), and
+    // a write anywhere in it is a board change. Node supports this on Linux,
+    // macOS and Windows for the versions this package requires.
+    const watcher = watch(store.taskDir, { recursive: true }, () => noteChange(ref.id))
     // A deleted board dir can make fs.watch emit; the next rescan cleans up.
     watcher.on("error", () => {})
     boards.set(ref.id, { store, watcher })
@@ -114,7 +134,7 @@ export function createTaskServer(serveRoot: string): Server {
         boards.delete(id)
       }
     }
-    for (const ref of found) if (!boards.has(ref.id)) openBoard(ref)
+    for (const ref of found) if (!boards.has(ref.id)) attachBoard(ref)
     ordered = found.map((ref) => ref.id)
     return found
   }
@@ -188,7 +208,7 @@ export function createTaskServer(serveRoot: string): Server {
   }
 
   function routeApi(
-    store: TaskStore,
+    store: Store,
     req: IncomingMessage,
     res: ServerResponse,
     path: string,
@@ -226,11 +246,11 @@ export function createTaskServer(serveRoot: string): Server {
       return
     }
 
-    const taskMatch = /^\/api\/tasks\/([^/]+)(\/comments(?:\/(\d+))?)?$/.exec(path)
+    const taskMatch = /^\/api\/tasks\/([^/]+)(\/comments(?:\/([^/]+))?)?$/.exec(path)
     if (taskMatch) {
       const number = store.parseId(decodeURIComponent(taskMatch[1]))
       if (taskMatch[3] && req.method === "DELETE") {
-        const commentId = Number(taskMatch[3])
+        const commentId = decodeURIComponent(taskMatch[3])
         const existing = store.comments(number).find((c) => c.id === commentId)
         if (!existing) {
           json(res, 404, { error: `no such comment: ${commentId}` })

package/src/store.test.ts

@@ -0,0 +1,305 @@
+/**
+ * The properties TAS-12 exists for, checked from the outside:
+ *
+ * 1. The text format round-trips — parse(serialize(x)) loses nothing.
+ * 2. `FileStore` behaves like the store always has (positions, links,
+ *    comments, cascade on delete).
+ * 3. `task migrate` reproduces a legacy SQLite board in files, exactly.
+ * 4. Concurrent-writer shapes merge by construction: a comment is a new file,
+ *    a claim is a one-line status diff.
+ */
+
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { FileStore, initProject, migrateBoard, openBoard } from "./file-store.ts"
+import { parseTicket, serializeTicket, type TicketDoc } from "./ticket-doc.ts"
+import { TaskStore, findBoardsByPrefix, findScopeRoot } from "./store.ts"
+
+function tempRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "task-test-"))
+  process.on("exit", () => rmSync(dir, { recursive: true, force: true }))
+  return dir
+}
+
+test("ticket documents round-trip, including the awkward bodies", () => {
+  const docs: TicketDoc[] = [
+    {
+      title: "Plain ticket",
+      description: "One line.",
+      status: "todo",
+      tags: [],
+      milestone: null,
+      needsHuman: false,
+      blockedBy: [],
+      prs: [],
+      position: 1024,
+      createdAt: "2026-08-15T16:00:33.758Z",
+      updatedAt: "2026-08-15T16:00:33.758Z",
+    },
+    {
+      title: 'Tricky: "quotes", colons: yes — and unicode ✓',
+      // A description that opens with a heading, contains a frontmatter-like
+      // fence, and ends without punctuation.
+      description: "# Not the title\n\n---\n\nstatus: not-a-field\n\n```md\n---\n```",
+      status: "in_progress",
+      tags: ["storage", "architecture"],
+      milestone: "v2 storage",
+      needsHuman: true,
+      blockedBy: [3, 7],
+      prs: ["https://github.com/x/y/pull/1"],
+      position: -512.5,
+      createdAt: "2026-08-15T16:00:33.758Z",
+      updatedAt: "2026-08-15T17:12:00.001Z",
+    },
+    {
+      title: "Empty description",
+      description: "",
+      status: "backlog",
+      tags: [],
+      milestone: null,
+      needsHuman: false,
+      blockedBy: [],
+      prs: [],
+      position: 0,
+      createdAt: "2026-08-15T16:00:33.758Z",
+      updatedAt: "2026-08-15T16:00:33.758Z",
+    },
+  ]
+  for (const doc of docs) {
+    assert.deepEqual(parseTicket(serializeTicket(doc), "test"), doc, doc.title)
+  }
+})
+
+test("hand-edits are forgiven where they're unambiguous", () => {
+  const text = [
+    "---",
+    "status: todo",
+    "milestone: launch", // unquoted string — the YAML instinct
+    "position: 8",
+    "created: 2026-08-15T16:00:33.758Z",
+    "updated: 2026-08-15T16:00:33.758Z",
+    "---",
+    "",
+    "# Hand-written ticket",
+    "",
+    "Body.",
+  ].join("\n")
+  const doc = parseTicket(text, "test")
+  assert.equal(doc.milestone, "launch")
+  assert.equal(doc.position, 8)
+
+  assert.throws(
+    () => parseTicket(text.replace("status: todo", "status: todoo"), "here"),
+    /here.*invalid status/,
+  )
+  assert.throws(() => parseTicket("no frontmatter", "here"), /here.*frontmatter/)
+})
+
+test("FileStore keeps the store's contract", () => {
+  const root = tempRoot()
+  const store = initProject(root, { name: "sample project" })
+  assert.equal(store.config.prefix, "SAM")
+  assert.ok(store instanceof FileStore)
+
+  const a = store.create({ title: "First", description: "alpha", tags: ["api"] })
+  const b = store.create({ title: "Second", status: "todo" })
+  const c = store.create({ title: "Third", status: "backlog" })
+  assert.deepEqual([a.number, b.number, c.number], [1, 2, 3])
+  // New tasks land at the bottom of their column.
+  assert.ok(b.position > a.position)
+
+  // Status move without an explicit slot lands on top of the new column.
+  const moved = store.update(c.number, { status: "todo" })
+  assert.ok(moved.position < a.position)
+  assert.equal(store.list({ statuses: ["todo"] })[0].number, c.number)
+
+  // One relation, two views, stored on one side only.
+  store.link(a.number, "blocked_by", b.number)
+  assert.deepEqual(store.get(b.number)!.blocks, [a.number])
+  const onDisk = readFileSync(join(root, ".task", "tickets", "1", "ticket.md"), "utf8")
+  assert.match(onDisk, /blocked_by: \[2\]/)
+  assert.doesNotMatch(
+    readFileSync(join(root, ".task", "tickets", "2", "ticket.md"), "utf8"),
+    /blocked_by/,
+  )
+  store.unlink(b.number, "blocks", a.number)
+  assert.deepEqual(store.get(a.number)!.blockedBy, [])
+
+  assert.throws(() => store.link(a.number, "blocks", a.number), /can't block itself/)
+  assert.throws(() => store.update(a.number, { blockedBy: [99] }), /no such task: SAM-99/)
+
+  // Comments: one file each, stable ids, author preserved.
+  const comment = store.addComment(a.number, "first!\n\nwith **markdown**", "claude")
+  assert.match(comment.id, /^\d{4}-\d{2}-\d{2}T\d{6}-claude$/)
+  assert.equal(store.comments(a.number)[0].body, "first!\n\nwith **markdown**")
+  assert.equal(store.commentCounts().get(a.number), 1)
+  const second = store.addComment(a.number, "again", "claude")
+  assert.notEqual(second.id, comment.id)
+  store.deleteComment(a.number, second.id)
+  assert.equal(store.comments(a.number).length, 1)
+  assert.throws(() => store.deleteComment(a.number, "../../escape"), /no such comment/)
+
+  // Delete cascades the relation away, like the FK did.
+  store.link(b.number, "blocked_by", a.number)
+  store.delete(a.number)
+  assert.equal(store.get(a.number), null)
+  assert.deepEqual(store.get(b.number)!.blockedBy, [])
+
+  // Numbers never move backwards past an existing ticket.
+  const d = store.create({ title: "Fourth" })
+  assert.equal(d.number, 4)
+})
+
+test("openBoard picks the backend by what's on disk", () => {
+  const fileRoot = tempRoot()
+  initProject(fileRoot, { name: "files" })
+  assert.ok(openBoard(fileRoot) instanceof FileStore)
+
+  const legacyRoot = tempRoot()
+  mkdirSync(join(legacyRoot, ".task"))
+  writeFileSync(
+    join(legacyRoot, ".task", "config.json"),
+    `${JSON.stringify({ name: "legacy", prefix: "LEG", version: 1 }, null, 2)}\n`,
+  )
+  const legacy = openBoard(legacyRoot)
+  assert.ok(legacy instanceof TaskStore)
+  legacy.close()
+})
+
+test("migrate reproduces a legacy board, byte-visible and loss-free", () => {
+  const root = tempRoot()
+  mkdirSync(join(root, ".task"))
+  writeFileSync(
+    join(root, ".task", "config.json"),
+    `${JSON.stringify({ name: "legacy board", prefix: "LEG", version: 1 }, null, 2)}\n`,
+  )
+  const legacy = new TaskStore(root)
+  const one = legacy.create({ title: "Keep me", description: "with *body*", tags: ["a", "b"] })
+  const two = legacy.create({
+    title: "Blocked one",
+    status: "in_progress",
+    milestone: "launch",
+    needsHuman: true,
+    blockedBy: [one.number],
+    prs: ["https://github.com/x/y/pull/9"],
+  })
+  legacy.addComment(one.number, "hello", "nick")
+  legacy.addComment(one.number, "and back", "claude")
+  const expectedTasks = legacy.list({})
+  const expectedComments = legacy.comments(one.number)
+  legacy.close()
+
+  const result = migrateBoard(root)
+  assert.deepEqual(result, { tasks: 2, comments: 2 })
+  assert.throws(() => migrateBoard(root), /already migrated/)
+
+  const store = openBoard(root)
+  assert.ok(store instanceof FileStore)
+  assert.deepEqual(store.list({}), expectedTasks)
+  assert.deepEqual(
+    store.comments(one.number).map(({ author, body, createdAt }) => ({ author, body, createdAt })),
+    expectedComments.map(({ author, body, createdAt }) => ({ author, body, createdAt })),
+  )
+  assert.deepEqual(store.get(two.number)!.blockedBy, [one.number])
+  assert.match(readFileSync(join(root, ".task", ".gitignore"), "utf8"), /tasks\.db/)
+  assert.equal(
+    (JSON.parse(readFileSync(join(root, ".task", "config.json"), "utf8")) as { version: number })
+      .version,
+    2,
+  )
+})
+
+test("archive moves finished tickets off the hot path, losing nothing", () => {
+  const root = tempRoot()
+  const store = initProject(root, { name: "archive test", prefix: "ARC" })
+  const keep = store.create({ title: "Still open" })
+  const old = store.create({ title: "Finished work" })
+  store.link(keep.number, "blocked_by", old.number)
+  store.addComment(old.number, "how it went", "nick")
+
+  // Only finished work qualifies — archive is history, not a hiding place.
+  assert.throws(() => store.archive(old.number), /is todo/)
+  store.update(old.number, { status: "done" })
+  const archived = store.archive(old.number)
+  assert.equal(archived.archived, true)
+
+  // Off the board and out of every default read…
+  assert.deepEqual(store.list({}).map((t) => t.number), [keep.number])
+  assert.equal(store.commentCounts().get(old.number), undefined)
+  // …but reads still reach it, comments included, and its links still show.
+  const shown = store.get(old.number)!
+  assert.equal(shown.archived, true)
+  assert.deepEqual(shown.blocks, [keep.number])
+  assert.equal(store.comments(old.number)[0].body, "how it went")
+  const listed = store.list({ archived: true })
+  assert.deepEqual(listed.map((t) => [t.number, t.archived]), [[old.number, true]])
+
+  // Writes refuse until unarchived, with a message that says what to do.
+  assert.throws(() => store.update(old.number, { title: "x" }), /archived — run/)
+  assert.throws(() => store.addComment(old.number, "x", "y"), /archived — run/)
+  assert.throws(() => store.delete(old.number), /archived — run/)
+  assert.throws(() => store.archive(old.number), /already archived/)
+  // Linking *to* an archived target refuses; pruning a stale link succeeds.
+  assert.throws(() => store.link(keep.number, "blocked_by", old.number), /archived — run/)
+  assert.deepEqual(store.update(keep.number, { blockedBy: [] }).blockedBy, [])
+
+  // Numbers stay reserved — the next ticket never reuses an archived one.
+  assert.equal(store.create({ title: "Next" }).number, 3)
+
+  // Round trip: unarchive puts it back exactly as it was.
+  const back = store.unarchive(old.number)
+  assert.equal(back.archived, undefined)
+  assert.equal(back.status, "done")
+  assert.deepEqual(store.list({ archived: true }), [])
+  assert.equal(store.comments(old.number).length, 1)
+  assert.throws(() => store.unarchive(old.number), /isn't archived/)
+})
+
+test("prefix routing helpers find the right board from anywhere", () => {
+  const repo = tempRoot()
+  initProject(repo, { name: "root board", prefix: "NIC" })
+  mkdirSync(join(repo, "projects", "widget"), { recursive: true })
+  initProject(join(repo, "projects", "widget"), { name: "widget", prefix: "WID" })
+
+  // From deep inside a package, the scope is still the repo root.
+  assert.equal(findScopeRoot(join(repo, "projects", "widget")), repo)
+  assert.equal(findScopeRoot(repo), repo)
+
+  const hit = findBoardsByPrefix(repo, "wid")
+  assert.deepEqual(hit.map((b) => b.id), ["projects/widget"])
+  assert.deepEqual(findBoardsByPrefix(repo, "NOPE"), [])
+})
+
+test("concurrent-writer shapes merge by construction", () => {
+  const root = tempRoot()
+  const store = initProject(root, { name: "merge" })
+  const task = store.create({ title: "Contended" })
+
+  // Two agents commenting at once = two files; simulate the second writer by
+  // dropping its file in directly, the way a git merge would.
+  store.addComment(task.number, "from session one", "claude")
+  const commentsDir = join(root, ".task", "tickets", String(task.number), "comments")
+  writeFileSync(
+    join(commentsDir, "2026-08-15T170000-other.md"),
+    "---\nauthor: \"other\"\ncreated: 2026-08-15T17:00:00.000Z\n---\n\nfrom session two\n",
+  )
+  assert.equal(store.comments(task.number).length, 2)
+
+  // A claim is a one-line diff: exactly one meaningful frontmatter line
+  // changes. `updated:` is excluded because it only changes when the update
+  // lands in a different millisecond than the create — true except when this
+  // test runs fast enough, which is exactly the kind of coin-flip a test must
+  // not depend on.
+  const path = join(root, ".task", "tickets", String(task.number), "ticket.md")
+  const before = readFileSync(path, "utf8").split("\n")
+  store.update(task.number, { status: "in_progress", position: task.position })
+  const after = readFileSync(path, "utf8").split("\n")
+  const changed = before.filter((line, i) => after[i] !== line)
+  assert.deepEqual(
+    changed.filter((line) => !line.startsWith("updated: ")),
+    ["status: todo"],
+  )
+})