Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

12.9 KB
Raw Blame
import { computeWorktreePath, type WorktreeEntry } from './worktree'
import { normWorktreePath } from './worktree-reconcile'
import { sharedWorktreeLocationRefusal } from './worktree-location'

// "Start with agent in a new worktree" on a GitHub issue card: the branch it creates, and what it
// does when that branch (or its folder) is already taken.
//
// The branch is named from the issue NUMBER and a slug of its TITLE, and the title is attacker-
// controlled: anyone can open an issue on a public repository and put whatever they like in it. So
// the slug is an ALLOWLIST (`[a-z0-9-]`, nothing else survives), it is capped, and the result never
// travels through a shell — it reaches git as one argv element (`worktree-ops.worktreeAdd`, which
// also refuses a leading `-`). A branch built here always passes `git check-ref-format --branch`:
// the alphabet has no `.`, `@`, `/`, `~`, `^`, `:`, `?`, `*`, `[`, `\`, space or control byte, and
// every name starts with the literal `issue-` (`issue-worktree.test.ts` runs the real git over the
// hostile cases).
//
// What is already on disk is never overwritten. An existing worktree for the same issue is offered
// for REUSE; a name or folder that is merely taken moves to the next free `-2`, `-3`, … suffix.

/** The longest slug a branch carries. Long enough to read, short enough for a path segment and a
 *  group chip. */
export const ISSUE_BRANCH_SLUG_MAX = 40

/** How many `-k` suffixes the planner tries before it gives up (a folder of 20 attempts for one
 *  issue is a mess a person should look at, not one the app should keep extending). */
export const ISSUE_BRANCH_SUFFIX_MAX = 20

/** Bounds the work a hostile 1 MB title can cause before the cap applies. */
const TITLE_SCAN_MAX = 1000

const MAX_ISSUE_NUMBER = 2 ** 31 - 1

function validNumber(value: unknown): value is number {
  return (
    typeof value === 'number' && Number.isSafeInteger(value) && value >= 1 && value <= MAX_ISSUE_NUMBER
  )
}

/**
 * The title as a branch slug: lower-case ASCII letters and digits, runs of anything else collapsed
 * to one `-`, trimmed, capped at {@link ISSUE_BRANCH_SLUG_MAX} (cut back to a word boundary when the
 * cap lands mid-word). Accented Latin keeps its base letter (`café` → `cafe`); every other script,
 * emoji, lookalike, bidi or zero-width character is dropped. `''` when nothing survives — the
 * caller then names the branch `issue-<N>` alone.
 */
export function issueBranchSlug(title: unknown): string {
  if (typeof title !== 'string') return ''
  // Lower-case BEFORE decomposing: `İ`.toLowerCase() is `i` + a combining dot, which the mark strip
  // below must see.
  const folded = title
    .slice(0, TITLE_SCAN_MAX)
    .toLowerCase()
    .normalize('NFKD')
    .replace(/\p{M}+/gu, '')
  let slug = folded.replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
  if (slug.length > ISSUE_BRANCH_SLUG_MAX) {
    const cut = slug.slice(0, ISSUE_BRANCH_SLUG_MAX)
    // Mid-word? Back up to the last separator, as long as that keeps at least half the budget.
    const midWord = slug[ISSUE_BRANCH_SLUG_MAX] !== '-'
    const lastDash = cut.lastIndexOf('-')
    slug = midWord && lastDash >= ISSUE_BRANCH_SLUG_MAX / 2 ? cut.slice(0, lastDash) : cut
    slug = slug.replace(/-+$/g, '')
  }
  return slug
}

/**
 * `issue-<N>-<slug>` (or `issue-<N>` when the title leaves no slug), with `-<suffix>` appended for
 * a suffix of 2 or more. `''` for a number that is not a real issue number.
 */
export function issueWorktreeBranch(number: unknown, title?: unknown, suffix = 1): string {
  if (!validNumber(number)) return ''
  const slug = issueBranchSlug(title)
  const base = slug ? `issue-${number}-${slug}` : `issue-${number}`
  return Number.isSafeInteger(suffix) && suffix >= 2 ? `${base}-${suffix}` : base
}

/** Is this branch one of the issue's own (`issue-<N>` or `issue-<N>-…`)? `issue-12` is not
 *  `issue-123`'s. Case-insensitive: a hand-made `Issue-12-x` is still that issue's. */
export function isIssueBranch(branch: unknown, number: number): boolean {
  if (typeof branch !== 'string' || !validNumber(number)) return false
  const b = branch.toLowerCase()
  return b === `issue-${number}` || b.startsWith(`issue-${number}-`)
}

/** Where a new worktree would go. */
export interface IssueWorktreeTarget {
  branch: string
  path: string
}

/** A worktree group frame on the canvas, and the branch it is bound to (stale frames excluded by
 *  the caller: a directory that is gone is nothing to reuse). */
export interface IssueWorktreeBoundGroup {
  groupId: string
  branch: string
  path: string
}

/** Something already on disk (or on the canvas) the user may want to reuse for this issue. */
export type IssueWorktreeExisting =
  /** A worktree for this issue that a group frame on this canvas is already bound to: reuse = open
   *  the agent in that frame. */
  | { kind: 'bound'; groupId: string; branch: string; path: string }
  /** A worktree for this issue on disk that no frame is bound to: reuse = adopt it (never deleted by
   *  Remove, because the app did not create it). */
  | { kind: 'orphan'; branch: string; path: string; entry: WorktreeEntry }
  /** The branch the app would create exists, but is checked out nowhere: reuse = check THAT branch
   *  out in a new worktree at `path`. */
  | { kind: 'branch'; branch: string; path: string }

export type IssueWorktreePlan =
  | { kind: 'refused'; reason: string }
  /** Nothing in the way (or only a name/folder that is merely taken — `renamedFrom` then names the
   *  branch that was wanted, so the caller can say why the new one ends in `-2`). */
  | { kind: 'create'; target: IssueWorktreeTarget; renamedFrom?: string }
  /** An existing worktree/branch for this issue: the person picks reuse or `alternative` (null when
   *  no free name was found within {@link ISSUE_BRANCH_SUFFIX_MAX} attempts). */
  | { kind: 'choose'; existing: IssueWorktreeExisting; alternative: IssueWorktreeTarget | null }

export interface IssueWorktreeInput {
  number: number
  /** The issue title — hostile input, only ever slugged. */
  title: unknown
  repoRoot: string
  /** The effective path template (`effectiveWorktreeTemplate`). */
  template: string
  /** `git worktree list` in git's order: the MAIN checkout is first. */
  entries: readonly WorktreeEntry[]
  /** Local branch names; null or empty when they could not be read (git then has the last word). */
  branches: readonly string[] | null
  /**
   * Remote-tracking branches as git lists them (`origin/issue-12-fix`). A name that exists on a
   * remote is TAKEN: creating a same-named local branch from the base would diverge from it, the
   * later push would be rejected, and a pull request from that remote branch — someone else's — would
   * share this session's branch name. The planner moves to `-k` rather than basing on it: starting
   * an agent on another person's branch is not what "start in a NEW worktree" asks for. Only as
   * fresh as the last fetch.
   */
  remoteBranches?: readonly string[]
  /** `worktree.basePath` — ONLY when it came from the git-shared settings file (see
   *  @shared/worktree-location): the location it produces must pass `sharedWorktreeLocationRefusal`. */
  sharedBasePath?: string
  /** Non-stale worktree-bound group frames on this canvas. */
  bound: readonly IssueWorktreeBoundGroup[]
}

/** Does anything live at this path? A probe that REJECTS reads as "yes": a failed read is never
 *  evidence of absence, and the cost of the wrong answer is only a `-2`. (A probe that folds a stat
 *  error into `false` — the app's `fs.exists` does — is backstopped by git, which refuses to add a
 *  worktree into a folder that is not empty.) */
export type PathProbe = (path: string) => Promise<boolean>

/**
 * Decide what "Start with agent in a new worktree" does for this issue. Reads the filesystem only
 * through `pathExists`, so the whole matrix is testable without a repository.
 */
export async function planIssueWorktree(
  input: IssueWorktreeInput,
  pathExists: PathProbe
): Promise<IssueWorktreePlan> {
  const canonical = issueWorktreeBranch(input.number, input.title)
  if (!canonical) return { kind: 'refused', reason: 'That is not a valid issue number.' }
  const repoRoot = input.repoRoot.trim()
  if (!repoRoot) return { kind: 'refused', reason: 'No git repository was found in this project’s folder.' }
  const pathFor = (branch: string): string => computeWorktreePath(repoRoot, branch, input.template)
  if (!pathFor(canonical)) {
    return {
      kind: 'refused',
      reason: 'No worktree location could be derived from the worktree path setting. Nothing was created.'
    }
  }
  // Every candidate (`-k` included) lives in the same folder, so one check on the wanted name
  // judges them all — before anything else is planned.
  const location = sharedWorktreeLocationRefusal({
    path: pathFor(canonical),
    repoRoot,
    branch: canonical,
    sharedBasePath: input.sharedBasePath
  })
  if (location) return { kind: 'refused', reason: location }

  const known = new Set<string>()
  for (const b of input.branches ?? []) known.add(b.toLowerCase())
  for (const e of input.entries) if (e.branch) known.add(e.branch.toLowerCase())
  // A frame's binding counts too: `entries` may be a failed (empty) read, and a bound branch or
  // folder is taken whatever git managed to list.
  for (const g of input.bound) known.add(g.branch.toLowerCase())
  for (const r of input.remoteBranches ?? []) {
    const slash = r.indexOf('/')
    if (slash > 0 && slash < r.length - 1) known.add(r.slice(slash + 1).toLowerCase())
  }
  // Every name this module builds is lower-case already; `known` is folded on the way in.
  const branchTaken = (b: string): boolean => known.has(b)
  const entryPaths = new Set(
    [...input.entries.map((e) => e.path), ...input.bound.map((g) => g.path)].map(normWorktreePath)
  )
  const pathTaken = async (p: string): Promise<boolean> => {
    if (entryPaths.has(normWorktreePath(p))) return true
    return pathExists(p).catch(() => true)
  }
  /** The first `base`, `base-2`, `base-3`, … whose branch AND folder are both free. */
  const firstFree = async (fromSuffix: number): Promise<IssueWorktreeTarget | null> => {
    for (let k = fromSuffix; k <= ISSUE_BRANCH_SUFFIX_MAX; k++) {
      const branch = issueWorktreeBranch(input.number, input.title, k)
      if (branchTaken(branch)) continue
      const path = pathFor(branch)
      if (!path || (await pathTaken(path))) continue
      return { branch, path }
    }
    return null
  }

  // 1. A worktree this issue already has. A frame bound to it beats an unbound one (that is where
  //    the issue's other sessions already are), and the exact name beats a sibling of it.
  const byName = <T extends { branch: string }>(xs: T[]): T | undefined =>
    xs.find((x) => x.branch.toLowerCase() === canonical) ?? xs[0]
  const boundHere = input.bound.filter((g) => isIssueBranch(g.branch, input.number))
  const boundPaths = new Set(input.bound.map((g) => normWorktreePath(g.path)))
  const orphans = input.entries
    .slice(1) // the main checkout is never "a worktree to reuse"
    .filter((e) => !e.isBare && !e.prunable && e.branch && isIssueBranch(e.branch, input.number))
    .filter((e) => !boundPaths.has(normWorktreePath(e.path)))
    .map((e) => ({ branch: e.branch as string, path: e.path, entry: e }))
  const bound = byName(boundHere)
  const orphan = bound ? undefined : byName(orphans)
  if (bound || orphan) {
    const existing: IssueWorktreeExisting = bound
      ? { kind: 'bound', groupId: bound.groupId, branch: bound.branch, path: bound.path }
      : { kind: 'orphan', branch: orphan!.branch, path: orphan!.path, entry: orphan!.entry }
    return { kind: 'choose', existing, alternative: await firstFree(1) }
  }

  // 2. The branch exists but is checked out NOWHERE: offer to check it out. (Checked out somewhere
  //    — the main checkout, or a registration whose folder is gone — it cannot be, so it is simply
  //    taken, and case 3 moves on to `-2`.)
  //    The branch is offered under ITS OWN spelling: `known` is case-folded, but git resolves the
  //    name it is given, and `issue-12-x` does not name a local `Issue-12-X` on a case-sensitive
  //    filesystem or in packed refs.
  const checkedOut = input.entries.some((e) => e.branch?.toLowerCase() === canonical)
  const existingBranch = (input.branches ?? []).find((b) => b.toLowerCase() === canonical)
  if (existingBranch && !checkedOut) {
    const path = pathFor(canonical)
    if (!(await pathTaken(path))) {
      return {
        kind: 'choose',
        existing: { kind: 'branch', branch: existingBranch, path },
        alternative: await firstFree(2)
      }
    }
  }

  // 3. A fresh worktree — under the wanted name when it is free, else the next free suffix.
  const target = await firstFree(1)
  if (!target) {
    return {
      kind: 'refused',
      reason: `Every name from ${canonical} to ${canonical}-${ISSUE_BRANCH_SUFFIX_MAX} is taken. Nothing was created.`
    }
  }
  return target.branch === canonical ? { kind: 'create', target } : { kind: 'create', target, renamedFrom: canonical }
}