@nickmeriano/task 0.10.0 → 0.12.0

package/src/board/source.ts

@@ -0,0 +1,422 @@
+/**
+ * A repository, read as boards.
+ *
+ * This is `findBoards` + `FileStore`, re-expressed against a git tree instead
+ * of a filesystem, and producing byte-identical API payloads. That
+ * equivalence is the whole point: the hosted board and an exported board's
+ * live proxy run the *same* SPA as `task serve`, so anything that differs
+ * here shows up as a broken screen rather than a type error. The shapes below
+ * are pinned to `server.ts` — change one and change both — and the ticket
+ * format itself is not restated: parsing comes from `ticket-doc.ts`, the one
+ * definition every server shares, in its lenient mode (a hand-edited file
+ * that no longer parses becomes a degraded ticket or a skipped comment, never
+ * a broken board).
+ *
+ * Read-only by construction. There is no code here that could write, which is
+ * how "the board can't edit your repo" stays true no matter what the routing
+ * layer does.
+ *
+ * Cache-free on purpose. A snapshot is immutable per commit, so *where* to
+ * keep one is a deployment question — the hosted worker layers isolate memory
+ * and KV over `snapshotAt`, the live proxy keeps a bounded `SnapshotMemory` —
+ * and this module answers only "what is at this commit".
+ */
+
+import {
+  parseAskLenient,
+  parseCommentLenient,
+  parseGoalLenient,
+  parseTicketLenient,
+  type TicketDoc,
+} from "../ticket-doc.ts"
+import { isTicketKey } from "../id.ts"
+import type { Ask, Comment, Goal, Task as StoredTask } from "../types.ts"
+import { fetchRepoArchive, headCommit, type CommitInfo } from "./github.ts"
+
+export { STATUSES, type Status } from "../types.ts"
+export type { Ask, Comment, Goal }
+
+const TASK_DIR = ".task"
+const CONFIG_FILE = "config.json"
+const TICKETS_DIR = "tickets"
+const TICKET_FILE = "ticket.md"
+const COMMENTS_DIR = "comments"
+const ASKS_DIR = "asks"
+const GOALS_DIR = "goals"
+
+/** Same ceiling as the CLI's `findBoards`, for the same reason. */
+const MAX_DEPTH = 6
+
+export interface BoardInfo {
+  id: string
+  name: string
+  prefix: string
+}
+
+/** A stored task plus the count `GET /tasks` sends — exactly what `task serve` lists. */
+export interface Task extends StoredTask {
+  commentCount: number
+}
+
+export interface BoardData {
+  info: BoardInfo
+  tasks: Task[]
+  /** Keyed by task key. */
+  comments: Map<string, Comment[]>
+  /** Live goals first, archived flagged — the shape `GET /goals` serves. */
+  goals: Goal[]
+}
+
+export interface Snapshot {
+  commit: CommitInfo
+  boards: BoardInfo[]
+  data: Map<string, BoardData>
+  /**
+   * Historically "the tree listing hit GitHub's cap". The tarball read is
+   * always complete, so this is now always false — kept because the SPA's
+   * payloads carry it.
+   */
+  truncated: boolean
+}
+
+export class BoardSourceError extends Error {
+  readonly status: number
+  /**
+   * Machine-readable cause, sent beside the message so the SPA can choose a
+   * screen rather than infer one from a status code. Optional: most of these
+   * are one of a kind and the message is the whole story.
+   */
+  readonly reason: string | null
+  constructor(status: number, message: string, reason: string | null = null) {
+    super(message)
+    this.name = "BoardSourceError"
+    this.status = status
+    this.reason = reason
+  }
+}
+
+function str(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : fallback
+}
+
+function num(value: unknown, fallback = 0): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback
+}
+
+interface ParsedConfig {
+  name: string
+  prefix: string
+  version: number
+}
+
+/** `.task/config.json`, defensively — it's a file anyone can hand-edit. */
+function parseConfig(bytes: Uint8Array, fallbackName: string): ParsedConfig {
+  try {
+    const parsed: unknown = JSON.parse(new TextDecoder().decode(bytes))
+    if (parsed && typeof parsed === "object") {
+      const config = parsed as Record<string, unknown>
+      return {
+        name: str(config.name, fallbackName),
+        prefix: str(config.prefix, "TASK").toUpperCase(),
+        version: num(config.version, 1),
+      }
+    }
+  } catch {
+    // fall through
+  }
+  return { name: fallbackName, prefix: "TASK", version: 1 }
+}
+
+/**
+ * Board directories, from a flat list of repo paths.
+ *
+ * The CLI finds a board by the presence of `.task/config.json`; so does this.
+ * Depth is capped the same way, and the ordering — "." first, then
+ * lexicographic — is copied so the default board is the same one you'd get
+ * locally.
+ */
+export function findBoardDirs(paths: string[]): string[] {
+  const marker = `${TASK_DIR}/${CONFIG_FILE}`
+  const dirs: string[] = []
+  for (const path of paths) {
+    // The directory has to be `.task` itself, not merely end in it — a bare
+    // suffix match would read `x.task/config.json` as a board at `x`.
+    if (path !== marker && !path.endsWith(`/${marker}`)) continue
+    const dir = path.slice(0, -(TASK_DIR.length + CONFIG_FILE.length + 2))
+    const id = dir === "" ? "." : dir.replace(/\/$/, "")
+    if (id !== "." && id.split("/").length > MAX_DEPTH) continue
+    dirs.push(id)
+  }
+  dirs.sort((a, b) => (a === "." ? -1 : b === "." ? 1 : a < b ? -1 : 1))
+  return dirs
+}
+
+/** `projects/phone/web` → "phone web"-ish fallback name, matching `task init`. */
+function nameFromDir(id: string): string {
+  if (id === ".") return "tasks"
+  return id.split("/").pop() ?? "tasks"
+}
+
+/**
+ * One board from its ticket files. `files` is keyed by path relative to the
+ * board's `.task/` — `tickets/12/ticket.md`, `tickets/12/comments/<stem>.md` —
+ * which is how `snapshotAt` fetches them and how the test feeds them from
+ * disk.
+ */
+export function readTicketsBoard(
+  id: string,
+  configBytes: Uint8Array,
+  files: Map<string, Uint8Array>,
+): BoardData {
+  const config = parseConfig(configBytes, nameFromDir(id))
+  const decoder = new TextDecoder()
+
+  const docs = new Map<string, TicketDoc>()
+  const comments = new Map<string, Comment[]>()
+  const asks = new Map<string, Ask[]>()
+  const goals: Goal[] = []
+  for (const [path, bytes] of files) {
+    // Goals: one file per goal, archived ones one level down. Old branches
+    // simply have no goals/ — the list stays empty and every reader tolerates
+    // a ticket's goal ref not resolving.
+    const goalMatch = new RegExp(`^${GOALS_DIR}/(archive/)?([^/]+)\\.md$`).exec(path)
+    if (goalMatch) {
+      if (goalMatch[2].startsWith(".")) continue
+      const doc = parseGoalLenient(decoder.decode(bytes))
+      if (doc) {
+        goals.push({
+          slug: goalMatch[2],
+          title: doc.title,
+          description: doc.description,
+          createdAt: doc.createdAt,
+          updatedAt: doc.updatedAt,
+          ...(goalMatch[1] ? { archived: true } : {}),
+        })
+      }
+      continue
+    }
+    const ticketMatch = new RegExp(`^${TICKETS_DIR}/([^/]+)/${TICKET_FILE}$`).exec(path)
+    if (ticketMatch && isTicketKey(ticketMatch[1])) {
+      const doc = parseTicketLenient(decoder.decode(bytes))
+      if (doc) docs.set(ticketMatch[1], doc)
+      continue
+    }
+    const commentMatch = new RegExp(`^${TICKETS_DIR}/([^/]+)/${COMMENTS_DIR}/([^/]+)\\.md$`).exec(
+      path,
+    )
+    if (commentMatch && isTicketKey(commentMatch[1]) && !commentMatch[2].startsWith(".")) {
+      const doc = parseCommentLenient(decoder.decode(bytes))
+      if (!doc) continue
+      const taskKey = commentMatch[1]
+      const list = comments.get(taskKey) ?? []
+      list.push({
+        id: commentMatch[2],
+        taskId: `${config.prefix}-${taskKey}`,
+        author: doc.author,
+        body: doc.body,
+        createdAt: doc.createdAt,
+      })
+      comments.set(taskKey, list)
+      continue
+    }
+    const askMatch = new RegExp(`^${TICKETS_DIR}/([^/]+)/${ASKS_DIR}/([^/]+)\\.md$`).exec(path)
+    if (askMatch && isTicketKey(askMatch[1]) && !askMatch[2].startsWith(".")) {
+      const doc = parseAskLenient(decoder.decode(bytes))
+      if (!doc) continue
+      const taskKey = askMatch[1]
+      const list = asks.get(taskKey) ?? []
+      // Ordinal assigned after the sort below — 0 is a placeholder.
+      list.push({
+        id: askMatch[2],
+        taskId: `${config.prefix}-${taskKey}`,
+        ordinal: 0,
+        text: doc.body,
+        author: doc.author,
+        createdAt: doc.createdAt,
+        resolvedAt: doc.resolvedAt,
+        resolvedBy: doc.resolvedBy,
+      })
+      asks.set(taskKey, list)
+    }
+  }
+  // Comments whose ticket file is missing or unreadable would count against a
+  // ticket that isn't drawn — drop them, and order the rest the CLI's way.
+  for (const taskKey of comments.keys()) {
+    if (!docs.has(taskKey)) comments.delete(taskKey)
+  }
+  for (const list of comments.values()) {
+    list.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id))
+  }
+  // Asks: same orphan rule, and ordinals are creation-order positions — the
+  // exact numbering the CLI's `asks()` derives.
+  for (const taskKey of asks.keys()) {
+    if (!docs.has(taskKey)) asks.delete(taskKey)
+  }
+  for (const list of asks.values()) {
+    list.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id))
+    list.forEach((ask, index) => (ask.ordinal = index + 1))
+  }
+
+  // `blocks` is derived from the other tickets' stored `blocked_by` — the
+  // relation lives on one side only, so the two views can't disagree.
+  const blocks = new Map<string, string[]>()
+  for (const [key, doc] of docs) {
+    for (const blocker of doc.blockedBy) {
+      blocks.set(blocker, [...(blocks.get(blocker) ?? []), key])
+    }
+  }
+  for (const list of blocks.values()) list.sort((a, b) => a.localeCompare(b))
+
+  const tasks: Task[] = [...docs.entries()]
+    .map(([key, doc]) => ({
+      id: `${config.prefix}-${key}`,
+      key,
+      title: doc.title,
+      description: doc.description,
+      status: doc.status,
+      tags: doc.tags,
+      goal: doc.goal,
+      needsHuman: (asks.get(key) ?? []).some((a) => !a.resolvedAt),
+      asks: asks.get(key) ?? [],
+      blocks: blocks.get(key) ?? [],
+      blockedBy: doc.blockedBy,
+      prs: doc.prs,
+      position: doc.position,
+      createdAt: doc.createdAt,
+      updatedAt: doc.updatedAt,
+      commentCount: comments.get(key)?.length ?? 0,
+    }))
+    .sort(
+      (a, b) =>
+        a.position - b.position ||
+        a.createdAt.localeCompare(b.createdAt) ||
+        a.key.localeCompare(b.key),
+    )
+
+  goals.sort(
+    (a, b) => Number(a.archived === true) - Number(b.archived === true) || a.slug.localeCompare(b.slug),
+  )
+  return { info: { id, name: config.name, prefix: config.prefix }, tasks, comments, goals }
+}
+
+/**
+ * Every board in a repository at a known commit, ready to serve.
+ *
+ * One request for the whole repository: every path, plus bytes for anything
+ * under a .task/ directory. (Earlier shapes — a tree listing plus per-file or
+ * batched blob reads — scaled subrequests with board size and tripped
+ * Workers' 50-subrequest ceiling; a tarball is one request regardless.)
+ *
+ * `ref` is only for the error message: told a branch, "this repository has
+ * no .task directory" is both wrong and confusing — the repository plainly
+ * has one, you were just looking at it — and `task init` is not the fix for
+ * previewing a branch that forked before the boards existed.
+ */
+export async function snapshotAt(
+  token: string,
+  owner: string,
+  repo: string,
+  commit: CommitInfo,
+  ref = "HEAD",
+): Promise<Snapshot> {
+  const { paths, files } = await fetchRepoArchive(token, owner, repo, commit.sha, (path) =>
+    path.startsWith(`${TASK_DIR}/`) || path.includes(`/${TASK_DIR}/`),
+  )
+  const dirs = findBoardDirs(paths)
+  if (dirs.length === 0) {
+    throw new BoardSourceError(
+      404,
+      ref === "HEAD"
+        ? "no .task directory in this repository — run `task init` and commit it"
+        : `no .task directory on ${ref}`,
+      "no-boards",
+    )
+  }
+
+  const data = new Map<string, BoardData>()
+  for (const id of dirs) {
+    const base = id === "." ? TASK_DIR : `${id}/${TASK_DIR}`
+    const configBytes = files.get(`${base}/${CONFIG_FILE}`)
+    if (!configBytes) continue
+
+    const prefix = `${base}/`
+    const ticketPaths = paths.filter(
+      (path) =>
+        (path.startsWith(`${prefix}${TICKETS_DIR}/`) || path.startsWith(`${prefix}${GOALS_DIR}/`)) &&
+        path.endsWith(".md"),
+    )
+    // A config with no committed tickets can be two very different things: a
+    // real (empty) text board, or a pre-0.6 board whose state is a SQLite
+    // database this app no longer reads. The config's version says which —
+    // skip the legacy one rather than render an empty board that lies.
+    if (ticketPaths.length === 0 && parseConfig(configBytes, "").version < 2) continue
+
+    const tickets = new Map<string, Uint8Array>()
+    for (const path of ticketPaths) {
+      const bytes = files.get(path)
+      if (bytes) tickets.set(path.slice(prefix.length), bytes)
+    }
+    const board = readTicketsBoard(id, configBytes, tickets)
+    data.set(board.info.id, board)
+  }
+  if (data.size === 0) {
+    throw new BoardSourceError(
+      404,
+      "found .task/config.json but no committed tickets — are .task/tickets/ gitignored, or is this a pre-0.6 SQLite board that still needs `task migrate` (@nickmeriano/task@0.6)?",
+    )
+  }
+
+  return {
+    commit,
+    boards: [...data.values()].map((board) => board.info),
+    data,
+    truncated: false,
+  }
+}
+
+/**
+ * Every board at `ref`, cache-free: "what is HEAD" plus one tarball. Callers
+ * that serve more than one view put a cache between the two — see
+ * `SnapshotMemory` — because the second request is the expensive one and a
+ * commit never changes.
+ */
+export async function loadSnapshot(
+  token: string,
+  owner: string,
+  repo: string,
+  ref: string,
+): Promise<Snapshot> {
+  const commit = await headCommit(token, owner, repo, ref)
+  return snapshotAt(token, owner, repo, commit, ref)
+}
+
+/**
+ * Parsed snapshots, keyed by `owner/repo@sha`, bounded.
+ *
+ * A commit is immutable, so this never serves anything stale: the only lookup
+ * that goes to GitHub on a warm instance is "what is HEAD right now", and a
+ * new commit is a new key. Bounded because an isolate's memory is not ours to
+ * fill; `Map` iterates in insertion order, so the first key is the oldest.
+ */
+export class SnapshotMemory {
+  private readonly snapshots = new Map<string, Snapshot>()
+  private readonly max: number
+
+  constructor(max = 24) {
+    this.max = max
+  }
+
+  get(key: string): Snapshot | undefined {
+    return this.snapshots.get(key)
+  }
+
+  remember(key: string, snapshot: Snapshot): Snapshot {
+    this.snapshots.set(key, snapshot)
+    while (this.snapshots.size > this.max) {
+      const oldest = this.snapshots.keys().next().value
+      if (oldest === undefined) break
+      this.snapshots.delete(oldest)
+    }
+    return snapshot
+  }
+}

package/src/board/tar.test.ts

@@ -0,0 +1,128 @@
+/**
+ * The tar walk is hand-written against a binary format, so it's tested the
+ * way the SQLite reader used to be: against archives built independently —
+ * here by a minimal tar *writer* that produces the same shapes GitHub's
+ * tarballs contain (ustar headers, a pax_global_header, pax path overrides,
+ * a wrapping root directory), gzipped through node:zlib.
+ */
+
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import { gzipSync } from "node:zlib"
+import { readTar, TarError } from "./tar.ts"
+
+const encoder = new TextEncoder()
+
+interface Entry {
+  name: string
+  type?: string
+  data?: string
+  /** Extra pax header naming this entry, the way GitHub emits long paths. */
+  paxPath?: string
+}
+
+function header(name: string, type: string, size: number): Uint8Array {
+  const block = new Uint8Array(512)
+  block.set(encoder.encode(name).subarray(0, 100), 0)
+  block.set(encoder.encode("0000644\0"), 100)
+  block.set(encoder.encode(size.toString(8).padStart(11, "0") + "\0"), 124)
+  block.set(encoder.encode("00000000000\0"), 136)
+  block[156] = type.charCodeAt(0)
+  block.set(encoder.encode("ustar\x0000"), 257)
+  // Checksum: field treated as spaces while summing.
+  block.set(encoder.encode("        "), 148)
+  const sum = block.reduce((a, b) => a + b, 0)
+  block.set(encoder.encode(sum.toString(8).padStart(6, "0") + "\0 "), 148)
+  return block
+}
+
+function tarball(entries: Entry[]): Uint8Array {
+  const blocks: Uint8Array[] = []
+  for (const entry of entries) {
+    if (entry.paxPath) {
+      const record = ` path=${entry.paxPath}\n`
+      const body = `${record.length + String(record.length + 2).length}${record}`
+      const bytes = encoder.encode(body)
+      blocks.push(header("./PaxHeaders/x", "x", bytes.length), pad(bytes))
+    }
+    const data = encoder.encode(entry.data ?? "")
+    blocks.push(header(entry.name, entry.type ?? "0", data.length))
+    if (data.length > 0) blocks.push(pad(data))
+  }
+  blocks.push(new Uint8Array(1024))
+  const total = blocks.reduce((n, b) => n + b.length, 0)
+  const out = new Uint8Array(total)
+  let at = 0
+  for (const block of blocks) {
+    out.set(block, at)
+    at += block.length
+  }
+  return out
+}
+
+function pad(data: Uint8Array): Uint8Array {
+  const padded = new Uint8Array(Math.ceil(data.length / 512) * 512)
+  padded.set(data)
+  return padded
+}
+
+function stream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new Response(gzipSync(bytes)).body!.pipeThrough(
+    new DecompressionStream("gzip"),
+  ) as ReadableStream<Uint8Array>
+}
+
+test("walks a GitHub-shaped tarball: root stripped, kept bytes kept, rest skipped", async () => {
+  const bytes = tarball([
+    { name: "pax_global_header", type: "g", data: "52 comment=1234\n" },
+    { name: "owner-repo-abc123/", type: "5" },
+    { name: "owner-repo-abc123/README.md", data: "# hi" },
+    { name: "owner-repo-abc123/.task/config.json", data: '{"name":"x","prefix":"X","version":2}' },
+    { name: "owner-repo-abc123/.task/tickets/1/ticket.md", data: "---\nstatus: todo\n---\n\n# T\n" },
+    { name: "owner-repo-abc123/big/blob.bin", data: "z".repeat(5000) },
+    { name: "owner-repo-abc123/pkg/.task/config.json", data: "{}" },
+  ])
+  const { paths, files } = await readTar(stream(bytes), (path) => path.includes(".task/"))
+  assert.deepEqual(paths, [
+    "README.md",
+    ".task/config.json",
+    ".task/tickets/1/ticket.md",
+    "big/blob.bin",
+    "pkg/.task/config.json",
+  ])
+  assert.deepEqual([...files.keys()], [
+    ".task/config.json",
+    ".task/tickets/1/ticket.md",
+    "pkg/.task/config.json",
+  ])
+  assert.equal(new TextDecoder().decode(files.get(".task/tickets/1/ticket.md")), "---\nstatus: todo\n---\n\n# T\n")
+})
+
+test("pax path records override the header name, as GitHub does for long paths", async () => {
+  const longPath = `owner-repo-abc123/${"deeply/".repeat(20)}.task/config.json`
+  const bytes = tarball([
+    { name: "owner-repo-abc123/x", paxPath: longPath, data: "{}" },
+  ])
+  const { paths, files } = await readTar(stream(bytes), () => true)
+  assert.deepEqual(paths, [longPath.slice("owner-repo-abc123/".length)])
+  assert.equal(files.size, 1)
+})
+
+test("ustar prefix fields are joined back onto the name", async () => {
+  const bytes = tarball([{ name: "owner-repo-abc123/plain.txt", data: "ok" }])
+  // Craft one entry using the prefix field by hand.
+  const block = header("tail.txt", "0", 2)
+  block.set(encoder.encode("owner-repo-abc123/some/dir"), 345)
+  const data = pad(encoder.encode("ok"))
+  const joined = new Uint8Array(bytes.length + block.length + data.length)
+  joined.set(block, 0)
+  joined.set(data, block.length)
+  joined.set(bytes, block.length + data.length)
+  const { paths } = await readTar(stream(joined), () => false)
+  assert.deepEqual(paths, ["some/dir/tail.txt", "plain.txt"])
+})
+
+test("a truncated archive throws instead of returning half a repository", async () => {
+  const bytes = tarball([{ name: "owner-repo-abc123/a.txt", data: "hello" }])
+  await assert.rejects(readTar(stream(bytes.subarray(0, 600)), () => true), TarError)
+})