@nickmeriano/task 0.7.1 → 0.9.0

package/src/claim-io.ts

@@ -0,0 +1,401 @@
+/**
+ * Ask I/O against claim branches (TAS-38, second round): a claimed ticket's
+ * truth lives on its claim branch, so ask *writes* on a claimed ticket go to
+ * the branch too — resolve, reopen, add, delete — as real commits, made and
+ * pushed without ever touching the checkout. The owner clicks a checkbox on
+ * main's board; the commit lands on `claude/task/tas-40`; the worker's next
+ * tick pulls it and sees the answer in the one place it was ever going to
+ * look. No parallel copies, no merge collision, no relay through comments.
+ *
+ * The mechanics are plain git plumbing: build the new tree in a temporary
+ * index (`read-tree` → `update-index` → `write-tree`), commit it with the
+ * branch tip as parent, and push fast-forward. A concurrent worker push just
+ * rejects ours; we refetch and reapply once against the new tip — the
+ * mutation is expressed as a function of the file's current bytes, so a
+ * retry can notice the work is already done and quietly stand down.
+ *
+ * Reads (the inbox's view of a claimed ticket) live here too, so reading and
+ * writing can never disagree about where an ask file is.
+ */
+
+import { rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+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 { ASKS_DIR, TICKETS_DIR } from "./file-store.ts"
+import type { Store } from "./store.ts"
+import type { Ask, Task } from "./types.ts"
+
+/**
+ * Soft git (from git.ts): null on any failure — callers decide whether that's
+ * an error. These run inside `task serve` request handlers, so a network call
+ * must never wait on a human: the shared module's no-prompt env turns a
+ * would-be credential prompt into a fast failure, and its timeout bounds a
+ * wedged remote. The 30s default is kept even for the fetches and pushes
+ * here — a serve request that can't finish in that is better off failing.
+ */
+const git = gitOut
+
+/** Like `git`, but with extra env — the temp-index dance needs GIT_INDEX_FILE. */
+function gitEnv(cwd: string, env: Record<string, string>, ...args: string[]): string | null {
+  const result = runGit(cwd, args, { env })
+  return result.status === 0 ? result.stdout : null
+}
+
+/**
+ * Every claim branch on origin right now, with its tip sha — one bounded
+ * `ls-remote`, the single unavoidable network call behind live claim status.
+ * Null means "origin can't be asked" (offline, no remote, auth would have
+ * prompted), which every caller treats as "act on file truth". This is the
+ * read-path twin of claim.ts's `remoteClaims`, deliberately separate: reads
+ * must never prompt for credentials — this runs inside `task serve` request
+ * handlers — while `task claim` itself may legitimately ask a human to log in.
+ */
+export function remoteClaimTips(store: Store): Map<string, string> | null {
+  let namespace: string
+  try {
+    namespace = claimNamespace(store.config)
+  } catch {
+    return null
+  }
+  const out = git(store.root, "ls-remote", "--heads", "origin", `${namespace}*`)
+  if (out === null) return null
+  const tips = new Map<string, string>()
+  for (const line of out.split("\n")) {
+    const [sha, ref] = line.split("\t")
+    if (ref?.startsWith("refs/heads/")) tips.set(ref.slice("refs/heads/".length), sha)
+  }
+  return tips
+}
+
+/**
+ * Make the local remote-tracking claim refs agree with the tips `ls-remote`
+ * just reported — fetching *only the branches that moved* (the tip sha says
+ * whether anything changed, so an unchanged claim costs no fetch at all) and
+ * deleting local refs for claims origin no longer has, so a released claim
+ * can't linger as a ghost. This is what keeps the inbox cheap under the UI's
+ * refetch-on-every-change behavior: steady state is one ls-remote and zero
+ * fetches.
+ */
+export function syncClaimRefs(store: Store, namespace: string, tips: Map<string, string>): void {
+  const stale = [...tips].filter(
+    ([branch, sha]) =>
+      git(store.root, "rev-parse", "--verify", "--quiet", `refs/remotes/origin/${branch}`) !== sha,
+  )
+  if (stale.length > 0) {
+    git(
+      store.root,
+      "fetch",
+      "--quiet",
+      "origin",
+      ...stale.map(([branch]) => `+refs/heads/${branch}:refs/remotes/origin/${branch}`),
+    )
+  }
+  const local = git(store.root, "for-each-ref", "--format=%(refname:short)", `refs/remotes/origin/${namespace}*`)
+  for (const short of local?.split("\n") ?? []) {
+    const branch = short.replace(/^origin\//, "")
+    if (branch && !tips.has(branch)) {
+      git(store.root, "update-ref", "-d", `refs/remotes/origin/${branch}`)
+    }
+  }
+}
+
+/** Force-refresh one claim branch's local ref — the write path's retry needs the moved tip. */
+function fetchClaimBranch(store: Store, branch: string): void {
+  git(store.root, "fetch", "--quiet", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`)
+}
+
+/**
+ * The ticket's claim branch if one exists on origin right now, else null —
+ * null also for "origin unreachable". Syncs the local claim refs as a side
+ * effect when a claim is found, so subsequent branch reads see the tip the
+ * answer was based on.
+ */
+export function claimFor(store: Store, key: string): string | null {
+  try {
+    const branch = claimBranch(store.config, key)
+    const tips = remoteClaimTips(store)
+    if (!tips?.has(branch)) return null
+    syncClaimRefs(store, claimNamespace(store.config), tips)
+    return branch
+  } catch {
+    return null
+  }
+}
+
+/** True when this checkout *is* the claim branch — then local writes are branch writes. */
+export function onClaimBranch(store: Store, branch: string): boolean {
+  return git(store.root, "symbolic-ref", "--quiet", "--short", "HEAD") === branch
+}
+
+/** The ask directory's path relative to the git toplevel — git speaks toplevel paths. */
+function askDirOnBranch(store: Store, key: string): string | null {
+  const toplevel = git(store.root, "rev-parse", "--show-toplevel")
+  if (!toplevel) return null
+  return [relative(toplevel, store.taskDir).split(sep).join("/"), TICKETS_DIR, key, ASKS_DIR]
+    .filter(Boolean)
+    .join("/")
+}
+
+/**
+ * The ask files of one ticket as its claim branch has them, leniently — the
+ * branch's bytes were written by another checkout and possibly an older CLI.
+ * Any git failure (ref gone between fetch and read, no asks dir) reads as
+ * "no asks on the branch", never an error.
+ */
+export function branchAsks(store: Store, branch: string, key: string): Omit<Ask, "ordinal">[] {
+  const dir = askDirOnBranch(store, key)
+  if (!dir) return []
+  const listing = git(store.root, "ls-tree", "--name-only", `origin/${branch}:${dir}`)
+  if (!listing) return []
+  const asks: Omit<Ask, "ordinal">[] = []
+  for (const name of listing.split("\n")) {
+    if (!name.endsWith(".md") || name.startsWith(".")) continue
+    const text = git(store.root, "show", `origin/${branch}:${dir}/${name}`)
+    if (text === null) continue
+    const doc = parseAskLenient(text)
+    if (!doc) continue
+    asks.push({
+      id: name.slice(0, -3),
+      taskId: store.displayId(key),
+      text: doc.body,
+      author: doc.author,
+      createdAt: doc.createdAt,
+      resolvedAt: doc.resolvedAt,
+      resolvedBy: doc.resolvedBy,
+    })
+  }
+  return asks
+}
+
+/**
+ * Local and branch asks, unioned by id with the branch winning — the branch
+ * holds the claim, so its version of a shared ask is the fresher one — then
+ * re-ordinaled over the union. These are the ordinals the inbox prints and
+ * the ones a resolve against a claimed ticket accepts.
+ */
+export function mergedAsks(store: Store, branch: string, task: Task): Ask[] {
+  const merged = new Map(task.asks.map((a) => [a.id, a as Omit<Ask, "ordinal">]))
+  for (const ask of branchAsks(store, branch, task.key)) merged.set(ask.id, ask)
+  return [...merged.values()]
+    .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id))
+    .map((ask, index) => ({ ...ask, ordinal: index + 1 }))
+}
+
+/**
+ * Commit one file change onto the claim branch and push it, without touching
+ * the checkout. `mutate` maps the file's current bytes (null = absent) to its
+ * next bytes (null = delete) — expressed that way so the fast-forward-reject
+ * retry can recompute against the moved tip, and return `null → no change`
+ * when someone else already made the edit.
+ */
+function writeOnClaimBranch(
+  store: Store,
+  branch: string,
+  path: string,
+  message: string,
+  mutate: (current: string | null) => string | null,
+): void {
+  const cwd = store.root
+  for (let attempt = 0; ; attempt++) {
+    const tip = git(cwd, "rev-parse", `refs/remotes/origin/${branch}`)
+    if (!tip) throw new Error(`can't read origin/${branch} — is origin reachable?`)
+
+    const current = git(cwd, "show", `${tip}:${path}`)
+    const next = mutate(current)
+    if (next === current || (next === null && current === null)) return // already there
+
+    const index = join(tmpdir(), `task-claim-index-${process.pid}-${Date.now()}`)
+    const env = { GIT_INDEX_FILE: index }
+    try {
+      if (gitEnv(cwd, env, "read-tree", tip) === null) {
+        throw new Error(`git read-tree failed on origin/${branch}`)
+      }
+      if (next === null) {
+        if (gitEnv(cwd, env, "update-index", "--force-remove", path) === null) {
+          throw new Error(`git update-index --force-remove failed for ${path}`)
+        }
+      } else {
+        const blob = runGit(cwd, ["hash-object", "-w", "--stdin"], { input: next })
+        const sha = blob.status === 0 ? blob.stdout : null
+        if (!sha) throw new Error("git hash-object failed")
+        if (
+          gitEnv(cwd, env, "update-index", "--add", "--cacheinfo", `100644,${sha},${path}`) === null
+        ) {
+          throw new Error(`git update-index failed for ${path}`)
+        }
+      }
+      const tree = gitEnv(cwd, env, "write-tree")
+      if (!tree) throw new Error("git write-tree failed")
+      const commit = git(cwd, "commit-tree", tree, "-p", tip, "-m", message)
+      if (!commit) {
+        throw new Error("git commit-tree failed — is git user.name/user.email configured?")
+      }
+      // The lease pins the remote ref to the tip this commit was built on:
+      // a moved branch rejects (retry below), and — the case a plain push
+      // gets dangerously wrong — a *deleted* branch rejects too, instead of
+      // being quietly re-created. A claim released mid-click must stay
+      // released; resurrecting the branch would re-lock the ticket.
+      if (
+        git(
+          cwd,
+          "push",
+          "--quiet",
+          "origin",
+          `${commit}:refs/heads/${branch}`,
+          `--force-with-lease=refs/heads/${branch}:${tip}`,
+        ) !== null
+      ) {
+        // Keep the local remote-tracking ref in step so an immediate re-read
+        // (the UI refetching the inbox) sees what was just pushed.
+        git(cwd, "update-ref", `refs/remotes/origin/${branch}`, commit)
+        return
+      }
+    } finally {
+      rmSync(index, { force: true })
+    }
+    // Push rejected — a worker moved the branch under us. Refetch and
+    // reapply once; a second rejection is contention worth surfacing.
+    if (attempt >= 1) {
+      throw new Error(
+        `origin/${branch} keeps moving — a worker is pushing; retry in a moment`,
+      )
+    }
+    fetchClaimBranch(store, branch)
+  }
+}
+
+// ── The routed operations ────────────────────────────────────────────────────
+//
+// One rule: writes about a claimed ticket's asks go where the ask's file is.
+// Resolve/reopen/delete follow the file (branch copy wins when both have it);
+// add goes to the branch, so the worker's done gate can see debt the owner
+// filed mid-claim. Unclaimed tickets — and the claim branch's own checkout —
+// stay plain local writes, uncommitted like every other CLI edit.
+
+/** How a routed write happened — `branch` set when it landed as a pushed commit. */
+export interface RoutedAsk {
+  ask: Ask
+  branch: string | null
+}
+
+export function addAskRouted(store: Store, key: string, text: string, author = ""): RoutedAsk {
+  const branch = claimFor(store, key)
+  if (!branch || onClaimBranch(store, branch)) {
+    return { ask: store.addAsk(key, text, author), branch: null }
+  }
+  const dir = askDirOnBranch(store, key)
+  if (!dir) return { ask: store.addAsk(key, text, author), branch: null }
+  const createdAt = new Date().toISOString()
+  const existing = new Set(branchAsks(store, branch, key).map((a) => a.id))
+  const stem = commentStem(createdAt, author)
+  let id = stem
+  for (let n = 2; existing.has(id); n++) id = `${stem}-${n}`
+  const doc: AskDoc = { author, createdAt, resolvedAt: null, resolvedBy: null, body: text }
+  writeOnClaimBranch(
+    store,
+    branch,
+    `${dir}/${id}.md`,
+    `chore(board): ask on ${store.displayId(key)}`,
+    // Absent → create; if a racing write took the name, keep theirs.
+    (current) => current ?? serializeAsk(doc),
+  )
+  const ask = mergedAsks(store, branch, store.get(key)!).find((a) => a.id === id)
+  if (!ask) throw new Error(`ask ${id} didn't land on ${branch} — retry`)
+  return { ask, branch }
+}
+
+export function setAskResolvedRouted(
+  store: Store,
+  key: string,
+  ref: string,
+  resolved: boolean,
+  resolvedBy = "",
+): RoutedAsk {
+  const branch = claimFor(store, key)
+  if (!branch || onClaimBranch(store, branch)) {
+    return {
+      ask: resolved ? store.resolveAsk(key, ref, resolvedBy) : store.reopenAsk(key, ref),
+      branch: null,
+    }
+  }
+  const task = store.get(key)
+  if (!task) throw new Error(`no such task: ${store.displayId(key)}`)
+  const union = mergedAsks(store, branch, task)
+  const target = findInUnion(store, key, union, ref)
+  const onBranch = branchAsks(store, branch, key).some((a) => a.id === target.id)
+  if (!onBranch) {
+    return {
+      ask: resolved
+        ? store.resolveAsk(key, target.id, resolvedBy)
+        : store.reopenAsk(key, target.id),
+      branch: null,
+    }
+  }
+  const dir = askDirOnBranch(store, key)!
+  const resolvedAt = new Date().toISOString()
+  writeOnClaimBranch(
+    store,
+    branch,
+    `${dir}/${target.id}.md`,
+    `chore(board): ${resolved ? "resolve" : "reopen"} ask [${target.ordinal}] on ${store.displayId(key)}`,
+    (current) => {
+      if (current === null) return null // deleted under us — nothing to write
+      const doc = parseAskLenient(current)
+      if (!doc) return current
+      if (resolved && doc.resolvedAt) return current // already resolved — stand down
+      if (!resolved && !doc.resolvedAt) return current
+      return serializeAsk({
+        ...doc,
+        resolvedAt: resolved ? resolvedAt : null,
+        resolvedBy: resolved ? resolvedBy : null,
+      })
+    },
+  )
+  const ask = mergedAsks(store, branch, task).find((a) => a.id === target.id)
+  return { ask: ask ?? { ...target, resolvedAt: resolved ? resolvedAt : null, resolvedBy: resolved ? resolvedBy : null }, branch }
+}
+
+export function deleteAskRouted(store: Store, key: string, ref: string): RoutedAsk {
+  const branch = claimFor(store, key)
+  if (!branch || onClaimBranch(store, branch)) {
+    return { ask: store.deleteAsk(key, ref), branch: null }
+  }
+  const task = store.get(key)
+  if (!task) throw new Error(`no such task: ${store.displayId(key)}`)
+  const union = mergedAsks(store, branch, task)
+  const target = findInUnion(store, key, union, ref)
+  const onBranch = branchAsks(store, branch, key).some((a) => a.id === target.id)
+  if (!onBranch) return { ask: store.deleteAsk(key, target.id), branch: null }
+  const dir = askDirOnBranch(store, key)!
+  writeOnClaimBranch(
+    store,
+    branch,
+    `${dir}/${target.id}.md`,
+    `chore(board): delete ask [${target.ordinal}] on ${store.displayId(key)}`,
+    () => null,
+  )
+  // The local copy of a both-sides ask goes too, or the union resurrects it.
+  if (task.asks.some((a) => a.id === target.id)) store.deleteAsk(key, target.id)
+  return { ask: target, branch }
+}
+
+/** Ordinal-or-id against the union — the numbering the inbox shows for claimed tickets. */
+function findInUnion(store: Store, key: string, union: Ask[], ref: string): Ask {
+  const trimmed = ref.trim()
+  const byOrdinal = /^\d+$/.test(trimmed)
+    ? union.find((a) => a.ordinal === Number(trimmed))
+    : undefined
+  const ask = byOrdinal ?? union.find((a) => a.id === trimmed)
+  if (!ask) {
+    const id = store.displayId(key)
+    throw new Error(
+      union.length === 0
+        ? `${id} has no asks`
+        : `no such ask on ${id}: ${ref} — ordinals run 1-${union.length} (\`task inbox\` lists them for claimed tickets)`,
+    )
+  }
+  return ask
+}