@nickmeriano/task 0.8.0 → 0.9.0

package/src/claim.ts

@@ -10,9 +10,15 @@
  * (the implement-task skill, a human).
  */
 
-import { spawnSync } from "node:child_process"
 import { join } from "node:path"
 import { FileStore, TICKETS_DIR, openBoard } from "./file-store.ts"
+import {
+  GIT_NETWORK_TIMEOUT_MS,
+  defaultBase,
+  git,
+  gitMust,
+  runGit,
+} from "./git.ts"
 import {
   boardConfig,
   findBoardsByPrefix,
@@ -37,23 +43,23 @@ export const DEFAULT_CLAIM_PREFIX = "task/claim/"
 const CLAIM_PREFIX_SHAPE = /^([A-Za-z0-9._-]+\/)+$/
 
 /**
- * The board's configured claim namespace before validation or defaulting —
- * `claims.branchPrefix`, falling back to the pre-0.8 top-level `claimPrefix`
- * (still read for one release so a version bump can't strand in-flight
- * claims; `task check` nags, `--fix` migrates). Exported for `task check`,
- * which wants the raw value to lint without the throw below.
- */
-export function configuredBranchPrefix(config: ProjectConfig): string | undefined {
-  return config.claims?.branchPrefix ?? config.claimPrefix
-}
-
-/**
- * The board's claim namespace: configured branch prefix (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 = configuredBranchPrefix(config) ?? 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(
@@ -79,9 +85,9 @@ export function openClaimCap(root: string): number | undefined {
   }
 }
 
-/** { 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}`
+/** { 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}`
 }
 
 /**
@@ -97,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]
@@ -152,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")
@@ -215,7 +192,7 @@ function assertUnderCap(openClaims: Set<string>, root: string, namespace: string
  * 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, options: ClaimOptions = {}): 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)) {
@@ -225,8 +202,8 @@ export function claim(store: Store, number: number, options: ClaimOptions = {}):
     )
   }
   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"
@@ -246,7 +223,7 @@ export function claim(store: Store, number: number, options: ClaimOptions = {}):
     )
   }
 
-  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",
@@ -254,7 +231,7 @@ export function claim(store: Store, number: number, options: ClaimOptions = {}):
     )
   }
 
-  gitMust(cwd, "fetch", "--quiet", "origin")
+  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).
@@ -282,23 +259,19 @@ export function claim(store: Store, number: number, options: ClaimOptions = {}):
     // 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()
@@ -311,7 +284,7 @@ export function claim(store: Store, number: number, options: ClaimOptions = {}):
     )
   }
 
-  return { task: store.get(number)!, branch, base }
+  return { task: store.get(key)!, branch, base }
 }
 
 export interface ReleaseResult {
@@ -326,9 +299,9 @@ 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
@@ -353,22 +326,22 @@ 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 {
@@ -380,15 +353,16 @@ export interface PromoteResult {
 /**
  * `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. Blocked and needs-human 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. Writes the ticket like
- * `update` does; committing is the caller's job.
+ * 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, number: number): PromoteResult {
-  const task = store.get(number)
-  const id = store.displayId(number)
+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(
@@ -396,9 +370,8 @@ export function promote(store: Store, number: number): PromoteResult {
       "invalid",
     )
   }
-  const updated = store.update(number, { status: "todo" })
+  const updated = store.update(key, { status: "todo" })
   const holds: string[] = []
-  if (updated.needsHuman) holds.push("flagged needs-human")
   const blockers = openBlockers(store, updated)
   if (blockers.length) holds.push(`blocked by ${blockers.join(", ")}`)
   return { task: updated, holds }
@@ -474,7 +447,7 @@ export function claimNext(stores: Store[], options: ClaimOptions = {}): ClaimRes
   for (const store of stores) {
     for (const task of claimableTasks(store)) {
       try {
-        return claim(store, task.number, options)
+        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