@nickmeriano/task 0.10.0 → 0.12.0

package/src/board/tar.ts

@@ -0,0 +1,199 @@
+/**
+ * A minimal streaming tar reader — just enough to walk a GitHub repository
+ * tarball. One pass, bounded memory: every entry's *path* is recorded, but
+ * bytes are kept only for the paths the caller's `keep` predicate selects;
+ * everything else is discarded chunk by chunk as it streams through, so a big
+ * repository costs no more memory than its boards.
+ *
+ * Understands what GitHub's tarballs actually contain: ustar headers with the
+ * split `prefix` field, a leading `pax_global_header`, and pax extended
+ * headers (`x`) or GNU longname entries (`L`) for paths longer than the
+ * header's 100 bytes. Checksums are not verified — the bytes come off a TLS
+ * connection from GitHub, not a tape from 1988.
+ */
+
+export class TarError extends Error {}
+
+const BLOCK = 512
+
+/** Reads exact byte counts off a stream, buffering only what's unconsumed. */
+class ByteReader {
+  private reader: ReadableStreamDefaultReader<Uint8Array>
+  private chunks: Uint8Array[] = []
+  private have = 0
+  private done = false
+
+  constructor(stream: ReadableStream<Uint8Array>) {
+    this.reader = stream.getReader()
+  }
+
+  private async pull(): Promise<boolean> {
+    if (this.done) return false
+    const { done, value } = await this.reader.read()
+    if (done) {
+      this.done = true
+      return false
+    }
+    if (value && value.length > 0) {
+      this.chunks.push(value)
+      this.have += value.length
+    }
+    return true
+  }
+
+  /** Exactly `n` bytes; null at a clean end-of-stream, throws mid-entry. */
+  async read(n: number): Promise<Uint8Array | null> {
+    while (this.have < n) {
+      if (!(await this.pull())) {
+        if (this.have === 0) return null
+        throw new TarError("truncated archive")
+      }
+    }
+    const out = new Uint8Array(n)
+    let filled = 0
+    while (filled < n) {
+      const head = this.chunks[0]
+      const take = Math.min(head.length, n - filled)
+      out.set(head.subarray(0, take), filled)
+      filled += take
+      if (take === head.length) this.chunks.shift()
+      else this.chunks[0] = head.subarray(take)
+    }
+    this.have -= n
+    return out
+  }
+
+  /** Discard `n` bytes without accumulating them. */
+  async skip(n: number): Promise<void> {
+    while (n > 0) {
+      if (this.chunks.length === 0) {
+        if (!(await this.pull())) throw new TarError("truncated archive")
+        continue
+      }
+      const head = this.chunks[0]
+      const take = Math.min(head.length, n)
+      if (take === head.length) this.chunks.shift()
+      else this.chunks[0] = head.subarray(take)
+      this.have -= take
+      n -= take
+    }
+  }
+}
+
+const decoder = new TextDecoder()
+
+function field(header: Uint8Array, start: number, length: number): string {
+  const slice = header.subarray(start, start + length)
+  const nul = slice.indexOf(0)
+  return decoder.decode(nul < 0 ? slice : slice.subarray(0, nul))
+}
+
+function octal(header: Uint8Array, start: number, length: number): number {
+  const text = field(header, start, length).trim()
+  if (text === "") return 0
+  const value = parseInt(text, 8)
+  if (Number.isNaN(value) || value < 0) throw new TarError("bad size field")
+  return value
+}
+
+/** The `path=` record of a pax extended header, if it has one. */
+function paxPath(data: Uint8Array): string | null {
+  // Records are "<len> <key>=<value>\n", len covering the whole record.
+  const text = decoder.decode(data)
+  for (let at = 0; at < text.length; ) {
+    const space = text.indexOf(" ", at)
+    if (space < 0) break
+    const length = Number(text.slice(at, space))
+    if (!Number.isInteger(length) || length <= 0) break
+    const record = text.slice(space + 1, at + length)
+    if (record.startsWith("path=")) return record.slice(5).replace(/\n$/, "")
+    at += length
+  }
+  return null
+}
+
+export interface TarContents {
+  /** Every regular file's path, root directory stripped. */
+  paths: string[]
+  /** Bytes of the paths `keep` selected. */
+  files: Map<string, Uint8Array>
+}
+
+/**
+ * Walk a (decompressed) tar stream. Paths are reported with the archive's
+ * root directory stripped — GitHub tarballs wrap everything in
+ * `<owner>-<repo>-<sha>/` — matching what a git tree listing would say.
+ */
+export async function readTar(
+  stream: ReadableStream<Uint8Array>,
+  keep: (path: string) => boolean,
+): Promise<TarContents> {
+  const bytes = new ByteReader(stream)
+  const paths: string[] = []
+  const files = new Map<string, Uint8Array>()
+
+  let overridePath: string | null = null
+  for (;;) {
+    const header = await bytes.read(BLOCK)
+    if (header === null) break
+    if (header.every((b) => b === 0)) {
+      // End marker: two zero blocks, then maybe padding. Nothing left to parse.
+      break
+    }
+
+    const size = octal(header, 124, 12)
+    const padded = Math.ceil(size / BLOCK) * BLOCK
+    const type = header[156]
+
+    // Extended headers name the *next* entry; the global one ('g') is skipped.
+    if (type === 0x78 /* x */ || type === 0x4c /* L */) {
+      const data = await bytes.read(size)
+      if (data === null) throw new TarError("truncated archive")
+      overridePath =
+        type === 0x78 ? (paxPath(data) ?? overridePath) : decoder.decode(data).replace(/\0+$/, "")
+      await bytes.skip(padded - size)
+      continue
+    }
+
+    let name = field(header, 0, 100)
+    // ustar splits long paths into prefix + name.
+    const prefix = field(header, 257, 6).startsWith("ustar") ? field(header, 345, 155) : ""
+    if (prefix) name = `${prefix}/${name}`
+    if (overridePath !== null) {
+      name = overridePath
+      overridePath = null
+    }
+
+    // Regular file entries only — directories, links and the global header
+    // carry no board bytes. Type '0' or the ancient NUL both mean "file".
+    if (type !== 0x30 && type !== 0) {
+      await bytes.skip(padded)
+      continue
+    }
+
+    // Strip the tarball's root directory. A path without one (no slash) is
+    // the metadata GitHub puts at the top level — not repository content.
+    const slash = name.indexOf("/")
+    if (slash < 0) {
+      await bytes.skip(padded)
+      continue
+    }
+    const path = name.slice(slash + 1)
+    if (path === "") {
+      await bytes.skip(padded)
+      continue
+    }
+
+    paths.push(path)
+    if (keep(path)) {
+      const data = await bytes.read(size)
+      if (data === null) throw new TarError("truncated archive")
+      files.set(path, data)
+      await bytes.skip(padded - size)
+    } else {
+      await bytes.skip(padded)
+    }
+  }
+
+  return { paths, files }
+}

package/src/claim-io.ts

@@ -24,6 +24,7 @@ import { join, relative, sep } from "node:path"
 import { claimBranch, claimNamespace } from "./claim.ts"
 import { gitOut, runGit } from "./git.ts"
 import { commentStem, parseAskLenient, serializeAsk, type AskDoc } from "./ticket-doc.ts"
+import { boardCommitMessage } from "./trailers.ts"
 import { ASKS_DIR, TICKETS_DIR } from "./file-store.ts"
 import type { Store } from "./store.ts"
 import type { Ask, Task } from "./types.ts"
@@ -298,7 +299,7 @@ export function addAskRouted(store: Store, key: string, text: string, author = "
     store,
     branch,
     `${dir}/${id}.md`,
-    `chore(board): ask on ${store.displayId(key)}`,
+    boardCommitMessage(`chore(board): ask on ${store.displayId(key)}`, "ask", store.displayId(key)),
     // Absent → create; if a racing write took the name, keep theirs.
     (current) => current ?? serializeAsk(doc),
   )
@@ -340,7 +341,11 @@ export function setAskResolvedRouted(
     store,
     branch,
     `${dir}/${target.id}.md`,
-    `chore(board): ${resolved ? "resolve" : "reopen"} ask [${target.ordinal}] on ${store.displayId(key)}`,
+    boardCommitMessage(
+      `chore(board): ${resolved ? "resolve" : "reopen"} ask [${target.ordinal}] on ${store.displayId(key)}`,
+      resolved ? "resolve-ask" : "reopen-ask",
+      store.displayId(key),
+    ),
     (current) => {
       if (current === null) return null // deleted under us — nothing to write
       const doc = parseAskLenient(current)
@@ -374,7 +379,11 @@ export function deleteAskRouted(store: Store, key: string, ref: string): RoutedA
     store,
     branch,
     `${dir}/${target.id}.md`,
-    `chore(board): delete ask [${target.ordinal}] on ${store.displayId(key)}`,
+    boardCommitMessage(
+      `chore(board): delete ask [${target.ordinal}] on ${store.displayId(key)}`,
+      "delete-ask",
+      store.displayId(key),
+    ),
     () => null,
   )
   // The local copy of a both-sides ask goes too, or the union resurrects it.

package/src/claim.test.ts

@@ -183,9 +183,54 @@ test("two concurrent claims of one ticket: exactly one wins", async () => {
     sh(winner, "git", "show", `origin/main:.task/tickets/${keys.one}/ticket.md`),
     /status: todo/,
   )
+  // The trailer contract (trailers.ts): the flip commit names its op and
+  // ticket in machine-readable trailers — pinned here because automation
+  // keys on them.
+  assert.equal(sh(winner, "git", "log", "-1", "--format=%(trailers:key=Task-Op,valueonly)"), "claim")
+  assert.equal(
+    sh(winner, "git", "log", "-1", "--format=%(trailers:key=Task-Id,valueonly)"),
+    `CLM-${keys.one}`,
+  )
   void bare
 })
 
+test("claim --dry-run: the real gates, the real exit codes, zero writes", async () => {
+  const { clone, keys } = fixture()
+  const dir = clone()
+  const branch = `task/claim/clm-${keys.one}`
+
+  // Would claim: exit 0 — and nothing moved. No branch local or remote, the
+  // checkout still on main, the ticket still todo.
+  const yes = await cli(dir, "claim", keys.one, "--dry-run")
+  assert.equal(yes.code, 0, yes.stderr)
+  assert.match(yes.stdout, /would claim CLM-/)
+  assert.equal(sh(dir, "git", "rev-parse", "--abbrev-ref", "HEAD"), "main")
+  assert.equal(sh(dir, "git", "branch", "--list", branch), "")
+  assert.equal(sh(dir, "git", "ls-remote", "--heads", "origin", branch), "")
+  assert.match(readFileSync(join(dir, ".task", "tickets", keys.one, "ticket.md"), "utf8"), /status: todo/)
+
+  // The gates are the real command's gates: blocked exits 2, a ticket someone
+  // else claimed exits 1 — the codes a scheduler scripts against.
+  assert.equal((await cli(dir, "claim", keys.blocked, "--dry-run")).code, 2)
+  const other = clone()
+  assert.equal((await cli(other, "claim", keys.one)).code, 0)
+  assert.equal((await cli(dir, "claim", keys.one, "--dry-run")).code, 1)
+
+  // --next --dry-run names the top of the queue without taking it.
+  const next = await cli(dir, "claim", "--next", "--dry-run", "--json")
+  assert.equal(next.code, 0, next.stderr)
+  const picked = JSON.parse(next.stdout) as { task: { key: string }; dryRun: boolean }
+  assert.equal(picked.dryRun, true)
+  assert.equal(picked.task.key, keys.jumper)
+  assert.equal(sh(dir, "git", "ls-remote", "--heads", "origin", `task/claim/clm-${keys.jumper}`), "")
+
+  // A dry run reserves nothing — the real claim right after still works.
+  assert.equal((await cli(dir, "claim", keys.jumper)).code, 0)
+
+  // No stop-before-writing seam exists for --release or --lock-only.
+  assert.equal((await cli(other, "claim", keys.two, "--lock-only", "--dry-run")).code, 1)
+})
+
 test("unclaimable tickets exit 2, before anything touches origin", async () => {
   const { clone, keys } = fixture()
   const dir = clone()
@@ -541,7 +586,17 @@ test("--lock-only claims from a dirty, branch-pinned checkout without touching i
   assert.match(sh(dir, "git", "show", `origin/${branch}:.task/tickets/${keys.one}/ticket.md`), /status: in_progress/)
   const message = sh(dir, "git", "log", "-1", "--format=%B", `origin/${branch}`)
   assert.match(message, /lock-only/)
-  assert.match(message, new RegExp(`delivered_by: pinned`))
+  assert.match(message, new RegExp(`Delivered-By: pinned`))
+  // Delivered-By shares one contiguous trailer block with the Task-Op/Task-Id
+  // contract (trailers.ts) — git must parse all three.
+  assert.equal(
+    sh(dir, "git", "log", "-1", "--format=%(trailers:key=Task-Op,valueonly)", `origin/${branch}`),
+    "claim",
+  )
+  assert.equal(
+    sh(dir, "git", "log", "-1", "--format=%(trailers:key=Delivered-By,valueonly)", `origin/${branch}`),
+    "pinned",
+  )
 
   // The lock is the same lock: both claim flavors lose to it from elsewhere.
   const other = clone()

package/src/claim.ts

@@ -30,6 +30,7 @@ import {
   type Store,
 } from "./store.ts"
 import { isTicketKey } from "./id.ts"
+import { boardCommitMessage } from "./trailers.ts"
 import { parseTicket, parseTicketLenient, serializeTicket, type TicketDoc } from "./ticket-doc.ts"
 import type { ProjectConfig, Status, Task } from "./types.ts"
 
@@ -193,6 +194,18 @@ export interface ClaimResult {
 export interface ClaimOptions {
   /** Claim past the root board's `claims.maxOpenCount` cap. */
   force?: boolean
+  /**
+   * Run the real claim's decision path — every validation, in order, against
+   * live origin state — and stop before the first write. No branch is
+   * created, no commit made, nothing pushed; the checkout is untouched. Exit
+   * semantics match the real command exactly, which is the point: automation
+   * (a scheduler deciding whether to wake a worker) asks "would a claim
+   * succeed right now?" through the same code that would perform it, so the
+   * answer can't drift from the rules. A "yes" is a reading, not a
+   * reservation — the dry run takes no lock, so a concurrent claimer can
+   * still win the ticket a moment later.
+   */
+  dryRun?: boolean
 }
 
 /**
@@ -278,6 +291,8 @@ export function claim(store: Store, key: string, options: ClaimOptions = {}): Cl
   const previous =
     git(cwd, "symbolic-ref", "--quiet", "--short", "HEAD").stdout ||
     gitMust(cwd, "rev-parse", "HEAD")
+  // Every gate is passed; the writes start here. A dry run stops instead.
+  if (options.dryRun) return { task: store.get(key)!, branch, base, previous }
   gitMust(cwd, "checkout", "--quiet", "-b", branch, base)
 
   const undo = (): void => {
@@ -292,7 +307,13 @@ export function claim(store: Store, key: string, options: ClaimOptions = {}): Cl
     assertClaimable(store, store.get(key), key)
     store.update(key, { status: "in_progress" })
     gitMust(cwd, "add", "--", join(store.taskDir, TICKETS_DIR, key))
-    gitMust(cwd, "commit", "--quiet", "-m", `chore(board): claim ${id} → in_progress`)
+    gitMust(
+      cwd,
+      "commit",
+      "--quiet",
+      "-m",
+      boardCommitMessage(`chore(board): claim ${id} → in_progress`, "claim", id),
+    )
   } catch (error) {
     undo()
     throw error
@@ -331,7 +352,7 @@ export interface LockOnlyClaimResult {
   task: Task
   branch: string
   base: string
-  /** The checkout's branch at claim time, recorded in the flip commit's `delivered_by:` trailer. */
+  /** The checkout's branch at claim time, recorded in the flip commit's `Delivered-By:` trailer. */
   deliveredBy: string
 }
 
@@ -348,7 +369,7 @@ export interface LockOnlyClaimResult {
  * update-index → write-tree → commit-tree) and pushed with the same
  * must-not-exist lease plain `claim` uses — the compare-and-swap is identical,
  * only the checkout stays where it is (dirty or pinned, doesn't matter). The
- * flip commit carries a `delivered_by: <branch>` trailer naming the checkout's
+ * flip commit carries a `Delivered-By: <branch>` trailer naming the checkout's
  * branch, so a lock-only claim is legible state — anyone reading the claim
  * branch sees where the work will actually land. Exit-code contract and
  * `--release` behave exactly like plain claim.
@@ -465,7 +486,9 @@ export function claimLockOnly(
       "-p",
       baseSha,
       "-m",
-      `chore(board): claim ${id} → in_progress (lock-only)\n\ndelivered_by: ${deliveredBy}`,
+      boardCommitMessage(`chore(board): claim ${id} → in_progress (lock-only)`, "claim", id, [
+        `Delivered-By: ${deliveredBy}`,
+      ]),
     )
     if (made.status !== 0) {
       throw new Error("git commit-tree failed — is git user.name/user.email configured?")

package/src/cli.ts

@@ -12,7 +12,7 @@
 import { spawn } from "node:child_process"
 import { readFileSync } from "node:fs"
 import type { Server } from "node:http"
-import { basename, join, relative, sep } from "node:path"
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path"
 import process from "node:process"
 import { resolveAuthor } from "./author.ts"
 import { checkBoards, checkRoot } from "./check.ts"
@@ -32,7 +32,8 @@ import { buildInbox, type InboxEntry } from "./inbox.ts"
 import { STALE_DAYS, buildOverview } from "./overview.ts"
 import { searchStore } from "./search.ts"
 import { detectRepo, parseSlug, publish, resolveHost } from "./publish.ts"
-import { createTaskServer } from "./server.ts"
+import { DEFAULT_OUT_DIR, writeExport } from "./export.ts"
+import { UI_DIR, createTaskServer } from "./server.ts"
 import { initProject, openBoard } from "./file-store.ts"
 import {
   CONFIG_FILE,
@@ -95,8 +96,10 @@ const BOOLEAN_FLAGS = new Set([
   "fix",
   "next",
   "force",
+  "no-functions",
   "reopen",
   "lock-only",
+  "dry-run",
 ])
 
 /**
@@ -830,7 +833,7 @@ function cmdLink(args: Args, action: "link" | "unlink"): void {
 }
 
 const CLAIM_USAGE =
-  'usage: task claim <id> [--lock-only] | task claim --next | task claim --release <id> --comment "<why>"'
+  'usage: task claim <id> [--lock-only] [--dry-run] | task claim --next [--dry-run] | task claim --release <id> --comment "<why>"'
 
 /**
  * `task claim <id>` / `task claim --next` / `task claim --release <id>` — see
@@ -840,8 +843,19 @@ const CLAIM_USAGE =
  */
 function cmdClaim(args: Args): void {
   const ref = args.positional[0]
-  const options = { force: Boolean(args.flags.force) }
+  const dryRun = Boolean(args.flags["dry-run"])
+  const options = { force: Boolean(args.flags.force), dryRun }
   const printClaim = (result: { task: Task; branch: string; base: string; previous: string }): void => {
+    if (dryRun) {
+      // Same exit-code contract as the real claim, nothing written: the
+      // scripted consumer branches on the code, the human reads the verdict.
+      if (args.flags.json) {
+        console.log(JSON.stringify({ task: result.task, branch: result.branch, dryRun: true }, null, 2))
+      } else {
+        console.log(`would claim ${result.task.id} — ${result.branch} (from ${result.base}); dry run, nothing written`)
+      }
+      return
+    }
     if (args.flags.json) {
       console.log(JSON.stringify({ task: result.task, branch: result.branch }, null, 2))
     } else {
@@ -878,12 +892,17 @@ function cmdClaim(args: Args): void {
       return
     }
     if (!ref) fail(CLAIM_USAGE)
+    if (dryRun && (args.flags["lock-only"] || args.flags.release)) {
+      // --lock-only builds its flip commit as it validates and --release only
+      // deletes; neither has a meaningful stop-before-writing seam.
+      fail("--dry-run applies to plain claim and --next only")
+    }
     const store = openStoreFor(ref)
     const key = store.parseId(ref)
     if (args.flags["lock-only"]) {
       // The branch-pinned session's claim: same lock, no checkout switch —
       // the work delivers on the branch this session was handed, and the flip
-      // commit's delivered_by: trailer says so. See claimLockOnly.
+      // commit's Delivered-By: trailer says so. See claimLockOnly.
       if (args.flags.release) fail(CLAIM_USAGE)
       const result = claimLockOnly(store, key, options)
       if (args.flags.json) {
@@ -899,7 +918,7 @@ function cmdClaim(args: Args): void {
           `claimed ${result.task.id} — ${result.branch} on origin (lock only, from ${result.base}), status in_progress`,
         )
         console.log(
-          `checkout untouched — keep working on ${result.deliveredBy} (recorded as delivered_by in the claim commit)`,
+          `checkout untouched — keep working on ${result.deliveredBy} (recorded as Delivered-By in the claim commit)`,
         )
       }
       return
@@ -1296,6 +1315,75 @@ function cmdServe(args: Args): void {
   })
 }
 
+/**
+ * `task export` — the same board, as files a static host can serve.
+ *
+ * Anchored exactly like `cmdServe`, because that's the promise: what comes out
+ * is what `task serve` would have served, read-only and honestly stale. The
+ * output is the prebuilt UI plus a `snapshot.json` the app reads instead of an
+ * API — no server, no network calls beyond the static files.
+ */
+function cmdExport(args: Args): void {
+  const serveRoot = findRoot(process.cwd()) ?? process.cwd()
+  const boards = findBoards(serveRoot)
+  if (boards.length === 0) {
+    fail("no .task directory found in this directory, any parent, or below — run `task init` first")
+  }
+  // Deliberately not under `.task/`: `task serve` watches that tree
+  // recursively, so an export written there would fire the change feed on
+  // every asset copied.
+  const out = str(args.flags, "out") ?? join(serveRoot, DEFAULT_OUT_DIR)
+  const outDir = isAbsolute(out) ? out : resolve(process.cwd(), out)
+
+  // The live proxy is written unless told not to. It is inert until the host
+  // has a token — it answers 503 and the board reads the snapshot — so the
+  // default costs nothing, and turning a deploy live becomes one secret
+  // rather than a re-export. The repository it reads is baked in: the export
+  // already knows (the same remote detection `task publish` uses), and one
+  // fewer setting on the host is one fewer thing to get wrong.
+  let functions: { repo: string } | undefined
+  let noRemote = false
+  if (!args.flags["no-functions"]) {
+    const slug = str(args.flags, "repo")
+    const ref = slug ? parseSlug(slug) : detectRepo(serveRoot)
+    if (slug && !ref) fail(`--repo must be owner/name — got ${JSON.stringify(slug)}`)
+    if (ref) functions = { repo: `${ref.owner}/${ref.repo}` }
+    else noRemote = true
+  }
+
+  let summary
+  try {
+    summary = writeExport({
+      serveRoot,
+      outDir,
+      uiDir: UI_DIR,
+      force: Boolean(args.flags.force),
+      base: str(args.flags, "base"),
+      functions,
+    })
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error))
+  }
+
+  if (args.flags.json) {
+    console.log(JSON.stringify(summary, null, 2))
+    return
+  }
+  const what = `${summary.tasks} task${summary.tasks === 1 ? "" : "s"} across ${summary.boards} board${summary.boards === 1 ? "" : "s"}`
+  console.log(`Exported ${what}${summary.commit ? ` at ${summary.commit.slice(0, 7)}` : ""}`)
+  console.log(`  ${summary.outDir}`)
+  console.log("Serve that directory from any static host — the board reads snapshot.json.")
+  if (summary.functions && functions) {
+    // One line, every run: this tier has no viewer auth, and the moment the
+    // function is written is the moment to say so. The README says the rest.
+    console.log(
+      `  ${summary.functions} reads ${functions.repo} live once the host has a TASK_GITHUB_TOKEN secret — to anyone who can reach it (README: "Live data for an exported board")`,
+    )
+  } else if (noRemote) {
+    console.log("  no live function written — no GitHub remote to read from; pass --repo owner/name to add one")
+  }
+}
+
 /**
  * `task publish` — the board, at a URL.
  *
@@ -1488,7 +1576,7 @@ Usage
                                 a provisioned branch (CI, a Claude web
                                 session): the lock lives on the claim
                                 branch, the work delivers on yours, and the
-                                flip commit's delivered_by: trailer records
+                                flip commit's Delivered-By: trailer records
                                 which. --release works on a lock-only claim
                                 the same way
   task claim --next [--board <P>] [--force]
@@ -1500,6 +1588,16 @@ Usage
                                 the nearest board. Exit codes: 0 claimed
                                 (prints the ticket), 1 queue empty, 2
                                 preconditions failed
+  task claim <id|--next> --dry-run
+                                the same decision path — every gate, against
+                                live origin state — stopped before the first
+                                write: no branch, no commit, checkout
+                                untouched. Same exit codes as the real
+                                command, so automation asks "would a claim
+                                succeed right now?" through the code that
+                                would perform it. A yes is a reading, not a
+                                reservation — no lock is taken. Plain claim
+                                and --next only
   task claim --release <id> --comment "<why>"
                                 abandon a claim: delete the branch on origin
                                 and locally — the status flip only lived on
@@ -1577,6 +1675,26 @@ Usage
                                 fails instead). Serves every board at or below
                                 here — in a monorepo the header becomes a
                                 board switcher
+  task export [--out <dir>] [--base <path>] [--force] [--no-functions | --repo <owner/name>]
+                                write the board out as static files — the same
+                                UI plus a snapshot.json it reads instead of an
+                                API, so any static host serves it read-only
+                                with no server behind it. Same boards as
+                                \`task serve\`; defaults to ./${DEFAULT_OUT_DIR}.
+                                --base is the URL path the export will live
+                                under (default /) — pass /board/ when it's
+                                hosted at example.com/board/ instead of a
+                                domain root. Re-exporting refreshes an earlier
+                                export in place and leaves anything else in
+                                there alone; a non-empty directory that isn't
+                                one needs --force. Also writes a Cloudflare
+                                Pages Function that reads the repo live from
+                                GitHub: inert until the host has a
+                                TASK_GITHUB_TOKEN secret (a fine-grained PAT,
+                                Contents: read-only), at which point the same
+                                deploy upgrades itself — no viewer auth, mind.
+                                The repo comes from your remotes; --repo sets
+                                it, --no-functions skips the function
   task publish [--public | --private] [--repo <owner/name>]
                                 give this repo's board a URL at
                                 task.nickmeriano.com, read-only, updated from
@@ -1679,6 +1797,8 @@ function main(): void | Promise<void> {
       return cmdCheck(args)
     case "serve":
       return cmdServe(args)
+    case "export":
+      return cmdExport(args)
     case "publish":
       return cmdPublish(args)
     case "unpublish":