@nickmeriano/task 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nickmeriano/task",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "A task manager that lives in your repo — plain-text tickets in .task/, a zero-dependency CLI for humans and agents, and a live kanban/table UI via `task serve`.",
   "license": "MIT",
@@ -40,11 +40,11 @@
     "skill"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && vite build ui",
+    "build": "tsc -p tsconfig.build.json && vite build ui && vite build -c vite.functions.config.ts",
     "prepack": "pnpm build",
     "dev": "vite ui",
     "lint": "eslint .",
-    "test": "node --test --experimental-strip-types src/*.test.ts ui/src/*.test.ts",
+    "test": "node --test --experimental-strip-types src/*.test.ts src/board/*.test.ts ui/src/*.test.ts",
     "typecheck": "tsc --noEmit && tsc --noEmit -p ui && tsc --noEmit -p ui/tsconfig.test.json"
   },
   "engines": {

package/skill/SKILL.md

@@ -91,6 +91,8 @@ task unarchive <id> --json             # put one back on the board
 task whoami                            # who comments are attributed to
 task check [--fix] --json              # lint the board files (dangling refs,
                                        # bad files); --fix repairs mechanically
+task export [--out dir] [--base path] [--force] [--no-functions] --json  # static files + a dormant live-proxy function — see
+                                       # "The UI" below
 ```
 
 `task publish` and `task unpublish` also exist — they give the board a URL so
@@ -186,7 +188,7 @@ don't switch: claim with `task claim <id> --lock-only` and keep working on
 your assigned branch. It takes the same atomic lock by pushing the
 `in_progress` flip commit built from origin's default branch — your checkout,
 even a dirty one, is never touched — and records your branch in the flip
-commit (`delivered_by:`), so anyone reading the claim sees where the work
+commit (`Delivered-By:`), so anyone reading the claim sees where the work
 lands. Do the rest of the ticket on your branch as usual, `task move <id>
 done` + `--pr` included. Otherwise plain `task claim` is right: it switches
 you to the claim branch, and prints a reminder about `--lock-only` if it just
@@ -294,6 +296,19 @@ This changes nothing for the other commands: they still operate on the
 nearest `.task/` walking up from the current directory, so `cd` into the
 package whose board you mean before running them.
 
+`task export [--out dir] [--base path] [--force] [--no-functions]` writes that same board out as static
+files — the UI plus a `snapshot.json` it reads instead of an API — for a CI
+job to put on a static host, read-only and with a staleness banner. It's a
+build step, not a way to look at the board: use `task serve` for that, and
+`--json` for anything you need to read yourself. Asked to deploy the board,
+follow the README's "Deploy the board" recipe rather than inventing a workflow
+— note it writes an SPA fallback (`_redirects`) that `task export` does not.
+The export also writes a Cloudflare Pages Function that stays dormant until
+the host has a `TASK_GITHUB_TOKEN` secret (a fine-grained PAT, Contents:
+read-only), then reads the repo live — with no viewer auth, which the README's
+"Live data for an exported board" spells out. `--no-functions` skips it.
+Never mint or paste a token yourself.
+
 On a git checkout with an origin, the served UI also carries a git surface:
 a branch chip (current branch, dirty board files, ahead/behind), board-scoped
 commits (`chore(board): …`, pathspec-limited to `.task/` so unrelated dirty

package/src/asks.test.ts

@@ -275,6 +275,17 @@ test("a claimed ticket's asks reach the inbox from its branch", async () => {
     sh(verify, "git", "show", `FETCH_HEAD:.task/tickets/${key}/asks/${askFile}`),
     /resolved_by: "nick"/,
   )
+  // The trailer contract (trailers.ts): the resolve landed as its own commit
+  // whose Task-Op/Task-Id automation keys on — pinned, because a poke
+  // workflow reads exactly these off the head of the push.
+  assert.equal(
+    sh(verify, "git", "log", "-1", "--format=%(trailers:key=Task-Op,valueonly)", "FETCH_HEAD"),
+    "resolve-ask",
+  )
+  assert.equal(
+    sh(verify, "git", "log", "-1", "--format=%(trailers:key=Task-Id,valueonly)", "FETCH_HEAD"),
+    `CIN-${key}`,
+  )
   const cleared = await cli(owner, "inbox", "--json")
   assert.equal((JSON.parse(cleared.stdout) as { inbox: InboxEntry[] }).inbox.length, 0)
 
@@ -289,6 +300,10 @@ test("a claimed ticket's asks reach the inbox from its branch", async () => {
     sh(verify, "git", "ls-tree", "--name-only", `FETCH_HEAD:.task/tickets/${key}/asks`).split("\n").length,
     2,
   )
+  assert.equal(
+    sh(verify, "git", "log", "-1", "--format=%(trailers:key=Task-Op,valueonly)", "FETCH_HEAD"),
+    "ask",
+  )
   const again = await cli(owner, "inbox", "--json")
   const entries = (JSON.parse(again.stdout) as { inbox: InboxEntry[] }).inbox
   assert.deepEqual(entries[0].asks.map((a) => a.text), ["Also rotate the old key"])

package/src/board/github.ts

@@ -0,0 +1,151 @@
+/**
+ * Reading a repository from GitHub, with a bearer token and nothing else.
+ *
+ * This is the read half of the hosted board's `worker/github.ts`, moved here
+ * so an exported board's live proxy (`handler.ts`) and the hosted worker read
+ * a repository through the same four calls. What deliberately did *not* move
+ * with it: everything that mints or exchanges a credential — App JWTs,
+ * installation tokens, the viewer's OAuth flow. Those are the hosted
+ * product's auth surface and stay in the worker; here a token is a string
+ * somebody already holds (a fine-grained PAT, an installation token the
+ * worker minted), and this module only ever spends it on reads.
+ *
+ * Web-standard only — `fetch`, `Response`, `DecompressionStream` — so the same
+ * source runs under Node 22, a Cloudflare Worker, and a Pages Function.
+ */
+
+import { readTar, TarError, type TarContents } from "./tar.ts"
+
+const API = "https://api.github.com"
+
+/** Sent on every call; GitHub rejects requests without a User-Agent. */
+const UA = "@nickmeriano/task"
+
+export class GitHubError extends Error {
+  readonly status: number
+  constructor(status: number, message: string) {
+    super(message)
+    this.name = "GitHubError"
+    this.status = status
+  }
+}
+
+async function apiGet<T>(token: string, path: string): Promise<T> {
+  const res = await fetch(`${API}${path}`, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/vnd.github+json",
+      "User-Agent": UA,
+    },
+  })
+  if (!res.ok) throw new GitHubError(res.status, `GET ${path} failed (${res.status})`)
+  return (await res.json()) as T
+}
+
+export interface RepoInfo {
+  defaultBranch: string
+  private: boolean
+}
+
+export async function repoInfo(token: string, owner: string, repo: string): Promise<RepoInfo> {
+  const data = await apiGet<{ default_branch: string; private: boolean }>(
+    token,
+    `/repos/${owner}/${repo}`,
+  )
+  return { defaultBranch: data.default_branch, private: data.private }
+}
+
+/**
+ * Branch names, for the board's branch switcher. One page of 100: a selector
+ * over more branches than that stops being a selector, and the switcher's
+ * search box only filters what's listed. Sorting is the caller's job — it
+ * knows the default branch; this endpoint doesn't.
+ */
+export async function listBranches(token: string, owner: string, repo: string): Promise<string[]> {
+  const data = await apiGet<Array<{ name: string }>>(
+    token,
+    `/repos/${owner}/${repo}/branches?per_page=100`,
+  )
+  return data.map((branch) => branch.name)
+}
+
+/** A commit's identity, so the board can say how fresh it is. */
+export interface CommitInfo {
+  sha: string
+  committedAt: string
+  message: string
+}
+
+export async function headCommit(
+  token: string,
+  owner: string,
+  repo: string,
+  ref: string,
+): Promise<CommitInfo> {
+  const data = await apiGet<{
+    sha: string
+    commit: { message: string; committer: { date: string } }
+  }>(token, `/repos/${owner}/${repo}/commits/${encodeURIComponent(ref)}`)
+  return {
+    sha: data.sha,
+    committedAt: data.commit.committer.date,
+    message: data.commit.message.split("\n")[0],
+  }
+}
+
+/**
+ * Did GitHub just say "that ref doesn't exist"?
+ *
+ * It says it two different ways, and the obvious one is the rarer one. Asking
+ * `/repos/{o}/{r}/commits/{ref}` for a branch that isn't there answers **422**
+ * ("No commit found for SHA: …"), not 404 — 404 is what you get when the
+ * repository itself is out of reach. Checking only for 404 let every dead
+ * `?ref=` link fall through to a generic "GitHub is unhappy — try again"
+ * screen: a retry prompt for something no amount of retrying will fix.
+ */
+export function isMissingRef(error: unknown): boolean {
+  return error instanceof GitHubError && (error.status === 404 || error.status === 422)
+}
+
+/**
+ * The whole repository at `sha`, in one request: every file path, plus the
+ * bytes of the paths `keep` selects.
+ *
+ * This replaced two earlier shapes, each broken by arithmetic. Per-file
+ * contents reads were one subrequest per ticket, against the 50-subrequest
+ * ceiling Workers get on the free plan — every cold board view of this repo
+ * 500'd. Batched GraphQL blob reads fixed that, but still cost one tree
+ * listing plus one request per 80 files, scaling with board size. A tarball
+ * is a single request whatever the repo holds, and it carries the path
+ * listing too. Streamed through gzip and a tar walk, keeping bytes only for
+ * `keep`-selected paths, so memory is bounded by the boards rather than the
+ * repository.
+ *
+ * The tarball endpoint answers with a redirect to codeload; fetch follows it.
+ */
+export async function fetchRepoArchive(
+  token: string,
+  owner: string,
+  repo: string,
+  sha: string,
+  keep: (path: string) => boolean,
+): Promise<TarContents> {
+  const res = await fetch(`${API}/repos/${owner}/${repo}/tarball/${encodeURIComponent(sha)}`, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/vnd.github+json",
+      "User-Agent": UA,
+    },
+  })
+  if (!res.ok || !res.body) {
+    throw new GitHubError(res.status, `could not read the repository archive (${res.status})`)
+  }
+  try {
+    return await readTar(res.body.pipeThrough(new DecompressionStream("gzip")), keep)
+  } catch (error) {
+    if (error instanceof TarError) {
+      throw new GitHubError(502, `could not read the repository archive (${error.message})`)
+    }
+    throw error
+  }
+}

package/src/board/handler.test.ts

@@ -0,0 +1,276 @@
+/**
+ * The live proxy, against a fake GitHub.
+ *
+ * `globalThis.fetch` is replaced with a tiny router that answers the four
+ * calls the handler makes — head commit, tarball, branches, repo info — from
+ * an in-memory repository, so what's under test is the handler's routing,
+ * caching and error shapes, not the network. The payloads themselves are
+ * pinned elsewhere (`source.test.ts` diffs them against the CLI's store).
+ */
+
+import assert from "node:assert/strict"
+import { afterEach, beforeEach, mock, test } from "node:test"
+import { gzipSync } from "node:zlib"
+import { createBoardHandler, type BoardHandler } from "./handler.ts"
+
+const encoder = new TextEncoder()
+
+/** Just enough tar to be a GitHub tarball: ustar headers, one root dir. */
+function tarball(root: string, files: Record<string, string>): Uint8Array {
+  const blocks: Uint8Array[] = []
+  for (const [path, text] of Object.entries(files)) {
+    const data = encoder.encode(text)
+    const header = new Uint8Array(512)
+    header.set(encoder.encode(`${root}/${path}`).subarray(0, 100), 0)
+    header.set(encoder.encode("0000644\0"), 100)
+    header.set(encoder.encode(data.length.toString(8).padStart(11, "0") + "\0"), 124)
+    header.set(encoder.encode("00000000000\0"), 136)
+    header[156] = 0x30
+    header.set(encoder.encode("ustar\x0000"), 257)
+    header.set(encoder.encode("        "), 148)
+    const sum = header.reduce((a, b) => a + b, 0)
+    header.set(encoder.encode(sum.toString(8).padStart(6, "0") + "\0 "), 148)
+    const padded = new Uint8Array(Math.ceil(data.length / 512) * 512)
+    padded.set(data)
+    blocks.push(header, padded)
+  }
+  blocks.push(new Uint8Array(1024))
+  const out = new Uint8Array(blocks.reduce((n, b) => n + b.length, 0))
+  let at = 0
+  for (const block of blocks) {
+    out.set(block, at)
+    at += block.length
+  }
+  return out
+}
+
+const CONFIG = JSON.stringify({ name: "acme", prefix: "ACM", version: 2 })
+const ticket = (title: string, status: string, position = 0) =>
+  `---\nstatus: ${status}\nposition: ${position}\ncreated: 2026-01-01T00:00:00.000Z\nupdated: 2026-01-01T00:00:00.000Z\n---\n\n# ${title}\n`
+
+/** Two commits: `main` at `aaa`, `feature` at `bbb`, each its own board state. */
+const COMMITS: Record<string, string> = { HEAD: "aaa", main: "aaa", feature: "bbb" }
+const TREES: Record<string, Record<string, string>> = {
+  aaa: {
+    ".task/config.json": CONFIG,
+    ".task/tickets/x7k4m/ticket.md": ticket("Ship it", "todo"),
+    ".task/tickets/x7k4m/comments/2026-01-02T000000-nick.md":
+      '---\nauthor: "nick"\ncreated: 2026-01-02T00:00:00.000Z\n---\n\nsoon',
+    ".task/goals/launch.md":
+      "---\ncreated: 2026-01-01T00:00:00.000Z\nupdated: 2026-01-01T00:00:00.000Z\n---\n\n# Launch\n",
+    "pkg/.task/config.json": JSON.stringify({ name: "pkg", prefix: "PKG", version: 2 }),
+    "pkg/.task/tickets/q3v8d/ticket.md": ticket("Nested", "backlog"),
+  },
+  bbb: {
+    ".task/config.json": CONFIG,
+    ".task/tickets/x7k4m/ticket.md": ticket("Ship it", "done"),
+    ".task/tickets/zz9zz/ticket.md": ticket("Only on the branch", "todo", 1),
+  },
+}
+
+interface Call {
+  path: string
+  auth: string | null
+}
+
+let calls: Call[] = []
+let githubStatus: number | null = null
+
+function fakeGitHub(input: string | URL | Request, init?: RequestInit): Promise<Response> {
+  const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url)
+  const auth = new Headers(init?.headers).get("Authorization")
+  calls.push({ path: url.pathname, auth })
+  if (githubStatus !== null) return Promise.resolve(new Response("nope", { status: githubStatus }))
+
+  const commit = /^\/repos\/acme\/widgets\/commits\/(.+)$/.exec(url.pathname)
+  if (commit) {
+    const sha = COMMITS[decodeURIComponent(commit[1])]
+    if (!sha) return Promise.resolve(new Response("{}", { status: 422 }))
+    return Promise.resolve(
+      Response.json({
+        sha,
+        commit: { message: `commit ${sha}\n\nbody`, committer: { date: "2026-01-03T00:00:00Z" } },
+      }),
+    )
+  }
+  const tar = /^\/repos\/acme\/widgets\/tarball\/(.+)$/.exec(url.pathname)
+  if (tar) {
+    const tree = TREES[tar[1]]
+    if (!tree) return Promise.resolve(new Response(null, { status: 404 }))
+    return Promise.resolve(new Response(gzipSync(tarball(`acme-widgets-${tar[1]}`, tree))))
+  }
+  if (url.pathname === "/repos/acme/widgets/branches") {
+    return Promise.resolve(Response.json([{ name: "feature" }, { name: "main" }, { name: "docs" }]))
+  }
+  if (url.pathname === "/repos/acme/widgets") {
+    return Promise.resolve(Response.json({ default_branch: "main", private: true }))
+  }
+  return Promise.resolve(new Response(null, { status: 404 }))
+}
+
+beforeEach(() => {
+  calls = []
+  githubStatus = null
+  mock.method(globalThis, "fetch", fakeGitHub)
+})
+afterEach(() => mock.restoreAll())
+
+function handler(extra: Partial<Parameters<typeof createBoardHandler>[0]> = {}): BoardHandler {
+  return createBoardHandler({ token: "ghp_test", repo: "acme/widgets", ...extra })
+}
+
+async function get(h: BoardHandler, path: string, base = "/api") {
+  const res = await h(new Request(`https://board.example${base}${path}`))
+  return { status: res.status, body: (await res.json()) as Record<string, unknown> }
+}
+
+test("answers the read routes in the serve API's shapes", async () => {
+  const h = handler()
+
+  const project = await get(h, "/project")
+  assert.equal(project.status, 200)
+  assert.deepEqual(project.body, {
+    name: "acme",
+    prefix: "ACM",
+    statuses: ["backlog", "todo", "in_progress", "done", "canceled"],
+    readOnly: true,
+    author: "",
+  })
+
+  const boards = await get(h, "/boards")
+  assert.deepEqual(boards.body, {
+    boards: [
+      { id: ".", name: "acme", prefix: "ACM" },
+      { id: "pkg", name: "pkg", prefix: "PKG" },
+    ],
+  })
+
+  const tasks = await get(h, "/tasks")
+  const list = tasks.body.tasks as Array<Record<string, unknown>>
+  assert.deepEqual(
+    list.map((t) => [t.id, t.status, t.commentCount]),
+    [["ACM-x7k4m", "todo", 1]],
+  )
+
+  const goals = await get(h, "/goals")
+  assert.deepEqual((goals.body.goals as Array<{ slug: string }>).map((g) => g.slug), ["launch"])
+
+  // Detail takes the display id or the bare key, like the CLI.
+  for (const id of ["ACM-x7k4m", "x7k4m"]) {
+    const detail = await get(h, `/tasks/${id}`)
+    assert.equal(detail.status, 200, id)
+    assert.equal((detail.body.task as { title: string }).title, "Ship it")
+    assert.deepEqual(
+      (detail.body.comments as Array<{ author: string; body: string }>).map((c) => [c.author, c.body]),
+      [["nick", "soon"]],
+    )
+  }
+  assert.equal((await get(h, "/tasks/nope1")).status, 404)
+  assert.equal((await get(h, "/tasks/not%20an%20id")).status, 400)
+
+  // `?board=` picks the nested board; an unknown one falls back to the default.
+  const nested = await get(h, "/tasks?board=pkg")
+  assert.deepEqual((nested.body.tasks as Array<{ id: string }>).map((t) => t.id), ["PKG-q3v8d"])
+  assert.equal((await get(h, "/project?board=nope")).body.prefix, "ACM")
+
+  // Not in this API: the SPA degrades on a 404 exactly as it does hosted.
+  assert.equal((await get(h, "/inbox")).status, 404)
+  assert.equal((await get(h, "/git/status")).status, 404)
+})
+
+test("anything but a read is refused with the read-only reason", async () => {
+  const h = handler()
+  const res = await h(
+    new Request("https://board.example/api/tasks", { method: "POST", body: "{}" }),
+  )
+  assert.equal(res.status, 405)
+  assert.equal(((await res.json()) as { reason: string }).reason, "read-only")
+  // Refused before GitHub is asked anything.
+  assert.equal(calls.length, 0)
+})
+
+test("?ref= reads another branch; a missing ref is a 404 the SPA can name", async () => {
+  const h = handler()
+  const branch = await get(h, "/tasks?ref=feature")
+  assert.deepEqual(
+    (branch.body.tasks as Array<{ id: string; status: string }>).map((t) => [t.id, t.status]),
+    [
+      ["ACM-x7k4m", "done"],
+      ["ACM-zz9zz", "todo"],
+    ],
+  )
+
+  const gone = await get(h, "/tasks?ref=gone")
+  assert.equal(gone.status, 404)
+  assert.equal(gone.body.reason, "no-such-ref")
+
+  // A ref that isn't a git name is ignored rather than sent to GitHub.
+  const bad = await get(h, "/tasks?ref=..%2F..%2Fetc")
+  assert.equal(bad.status, 200)
+  assert.ok(calls.every((c) => !c.path.includes("etc")))
+})
+
+test("/branches lists the repo's branches, default first", async () => {
+  const h = handler()
+  const res = await get(h, "/branches")
+  assert.deepEqual(res.body, {
+    branches: [
+      { name: "main", isDefault: true },
+      { name: "docs", isDefault: false },
+      { name: "feature", isDefault: false },
+    ],
+  })
+})
+
+test("one tarball per commit, however many requests ask", async () => {
+  const h = handler()
+  // The SPA's boot: four requests at once, before anything is cached.
+  await Promise.all([get(h, "/boards"), get(h, "/project"), get(h, "/tasks"), get(h, "/goals")])
+  await get(h, "/tasks/x7k4m")
+  const tarballs = calls.filter((c) => c.path.includes("/tarball/"))
+  assert.equal(tarballs.length, 1, "the tarball was fetched more than once for one sha")
+  // HEAD is asked every time — that is the freshness check.
+  assert.equal(calls.filter((c) => c.path.includes("/commits/")).length, 5)
+  // Another ref is another commit, hence another tarball; then cached too.
+  await get(h, "/tasks?ref=feature")
+  await get(h, "/tasks?ref=feature")
+  assert.equal(calls.filter((c) => c.path.includes("/tarball/")).length, 2)
+})
+
+test("the token can be a getter, and no token is a 503 the probe reads as no API", async () => {
+  let minted = 0
+  const h = handler({
+    token: async () => {
+      minted++
+      return "ghp_minted"
+    },
+  })
+  assert.equal((await get(h, "/project")).status, 200)
+  assert.equal(minted, 1)
+  assert.equal(calls[0].auth, "Bearer ghp_minted")
+
+  const unset = handler({ token: () => "" })
+  const res = await get(unset, "/project")
+  assert.equal(res.status, 503)
+  assert.equal(res.body.reason, "no-token")
+})
+
+test("mounted under a base path, only that path is the API", async () => {
+  const h = handler({ basePath: "/board/api" })
+  assert.equal((await get(h, "/project", "/board/api")).status, 200)
+  assert.equal((await get(h, "/project", "/api")).status, 404)
+  assert.equal((await get(h, "", "/board/api")).status, 404)
+})
+
+test("GitHub refusing the token is a 502, not a board", async () => {
+  githubStatus = 401
+  const res = await get(handler(), "/project")
+  assert.equal(res.status, 502)
+  assert.equal(res.body.reason, "github")
+  assert.match(String(res.body.error), /401/)
+})
+
+test("a repo that isn't owner/name is refused at construction", () => {
+  assert.throws(() => createBoardHandler({ token: "t", repo: "not a repo" }), /owner\/name/)
+  assert.throws(() => createBoardHandler({ token: "t", repo: "a/b/c" }), /owner\/name/)
+})