@nickmeriano/task 0.10.0 → 0.12.0

package/src/board/handler.ts

@@ -0,0 +1,228 @@
+/**
+ * The live proxy: an exported board's API, as one fetch handler.
+ *
+ * `task export` ships the board as static files plus a baked `snapshot.json`.
+ * Drop this next to them — as a Cloudflare Pages Function, or behind any host
+ * that can run a `(Request) => Response` — hand it a token, and the same
+ * files become a live board: the SPA probes for an API before it mounts,
+ * finds this one answering, and never reads the snapshot at all. No token,
+ * no function, and the probe fails and the snapshot is what you get. The
+ * upgrade is the deploy, not a rebuild.
+ *
+ * The routes are `task serve`'s read routes — the same ones the snapshot
+ * answers (`ui/src/snapshot.ts`), plus the two things a live proxy is *for*:
+ * `?ref=` to read any branch, and `/branches` so the switcher has something to
+ * list. Payloads come from `source.ts`, which is what the hosted board serves,
+ * so a board rendered from this differs from the hosted one in one thing:
+ * who may look. This tier has no viewer auth — the perimeter is wherever you
+ * deploy it — and it says so in `/project` the only way the SPA reads:
+ * `readOnly: true`, no `git` capability.
+ *
+ * Read-only by construction: anything but GET is a 405 before a token is
+ * even resolved.
+ */
+
+import { GitHubError, headCommit, isMissingRef, listBranches, repoInfo } from "./github.ts"
+import {
+  BoardSourceError,
+  SnapshotMemory,
+  STATUSES,
+  snapshotAt,
+  type BoardData,
+  type Snapshot,
+} from "./source.ts"
+
+export interface BoardHandlerOptions {
+  /**
+   * A bearer token GitHub will accept for reading the repository — a
+   * fine-grained PAT with `Contents: Read-only` on this one repo is the
+   * shape the README walks through — or a function that produces one, for
+   * an adapter that mints its own (an installation token, say). Called per
+   * request; cache in the getter if minting is expensive.
+   */
+  token: string | (() => string | Promise<string>)
+  /** `owner/name`. */
+  repo: string
+  /** What a request with no `?ref=` reads. Default `HEAD`: the default branch. */
+  ref?: string
+  /**
+   * Where the handler is mounted, so it can strip the prefix off incoming
+   * paths. `task export` writes `<base>api` here — `/api` at a domain root,
+   * `/board/api` under `--base /board/` — matching where the SPA looks.
+   */
+  basePath?: string
+  /** Snapshots kept in memory, by commit. Default 24. */
+  maxCachedSnapshots?: number
+}
+
+export type BoardHandler = (request: Request) => Promise<Response>
+
+const REF_PATTERN = /^[\w.\-/]{1,255}$/
+
+/** `owner/name`, both halves as GitHub spells them. */
+export const REPO_PATTERN = /^[\w.-]+\/[\w.-]+$/
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "Content-Type": "application/json; charset=utf-8",
+      // Every answer is "the repository right now"; nothing between this
+      // function and the browser should hold on to one.
+      "Cache-Control": "no-store",
+    },
+  })
+}
+
+/** The board the request asked for, or the repo's default — `pickBoard`'s rule. */
+function pickBoard(snapshot: Snapshot, requested: string | null): BoardData | null {
+  const id = requested && snapshot.data.has(requested) ? requested : snapshot.boards[0]?.id
+  return id === undefined ? null : (snapshot.data.get(id) ?? null)
+}
+
+export function createBoardHandler(options: BoardHandlerOptions): BoardHandler {
+  const { repo: slug, ref: defaultRef = "HEAD" } = options
+  if (!REPO_PATTERN.test(slug)) throw new Error(`repo must be owner/name — got ${JSON.stringify(slug)}`)
+  const [owner, repo] = slug.split("/")
+  const basePath = (options.basePath ?? "/api").replace(/\/+$/, "")
+  const memory = new SnapshotMemory(options.maxCachedSnapshots)
+  // A cold start sees the SPA's four boot requests at once, all for the same
+  // commit. One tarball, not four: the first caller's load is shared with
+  // everyone who asks for that sha while it is still in flight.
+  const inFlight = new Map<string, Promise<Snapshot>>()
+
+  async function resolveToken(): Promise<string> {
+    const token = typeof options.token === "function" ? await options.token() : options.token
+    if (!token) {
+      // Unconfigured is not an error the board can act on; it is "no API",
+      // and a 5xx is exactly what makes the SPA's probe fall back to the
+      // snapshot sitting next to this function.
+      throw new BoardSourceError(503, "no GitHub token configured for the live board", "no-token")
+    }
+    return token
+  }
+
+  async function load(token: string, ref: string, explicit: boolean): Promise<Snapshot> {
+    let commit
+    try {
+      commit = await headCommit(token, owner, repo, ref)
+    } catch (error) {
+      // With an explicit ref, a miss almost always means the branch — a
+      // deleted preview, a typo — not the repository.
+      if (explicit && isMissingRef(error)) {
+        throw new BoardSourceError(404, `no such branch or ref: ${ref}`, "no-such-ref")
+      }
+      throw error
+    }
+    const key = `${owner}/${repo}@${commit.sha}`
+    const cached = memory.get(key)
+    if (cached) return cached
+    let pending = inFlight.get(key)
+    if (!pending) {
+      pending = snapshotAt(token, owner, repo, commit, ref)
+        .then((snapshot) => memory.remember(key, snapshot))
+        .finally(() => inFlight.delete(key))
+      inFlight.set(key, pending)
+    }
+    return pending
+  }
+
+  async function handle(request: Request): Promise<Response> {
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      // Every editing affordance is already hidden by `readOnly`; this is the
+      // backstop, in the shape `ApiError` reads.
+      return json(
+        { error: "this board is read-only — commit and push to change it", reason: "read-only" },
+        405,
+      )
+    }
+    const url = new URL(request.url)
+    if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`)) {
+      return json({ error: `not an API path: ${url.pathname}` }, 404)
+    }
+    const route = url.pathname.slice(basePath.length) || "/"
+    const token = await resolveToken()
+
+    if (route === "/branches") {
+      // Default branch first (it's the way back), then alphabetical — the
+      // hosted board's order, which is the order the switcher expects.
+      const [names, info] = await Promise.all([
+        listBranches(token, owner, repo),
+        repoInfo(token, owner, repo),
+      ])
+      const branches = names
+        .map((name) => ({ name, isDefault: name === info.defaultBranch }))
+        .sort((a, b) => Number(b.isDefault) - Number(a.isDefault) || a.name.localeCompare(b.name))
+      return json({ branches })
+    }
+
+    // A ref is a viewer-supplied string that lands in a URL path; anything
+    // outside git's own naming rules is ignored rather than escaped.
+    const requestedRef = url.searchParams.get("ref")
+    const ref =
+      requestedRef && REF_PATTERN.test(requestedRef) && !requestedRef.includes("..")
+        ? requestedRef
+        : null
+    const snapshot = await load(token, ref ?? defaultRef, ref !== null)
+
+    if (route === "/boards") return json({ boards: snapshot.boards })
+
+    const board = pickBoard(snapshot, url.searchParams.get("board"))
+    if (!board) return json({ error: "no such board" }, 404)
+
+    if (route === "/project") {
+      return json({
+        name: board.info.name,
+        prefix: board.info.prefix,
+        statuses: STATUSES,
+        // The payload the SPA reads to decide whether to offer editing at all.
+        // The data is a commit; the only way to change one is to push.
+        readOnly: true,
+        // Locally this is who would author a comment. Nothing here can
+        // comment, and nothing here knows who is looking.
+        author: "",
+      })
+    }
+    if (route === "/tasks") return json({ tasks: board.tasks })
+    if (route === "/goals") return json({ goals: board.goals })
+
+    const detail = /^\/tasks\/([^/]+)$/.exec(route)
+    if (detail) {
+      // The CLI accepts "PREFIX-x7k4m" or "x7k4m"; so does this.
+      const match = /^(?:[A-Za-z0-9]+-)?([A-Za-z0-9]+)$/.exec(decodeURIComponent(detail[1]))
+      if (!match) return json({ error: "invalid task id" }, 400)
+      const key = match[1].toLowerCase()
+      const task = board.tasks.find((candidate) => candidate.key === key)
+      if (!task) return json({ error: `no such task: ${key}` }, 404)
+      return json({ task, comments: board.comments.get(key) ?? [] })
+    }
+
+    // `/inbox` and the git surface are deliberately absent: the SPA degrades
+    // to no inbox and no git chrome when they 404, same as the hosted board.
+    return json({ error: `not here: ${route}` }, 404)
+  }
+
+  return async (request) => {
+    try {
+      return await handle(request)
+    } catch (error) {
+      if (error instanceof BoardSourceError) {
+        return json({ error: error.message, reason: error.reason }, error.status)
+      }
+      if (error instanceof GitHubError) {
+        // A bad or expired token, a repo the token can't see, GitHub itself
+        // down: all of them are "the live board can't answer right now". A
+        // 5xx is deliberate — on the boot probe it is what sends the SPA to
+        // the snapshot instead of an error screen.
+        return json(
+          {
+            error: `GitHub answered ${error.status} — check the token and the repository name`,
+            reason: "github",
+          },
+          502,
+        )
+      }
+      return json({ error: error instanceof Error ? error.message : "internal error" }, 500)
+    }
+  }
+}

package/src/board/pages-function.ts

@@ -0,0 +1,42 @@
+/**
+ * The Cloudflare Pages Function `task export --functions` writes.
+ *
+ * Bundled into one dependency-free module (`dist/functions/board.js`, built
+ * by `vite.functions.config.ts`) because the deployed directory has no
+ * `node_modules` — the file has to carry the handler with it. The export
+ * copies it to `functions[/<base>]/api/[[path]].js` and fills in the two
+ * placeholders below; nothing else about it is per-repo.
+ *
+ * The token is read per request from the Pages project's secrets. Unset, the
+ * function answers 503 without touching GitHub: the SPA's boot probe reads
+ * that as "no API" and falls back to the snapshot beside this file, which is
+ * the documented behaviour of a live board that isn't configured yet.
+ */
+
+import { createBoardHandler, type BoardHandler } from "./handler.ts"
+
+/** Replaced by `task export` when the file is written. */
+const REPO = "__TASK_EXPORT_REPO__"
+const BASE_PATH = "__TASK_EXPORT_BASE_PATH__"
+
+/** The secret's name in the Pages project; the README says how to set it. */
+export const TOKEN_SECRET = "TASK_GITHUB_TOKEN"
+
+interface PagesContext {
+  request: Request
+  env: Record<string, string | undefined>
+}
+
+let currentToken = ""
+let handler: BoardHandler | null = null
+
+export function onRequest(context: PagesContext): Promise<Response> | Response {
+  const token = context.env[TOKEN_SECRET]
+  if (!token) return new Response(null, { status: 503 })
+  currentToken = token
+  // One handler per isolate, so the snapshot cache survives between requests;
+  // the token is read through a getter so a rotated secret takes effect
+  // without waiting for the isolate to be recycled.
+  handler ??= createBoardHandler({ token: () => currentToken, repo: REPO, basePath: BASE_PATH })
+  return handler(context.request)
+}

package/src/board/source.test.ts

@@ -0,0 +1,203 @@
+/**
+ * The hosted board and an exported board's live proxy serve the same SPA as
+ * `task serve`, so their payloads have to be the same payloads — not
+ * "compatible", the same. This diffs them against the CLI's own `FileStore`.
+ *
+ * That is the test that actually protects the design: if someone adds a field
+ * to the CLI's `toTask` and not here, the hosted board silently loses it, and
+ * the only symptom is a piece of the UI that renders blank for one deployment
+ * and not the other.
+ */
+
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { fileURLToPath } from "node:url"
+import { join } from "node:path"
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import type { Store } from "../store.ts"
+import { FileStore, initProject } from "../file-store.ts"
+import { findBoardDirs, readTicketsBoard, type BoardData } from "./source.ts"
+
+const REPO_ROOT = fileURLToPath(new URL("../../../../..", import.meta.url))
+
+/** Every board this repo actually commits, as `findBoards` would order them. */
+const BOARDS = [".", "projects/inspo", "projects/phone/web", "projects/portal", "projects/task/cli"]
+
+function tempRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "board-source-test-"))
+  process.on("exit", () => rmSync(dir, { recursive: true, force: true }))
+  return dir
+}
+
+/** A board's `.task/` read off disk into the path→bytes map the worker sees. */
+function ticketFiles(taskDir: string): Map<string, Uint8Array> {
+  const files = new Map<string, Uint8Array>()
+  for (const dir of ["goals", "goals/archive"]) {
+    const goalsDir = join(taskDir, dir)
+    if (!existsSync(goalsDir)) continue
+    for (const entry of readdirSync(goalsDir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith(".md")) continue
+      files.set(`${dir}/${entry.name}`, new Uint8Array(readFileSync(join(goalsDir, entry.name))))
+    }
+  }
+  const ticketsDir = join(taskDir, "tickets")
+  if (!existsSync(ticketsDir)) return files
+  for (const number of readdirSync(ticketsDir)) {
+    const ticket = join(ticketsDir, number, "ticket.md")
+    if (existsSync(ticket)) {
+      files.set(`tickets/${number}/ticket.md`, new Uint8Array(readFileSync(ticket)))
+    }
+    for (const kind of ["comments", "asks"]) {
+      const dir = join(ticketsDir, number, kind)
+      if (!existsSync(dir)) continue
+      for (const entry of readdirSync(dir)) {
+        files.set(
+          `tickets/${number}/${kind}/${entry}`,
+          new Uint8Array(readFileSync(join(dir, entry))),
+        )
+      }
+    }
+  }
+  return files
+}
+
+function loadTicketsBoard(id: string, root: string): BoardData {
+  const taskDir = join(root, ".task")
+  return readTicketsBoard(
+    id,
+    new Uint8Array(readFileSync(join(taskDir, "config.json"))),
+    ticketFiles(taskDir),
+  )
+}
+
+/** `GET /api/tasks` + per-task comments, straight from the CLI store. */
+function expectedPayloads(store: Store) {
+  const counts = store.commentCounts()
+  const tasks = store.list().map((task) => ({
+    ...task,
+    commentCount: counts.get(task.key) ?? 0,
+  }))
+  return { tasks, comments: new Map(tasks.map((t) => [t.key, store.comments(t.key)])) }
+}
+
+function assertSamePayloads(id: string, hosted: BoardData, store: Store): void {
+  assert.equal(hosted.info.name, store.config.name, `${id}: project name`)
+  assert.equal(hosted.info.prefix, store.config.prefix, `${id}: prefix`)
+  const expected = expectedPayloads(store)
+  assert.equal(hosted.tasks.length, expected.tasks.length, `${id}: task count`)
+  for (let i = 0; i < expected.tasks.length; i++) {
+    assert.deepEqual(hosted.tasks[i], expected.tasks[i], `${id}: task ${expected.tasks[i].id}`)
+  }
+  for (const task of expected.tasks) {
+    assert.deepEqual(
+      hosted.comments.get(task.key) ?? [],
+      expected.comments.get(task.key),
+      `${id}: comments on ${task.id}`,
+    )
+  }
+  assert.deepEqual(
+    hosted.goals,
+    [...store.goals(), ...store.goals(true)],
+    `${id}: goals`,
+  )
+}
+
+test("finds the same boards the CLI would, in the same order", () => {
+  // The shape a recursive git-tree listing arrives in, plus the noise it
+  // really contains: nested boards, unrelated files, and a `.task` path that
+  // is a file rather than a board.
+  const paths = [
+    "README.md",
+    ".task/config.json",
+    ".task/tickets/1/ticket.md",
+    "projects/phone/web/.task/config.json",
+    "projects/task/cli/.task/config.json",
+    "docs/.taskrc",
+    "vendor/thing/.task/config.json.bak",
+    // A directory that merely *ends* in `.task` is not a board directory.
+    "lib/x.task/config.json",
+  ]
+  assert.deepEqual(findBoardDirs(paths), [".", "projects/phone/web", "projects/task/cli"])
+})
+
+test("ignores boards nested deeper than the CLI would walk", () => {
+  const deep = "a/b/c/d/e/f/g/.task/config.json"
+  assert.deepEqual(findBoardDirs([deep]), [])
+  assert.deepEqual(findBoardDirs(["a/b/c/.task/config.json"]), ["a/b/c"])
+})
+
+test("text boards produce the same payloads the CLI's FileStore does", () => {
+  const root = tempRoot()
+  const store = initProject(root, { name: "fixture board", prefix: "FIX" })
+  store.createGoal({ title: "Launch", description: "the shared why" })
+  const one = store.create({
+    title: "Every field exercised",
+    description: "A *body* with\n\n# an inner heading\n\nand `code`.",
+    tags: ["api", "infra"],
+    goal: "launch",
+    prs: ["https://github.com/x/y/pull/3"],
+  })
+  store.addAsk(one.key, "Approve the launch window", "claude")
+  const two = store.create({ title: "Mover", status: "backlog" })
+  store.create({ title: "Plain" })
+  store.update(two.key, { status: "in_progress" }) // lands on top → negative position
+  store.link(two.key, "blocked_by", one.key)
+  store.addComment(one.key, "first, with **markdown**", "nick")
+  store.addComment(one.key, "second", "claude")
+
+  assertSamePayloads("fixture", loadTicketsBoard("fixture", root), store)
+})
+
+test("this repo's committed boards read as text, same as the CLI reads them", () => {
+  for (const id of BOARDS) {
+    const root = id === "." ? REPO_ROOT : join(REPO_ROOT, id)
+    assertSamePayloads(id, loadTicketsBoard(id, root), new FileStore(root))
+  }
+})
+
+test("every committed board is non-empty and self-consistent", () => {
+  // A smoke check that the fixtures above are actually exercising something —
+  // boards that all happened to be empty would make the diff vacuous.
+  const loaded = BOARDS.map((id) =>
+    loadTicketsBoard(id, id === "." ? REPO_ROOT : join(REPO_ROOT, id)),
+  )
+  const total = loaded.reduce((sum, board) => sum + board.tasks.length, 0)
+  assert.ok(total > 10, `expected the repo's boards to hold real tasks, found ${total}`)
+
+  for (const board of loaded) {
+    for (const task of board.tasks) {
+      assert.match(task.id, /^[A-Z0-9]+-[a-z0-9]+$/, `${board.info.id}: display id`)
+      assert.ok(Array.isArray(task.tags), `${board.info.id}: tags parsed`)
+      assert.equal(typeof task.needsHuman, "boolean", `${board.info.id}: needsHuman`)
+    }
+  }
+})
+
+test("a broken ticket degrades instead of breaking the board", () => {
+  const config = new TextEncoder().encode(
+    JSON.stringify({ name: "rough", prefix: "RGH", version: 2 }),
+  )
+  const encode = (s: string) => new TextEncoder().encode(s)
+  const board = readTicketsBoard(
+    "rough",
+    config,
+    new Map([
+      ["tickets/bad2c/ticket.md", encode("---\nstatus: todoo\nposition: not-a-number\n---\n\nno heading")],
+      ["tickets/gone3/ticket.md", encode("not even frontmatter")],
+      ["tickets/fine4/ticket.md", encode("---\nstatus: todo\nposition: 1\ncreated: c\nupdated: u\n---\n\n# Fine\n")],
+      // A comment on a ticket that didn't parse must not surface anywhere.
+      ["tickets/gone3/comments/2026-08-15T120000-x.md", encode("---\nauthor: \"x\"\ncreated: c\n---\n\nhi")],
+      // A pre-TAS-42 numeric directory is not a ticket to this reader at all.
+      ["tickets/42/ticket.md", encode("---\nstatus: todo\nposition: 1\ncreated: c\nupdated: u\n---\n\n# Old format\n")],
+    ]),
+  )
+  assert.deepEqual(
+    board.tasks.map((t) => [t.key, t.status, t.title]),
+    [
+      ["bad2c", "backlog", ""],
+      ["fine4", "todo", "Fine"],
+    ],
+  )
+  assert.equal(board.comments.size, 0)
+})