@nickmeriano/task 0.9.0 → 0.11.0

package/src/cli.ts

@@ -12,25 +12,28 @@
 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"
 import {
   ClaimError,
   claim,
+  claimLockOnly,
   claimNext,
   claimableTasks,
   promote,
   release,
   selectionBoards,
+  sweep,
 } from "./claim.ts"
 import { addAskRouted, setAskResolvedRouted } from "./claim-io.ts"
 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,
@@ -94,6 +97,8 @@ const BOOLEAN_FLAGS = new Set([
   "next",
   "force",
   "reopen",
+  "lock-only",
+  "dry-run",
 ])
 
 /**
@@ -827,7 +832,7 @@ function cmdLink(args: Args, action: "link" | "unlink"): void {
 }
 
 const CLAIM_USAGE =
-  'usage: task claim <id> | 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
@@ -837,12 +842,33 @@ const CLAIM_USAGE =
  */
 function cmdClaim(args: Args): void {
   const ref = args.positional[0]
-  const options = { force: Boolean(args.flags.force) }
-  const printClaim = (result: { task: Task; branch: string; base: string }): void => {
+  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 {
       console.log(`claimed ${result.task.id} — on ${result.branch} (from ${result.base}), status in_progress`)
+      // The backstop for branch-pinned sessions: a harness that assigned this
+      // checkout a branch expects the work to land there, and a plain claim
+      // just moved HEAD somewhere else. The skill carries the rule; this line
+      // is for the worker that hasn't read it.
+      const defaultLocal = result.base.replace(/^origin\//, "")
+      if (result.previous !== defaultLocal && result.previous !== result.branch) {
+        console.log(
+          `note: this moved you off ${result.previous} — if your work must deliver on ${result.previous}, \`task claim --release ${result.task.id} --comment "…"\` and re-claim with --lock-only`,
+        )
+      }
     }
   }
   try {
@@ -851,7 +877,7 @@ function cmdClaim(args: Args): void {
       // ticket across the selection scope (--board > root `boards` > nearest),
       // retrying past lost races internally.
       if (ref) fail("pass an id or --next, not both")
-      if (args.flags.release) fail(CLAIM_USAGE)
+      if (args.flags.release || args.flags["lock-only"]) fail(CLAIM_USAGE)
       const result = claimNext(selectionBoards(process.cwd(), boardFlag(args)), options)
       if (!result) {
         if (args.flags.json) {
@@ -865,8 +891,37 @@ 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.
+      if (args.flags.release) fail(CLAIM_USAGE)
+      const result = claimLockOnly(store, key, options)
+      if (args.flags.json) {
+        console.log(
+          JSON.stringify(
+            { task: result.task, branch: result.branch, deliveredBy: result.deliveredBy },
+            null,
+            2,
+          ),
+        )
+      } else {
+        console.log(
+          `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)`,
+        )
+      }
+      return
+    }
     if (args.flags.release) {
       // A released claim must leave its failure context behind: the branch
       // (and whatever was tried on it) is about to evaporate, so the reason
@@ -906,6 +961,50 @@ function cmdClaim(args: Args): void {
   }
 }
 
+/**
+ * `task sweep` — the janitor: delete every claim branch on origin whose ticket
+ * is done, canceled, or missing on the current checkout. Zero judgment on
+ * purpose — the trigger belongs to a runner (CI on push-to-main or cron), not
+ * an agent. Exit codes: 0 clean (including nothing to do), 1 a deletion was
+ * attempted and failed — a failing sweep means this runner can't delete
+ * branches either, which is worth an alert.
+ */
+function cmdSweep(args: Args): void {
+  try {
+    const result = sweep(process.cwd())
+    if (args.flags.json) {
+      console.log(JSON.stringify({ sweep: result }, null, 2))
+    } else {
+      for (const entry of result.swept) {
+        console.log(
+          `swept ${entry.branch} — ${entry.reason === "missing" ? `no ticket ${entry.ticket}` : `${entry.ticket} is ${entry.reason}`}`,
+        )
+      }
+      for (const entry of result.kept) {
+        console.log(`kept ${entry.branch} — ${entry.ticket} is ${entry.status}`)
+      }
+      for (const branch of result.skipped) {
+        console.log(
+          `skipped ${branch} — not a name \`task claim\` mints (foreign or pre-migration); delete it by hand if it's stale`,
+        )
+      }
+      for (const entry of result.failed) {
+        console.error(`error: couldn't delete ${entry.branch} — ${entry.error}`)
+      }
+      if (!result.swept.length && !result.kept.length && !result.skipped.length && !result.failed.length) {
+        console.log("no claim branches on origin — nothing to sweep")
+      }
+    }
+    if (result.failed.length) process.exit(1)
+  } catch (error) {
+    if (error instanceof ClaimError) {
+      console.error(`error: ${error.message}`)
+      process.exit(2)
+    }
+    throw error
+  }
+}
+
 /** `task instructions` — the shipped agent conventions, self-served at runtime. */
 function cmdInstructions(): void {
   // skill/ ships in the npm package; `../` from both dist/cli.js and
@@ -1215,6 +1314,49 @@ 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)
+
+  let summary
+  try {
+    summary = writeExport({
+      serveRoot,
+      outDir,
+      uiDir: UI_DIR,
+      force: Boolean(args.flags.force),
+      base: str(args.flags, "base"),
+    })
+  } 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.")
+}
+
 /**
  * `task publish` — the board, at a URL.
  *
@@ -1396,6 +1538,20 @@ Usage
                                 is refused (--force overrides). Exit codes:
                                 0 claimed, 1 already claimed, 2 not claimable
                                 (not todo, blocked, dirty tree, at the cap)
+  task claim <id> --lock-only [--force]
+                                take the lock without touching the checkout:
+                                the in_progress flip commit is built against
+                                origin's default branch in a temporary index
+                                and pushed as the claim branch — same atomic
+                                lock, same exit codes, but HEAD, the working
+                                tree and the index stay exactly where they
+                                are (dirty is fine). For sessions pinned to
+                                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
+                                which. --release works on a lock-only claim
+                                the same way
   task claim --next [--board <P>] [--force]
                                 claim the top claimable ticket in one call,
                                 retrying past lost races internally — the
@@ -1405,13 +1561,41 @@ 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
                                 the branch, so deleting it is the revert. The
                                 comment is required and lands on the ticket
                                 (attributed like task comment, uncommitted),
-                                so the next worker inherits what was tried
+                                so the next worker inherits what was tried.
+                                The deletion is verified with ls-remote: an
+                                environment that silently drops deletion
+                                pushes fails loudly instead of reporting a
+                                release that didn't happen
+  task sweep                    the janitor: delete every claim branch on
+                                origin whose ticket is done, canceled, or
+                                missing on the current checkout, across all
+                                the repo's boards. Scoped to names \`claim\`
+                                mints (<prefix>-<valid key>): anything else
+                                under the namespace — pre-migration numeric
+                                claims, hand-made branches — is reported and
+                                left alone, since it may be an open PR's
+                                head. Pure git, zero judgment — run it from
+                                a runner that can delete remote branches (CI
+                                on push-to-main or cron) to heal stale
+                                claims left by environments that can't.
+                                Prints swept/kept/skipped; exits non-zero if
+                                a deletion was attempted and failed
   task list --claimable [--board <P>]
                                 the claim queue: todo tickets in position
                                 order, minus blocked / already claimed on
@@ -1464,6 +1648,19 @@ 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]
+                                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
   task publish [--public | --private] [--repo <owner/name>]
                                 give this repo's board a URL at
                                 task.nickmeriano.com, read-only, updated from
@@ -1536,6 +1733,8 @@ function main(): void | Promise<void> {
       return cmdLink(args, "unlink")
     case "claim":
       return cmdClaim(args)
+    case "sweep":
+      return cmdSweep(args)
     case "instructions":
       return cmdInstructions()
     case "ask":
@@ -1564,6 +1763,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":

package/src/export.test.ts

@@ -0,0 +1,254 @@
+/**
+ * `task export` writes a file another program reads, so what's checked here is
+ * the contract rather than the code: every field comes from the same store
+ * call the matching `/api/…` route makes, and the directory it lands in
+ * refreshes without eating what someone else put there.
+ *
+ * The round trip through the actual reader (`parseSnapshot` + `snapshotSource`)
+ * lives in `ui/src/deployment.test.ts` — it's the UI's tsconfig that can see
+ * both sides.
+ */
+
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import { execFileSync } from "node:child_process"
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { initProject, openBoard } from "./file-store.ts"
+import { buildSnapshot, writeExport, SNAPSHOT_FILE, SNAPSHOT_VERSION, type Snapshot } from "./export.ts"
+import { STATUSES } from "./types.ts"
+
+function tempRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "task-export-"))
+  process.on("exit", () => rmSync(dir, { recursive: true, force: true }))
+  return dir
+}
+
+/** A fake `ui/dist` — the shape of one is all the copy step cares about. */
+function fakeUi(): string {
+  const dir = tempRoot()
+  writeFileSync(join(dir, "index.html"), "<!doctype html><html><head><title>board</title></head></html>")
+  mkdirSync(join(dir, "assets"))
+  writeFileSync(join(dir, "assets", "index-abc123.js"), "// bundle")
+  return dir
+}
+
+/** A single-board repo with enough in it to be worth exporting. */
+function board(): string {
+  const root = tempRoot()
+  const store = initProject(root, { name: "acme", prefix: "ACM" })
+  const talked = store.create({ title: "Ship the export", status: "todo" })
+  store.addComment(talked.key, "on it", "claude")
+  store.addComment(talked.key, "still on it", "claude")
+  store.create({ title: "Quiet ticket", status: "backlog" })
+  const finished = store.create({ title: "Already shipped", status: "done" })
+  store.archive(finished.key)
+  store.createGoal({ title: "Launch", slug: "launch" })
+  store.createGoal({ title: "Old plan", slug: "old-plan" })
+  store.archiveGoal("old-plan")
+  store.close()
+  return root
+}
+
+test("the snapshot answers what the serve API answers", () => {
+  const root = board()
+  const store = openBoard(root)
+
+  const snapshot = buildSnapshot(root)
+  const data = snapshot.data["."]
+
+  // /api/project — field for field, minus readOnly (the reader forces it).
+  assert.equal(data.project.name, store.config.name)
+  assert.equal(data.project.prefix, store.config.prefix)
+  assert.deepEqual(data.project.statuses, STATUSES)
+  assert.equal(typeof data.project.author, "string")
+  assert.ok(!("readOnly" in data.project))
+
+  // /api/tasks — the same list, in the same order, with the same counts.
+  const tasks = store.list()
+  const counts = store.commentCounts()
+  assert.deepEqual(
+    data.tasks,
+    tasks.map((t) => ({ ...t, commentCount: counts.get(t.key) ?? 0 })),
+  )
+
+  // /api/goals — live first, archived riding along flagged.
+  assert.deepEqual(data.goals, [...store.goals(), ...store.goals(true)])
+  assert.ok(data.goals.some((g) => g.archived))
+
+  // /api/tasks/:n — comments per task, oldest first, empty ones omitted.
+  const talkative = tasks.find((t) => t.title === "Ship the export")!
+  const quiet = tasks.find((t) => t.title === "Quiet ticket")!
+  assert.deepEqual(data.comments[talkative.key], store.comments(talkative.key))
+  assert.equal(data.comments[quiet.key], undefined)
+
+  store.close()
+})
+
+test("an archived ticket is off the board, in the export too", () => {
+  const root = board()
+
+  const snapshot = buildSnapshot(root)
+
+  assert.ok(!snapshot.data["."].tasks.some((t) => t.title === "Already shipped"))
+})
+
+test("a monorepo root exports every board, keyed by what /boards says", () => {
+  const root = tempRoot()
+  initProject(root, { name: "acme", prefix: "ACM" }).close()
+  const nested = join(root, "projects", "widget")
+  mkdirSync(nested, { recursive: true })
+  initProject(nested, { name: "widget", prefix: "WID" }).close()
+
+  const snapshot = buildSnapshot(root)
+
+  assert.deepEqual(
+    snapshot.boards.map((b) => b.id),
+    [".", "projects/widget"],
+  )
+  assert.deepEqual(snapshot.boards[1], { id: "projects/widget", name: "widget", prefix: "WID" })
+  // Every board in the list has an entry, and nothing else does.
+  assert.deepEqual(Object.keys(snapshot.data).sort(), [".", "projects/widget"])
+})
+
+test("a board with nothing above or below it is not an export", () => {
+  assert.throws(() => buildSnapshot(tempRoot()), /run `task init`/)
+})
+
+test("the commit is the HEAD it was exported from, or null outside a repo", () => {
+  const loose = board()
+
+  assert.equal(buildSnapshot(loose).meta.commit, null)
+
+  const repo = board()
+  const git = (...args: string[]) =>
+    execFileSync("git", args, { cwd: repo, stdio: ["ignore", "pipe", "ignore"] })
+  git("init", "-q")
+  git("config", "user.email", "t@example.com")
+  git("config", "user.name", "Test")
+  git("add", "-A")
+  git("commit", "-qm", "board")
+  const head = git("rev-parse", "HEAD").toString().trim()
+
+  assert.equal(buildSnapshot(repo).meta.commit, head)
+})
+
+test("the export is the assets plus the snapshot", () => {
+  const root = board()
+  const out = join(tempRoot(), "board")
+
+  const summary = writeExport({ serveRoot: root, outDir: out, uiDir: fakeUi() })
+
+  assert.ok(existsSync(join(out, "index.html")))
+  assert.ok(existsSync(join(out, "assets", "index-abc123.js")))
+  const snapshot = JSON.parse(readFileSync(join(out, SNAPSHOT_FILE), "utf8")) as Snapshot
+  assert.equal(snapshot.version, SNAPSHOT_VERSION)
+  assert.equal(snapshot.boards.length, 1)
+  assert.deepEqual(summary, {
+    outDir: out,
+    base: "/",
+    boards: 1,
+    tasks: snapshot.data["."].tasks.length,
+    commit: null,
+    builtAt: snapshot.meta.builtAt,
+  })
+})
+
+test("exporting without a built UI says which build to run", () => {
+  assert.throws(
+    () =>
+      writeExport({
+        serveRoot: board(),
+        outDir: join(tempRoot(), "board"),
+        uiDir: join(tempRoot(), "never-built"),
+      }),
+    /run the package build/,
+  )
+})
+
+test("exporting onto the UI build is refused, not a way to delete it", () => {
+  const ui = fakeUi()
+
+  assert.throws(
+    () => writeExport({ serveRoot: board(), outDir: ui, uiDir: ui, force: true }),
+    /the UI build itself/,
+  )
+  assert.ok(existsSync(join(ui, "index.html")))
+})
+
+test("re-exporting refreshes in place and leaves a deployed function alone", () => {
+  const root = board()
+  const out = join(tempRoot(), "board")
+  const ui = fakeUi()
+  writeExport({ serveRoot: root, outDir: out, uiDir: ui })
+  // TAS-33's room: something the export didn't put there and must not remove.
+  mkdirSync(join(out, "functions"))
+  writeFileSync(join(out, "functions", "handler.js"), "// live proxy")
+  // A stale bundle from the previous build, which it *should* remove.
+  writeFileSync(join(out, "assets", "index-old.js"), "// last time")
+
+  const store = openBoard(root)
+  store.create({ title: "Added since the last export", status: "todo" })
+  store.close()
+  writeExport({ serveRoot: root, outDir: out, uiDir: ui })
+
+  const snapshot = JSON.parse(readFileSync(join(out, SNAPSHOT_FILE), "utf8")) as Snapshot
+  assert.ok(snapshot.data["."].tasks.some((t) => t.title === "Added since the last export"))
+  assert.equal(readFileSync(join(out, "functions", "handler.js"), "utf8"), "// live proxy")
+  assert.ok(!existsSync(join(out, "assets", "index-old.js")))
+})
+
+test("a directory that isn't a previous export is refused, not overwritten", () => {
+  const root = board()
+  const out = join(tempRoot(), "not-an-export")
+  mkdirSync(out)
+  writeFileSync(join(out, "thesis.md"), "years of work")
+
+  assert.throws(
+    () => writeExport({ serveRoot: root, outDir: out, uiDir: fakeUi() }),
+    /--force/,
+  )
+  assert.equal(readFileSync(join(out, "thesis.md"), "utf8"), "years of work")
+
+  // --force writes in; it still only ever overwrites what it writes.
+  writeExport({ serveRoot: root, outDir: out, uiDir: fakeUi(), force: true })
+  assert.ok(existsSync(join(out, SNAPSHOT_FILE)))
+  assert.equal(readFileSync(join(out, "thesis.md"), "utf8"), "years of work")
+})
+
+// ── The mount point, stamped into the page ──────────────────────────────────
+
+test("the exported page carries its mount point as a <base> tag", () => {
+  const root = board()
+
+  const atRoot = join(tempRoot(), "root")
+  writeExport({ serveRoot: root, outDir: atRoot, uiDir: fakeUi() })
+  assert.match(readFileSync(join(atRoot, "index.html"), "utf8"), /<head><base href="\/" \/>/)
+
+  const atSubpath = join(tempRoot(), "sub")
+  const summary = writeExport({ serveRoot: root, outDir: atSubpath, uiDir: fakeUi(), base: "board" })
+  assert.equal(summary.base, "/board/")
+  assert.match(
+    readFileSync(join(atSubpath, "index.html"), "utf8"),
+    /<head><base href="\/board\/" \/>/,
+  )
+})
+
+test("a base that isn't a plain URL path is refused", () => {
+  const root = board()
+  for (const bad of ["//cdn.example.com", "/a b/", '/"/']) {
+    assert.throws(
+      () => writeExport({ serveRoot: root, outDir: join(tempRoot(), "out"), uiDir: fakeUi(), base: bad }),
+      /--base/,
+      bad,
+    )
+  }
+})