@nickmeriano/task 0.7.1 → 0.9.0

package/src/git-serve.ts

@@ -0,0 +1,595 @@
+/**
+ * The git surface behind `task serve`'s `/api/git/*` (TAS-42): status,
+ * branches, board-scoped commits, checkout, PRs, and claim release — the
+ * conductor-style layer that makes board edits (which are plain working-tree
+ * writes) visible and committable from the UI.
+ *
+ * Everything here is deliberately scoped to board files. There is no shadow
+ * branch and no auto-commit: edits keep landing in the working tree, and
+ * isolation comes from pathspec-scoped commits — `git add`/`git commit`
+ * limited to each board's `.task` directory commits board changes cleanly
+ * even when the rest of the tree is dirty.
+ *
+ * The whole surface degrades to absent: no git, no origin, or an unreadable
+ * repo means `capability()` returns null, `/api/project` omits its `git`
+ * block, and the UI renders nothing — the same self-hiding rule the hosted
+ * branch switcher follows. Spawns are the shared non-interactive, bounded
+ * ones from git.ts; like the rest of the serve path, a request must fail
+ * fast rather than wait on a human.
+ */
+
+import { spawnSync } from "node:child_process"
+import { relative, sep } from "node:path"
+import { claimBranch, claimNamespace, release } from "./claim.ts"
+import { remoteClaimTips, syncClaimRefs } from "./claim-io.ts"
+import { GIT_NETWORK_TIMEOUT_MS, defaultBase, detectRepo, git, gitOut, runGit, type RepoRef } from "./git.ts"
+import type { Store } from "./store.ts"
+
+export interface ServedBoard {
+  /** Board id as the API speaks it — path relative to the serve root, "." for the root. */
+  id: string
+  store: Store
+}
+
+/** A failure the route turns into a JSON error with this status. */
+export class GitServeError extends Error {
+  readonly status: number
+  constructor(message: string, status = 400) {
+    super(message)
+    this.status = status
+  }
+}
+
+export interface GitCapability {
+  /** GitHub identity when origin parses as one — PR affordances need it. */
+  repo: RepoRef | null
+  /** Origin's default branch, short name — the base PRs and board branches default to. */
+  defaultBranch: string
+  /** `gh` on PATH: PR creation and derived PR state; otherwise compare-URL fallback. */
+  gh: boolean
+}
+
+export interface DirtyFile {
+  board: string
+  /** Path relative to the repo toplevel — what the commit pathspec speaks. */
+  path: string
+  /** The ticket the file belongs to, when it's a ticket file. */
+  ticket: string | null
+  status: "modified" | "added" | "deleted" | "untracked"
+}
+
+export interface ClaimInfo {
+  board: string
+  ticket: string
+  branch: string
+  /** Commits on the claim branch beyond the default base — what a release discards. */
+  commits: number
+}
+
+export interface GitStatus {
+  branch: string | null
+  detached: boolean
+  defaultBranch: string
+  upstream: string | null
+  ahead: number | null
+  behind: number | null
+  dirty: DirtyFile[]
+  /** Tracked modifications outside every board dir — the "rest of the tree" count. */
+  otherDirty: number
+  claims: ClaimInfo[]
+}
+
+export interface GitBranch {
+  name: string
+  current: boolean
+  isDefault: boolean
+}
+
+interface PrRef {
+  number: number
+  url: string
+  title: string
+  state: "open" | "merged" | "closed"
+  draft: boolean
+}
+
+/** The gh-less PR fallback: GitHub's compare page, ready to open in a tab. */
+export function compareUrl(repo: RepoRef, base: string, branch: string): string {
+  return `https://github.com/${repo.owner}/${repo.repo}/compare/${encodeURIComponent(
+    base,
+  )}...${encodeURIComponent(branch)}?expand=1`
+}
+
+const GH_ENV = { GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", GH_PAGER: "cat" }
+const CLAIMS_TTL_MS = 30_000
+const PR_TTL_MS = 30_000
+
+function runGh(cwd: string, args: string[]): { status: number; stdout: string; stderr: string } {
+  const result = spawnSync("gh", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: GIT_NETWORK_TIMEOUT_MS,
+    env: { ...process.env, ...GH_ENV },
+  })
+  if (result.error) return { status: 1, stdout: "", stderr: result.error.message }
+  return {
+    status: result.status ?? 1,
+    stdout: (result.stdout ?? "").trim(),
+    stderr: (result.stderr ?? "").trim(),
+  }
+}
+
+export class GitServe {
+  private readonly root: string
+  private readonly boards: () => ServedBoard[]
+  private ghChecked: boolean | null = null
+  private claimsCache: { at: number; claims: ClaimInfo[] } | null = null
+  private readonly prCache = new Map<string, { at: number; pr: PrRef | null }>()
+
+  constructor(serveRoot: string, boards: () => ServedBoard[]) {
+    this.root = serveRoot
+    this.boards = boards
+  }
+
+  /** The repo toplevel, or null when this isn't a git checkout at all. */
+  toplevel(): string | null {
+    return gitOut(this.root, "rev-parse", "--show-toplevel")
+  }
+
+  /** Where the actual git dir lives (worktrees put it elsewhere) — for the HEAD watch. */
+  gitDir(): string | null {
+    return gitOut(this.root, "rev-parse", "--absolute-git-dir")
+  }
+
+  /**
+   * Null is the whole off-switch: not a git repo, no origin, or no resolvable
+   * default branch all mean the served UI draws no git surface at all.
+   */
+  capability(): GitCapability | null {
+    const top = this.toplevel()
+    if (!top) return null
+    if (gitOut(this.root, "remote", "get-url", "origin") === null) return null
+    let base: string
+    try {
+      base = defaultBase(this.root)
+    } catch {
+      return null
+    }
+    if (this.ghChecked === null) {
+      const gh = spawnSync("gh", ["--version"], { encoding: "utf8", timeout: 10_000 })
+      this.ghChecked = !gh.error && gh.status === 0
+    }
+    return {
+      repo: detectRepo(this.root),
+      defaultBranch: base.replace(/^origin\//, ""),
+      gh: this.ghChecked,
+    }
+  }
+
+  /**
+   * `git status --porcelain=v2` records as {kind, xy, path}. v2 on purpose,
+   * everywhere: its records are token-addressed from the record tag, so the
+   * stdout trim in runGit (which eats v1's leading space on the first line)
+   * can't shift a path by a character.
+   */
+  private porcelain(...extra: string[]): { kind: string; xy: string; path: string }[] | null {
+    const out = gitOut(this.root, "status", "--porcelain=v2", ...extra)
+    return out === null ? null : this.parseRecords(out)
+  }
+
+  private parseRecords(out: string): { kind: string; xy: string; path: string }[] {
+    const records: { kind: string; xy: string; path: string }[] = []
+    for (const line of out === "" ? [] : out.split("\n")) {
+      const kind = line[0]
+      if (kind === "?") {
+        records.push({ kind, xy: "", path: line.slice(2) })
+      } else if (kind === "1" || kind === "u") {
+        const parts = line.split(" ")
+        records.push({ kind, xy: parts[1] ?? "", path: parts.slice(kind === "1" ? 8 : 10).join(" ") })
+      } else if (kind === "2") {
+        const parts = line.split(" ")
+        records.push({ kind, xy: parts[1] ?? "", path: parts.slice(9).join(" ").split("\t")[0] })
+      }
+    }
+    return records
+  }
+
+  /** Each board's `.task` dir as a toplevel-relative posix pathspec. */
+  private boardDirs(top: string): Map<string, string> {
+    const dirs = new Map<string, string>()
+    for (const { id, store } of this.boards()) {
+      const rel = relative(top, store.taskDir).split(sep).join("/")
+      if (rel === "" || rel.startsWith("..")) continue
+      dirs.set(id, rel)
+    }
+    return dirs
+  }
+
+  status(): GitStatus {
+    const cap = this.capability()
+    const top = this.toplevel()
+    if (!cap || !top) throw new GitServeError("no git surface here", 404)
+
+    // One spawn answers branch, upstream, ahead/behind and every path:
+    // porcelain v2 with --branch headers. -uall so a freshly added ticket
+    // (untracked until its first commit) shows up as board dirt.
+    const out = gitOut(this.root, "status", "--porcelain=v2", "--branch", "-uall")
+    if (out === null) throw new GitServeError("git status failed", 500)
+
+    let branch: string | null = null
+    let upstream: string | null = null
+    let ahead: number | null = null
+    let behind: number | null = null
+    const dirty: DirtyFile[] = []
+    let otherDirty = 0
+    const dirs = this.boardDirs(top)
+
+    const classify = (path: string): { board: string; ticket: string | null } | null => {
+      for (const [board, dir] of dirs) {
+        if (path === dir || path.startsWith(`${dir}/`)) {
+          const rest = path.slice(dir.length + 1)
+          const ticket = /^(?:tickets|archive)\/([^/]+)\//.exec(rest)
+          return { board, ticket: ticket ? ticket[1] : null }
+        }
+      }
+      return null
+    }
+
+    for (const line of out === "" ? [] : out.split("\n")) {
+      if (line.startsWith("# branch.head ")) {
+        const name = line.slice("# branch.head ".length)
+        branch = name === "(detached)" ? null : name
+        continue
+      }
+      if (line.startsWith("# branch.upstream ")) {
+        upstream = line.slice("# branch.upstream ".length)
+        continue
+      }
+      if (line.startsWith("# branch.ab ")) {
+        const ab = /^# branch\.ab \+(\d+) -(\d+)$/.exec(line)
+        if (ab) {
+          ahead = Number(ab[1])
+          behind = Number(ab[2])
+        }
+        continue
+      }
+      continue
+    }
+
+    for (const { kind, xy, path } of this.parseRecords(out)) {
+      const board = classify(path)
+      if (board) {
+        const status: DirtyFile["status"] =
+          kind === "?"
+            ? "untracked"
+            : xy.includes("D")
+              ? "deleted"
+              : xy.includes("A")
+                ? "added"
+                : "modified"
+        dirty.push({ board: board.board, path, ticket: board.ticket, status })
+      } else if (kind !== "?") {
+        otherDirty++
+      }
+    }
+
+    dirty.sort((a, b) => a.path.localeCompare(b.path))
+    return {
+      branch,
+      detached: branch === null,
+      defaultBranch: cap.defaultBranch,
+      upstream,
+      ahead,
+      behind,
+      dirty,
+      otherDirty,
+      claims: this.claims(),
+    }
+  }
+
+  /**
+   * Live claims across the served boards — branch name plus the commit count
+   * a release would discard. One bounded ls-remote per board (claim-io's
+   * moved-tip-only fetch keeps the follow-up cheap), cached briefly because
+   * status refetches on every SSE tick and origin doesn't move that fast.
+   * Offline degrades to [] — no claims surface, same as the inbox's rule.
+   */
+  private claims(): ClaimInfo[] {
+    const cached = this.claimsCache
+    if (cached && Date.now() - cached.at < CLAIMS_TTL_MS) return cached.claims
+    const claims: ClaimInfo[] = []
+    for (const { id, store } of this.boards()) {
+      let namespace: string
+      try {
+        namespace = claimNamespace(store.config)
+      } catch {
+        continue
+      }
+      const tips = remoteClaimTips(store)
+      if (!tips || tips.size === 0) continue
+      syncClaimRefs(store, namespace, tips)
+      for (const task of store.list({ statuses: ["backlog", "todo", "in_progress"] })) {
+        const branch = claimBranch(store.config, task.key)
+        if (!tips.has(branch)) continue
+        const count = gitOut(
+          this.root,
+          "rev-list",
+          "--count",
+          `refs/remotes/origin/${branch}`,
+          "--not",
+          defaultBase(this.root),
+        )
+        claims.push({ board: id, ticket: task.key, branch, commits: Number(count ?? 0) })
+      }
+    }
+    this.claimsCache = { at: Date.now(), claims }
+    return claims
+  }
+
+  branches(): GitBranch[] {
+    const cap = this.capability()
+    if (!cap) throw new GitServeError("no git surface here", 404)
+    const out = gitOut(this.root, "for-each-ref", "--format=%(refname:short)", "refs/heads")
+    if (out === null) throw new GitServeError("git for-each-ref failed", 500)
+    const current = gitOut(this.root, "symbolic-ref", "--quiet", "--short", "HEAD")
+    return (out === "" ? [] : out.split("\n")).map((name) => ({
+      name,
+      current: name === current,
+      isDefault: name === cap.defaultBranch,
+    }))
+  }
+
+  /**
+   * Commit the working tree's board changes — and nothing else. `git add` and
+   * `git commit` are both pathspec-limited to the boards' `.task` dirs, so a
+   * dirty tree elsewhere (half-finished code, scratch files) neither blocks
+   * the commit nor leaks into it. With `newBranch` the commit lands on a
+   * fresh branch cut from `base` (default: wherever HEAD is now) — the
+   * default-branch flow, where board edits shouldn't land on main directly.
+   */
+  commit(body: {
+    message?: unknown
+    newBranch?: unknown
+    base?: unknown
+  }): { commit: string; branch: string | null; files: string[] } {
+    const top = this.toplevel()
+    if (!this.capability() || !top) throw new GitServeError("no git surface here", 404)
+    const message = typeof body.message === "string" ? body.message.trim() : ""
+    if (!message) throw new GitServeError("message is required")
+
+    const dirs = [...this.boardDirs(top).values()]
+    if (dirs.length === 0) throw new GitServeError("no board directories inside this repository")
+    const records = this.porcelain("-uall", "--", ...dirs)
+    if (records === null) throw new GitServeError("git status failed", 500)
+    if (records.length === 0) {
+      throw new GitServeError("nothing to commit — no board files have changed")
+    }
+    const files = records.map((r) => r.path)
+
+    if (body.newBranch !== undefined) {
+      const name = typeof body.newBranch === "string" ? body.newBranch.trim() : ""
+      if (!name || runGit(this.root, ["check-ref-format", "--branch", name]).status !== 0) {
+        throw new GitServeError(`not a valid branch name: ${String(body.newBranch)}`)
+      }
+      if (git(this.root, "show-ref", "--verify", "--quiet", `refs/heads/${name}`).status === 0) {
+        throw new GitServeError(`branch ${name} already exists`)
+      }
+      const base = typeof body.base === "string" && body.base.trim() !== "" ? body.base.trim() : null
+      if (base && gitOut(this.root, "rev-parse", "--verify", "--quiet", `${base}^{commit}`) === null) {
+        throw new GitServeError(`base not found: ${base}`)
+      }
+      const created = runGit(this.root, ["checkout", "--quiet", "-b", name, ...(base ? [base] : [])])
+      if (created.status !== 0) {
+        throw new GitServeError(`couldn't create ${name}: ${created.stderr || created.stdout}`)
+      }
+    }
+
+    const add = runGit(this.root, ["add", "-A", "--", ...dirs])
+    if (add.status !== 0) throw new GitServeError(`git add failed: ${add.stderr}`, 500)
+    const commit = runGit(this.root, ["commit", "--quiet", "-m", message, "--", ...dirs])
+    if (commit.status !== 0) {
+      throw new GitServeError(`git commit failed: ${commit.stderr || commit.stdout}`, 500)
+    }
+    return {
+      commit: gitOut(this.root, "rev-parse", "HEAD") ?? "",
+      branch: gitOut(this.root, "symbolic-ref", "--quiet", "--short", "HEAD"),
+      files,
+    }
+  }
+
+  /**
+   * Switch branches — refused while tracked files outside the board dirs are
+   * dirty. No stashing magic: board dirt rides along (that's the working
+   * style this whole surface supports), but half-finished code does not get
+   * silently carried onto another branch by a click in a board UI.
+   */
+  checkout(body: { branch?: unknown }): { branch: string } {
+    const top = this.toplevel()
+    if (!this.capability() || !top) throw new GitServeError("no git surface here", 404)
+    const branch = typeof body.branch === "string" ? body.branch.trim() : ""
+    if (!branch) throw new GitServeError("branch is required")
+    if (git(this.root, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`).status !== 0) {
+      throw new GitServeError(`no local branch named ${branch}`)
+    }
+    const tracked = this.porcelain("-uno")
+    if (tracked === null) throw new GitServeError("git status failed", 500)
+    const dirs = [...this.boardDirs(top).values()]
+    const outside = tracked
+      .map((r) => r.path)
+      .filter((p) => !dirs.some((d) => p === d || p.startsWith(`${d}/`)))
+    if (outside.length > 0) {
+      const shown = outside.slice(0, 3).join(", ")
+      throw new GitServeError(
+        `${outside.length} file${outside.length === 1 ? " has" : "s have"} uncommitted changes outside the board (${shown}${outside.length > 3 ? ", …" : ""}) — commit or stash them in a terminal first; switching under them from here would be a surprise`,
+        409,
+      )
+    }
+    const result = runGit(this.root, ["checkout", "--quiet", branch])
+    if (result.status !== 0) {
+      throw new GitServeError(`git checkout failed: ${result.stderr || result.stdout}`)
+    }
+    return { branch }
+  }
+
+  /**
+   * Open a PR for a branch: push it, then `gh pr create` when gh is here —
+   * falling back to the GitHub compare URL for the UI to open when it isn't.
+   * On a created PR the URL is written into the `prs:` frontmatter of every
+   * ticket whose files the branch touches: files remember, git informs.
+   */
+  pr(body: {
+    branch?: unknown
+    base?: unknown
+    title?: unknown
+    body?: unknown
+    draft?: unknown
+  }): { url: string; created: boolean; tickets: string[] } {
+    const cap = this.capability()
+    const top = this.toplevel()
+    if (!cap || !top) throw new GitServeError("no git surface here", 404)
+    const current = gitOut(this.root, "symbolic-ref", "--quiet", "--short", "HEAD")
+    const branch = typeof body.branch === "string" && body.branch.trim() ? body.branch.trim() : current
+    if (!branch) throw new GitServeError("no branch to open a PR for — HEAD is detached")
+    const base = typeof body.base === "string" && body.base.trim() ? body.base.trim() : cap.defaultBranch
+    if (branch === base) throw new GitServeError(`${branch} is the base branch — nothing to open`)
+    // No way to end in a PR (or even a compare page)? Say so before pushing.
+    if (!cap.gh && !cap.repo) {
+      throw new GitServeError("origin isn't a GitHub remote and gh isn't installed — open the PR by hand", 501)
+    }
+
+    const push = runGit(this.root, ["push", "--quiet", "-u", "origin", branch], {
+      timeoutMs: GIT_NETWORK_TIMEOUT_MS,
+    })
+    if (push.status !== 0) {
+      throw new GitServeError(`push of ${branch} failed: ${push.stderr || push.stdout}`, 502)
+    }
+
+    if (!cap.gh) {
+      return { url: compareUrl(cap.repo!, base, branch), created: false, tickets: [] }
+    }
+
+    const title = typeof body.title === "string" && body.title.trim() ? body.title.trim() : branch
+    const description = typeof body.body === "string" ? body.body : ""
+    const args = ["pr", "create", "--head", branch, "--base", base, "--title", title, "--body", description]
+    if (body.draft === true) args.push("--draft")
+    const created = runGh(this.root, args)
+    if (created.status !== 0) {
+      throw new GitServeError(`gh pr create failed: ${created.stderr || created.stdout}`, 502)
+    }
+    const url = /https:\/\/\S+\/pull\/\d+/.exec(created.stdout)?.[0] ?? created.stdout
+    this.prCache.delete(branch)
+    return { url, created: true, tickets: this.attachPrUrl(top, branch, base, url) }
+  }
+
+  /** Append `url` to the prs: of every ticket the branch's commits touch. */
+  private attachPrUrl(top: string, branch: string, base: string, url: string): string[] {
+    const baseRef =
+      gitOut(this.root, "rev-parse", "--verify", "--quiet", `origin/${base}^{commit}`) !== null
+        ? `origin/${base}`
+        : base
+    const diff = gitOut(this.root, "diff", "--name-only", `${baseRef}...${branch}`)
+    if (diff === null || diff === "") return []
+    const dirs = this.boardDirs(top)
+    const stores = new Map(this.boards().map((b) => [b.id, b.store]))
+    const attached: string[] = []
+    const seen = new Set<string>()
+    for (const path of diff.split("\n")) {
+      for (const [board, dir] of dirs) {
+        if (!path.startsWith(`${dir}/`)) continue
+        const ticket = /^tickets\/([^/]+)\//.exec(path.slice(dir.length + 1))
+        if (!ticket) continue
+        const ticketKey = ticket[1]
+        const seenKey = `${board}:${ticketKey}`
+        if (seen.has(seenKey)) continue
+        seen.add(seenKey)
+        const store = stores.get(board)
+        const task = store?.get(ticketKey)
+        if (!store || !task || task.prs.includes(url)) continue
+        try {
+          store.update(ticketKey, { prs: [...task.prs, url] })
+          attached.push(task.id)
+        } catch {
+          // A refused update (archived, gone) must not fail the PR that exists.
+        }
+      }
+    }
+    return attached
+  }
+
+  /** Derived, display-only PR state for a branch — gh only, briefly cached. */
+  prFor(branch: string): { pr: PrRef | null } {
+    const cap = this.capability()
+    if (!cap) throw new GitServeError("no git surface here", 404)
+    if (!cap.gh) return { pr: null }
+    const cached = this.prCache.get(branch)
+    if (cached && Date.now() - cached.at < PR_TTL_MS) return { pr: cached.pr }
+    const out = runGh(this.root, [
+      "pr",
+      "list",
+      "--head",
+      branch,
+      "--state",
+      "all",
+      "--json",
+      "number,url,title,state,isDraft",
+      "--limit",
+      "10",
+    ])
+    let pr: PrRef | null = null
+    if (out.status === 0) {
+      try {
+        const rows = JSON.parse(out.stdout) as {
+          number: number
+          url: string
+          title: string
+          state: string
+          isDraft: boolean
+        }[]
+        const pick =
+          rows.find((r) => r.state === "OPEN") ??
+          rows.find((r) => r.state === "MERGED") ??
+          rows[0] ??
+          null
+        if (pick) {
+          pr = {
+            number: pick.number,
+            url: pick.url,
+            title: pick.title,
+            state: pick.state.toLowerCase() as PrRef["state"],
+            draft: pick.isDraft,
+          }
+        }
+      } catch {
+        pr = null
+      }
+    }
+    this.prCache.set(branch, { at: Date.now(), pr })
+    return { pr }
+  }
+
+  /**
+   * The drag-to-release flow's server half (TAS-26): abandon a ticket's claim
+   * exactly like `task claim --release` — delete the branch on origin and
+   * locally — so the caller can then apply the move as a plain file edit.
+   * Fails whole: if the branch can't be deleted (offline, no push access),
+   * the claim stands and the caller moves nothing.
+   */
+  releaseClaim(
+    store: Store,
+    body: { key?: unknown; note?: unknown },
+    author: string,
+  ): { branch: string } {
+    if (!this.capability()) throw new GitServeError("no git surface here", 404)
+    const key = typeof body.key === "string" ? body.key.trim() : ""
+    if (!key) throw new GitServeError("key is required")
+    const result = release(store, key)
+    this.claimsCache = null
+    const note = typeof body.note === "string" ? body.note.trim() : ""
+    store.addComment(
+      key,
+      note || "Released the claim from the board — the branch and its commits are gone.",
+      author,
+    )
+    return { branch: result.branch }
+  }
+}