@nickmeriano/task 0.6.0 → 0.7.0

package/src/claim.ts

@@ -0,0 +1,302 @@
+/**
+ * `task claim` — atomic ticket claiming, for humans and scheduled agents alike
+ * (NIC-7 / TAS-21). The claim *is* the ticket's work branch: one deterministic
+ * name per ticket, creating it on origin is claiming it, and git's atomic ref
+ * creation is the lock. Branch existence = claimed; the branch dies at merge,
+ * so there is no claim state to clean up.
+ *
+ * The CLI stays board-level and forge-agnostic — everything here is plain git
+ * against `origin`. PR/session awareness belongs to whatever drives the claim
+ * (the implement-task skill, a human).
+ */
+
+import { spawnSync } from "node:child_process"
+import { join } from "node:path"
+import { FileStore, TICKETS_DIR } from "./file-store.ts"
+import type { Store } from "./store.ts"
+import type { ProjectConfig, Task } from "./types.ts"
+
+/**
+ * The branch namespace claims live under when the board doesn't configure
+ * one. Deliberately vendor-neutral: repos whose workers are Claude Code cloud
+ * sessions set `"claimPrefix": "claude/task/"` in `.task/config.json` — the
+ * one namespace that runtime can push without extra ceremony — and any other
+ * convention is equally valid. The key is committed with the board so every
+ * worker and every clone agree on what "claimed" looks like; a lock two
+ * sides spell differently is no lock at all.
+ */
+export const DEFAULT_CLAIM_PREFIX = "task/claim/"
+
+/** Slash-terminated path segments of ref-safe characters. */
+const CLAIM_PREFIX_SHAPE = /^([A-Za-z0-9._-]+\/)+$/
+
+/**
+ * The board's claim namespace: configured `claimPrefix` (a trailing slash is
+ * implied) or the default. Validated here because it becomes a git ref and an
+ * ls-remote glob — a malformed value must fail the claim, not corrupt it.
+ */
+export function claimNamespace(config: ProjectConfig): string {
+  const raw = config.claimPrefix ?? DEFAULT_CLAIM_PREFIX
+  const prefix = raw.endsWith("/") ? raw : `${raw}/`
+  if (!CLAIM_PREFIX_SHAPE.test(prefix) || prefix.includes("..") || /(^|\/)\./.test(prefix)) {
+    throw new ClaimError(
+      `invalid claimPrefix in .task/config.json: ${JSON.stringify(raw)} — use slash-separated segments like "task/claim/" or "claude/task/"`,
+      "invalid",
+    )
+  }
+  return prefix
+}
+
+/** { prefix: "TAS" }, 21 → "task/claim/tas-21" (or under the configured namespace). */
+export function claimBranch(config: ProjectConfig, number: number): string {
+  return `${claimNamespace(config)}${config.prefix.toLowerCase()}-${number}`
+}
+
+/**
+ * Why a claim was refused: "claimed" (someone holds the branch — exit 1, pick
+ * the next ticket) vs "invalid" (the ticket or the tree isn't claimable —
+ * exit 2, fix something).
+ */
+export class ClaimError extends Error {
+  readonly kind: "claimed" | "invalid"
+  constructor(message: string, kind: "claimed" | "invalid") {
+    super(message)
+    this.kind = kind
+  }
+}
+
+interface GitResult {
+  status: number
+  stdout: string
+  stderr: string
+}
+
+function git(cwd: string, ...args: string[]): GitResult {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8" })
+  if (result.error) throw result.error
+  return {
+    status: result.status ?? 1,
+    stdout: (result.stdout ?? "").trim(),
+    stderr: (result.stderr ?? "").trim(),
+  }
+}
+
+/** Run git and throw on failure — for the steps that have no soft outcome. */
+function gitMust(cwd: string, ...args: string[]): string {
+  const result = git(cwd, ...args)
+  if (result.status !== 0) {
+    throw new Error(`git ${args[0]} failed: ${result.stderr || result.stdout}`)
+  }
+  return result.stdout
+}
+
+/**
+ * The base every claim branch starts from: origin's default branch. Resolved
+ * from `origin/HEAD` when the clone recorded it, with a main/master fallback
+ * for repos wired up by hand (`git remote add` + push never sets origin/HEAD).
+ */
+function defaultBase(cwd: string): string {
+  const head = git(cwd, "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
+  if (head.status === 0) return head.stdout.replace(/^refs\/remotes\//, "")
+  for (const name of ["main", "master"]) {
+    if (git(cwd, "show-ref", "--verify", "--quiet", `refs/remotes/origin/${name}`).status === 0) {
+      return `origin/${name}`
+    }
+  }
+  throw new Error(
+    "couldn't resolve origin's default branch — origin/HEAD is unset and neither origin/main nor origin/master exists",
+  )
+}
+
+/** Every claim branch that exists on origin right now — one network call. */
+export function remoteClaims(cwd: string, namespace: string): Set<string> {
+  const out = gitMust(cwd, "ls-remote", "--heads", "origin", `${namespace}*`)
+  const names = new Set<string>()
+  for (const line of out.split("\n")) {
+    const ref = line.split("\t")[1]
+    if (ref?.startsWith("refs/heads/")) names.add(ref.slice("refs/heads/".length))
+  }
+  return names
+}
+
+function remoteBranchExists(cwd: string, branch: string): boolean {
+  return gitMust(cwd, "ls-remote", "--heads", "origin", branch) !== ""
+}
+
+/** Blockers still in the way — anything not done or canceled still blocks. */
+function openBlockers(store: Store, task: Task): string[] {
+  return task.blockedBy
+    .map((n) => store.get(n))
+    .filter((b): b is Task => b !== null && b.status !== "done" && b.status !== "canceled")
+    .map((b) => b.id)
+}
+
+/** Throws ClaimError("invalid") unless `task` is claimable right now. */
+function assertClaimable(store: Store, task: Task | null, number: number): asserts task is Task {
+  const id = store.displayId(number)
+  if (!task) throw new ClaimError(`no such task: ${id}`, "invalid")
+  if (task.status !== "todo") {
+    throw new ClaimError(`${id} is ${task.status} — only todo tickets can be claimed`, "invalid")
+  }
+  if (task.needsHuman) throw new ClaimError(`${id} needs a human — not claimable`, "invalid")
+  const blockers = openBlockers(store, task)
+  if (blockers.length) {
+    throw new ClaimError(`${id} is blocked by ${blockers.join(", ")} — not claimable`, "invalid")
+  }
+}
+
+export interface ClaimResult {
+  task: Task
+  branch: string
+  base: string
+}
+
+/**
+ * Claim `number`: validate, branch off origin's default branch, flip the
+ * ticket to in_progress as the branch's first commit, and push. The push
+ * carries `--force-with-lease=<branch>:` (empty expectation = "the ref must
+ * not exist"), so creating the remote branch is a compare-and-swap: two
+ * concurrent claimers of the same ticket, exactly one wins — and a branch
+ * someone pre-created without a claim commit can't be hijacked by a plain
+ * fast-forward. Leaves the winner checked out on the claim branch.
+ */
+export function claim(store: Store, number: number): ClaimResult {
+  if (!(store instanceof FileStore)) {
+    throw new ClaimError("claiming needs a text-format board — run `task migrate` first", "invalid")
+  }
+  const cwd = store.root
+  const branch = claimBranch(store.config, number)
+  const id = store.displayId(number)
+
+  // The local-branch check comes before ticket validation on purpose: on the
+  // claim branch itself the ticket reads in_progress, and "already claimed"
+  // (exit 1, move on) is the truthful answer there — not a validation failure.
+  const tree = git(cwd, "status", "--porcelain")
+  if (tree.status !== 0) {
+    throw new ClaimError(`not a git repository: ${cwd}`, "invalid")
+  }
+  if (git(cwd, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`).status === 0) {
+    throw new ClaimError(
+      `${id} is already claimed — ${branch} exists locally (finish it, or \`task claim --release ${id}\`)`,
+      "claimed",
+    )
+  }
+
+  assertClaimable(store, store.get(number), number)
+  if (tree.stdout !== "") {
+    throw new ClaimError(
+      "working tree is dirty — commit or stash before claiming, the claim switches branches",
+      "invalid",
+    )
+  }
+
+  gitMust(cwd, "fetch", "--quiet", "origin")
+  if (remoteBranchExists(cwd, branch)) {
+    throw new ClaimError(`${id} is already claimed — ${branch} exists on origin`, "claimed")
+  }
+
+  const base = defaultBase(cwd)
+  // So a failed claim can put the checkout back exactly where it was —
+  // a branch name usually, a bare sha when HEAD was detached.
+  const previous =
+    git(cwd, "symbolic-ref", "--quiet", "--short", "HEAD").stdout ||
+    gitMust(cwd, "rev-parse", "HEAD")
+  gitMust(cwd, "checkout", "--quiet", "-b", branch, base)
+
+  const undo = (): void => {
+    git(cwd, "checkout", "--quiet", previous)
+    git(cwd, "branch", "--quiet", "-D", branch)
+  }
+
+  try {
+    // Re-validate against the base branch: the pre-checkout validation read
+    // whatever happened to be checked out, this one reads the truth the claim
+    // will actually be built on.
+    assertClaimable(store, store.get(number), number)
+    store.update(number, { status: "in_progress" })
+    gitMust(cwd, "add", "--", join(store.taskDir, TICKETS_DIR, String(number)))
+    gitMust(cwd, "commit", "--quiet", "-m", `chore(board): claim ${id} → in_progress`)
+  } catch (error) {
+    undo()
+    throw error
+  }
+
+  const push = git(
+    cwd,
+    "push",
+    "--quiet",
+    "-u",
+    "origin",
+    branch,
+    `--force-with-lease=refs/heads/${branch}:`,
+  )
+  if (push.status !== 0) {
+    undo()
+    if (remoteBranchExists(cwd, branch)) {
+      throw new ClaimError(`${id} is already claimed — ${branch} was just created on origin`, "claimed")
+    }
+    throw new ClaimError(
+      `${id}: push of ${branch} was rejected (likely a concurrent claim) — ${push.stderr || "no detail from git"}`,
+      "claimed",
+    )
+  }
+
+  return { task: store.get(number)!, branch, base }
+}
+
+export interface ReleaseResult {
+  branch: string
+  /** Whether a branch was actually there to delete, per side. */
+  remote: boolean
+  local: boolean
+}
+
+/**
+ * Abandon a claim cleanly: delete the branch on origin and locally. The status
+ * flip only ever existed as a commit on that branch, so deleting it *is* the
+ * revert — the default branch never saw in_progress.
+ */
+export function release(store: Store, number: number): ReleaseResult {
+  const cwd = store.root
+  const branch = claimBranch(store.config, number)
+
+  const onBranch =
+    git(cwd, "symbolic-ref", "--quiet", "--short", "HEAD").stdout === branch
+  if (onBranch) {
+    const tree = gitMust(cwd, "status", "--porcelain")
+    if (tree !== "") {
+      throw new ClaimError(
+        `working tree on ${branch} is dirty — commit elsewhere or discard before releasing`,
+        "invalid",
+      )
+    }
+    // Step off the branch so it can be deleted: onto the local default branch
+    // when there is one, detached onto the remote base otherwise.
+    const base = defaultBase(cwd)
+    const local = base.replace(/^origin\//, "")
+    if (git(cwd, "show-ref", "--verify", "--quiet", `refs/heads/${local}`).status === 0) {
+      gitMust(cwd, "checkout", "--quiet", local)
+    } else {
+      gitMust(cwd, "checkout", "--quiet", "--detach", base)
+    }
+  }
+
+  const local = git(cwd, "branch", "--quiet", "-D", branch).status === 0
+  const remote = remoteBranchExists(cwd, branch)
+  if (remote) gitMust(cwd, "push", "--quiet", "origin", "--delete", branch)
+  return { branch, remote, local }
+}
+
+/**
+ * The dispatcher's queue view: `todo` in position order, minus needs-human,
+ * minus blocked, minus tickets whose claim branch already exists on origin
+ * (one ls-remote for the whole namespace). The top entry is next up.
+ */
+export function claimableTasks(store: Store): Task[] {
+  const claimed = remoteClaims(store.root, claimNamespace(store.config))
+  return store
+    .list({ statuses: ["todo"] })
+    .filter((t) => !t.needsHuman)
+    .filter((t) => openBlockers(store, t).length === 0)
+    .filter((t) => !claimed.has(claimBranch(store.config, t.number)))
+}

package/src/cli.ts

@@ -16,6 +16,7 @@ import type { Server } from "node:http"
 import { basename, join } from "node:path"
 import process from "node:process"
 import { resolveAuthor } from "./author.ts"
+import { ClaimError, claim, claimableTasks, release } from "./claim.ts"
 import { detectRepo, parseSlug, publish, resolveHost } from "./publish.ts"
 import { createTaskServer } from "./server.ts"
 import { initProject, migrateBoard, openBoard } from "./file-store.ts"
@@ -75,6 +76,8 @@ const BOOLEAN_FLAGS = new Set([
   "needs-human",
   "no-needs-human",
   "archived",
+  "claimable",
+  "release",
   "open",
   "no-open",
   "strict-port",
@@ -284,6 +287,22 @@ function cmdAdd(args: Args): void {
 
 function cmdList(args: Args): void {
   const store = openStore()
+  if (args.flags.claimable) {
+    // The dispatcher's queue view (TAS-21): claimable already pins the status
+    // set and consults origin, so the board-shaping flags don't compose.
+    for (const flag of ["status", "all", "archived"]) {
+      if (args.flags[flag] !== undefined) fail(`--claimable can't be combined with --${flag}`)
+    }
+    const tasks = claimableTasks(store)
+    if (args.flags.json) {
+      console.log(JSON.stringify({ tasks }, null, 2))
+    } else if (tasks.length === 0) {
+      console.log("nothing claimable — no unblocked, unclaimed todo tickets")
+    } else {
+      table(tasks.map(taskRow))
+    }
+    return
+  }
   const archived = Boolean(args.flags.archived)
   const statusFlag = str(args.flags, "status")
   const statuses = statusFlag
@@ -519,6 +538,44 @@ function cmdLink(args: Args, action: "link" | "unlink"): void {
   }
 }
 
+/**
+ * `task claim <id>` / `task claim --release <id>` — see claim.ts for the
+ * mechanics. Exit codes are the contract callers script against: 0 claimed,
+ * 1 already claimed (pick the next ticket), 2 not claimable (fix something).
+ */
+function cmdClaim(args: Args): void {
+  const ref = args.positional[0]
+  if (!ref) fail("usage: task claim <id> | task claim --release <id>")
+  const store = openStoreFor(ref)
+  const number = store.parseId(ref)
+  try {
+    if (args.flags.release) {
+      const result = release(store, number)
+      if (args.flags.json) {
+        console.log(JSON.stringify({ released: result }, null, 2))
+      } else if (!result.remote && !result.local) {
+        console.log(`${store.displayId(number)} wasn't claimed — no ${result.branch} to delete`)
+      } else {
+        const where = [result.remote && "origin", result.local && "local"].filter(Boolean)
+        console.log(`released ${store.displayId(number)} — deleted ${result.branch} (${where.join(" and ")})`)
+      }
+      return
+    }
+    const result = claim(store, number)
+    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`)
+    }
+  } catch (error) {
+    if (error instanceof ClaimError) {
+      console.error(`error: ${error.message}`)
+      process.exit(error.kind === "claimed" ? 1 : 2)
+    }
+    throw error
+  }
+}
+
 const AUTHOR_SOURCE: Record<string, string> = {
   flag: "--author",
   env: "$TASK_AUTHOR",
@@ -764,7 +821,7 @@ Usage
   task add <title> [--description <text>] [--status <s>] [--tags <a,b>]
                    [--milestone <m>] [--needs-human]
   task list [--status <s1,s2>] [--tag <a,b>] [--milestone <m>]
-            [--needs-human] [--all] [--archived]
+            [--needs-human] [--all] [--archived] [--claimable]
   task show <id>
   task update <id> [--title <t>] [--description <text>] [--status <s>]
                    [--tags <a,b>] [--milestone <m>]
@@ -777,6 +834,24 @@ Usage
   task link <id> --blocks <id>  mark a dependency — one relation, visible from
                                 both tasks (A blocked by B ⇔ B blocks A)
   task unlink <id> (--blocks <id> | --blocked-by <id>)
+  task claim <id>               claim a ticket before working it: branch
+                                <claimPrefix><prefix>-<n> off origin's default
+                                branch, ticket → in_progress as its first
+                                commit, pushed. The namespace defaults to
+                                task/claim/ — set "claimPrefix" in
+                                .task/config.json to change it (e.g.
+                                "claude/task/", which Claude cloud sessions
+                                can push). Branch on origin = claimed —
+                                git's atomic ref creation is the lock, so two
+                                concurrent claimers can't both win. Exit codes:
+                                0 claimed, 1 already claimed, 2 not claimable
+                                (not todo, blocked, needs-human, dirty tree)
+  task claim --release <id>     abandon a claim: delete the branch on origin
+                                and locally — the status flip only lived on
+                                the branch, so deleting it is the revert
+  task list --claimable         the claim queue: todo tickets in position
+                                order, minus blocked / needs-human / already
+                                claimed on origin. Top entry is next up
   task comment <id> <text> [--author <who>]
   task delete <id>
   task boards                   every board in this repo — prefix, name, path,
@@ -862,6 +937,8 @@ function main(): void | Promise<void> {
       return cmdLink(args, "link")
     case "unlink":
       return cmdLink(args, "unlink")
+    case "claim":
+      return cmdClaim(args)
     case "comment":
       return cmdComment(args)
     case "whoami":

package/src/index.ts

@@ -27,6 +27,18 @@ export {
   type TicketDoc,
   type CommentDoc,
 } from "./ticket-doc.ts"
+export {
+  DEFAULT_CLAIM_PREFIX,
+  ClaimError,
+  claim,
+  claimBranch,
+  claimNamespace,
+  claimableTasks,
+  release,
+  remoteClaims,
+  type ClaimResult,
+  type ReleaseResult,
+} from "./claim.ts"
 export { createTaskServer } from "./server.ts"
 export { resolveAuthor, ANONYMOUS, type Author, type AuthorSource } from "./author.ts"
 export * from "./types.ts"

package/src/types.ts

@@ -59,6 +59,14 @@ export interface ProjectConfig {
   /** Uppercase id prefix, e.g. "PHO" → PHO-1, PHO-2, … */
   prefix: string
   version: number
+  /**
+   * Branch namespace `task claim` creates claim branches under — committed
+   * with the board on purpose, so every worker and every clone agree on what
+   * "claimed" looks like. Defaults to "task/claim/"; repos whose workers are
+   * Claude Code cloud sessions set "claude/task/", the one prefix that
+   * runtime can push without extra ceremony.
+   */
+  claimPrefix?: string
 }
 
 export interface TaskFilter {