@nickmeriano/task 0.7.1 → 0.9.0

package/src/claim.ts

@@ -10,10 +10,22 @@
  * (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 { FileStore, TICKETS_DIR, openBoard } from "./file-store.ts"
+import {
+  GIT_NETWORK_TIMEOUT_MS,
+  defaultBase,
+  git,
+  gitMust,
+  runGit,
+} from "./git.ts"
+import {
+  boardConfig,
+  findBoardsByPrefix,
+  findRoot,
+  findScopeRoot,
+  type Store,
+} from "./store.ts"
 import type { ProjectConfig, Task } from "./types.ts"
 
 /**
@@ -31,25 +43,51 @@ export const DEFAULT_CLAIM_PREFIX = "task/claim/"
 const CLAIM_PREFIX_SHAPE = /^([A-Za-z0-9._-]+\/)+$/
 
 /**
- * The board's claim namespace: configured `claimPrefix` (a trailing slash is
+ * The board's claim namespace: `claims.branchPrefix` (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.
+ *
+ * The pre-0.8 top-level `claimPrefix` spelling is not honored — no consumers,
+ * no compat (TAS-41) — but silently *defaulting* over it would be worse than
+ * a shim: the board's committed lock convention would change under every
+ * worker at once. So its presence refuses, loudly, by name.
  */
 export function claimNamespace(config: ProjectConfig): string {
-  const raw = config.claimPrefix ?? DEFAULT_CLAIM_PREFIX
+  if (config.claimPrefix !== undefined && config.claims?.branchPrefix === undefined) {
+    throw new ClaimError(
+      '`claimPrefix` in .task/config.json is the pre-0.8 spelling and is no longer read — rename it to `claims: { "branchPrefix": … }`',
+      "invalid",
+    )
+  }
+  const raw = config.claims?.branchPrefix ?? 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 claims.branchPrefix 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}`
+/**
+ * The repo-wide cap on open claims: `claims.maxOpenCount` read from the
+ * *root* board's config (the outermost `.task/` above `root`), never the
+ * nearest one — a WIP cap each board could set for itself is no cap at all.
+ * Absent, unparseable or nonsensical values all mean "no cap".
+ */
+export function openClaimCap(root: string): number | undefined {
+  try {
+    const cap = boardConfig(findScopeRoot(root)).claims?.maxOpenCount
+    return typeof cap === "number" && Number.isInteger(cap) && cap > 0 ? cap : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** { prefix: "TAS" }, "x7k4m" → "task/claim/tas-x7k4m" (or under the configured namespace). */
+export function claimBranch(config: ProjectConfig, key: string): string {
+  return `${claimNamespace(config)}${config.prefix.toLowerCase()}-${key}`
 }
 
 /**
@@ -65,52 +103,18 @@ export class ClaimError extends Error {
   }
 }
 
-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)
+/** Network git that throws on failure, with the timeout a real remote deserves. */
+function gitNetMust(cwd: string, ...args: string[]): string {
+  const result = runGit(cwd, args, { timeoutMs: GIT_NETWORK_TIMEOUT_MS })
   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 out = gitNetMust(cwd, "ls-remote", "--heads", "origin", `${namespace}*`)
   const names = new Set<string>()
   for (const line of out.split("\n")) {
     const ref = line.split("\t")[1]
@@ -120,25 +124,30 @@ export function remoteClaims(cwd: string, namespace: string): Set<string> {
 }
 
 function remoteBranchExists(cwd: string, branch: string): boolean {
-  return gitMust(cwd, "ls-remote", "--heads", "origin", branch) !== ""
+  return gitNetMust(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))
+    .map((k) => store.get(k))
     .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)
+/**
+ * Throws ClaimError("invalid") unless `task` is claimable right now. Open asks
+ * deliberately don't gate here: a ticket can be agent-implementable while a
+ * person owes it something in parallel — the done gate keeps that honest. An
+ * ask that must land *before* the work starts is a `blocked_by` on a thin
+ * human ticket, which the blocker check below already enforces.
+ */
+function assertClaimable(store: Store, task: Task | null, key: string): asserts task is Task {
+  const id = store.displayId(key)
   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")
@@ -151,6 +160,29 @@ export interface ClaimResult {
   base: string
 }
 
+export interface ClaimOptions {
+  /** Claim past the root board's `claims.maxOpenCount` cap. */
+  force?: boolean
+}
+
+/**
+ * The WIP-cap gate every claim passes through: while `maxOpenCount` claim
+ * branches exist on origin, claiming more is refused (exit 2 — the fix is to
+ * finish or release one, not to pick a different ticket). Existence on origin
+ * is the definition of "open": a claim branch dies at merge or release, so a
+ * lingering merged branch counts — deliberate pressure to clean it up. The
+ * cap applies to humans and agents alike; `--force` is the escape.
+ */
+function assertUnderCap(openClaims: Set<string>, root: string, namespace: string): void {
+  const cap = openClaimCap(root)
+  if (cap !== undefined && openClaims.size >= cap) {
+    throw new ClaimError(
+      `${openClaims.size} claim branch${openClaims.size === 1 ? "" : "es"} already open under ${namespace} — at the root board's maxOpenCount cap (${cap}); finish or \`task claim --release\` one, or pass --force`,
+      "invalid",
+    )
+  }
+}
+
 /**
  * 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
@@ -160,18 +192,27 @@ export interface ClaimResult {
  * 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 {
+export function claim(store: Store, key: string, options: ClaimOptions = {}): ClaimResult {
+  // Unreachable since openBoard refuses pre-0.6 boards, kept as the narrowing
+  // that lets the rest of this function assume text-canonical semantics.
   if (!(store instanceof FileStore)) {
-    throw new ClaimError("claiming needs a text-format board — run `task migrate` first", "invalid")
+    throw new ClaimError(
+      "claiming needs a text-format board — run `npx @nickmeriano/task@0.6 migrate` once",
+      "invalid",
+    )
   }
   const cwd = store.root
-  const branch = claimBranch(store.config, number)
-  const id = store.displayId(number)
+  const branch = claimBranch(store.config, key)
+  const id = store.displayId(key)
 
   // 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")
+  // -uno everywhere a claim reads the tree: only *tracked* modifications block
+  // a branch switch. Untracked files ride along untouched — and the release
+  // flow deliberately leaves one (the reason comment), so counting them would
+  // wedge the release-then-claim-next loop this exists for.
+  const tree = git(cwd, "status", "--porcelain", "-uno")
   if (tree.status !== 0) {
     throw new ClaimError(`not a git repository: ${cwd}`, "invalid")
   }
@@ -182,7 +223,7 @@ export function claim(store: Store, number: number): ClaimResult {
     )
   }
 
-  assertClaimable(store, store.get(number), number)
+  assertClaimable(store, store.get(key), key)
   if (tree.stdout !== "") {
     throw new ClaimError(
       "working tree is dirty — commit or stash before claiming, the claim switches branches",
@@ -190,10 +231,16 @@ export function claim(store: Store, number: number): ClaimResult {
     )
   }
 
-  gitMust(cwd, "fetch", "--quiet", "origin")
-  if (remoteBranchExists(cwd, branch)) {
+  gitNetMust(cwd, "fetch", "--quiet", "origin")
+  // One ls-remote answers both gates: is this ticket taken, and is the repo
+  // at its WIP cap. "Already claimed" wins — that's exit 1 (pick the next
+  // ticket), where the cap is exit 2 (fix something).
+  const namespace = claimNamespace(store.config)
+  const openClaims = remoteClaims(cwd, namespace)
+  if (openClaims.has(branch)) {
     throw new ClaimError(`${id} is already claimed — ${branch} exists on origin`, "claimed")
   }
+  if (!options.force) assertUnderCap(openClaims, cwd, namespace)
 
   const base = defaultBase(cwd)
   // So a failed claim can put the checkout back exactly where it was —
@@ -212,23 +259,19 @@ export function claim(store: Store, number: number): ClaimResult {
     // 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)))
+    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`)
   } catch (error) {
     undo()
     throw error
   }
 
-  const push = git(
+  const push = runGit(
     cwd,
-    "push",
-    "--quiet",
-    "-u",
-    "origin",
-    branch,
-    `--force-with-lease=refs/heads/${branch}:`,
+    ["push", "--quiet", "-u", "origin", branch, `--force-with-lease=refs/heads/${branch}:`],
+    { timeoutMs: GIT_NETWORK_TIMEOUT_MS },
   )
   if (push.status !== 0) {
     undo()
@@ -241,7 +284,7 @@ export function claim(store: Store, number: number): ClaimResult {
     )
   }
 
-  return { task: store.get(number)!, branch, base }
+  return { task: store.get(key)!, branch, base }
 }
 
 export interface ReleaseResult {
@@ -256,14 +299,14 @@ export interface ReleaseResult {
  * 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 {
+export function release(store: Store, key: string): ReleaseResult {
   const cwd = store.root
-  const branch = claimBranch(store.config, number)
+  const branch = claimBranch(store.config, key)
 
   const onBranch =
     git(cwd, "symbolic-ref", "--quiet", "--short", "HEAD").stdout === branch
   if (onBranch) {
-    const tree = gitMust(cwd, "status", "--porcelain")
+    const tree = gitMust(cwd, "status", "--porcelain", "-uno")
     if (tree !== "") {
       throw new ClaimError(
         `working tree on ${branch} is dirty — commit elsewhere or discard before releasing`,
@@ -283,20 +326,134 @@ export function release(store: Store, number: number): ReleaseResult {
 
   const local = git(cwd, "branch", "--quiet", "-D", branch).status === 0
   const remote = remoteBranchExists(cwd, branch)
-  if (remote) gitMust(cwd, "push", "--quiet", "origin", "--delete", branch)
+  if (remote) gitNetMust(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.
+ * The dispatcher's queue view: `todo` in position order, minus blocked, minus
+ * tickets whose claim branch already exists on origin (one ls-remote for the
+ * whole namespace). The top entry is next up. Open asks don't exclude a
+ * ticket — see assertClaimable.
  */
 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)))
+    .filter((t) => !claimed.has(claimBranch(store.config, t.key)))
+}
+
+export interface PromoteResult {
+  task: Task
+  /** Claim-time gates still in the way — promoted, but not claimable yet. */
+  holds: string[]
+}
+
+/**
+ * `task promote` — the human "build this" call, as a verb: `backlog` → `todo`.
+ * No quality gate: planning happens at claim time (the worker's plan tick),
+ * so a one-line backlog ticket is promotable. Blockers are claim-time facts
+ * that `claim`/`--claimable` already enforce live, so promoting a blocked
+ * ticket is legitimate sequencing ("build this once NIC-11 lands") — reported
+ * as a hold, never refused. Open asks aren't a hold at all: they don't gate
+ * claiming, only done. Writes the ticket like `update` does; committing is
+ * the caller's job.
+ */
+export function promote(store: Store, key: string): PromoteResult {
+  const task = store.get(key)
+  const id = store.displayId(key)
+  if (!task) throw new ClaimError(`no such task: ${id}`, "invalid")
+  if (task.status !== "backlog") {
+    throw new ClaimError(
+      `${id} is ${task.status} — only backlog tickets can be promoted`,
+      "invalid",
+    )
+  }
+  const updated = store.update(key, { status: "todo" })
+  const holds: string[] = []
+  const blockers = openBlockers(store, updated)
+  if (blockers.length) holds.push(`blocked by ${blockers.join(", ")}`)
+  return { task: updated, holds }
+}
+
+/**
+ * The boards `claim --next` and `list --claimable` select over, in priority
+ * order. Resolution: an explicit `--board` list > the root board's top-level
+ * `boards` key > the nearest board alone. The list is *selection scope*, not
+ * permission — `task claim <id>` works on any board regardless — and it's
+ * read from the repo's root board only, so a vendored board can't opt itself
+ * into a repo's automation by shipping a config.
+ */
+export function selectionBoards(cwd: string, prefixes?: string[]): Store[] {
+  const scope = findScopeRoot(cwd)
+  let wanted = prefixes?.length ? prefixes : undefined
+  if (!wanted) {
+    try {
+      const boards = boardConfig(scope).boards
+      if (Array.isArray(boards) && boards.length > 0) wanted = boards.map(String)
+    } catch {
+      // No readable root board — same answer as no boards list.
+    }
+  }
+  if (!wanted) {
+    const nearest = findRoot(cwd)
+    if (!nearest) {
+      throw new ClaimError(
+        "no .task directory found in this directory or any parent — run `task init` first",
+        "invalid",
+      )
+    }
+    return [openBoard(nearest)]
+  }
+  return wanted.map((prefix) => {
+    const matches = findBoardsByPrefix(scope, prefix)
+    if (matches.length === 1) return openBoard(matches[0].root)
+    throw new ClaimError(
+      matches.length === 0
+        ? `no board with prefix ${prefix.toUpperCase()} in this repo — check --board and the root board's "boards" list`
+        : `prefix ${prefix.toUpperCase()} is ambiguous — boards at: ${matches.map((m) => m.id).join(", ")}`,
+      "invalid",
+    )
+  })
+}
+
+/**
+ * `task claim --next`: walk the selection scope in priority order and claim
+ * the first ticket that sticks. Losing a race for one ticket (another worker
+ * pushed its branch first) means *try the next*, so every ClaimError inside
+ * the loop is a skip — which is why the repo-level preconditions (dirty tree,
+ * malformed prefix, WIP cap) are asserted up front, where they still mean
+ * "stop and fix something" (exit 2) instead of draining the queue to a bogus
+ * "nothing claimable". Returns null when the queue really is empty (exit 1).
+ */
+export function claimNext(stores: Store[], options: ClaimOptions = {}): ClaimResult | null {
+  const first = stores[0]
+  const tree = git(first.root, "status", "--porcelain", "-uno")
+  if (tree.status !== 0) {
+    throw new ClaimError(`not a git repository: ${first.root}`, "invalid")
+  }
+  if (tree.stdout !== "") {
+    throw new ClaimError(
+      "working tree is dirty — commit or stash before claiming, the claim switches branches",
+      "invalid",
+    )
+  }
+  for (const store of stores) claimNamespace(store.config)
+  if (!options.force) {
+    const namespace = claimNamespace(first.config)
+    assertUnderCap(remoteClaims(first.root, namespace), first.root, namespace)
+  }
+  for (const store of stores) {
+    for (const task of claimableTasks(store)) {
+      try {
+        return claim(store, task.key, options)
+      } catch (error) {
+        // Claimed out from under us, or changed since listing — next in line.
+        if (error instanceof ClaimError) continue
+        throw error
+      }
+    }
+  }
+  return null
 }