@doccy/fell 0.1.0

package/lib/git.ts

@@ -0,0 +1,372 @@
+/**
+ * Git and GitHub CLI operations for worktree management.
+ * Uses Bun's native $ shell API for all subprocess calls.
+ */
+
+import { $ } from "bun"
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface Worktree {
+  path: string
+  head: string
+  branch: string | null
+  isBare: boolean
+  isMain: boolean
+  isLocked: boolean
+  lockReason: string | null
+  isPrunable: boolean
+  prunableReason: string | null
+  isDetached: boolean
+}
+
+export interface PrInfo {
+  number: number
+  state: "OPEN" | "CLOSED" | "MERGED"
+  url: string
+  title: string
+}
+
+export type PrStatus =
+  | { type: "loading" }
+  | { type: "found"; pr: PrInfo }
+  | { type: "none" }
+  | { type: "error"; message: string }
+  | { type: "skipped" }
+
+export interface FileStatus {
+  /** Staged files (added/modified/deleted in index) */
+  staged: number
+  /** Unstaged modifications to tracked files */
+  modified: number
+  /** Untracked files */
+  untracked: number
+  /** Commits ahead of remote tracking branch */
+  ahead: number
+  /** Commits behind remote tracking branch */
+  behind: number
+}
+
+export type FileStatusResult =
+  | { type: "loading" }
+  | { type: "clean" }
+  | { type: "dirty"; status: FileStatus }
+  | { type: "error" }
+
+/** Diagnostic result from checking gh CLI availability. */
+export type GhDiagnostic =
+  | { type: "checking" }
+  | { type: "available" }
+  | { type: "not-installed" }
+  | { type: "not-authenticated"; detail: string }
+
+// ---------------------------------------------------------------------------
+// Worktree operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse `git worktree list --porcelain` into structured data.
+ * The first entry is always the main worktree.
+ */
+export async function listWorktrees(): Promise<Worktree[]> {
+  const result = await $`git worktree list --porcelain`.nothrow().quiet()
+  if (result.exitCode !== 0) return []
+
+  const stdout = result.stdout.toString()
+  const blocks = stdout.trim().split("\n\n")
+  const worktrees: Worktree[] = []
+
+  for (const block of blocks) {
+    const lines = block.trim().split("\n")
+    let path = ""
+    let head = ""
+    let branch: string | null = null
+    let isBare = false
+    let isDetached = false
+    let isLocked = false
+    let lockReason: string | null = null
+    let isPrunable = false
+    let prunableReason: string | null = null
+
+    for (const line of lines) {
+      if (line.startsWith("worktree ")) path = line.slice(9)
+      else if (line.startsWith("HEAD ")) head = line.slice(5)
+      else if (line.startsWith("branch "))
+        branch = line.slice(7).replace("refs/heads/", "")
+      else if (line === "bare") isBare = true
+      else if (line === "detached") isDetached = true
+      else if (line === "locked") isLocked = true
+      else if (line.startsWith("locked ")) {
+        isLocked = true
+        lockReason = line.slice(7)
+      } else if (line === "prunable") isPrunable = true
+      else if (line.startsWith("prunable ")) {
+        isPrunable = true
+        prunableReason = line.slice(9)
+      }
+    }
+
+    if (path) {
+      worktrees.push({
+        path,
+        head,
+        branch,
+        isBare,
+        isMain: worktrees.length === 0,
+        isLocked,
+        lockReason,
+        isPrunable,
+        prunableReason,
+        isDetached,
+      })
+    }
+  }
+
+  return worktrees
+}
+
+/**
+ * Remove a worktree directory and its git administrative tracking.
+ * Use force when the worktree has uncommitted changes.
+ */
+export async function removeWorktree(
+  path: string,
+  force = false,
+): Promise<{ ok: boolean; error?: string }> {
+  const flags = force ? ["--force"] : []
+  const result = await $`git worktree remove ${flags} ${path}`.nothrow().quiet()
+  if (result.exitCode !== 0) {
+    return { ok: false, error: result.stderr.toString().trim() }
+  }
+  return { ok: true }
+}
+
+/**
+ * Dry-run prune to show what stale references would be cleaned.
+ * Returns human-readable descriptions of each stale entry.
+ */
+export async function pruneWorktreesDryRun(): Promise<string[]> {
+  const result = await $`git worktree prune --dry-run -v`.nothrow().quiet()
+  return result.stdout.toString().trim().split("\n").filter(Boolean)
+}
+
+/** Actually prune stale worktree references. */
+export async function pruneWorktrees(): Promise<{
+  ok: boolean
+  error?: string
+}> {
+  const result = await $`git worktree prune`.nothrow().quiet()
+  if (result.exitCode !== 0) {
+    return { ok: false, error: result.stderr.toString().trim() }
+  }
+  return { ok: true }
+}
+
+/**
+ * Delete a local git branch.
+ * Force (-D) deletes even when not fully merged.
+ */
+export async function deleteBranch(
+  name: string,
+  force = false,
+): Promise<{ ok: boolean; error?: string }> {
+  const flag = force ? "-D" : "-d"
+  const result = await $`git branch ${flag} ${name}`.nothrow().quiet()
+  if (result.exitCode !== 0) {
+    return { ok: false, error: result.stderr.toString().trim() }
+  }
+  return { ok: true }
+}
+
+// ---------------------------------------------------------------------------
+// File status (per-worktree)
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the working tree status for a specific worktree path.
+ * Uses `git -C <path> status --porcelain=v2 --branch` to parse
+ * staged, modified, untracked counts and ahead/behind info.
+ */
+export async function fetchWorktreeFileStatus(
+  worktreePath: string,
+): Promise<FileStatusResult> {
+  const result =
+    await $`git -C ${worktreePath} status --porcelain=v2 --branch`
+      .nothrow()
+      .quiet()
+
+  if (result.exitCode !== 0) return { type: "error" }
+
+  const stdout = result.stdout.toString()
+  let staged = 0
+  let modified = 0
+  let untracked = 0
+  let ahead = 0
+  let behind = 0
+
+  for (const line of stdout.split("\n")) {
+    if (line.startsWith("# branch.ab ")) {
+      // Format: "# branch.ab +N -M"
+      const match = line.match(/\+(\d+) -(\d+)/)
+      if (match) {
+        ahead = parseInt(match[1], 10)
+        behind = parseInt(match[2], 10)
+      }
+    } else if (line.startsWith("1 ") || line.startsWith("2 ")) {
+      // Ordinary/rename entries: XY field is chars 2-3
+      const xy = line.slice(2, 4)
+      const indexStatus = xy[0]
+      const worktreeStatus = xy[1]
+      if (indexStatus !== ".") staged++
+      if (worktreeStatus !== ".") modified++
+    } else if (line.startsWith("u ")) {
+      // Unmerged entry - count as modified
+      modified++
+    } else if (line.startsWith("? ")) {
+      untracked++
+    }
+  }
+
+  const isDirty = staged + modified + untracked + ahead + behind > 0
+  if (!isDirty) return { type: "clean" }
+
+  return {
+    type: "dirty",
+    status: { staged, modified, untracked, ahead, behind },
+  }
+}
+
+/** A single file entry from git status with its change type. */
+export interface FileEntry {
+  path: string
+  status: "staged" | "modified" | "untracked" | "unmerged"
+}
+
+/**
+ * Get the list of changed files in a worktree.
+ * Returns individual file paths with their status category.
+ */
+export async function fetchWorktreeFileList(
+  worktreePath: string,
+): Promise<FileEntry[]> {
+  const result =
+    await $`git -C ${worktreePath} status --porcelain=v2 --branch`
+      .nothrow()
+      .quiet()
+
+  if (result.exitCode !== 0) return []
+
+  const entries: FileEntry[] = []
+
+  for (const line of result.stdout.toString().split("\n")) {
+    if (line.startsWith("1 ")) {
+      // Ordinary entry: "1 XY sub mH mI mW hH hI path"
+      const xy = line.slice(2, 4)
+      const path = line.split("\t")[0]?.split(" ").pop() ?? line.slice(113)
+      // Parse path from the fixed-width porcelain v2 format
+      const parts = line.split(" ")
+      const filePath = parts.slice(8).join(" ")
+      if (xy[0] !== ".") entries.push({ path: filePath, status: "staged" })
+      else if (xy[1] !== ".") entries.push({ path: filePath, status: "modified" })
+    } else if (line.startsWith("2 ")) {
+      // Rename entry: "2 XY sub mH mI mW hH hI X\tscore\tpath\torigPath"
+      const tabParts = line.split("\t")
+      const filePath = tabParts[1] ?? ""
+      entries.push({ path: filePath, status: "staged" })
+    } else if (line.startsWith("u ")) {
+      // Unmerged: "u XY sub m1 m2 m3 mW h1 h2 h3 path"
+      const parts = line.split(" ")
+      entries.push({ path: parts.slice(10).join(" "), status: "unmerged" })
+    } else if (line.startsWith("? ")) {
+      entries.push({ path: line.slice(2), status: "untracked" })
+    }
+  }
+
+  return entries
+}
+
+/**
+ * Open a directory in the system file manager.
+ * macOS: Finder, Linux: xdg-open, Windows: explorer.
+ */
+export async function openDirectory(path: string): Promise<void> {
+  const platform = process.platform
+  if (platform === "darwin") {
+    await $`open ${path}`.nothrow().quiet()
+  } else if (platform === "win32") {
+    await $`explorer ${path}`.nothrow().quiet()
+  } else {
+    await $`xdg-open ${path}`.nothrow().quiet()
+  }
+}
+
+// ---------------------------------------------------------------------------
+// GitHub CLI diagnostics
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine the availability of the `gh` CLI.
+ * Uses `Bun.which` to check the binary exists on PATH, then
+ * attempts a lightweight repo query to verify auth/repo access.
+ */
+export async function checkGhStatus(): Promise<GhDiagnostic> {
+  // Fast path: check if the binary is on PATH at all
+  if (!Bun.which("gh")) {
+    return { type: "not-installed" }
+  }
+
+  // Binary exists - verify it can actually query this repo (auth + repo context)
+  const result = await $`gh repo view --json name`.nothrow().quiet()
+  if (result.exitCode === 0) {
+    return { type: "available" }
+  }
+
+  const stderr = result.stderr.toString()
+  return {
+    type: "not-authenticated",
+    detail: stderr.trim().split("\n")[0] ?? "unknown error",
+  }
+}
+
+// ---------------------------------------------------------------------------
+// GitHub PR lookups
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch the most recent PR for a branch via `gh` CLI.
+ * Returns null when no PR exists or gh is unavailable.
+ */
+export async function fetchPrForBranch(
+  branch: string,
+): Promise<PrInfo | null> {
+  const result =
+    await $`gh pr list --head ${branch} --state all --json number,state,url,title --limit 5`
+      .nothrow()
+      .quiet()
+
+  if (result.exitCode !== 0) return null
+
+  try {
+    const prs = JSON.parse(result.stdout.toString()) as Array<{
+      number: number
+      state: string
+      url: string
+      title: string
+    }>
+    if (prs.length === 0) return null
+
+    // Most recent PR first
+    prs.sort((a, b) => b.number - a.number)
+    const pr = prs[0]
+    return {
+      number: pr.number,
+      state: pr.state as PrInfo["state"],
+      url: pr.url,
+      title: pr.title,
+    }
+  } catch {
+    return null
+  }
+}

package/lib/tui.ts

@@ -0,0 +1,286 @@
+/**
+ * Terminal UI primitives for fell.
+ * Stateless helpers: ANSI colours, key parsing, text formatting,
+ * and the help screen content.
+ */
+
+import type { PrStatus, FileStatusResult } from "./git"
+
+// ---------------------------------------------------------------------------
+// ANSI escape helpers
+// ---------------------------------------------------------------------------
+
+const ESC = "\x1b"
+const CSI = `${ESC}[`
+
+/** Colour/style wrappers using standard ANSI escape codes. */
+export const c = {
+  dim: (s: string) => `${CSI}2m${s}${CSI}0m`,
+  bold: (s: string) => `${CSI}1m${s}${CSI}0m`,
+  italic: (s: string) => `${CSI}3m${s}${CSI}0m`,
+  underline: (s: string) => `${CSI}4m${s}${CSI}0m`,
+  inverse: (s: string) => `${CSI}7m${s}${CSI}0m`,
+  cyan: (s: string) => `${CSI}36m${s}${CSI}0m`,
+  green: (s: string) => `${CSI}32m${s}${CSI}0m`,
+  red: (s: string) => `${CSI}31m${s}${CSI}0m`,
+  yellow: (s: string) => `${CSI}33m${s}${CSI}0m`,
+  magenta: (s: string) => `${CSI}35m${s}${CSI}0m`,
+  white: (s: string) => `${CSI}37m${s}${CSI}0m`,
+  lime: (s: string) => `${CSI}38;5;154m${s}${CSI}0m`,
+} as const
+
+export const SPINNER_FRAMES = [
+  "\u28CB", "\u28D9", "\u28F9", "\u28F8", "\u28FC", "\u28F4",
+  "\u28E6", "\u28E7", "\u28C7", "\u28CF",
+] as const
+
+// ---------------------------------------------------------------------------
+// Terminal control
+// ---------------------------------------------------------------------------
+
+export const term = {
+  enterAltScreen: () => process.stdout.write(`${CSI}?1049h`),
+  exitAltScreen: () => process.stdout.write(`${CSI}?1049l`),
+  hideCursor: () => process.stdout.write(`${CSI}?25l`),
+  showCursor: () => process.stdout.write(`${CSI}?25h`),
+  home: () => process.stdout.write(`${CSI}H`),
+  clearBelow: () => process.stdout.write(`${CSI}J`),
+  clearScreen: () => process.stdout.write(`${CSI}2J`),
+  /** Erase from cursor to end of line - append to each line to prevent ghost chars. */
+  EL: `${CSI}K`,
+}
+
+// ---------------------------------------------------------------------------
+// Text utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * OSC 8 hyperlink - clickable in iTerm2, Kitty, WezTerm, etc.
+ * Terminals that don't support it simply render the text.
+ */
+export function hyperlink(text: string, url: string): string {
+  return `${ESC}]8;;${url}\x07${text}${ESC}]8;;\x07`
+}
+
+/** Strip ANSI escape codes (colours + OSC 8 links) for width calculation. */
+export function stripAnsi(s: string): string {
+  return s
+    .replace(/\x1b\][^\x07]*\x07/g, "") // OSC sequences
+    .replace(/\x1b\[[0-9;]*m/g, "") // SGR sequences
+}
+
+/** Visible character count excluding ANSI codes. */
+export function visibleLength(s: string): number {
+  return stripAnsi(s).length
+}
+
+/** Pad a (possibly ANSI-coloured) string to `width` visible chars. */
+export function pad(s: string, width: number): string {
+  const diff = width - visibleLength(s)
+  return diff > 0 ? s + " ".repeat(diff) : s
+}
+
+/** Truncate plain text with ".." suffix when it exceeds `width`. */
+export function truncate(s: string, width: number): string {
+  if (s.length <= width) return s
+  if (width <= 2) return s.slice(0, width)
+  return s.slice(0, width - 2) + ".."
+}
+
+/** Replace $HOME prefix with ~ and truncate to maxWidth. */
+export function shortenPath(fullPath: string, maxWidth: number): string {
+  const home = process.env.HOME ?? ""
+  let display = fullPath
+  if (home && display.startsWith(home)) {
+    display = "~" + display.slice(home.length)
+  }
+  return truncate(display, maxWidth)
+}
+
+// ---------------------------------------------------------------------------
+// Key parsing
+// ---------------------------------------------------------------------------
+
+export type Key =
+  | "up"
+  | "down"
+  | "left"
+  | "right"
+  | "enter"
+  | "space"
+  | "escape"
+  | "backspace"
+  | "ctrl-c"
+  | { char: string }
+
+/** Parse raw stdin bytes into a Key value. */
+export function parseKey(data: Buffer): Key {
+  if (data[0] === 0x1b && data[1] === 0x5b) {
+    switch (data[2]) {
+      case 0x41:
+        return "up"
+      case 0x42:
+        return "down"
+      case 0x43:
+        return "right"
+      case 0x44:
+        return "left"
+    }
+  }
+  switch (data[0]) {
+    case 0x03:
+      return "ctrl-c"
+    case 0x0d:
+    case 0x0a:
+      return "enter"
+    case 0x20:
+      return "space"
+    case 0x7f:
+      return "backspace"
+    case 0x1b:
+      return "escape"
+  }
+  return { char: data.toString("utf8") }
+}
+
+/** Extract the character value from a Key, or null for special keys. */
+export function keyChar(key: Key): string | null {
+  if (typeof key === "object" && "char" in key) return key.char
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// PR status formatting
+// ---------------------------------------------------------------------------
+
+/** Render a PrStatus value to a coloured string for the worktree list. */
+export function formatPrStatus(status: PrStatus, spinnerFrame: number): string {
+  switch (status.type) {
+    case "loading": {
+      const frame = SPINNER_FRAMES[spinnerFrame % SPINNER_FRAMES.length]
+      return c.dim(`${frame} fetching`)
+    }
+    case "found": {
+      const { pr } = status
+      const tag = hyperlink(`#${pr.number}`, pr.url)
+      switch (pr.state) {
+        case "MERGED":
+          return c.green(`${tag} merged`)
+        case "OPEN":
+          return c.yellow(`${tag} open`)
+        case "CLOSED":
+          return c.red(`${tag} closed`)
+      }
+      break
+    }
+    case "none":
+      return c.dim("no PR")
+    case "error":
+      return c.dim("fetch error")
+    case "skipped":
+      return c.dim("-")
+  }
+  return ""
+}
+
+// ---------------------------------------------------------------------------
+// File status formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a file status sub-line for a worktree.
+ * Returns null if clean or still loading - only renders when dirty.
+ * Warning triangle prefix to draw attention to uncommitted/unpushed work.
+ */
+export function formatFileStatus(result: FileStatusResult): string | null {
+  if (result.type !== "dirty") return null
+
+  const { staged, modified, untracked, ahead, behind } = result.status
+  const parts: string[] = []
+
+  if (staged > 0) parts.push(c.green(`${staged} staged`))
+  if (modified > 0) parts.push(c.yellow(`${modified} modified`))
+  if (untracked > 0) parts.push(c.dim(`${untracked} untracked`))
+  if (ahead > 0) parts.push(c.cyan(`${ahead} unpushed`))
+  if (behind > 0) parts.push(c.magenta(`${behind} behind`))
+
+  if (parts.length === 0) return null
+
+  return `${c.yellow("\u26A0")} ${parts.join(c.dim("  \u00B7  "))}`
+}
+
+// ---------------------------------------------------------------------------
+// Help screen
+// ---------------------------------------------------------------------------
+
+export function renderHelpLines(): string[] {
+  return [
+    "",
+    `  ${c.bold("KEYBINDINGS")}`,
+    "",
+    `    ${c.cyan("up/down")} or ${c.cyan("k/j")}   Navigate`,
+    `    ${c.cyan("space")}             Toggle selection on focused item`,
+    `    ${c.cyan("a")}                 Select / deselect all`,
+    `    ${c.cyan("e")}                 Expand / collapse file list for focused worktree`,
+    `    ${c.cyan("o")}                 Open focused worktree in file manager`,
+    `    ${c.cyan("d")}                 Delete focused or selected worktree(s)`,
+    `    ${c.cyan("p")}                 Prune stale worktree references`,
+    `    ${c.cyan("r")}                 Refresh list + re-fetch PR statuses`,
+    `    ${c.cyan("?")}                 Toggle this help screen`,
+    `    ${c.cyan("q")} / ${c.cyan("ctrl+c")}        Quit`,
+    "",
+    `  ${c.bold("PRUNE vs DELETE")}`,
+    "",
+    `    ${c.yellow("prune")}   Cleans up ${c.italic("stale administrative references")}. When a worktree`,
+    `            directory has been manually deleted (rm -rf) but git still`,
+    `            tracks it, prune removes those orphaned references.`,
+    `            ${c.dim("Safe: only affects already-missing worktrees.")}`,
+    "",
+    `    ${c.yellow("delete")}  ${c.italic("Properly removes")} a worktree: deletes the working directory`,
+    `            and cleans up git tracking. Optionally also force-deletes`,
+    `            the associated branch. Use for worktrees you no longer need.`,
+    `            ${c.dim("Destructive: removes files from disk.")}`,
+    "",
+    `  ${c.dim("press ? or escape to return")}`,
+  ]
+}
+
+// ---------------------------------------------------------------------------
+// Non-interactive help (--help flag)
+// ---------------------------------------------------------------------------
+
+export function printCliHelp(): void {
+  console.log()
+  console.log(`  ${c.dim("▐▘ █▌ ▐  ▐")}  ${c.dim("Interactive git worktree manager")}`)
+  console.log(`  ${c.dim("▜▘ ▙▖ ▐▖ ▐▖")}`)
+  console.log()
+  console.log(c.yellow("  USAGE"))
+  console.log()
+  console.log(`    ${c.dim("$")} fell            ${c.dim("Interactive mode (default)")}`)
+  console.log(`    ${c.dim("$")} fell ${c.cyan("--list")}     ${c.dim("Print worktrees and exit")}`)
+  console.log(`    ${c.dim("$")} fell ${c.cyan("--help")}     ${c.dim("Show this help")}`)
+  console.log()
+  console.log(c.yellow("  INTERACTIVE COMMANDS"))
+  console.log()
+  console.log(`    ${c.cyan("up/down")} or ${c.cyan("k/j")}   Navigate worktree list`)
+  console.log(`    ${c.cyan("space")}             Toggle selection`)
+  console.log(`    ${c.cyan("a")}                 Select / deselect all`)
+  console.log(`    ${c.cyan("e")}                 Expand / collapse file list`)
+  console.log(`    ${c.cyan("o")}                 Open worktree in file manager`)
+  console.log(`    ${c.cyan("d")}                 Delete worktree(s) + optionally branches`)
+  console.log(`    ${c.cyan("p")}                 Prune stale references`)
+  console.log(`    ${c.cyan("r")}                 Refresh list + PR statuses`)
+  console.log(`    ${c.cyan("?")}                 In-app help (prune vs delete explained)`)
+  console.log(`    ${c.cyan("q")} / ${c.cyan("ctrl+c")}        Quit`)
+  console.log()
+  console.log(c.yellow("  PRUNE vs DELETE"))
+  console.log()
+  console.log(`    ${c.bold("prune")}   Removes stale git references to worktrees whose directories`)
+  console.log(`            no longer exist. Equivalent to ${c.cyan("git worktree prune")}.`)
+  console.log(`            Does ${c.underline("not")} touch any actual worktree directories.`)
+  console.log()
+  console.log(`    ${c.bold("delete")}  Removes the worktree directory from disk and cleans up git`)
+  console.log(`            tracking. Equivalent to ${c.cyan("git worktree remove <path>")}.`)
+  console.log(`            Optionally also deletes the associated branch.`)
+  console.log()
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@doccy/fell",
+  "version": "0.1.0",
+  "description": "Interactive git worktree manager. Navigate, inspect, delete, and prune worktrees with async PR status fetching.",
+  "license": "MIT",
+  "bin": {
+    "fell": "cli.ts"
+  },
+  "type": "module",
+  "files": [
+    "cli.ts",
+    "lib/"
+  ],
+  "keywords": [
+    "git",
+    "worktree",
+    "cli",
+    "tui",
+    "interactive",
+    "prune",
+    "bun"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/medlo-aus/fell.git"
+  },
+  "homepage": "https://github.com/medlo-aus/fell",
+  "bugs": {
+    "url": "https://github.com/medlo-aus/fell/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}