arborista 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Jaquith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# arborista
+
+`arborista` is a Bun/TypeScript CLI for elegant git worktree oversight.
+
+## Install
+
+`arborista` is published on npm, but it runs on Bun.
+
+```sh
+npm install -g arborista
+```
+
+If Bun is not already installed, install it first from `https://bun.sh`.
+
+## Git Hooks
+
+This project uses [hk](https://github.com/jdx/hk) for git hook management. The configuration is in `hk.pkl`.
+
+To install the hooks in your local clone:
+
+```sh
+hk install
+```
+
+The configured hooks run `bun run check` on `pre-commit` and `pre-push`.
+
+## Config
+
+Config lives at `~/.config/arborista/arborista.jsonc`.
+
+Example:
+
+```jsonc
+{
+	"root": "~/Dev/.arborista",
+}
+```
+
+Only `root` is used in v1. Commands always act on repo found from current working directory.
+
+## Commands
+
+```sh
+arborista list [--dir]
+arborista ls [--dir]
+arborista new <branch> [--from <start-point>]
+arborista dir <branch>
+arborista rm <branch> [--branch]
+arborista move
+```
+
+## Comparison to Git
+
+For a 1:1 mapping from each `arb` command to the exact underlying Git commands, see `docs/comparison-to-git.md`.

package/bin/arb.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const binDirectory = path.dirname(fileURLToPath(import.meta.url))
+const entrypoint = path.join(binDirectory, "..", "src", "index.ts")
+
+const result = spawnSync(
+	"bun",
+	["run", "--bun", entrypoint, ...process.argv.slice(2)],
+	{
+		stdio: "inherit",
+		env: {
+			...process.env,
+			ARBORISTA_EXECUTABLE: "arb",
+		},
+	},
+)
+
+if (result.error && result.error.code === "ENOENT") {
+	console.error("arborista requires Bun. Install it from https://bun.sh")
+	process.exit(1)
+}
+
+if (result.error) {
+	throw result.error
+}
+
+process.exit(result.status ?? 1)

package/bin/arborista.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const binDirectory = path.dirname(fileURLToPath(import.meta.url))
+const entrypoint = path.join(binDirectory, "..", "src", "index.ts")
+
+const result = spawnSync(
+	"bun",
+	["run", "--bun", entrypoint, ...process.argv.slice(2)],
+	{
+		stdio: "inherit",
+		env: {
+			...process.env,
+			ARBORISTA_EXECUTABLE: "arborista",
+		},
+	},
+)
+
+if (result.error && result.error.code === "ENOENT") {
+	console.error("arborista requires Bun. Install it from https://bun.sh")
+	process.exit(1)
+}
+
+if (result.error) {
+	throw result.error
+}
+
+process.exit(result.status ?? 1)

package/docs/comparison-to-git.md

@@ -0,0 +1,270 @@
+# `arb` vs raw Git
+
+This document maps each `arb` command to the exact Git commands it runs today.
+
+Assumptions used below:
+
+- `<repo>`: the primary repository checkout
+- `<branch>`: the branch name you pass to `arb`
+- `<base>`: either the explicit `--from` value or the default base branch `arb` resolves
+- `<managed-root>`: the configured root, defaulting to `~/.arborista`
+- `<worktree-path>`: `<managed-root>/<repo-name>/<branch-with-slashes-replaced-by-dashes>`
+
+Example:
+
+```text
+branch: feature/api-cleanup
+worktree-path: ~/.arborista/arborista/feature-api-cleanup
+```
+
+## `arb new <branch>`
+
+`arb` always inspects existing worktrees first:
+
+```bash
+git worktree list --porcelain
+```
+
+If any listed worktree path no longer exists on disk, `arb` also runs:
+
+```bash
+git worktree prune --expire now
+git worktree list --porcelain
+```
+
+Then it checks whether the local branch already exists:
+
+```bash
+git show-ref --verify --quiet refs/heads/<branch>
+```
+
+If the branch already exists, `arb new <branch>` runs:
+
+```bash
+git worktree add <worktree-path> <branch>
+```
+
+If the branch does not already exist, `arb new <branch>` resolves a base branch and then runs:
+
+```bash
+git symbolic-ref refs/remotes/origin/HEAD
+```
+
+If that fails, it tries:
+
+```bash
+git rev-parse --verify --quiet origin/main^{commit}
+git rev-parse --verify --quiet origin/master^{commit}
+```
+
+Then it creates both the branch and worktree with:
+
+```bash
+git worktree add -b <branch> <worktree-path> <base>
+git config branch.<branch>.remote origin
+git config branch.<branch>.merge refs/heads/<branch>
+```
+
+If you pass `--from <start-point>`, `arb` skips base-branch detection and uses exactly:
+
+```bash
+git worktree add -b <branch> <worktree-path> <start-point>
+git config branch.<branch>.remote origin
+git config branch.<branch>.merge refs/heads/<branch>
+```
+
+## `arb dir <branch>`
+
+`arb` does not have a single raw Git equivalent here. It computes the managed path and validates repo state with:
+
+```bash
+git worktree list --porcelain
+```
+
+If any listed worktree path no longer exists on disk, `arb` also runs:
+
+```bash
+git worktree prune --expire now
+git worktree list --porcelain
+```
+
+If it needs to distinguish between "branch exists but is unmanaged" and "branch does not exist", it also runs:
+
+```bash
+git show-ref --verify --quiet refs/heads/<branch>
+```
+
+If the branch is already managed at the expected location, `arb` prints `<worktree-path>`.
+
+## `arb list`
+
+`arb list` runs:
+
+```bash
+git worktree list --porcelain
+```
+
+If any listed worktree path no longer exists on disk, `arb` also runs:
+
+```bash
+git worktree prune --expire now
+git worktree list --porcelain
+```
+
+Then `arb` filters that output to only worktrees inside its managed layout and prints branch names.
+
+## `arb list --dir`
+
+Same Git command sequence as `arb list`:
+
+```bash
+git worktree list --porcelain
+```
+
+Possibly followed by:
+
+```bash
+git worktree prune --expire now
+git worktree list --porcelain
+```
+
+Then `arb` prints the matching managed worktree directories instead of branch names.
+
+## `arb rm <branch>`
+
+`arb` first inspects worktrees:
+
+```bash
+git worktree list --porcelain
+```
+
+If any listed worktree path no longer exists on disk, `arb` also runs:
+
+```bash
+git worktree prune --expire now
+git worktree list --porcelain
+```
+
+If it finds the managed worktree for `<branch>`, it removes it with:
+
+```bash
+git worktree remove <worktree-path>
+```
+
+That is the full raw Git equivalent for plain `arb rm <branch>`.
+
+## `arb rm <branch> --branch`
+
+`arb` first inspects worktrees:
+
+```bash
+git worktree list --porcelain
+```
+
+If any listed worktree path no longer exists on disk, `arb` also runs:
+
+```bash
+git worktree prune --expire now
+git worktree list --porcelain
+```
+
+Then it checks whether the local branch exists:
+
+```bash
+git show-ref --verify --quiet refs/heads/<branch>
+```
+
+If the managed worktree exists, it runs:
+
+```bash
+git worktree remove <worktree-path>
+```
+
+If the local branch exists, it also runs:
+
+```bash
+git branch -d <branch>
+```
+
+## `arb move`
+
+`arb move` only works when run from inside a Git worktree on a branch with no uncommitted changes.
+
+It first identifies the repo root and current checkout:
+
+```bash
+git rev-parse --show-toplevel
+git rev-parse --show-toplevel
+git symbolic-ref --quiet --short HEAD
+git status --porcelain
+```
+
+Then it inspects known worktrees:
+
+```bash
+git worktree list --porcelain
+```
+
+If any listed worktree path no longer exists on disk, `arb` also runs:
+
+```bash
+git worktree prune --expire now
+git worktree list --porcelain
+```
+
+Next it chooses a safe branch to switch the current checkout to before moving the current branch into a managed worktree.
+
+To resolve the preferred fallback branch, it tries:
+
+```bash
+git symbolic-ref refs/remotes/origin/HEAD
+```
+
+If that fails, it tries:
+
+```bash
+git rev-parse --verify --quiet origin/main^{commit}
+git rev-parse --verify --quiet origin/master^{commit}
+```
+
+Then it checks for a local branch to switch to. The first check is the local name derived from the resolved base branch, if that name is different from the current branch. For example, if the resolved base branch is `origin/main`, the first local-branch check is:
+
+```bash
+git show-ref --verify --quiet refs/heads/main
+```
+
+After that, it tries `main` and `master` as fallbacks, skipping duplicates and skipping the current branch. So depending on the repo state, it may also run:
+
+```bash
+git show-ref --verify --quiet refs/heads/main
+git show-ref --verify --quiet refs/heads/master
+```
+
+If a safe local branch exists, `arb` switches away from the current branch with:
+
+```bash
+git switch <safe-branch>
+```
+
+If no safe local branch exists, `arb` detaches HEAD instead:
+
+```bash
+git switch --detach HEAD
+```
+
+Finally it recreates the current branch as a managed worktree with:
+
+```bash
+git worktree add <worktree-path> <current-branch>
+```
+
+## What `arb` adds beyond raw Git
+
+The Git commands above are the real underlying operations. What `arb` adds is orchestration around them:
+
+- A consistent managed path layout under `~/.arborista` by default
+- Automatic branch-to-directory name normalization by replacing `/` with `-`
+- Automatic stale-worktree pruning when `git worktree list --porcelain` references missing paths
+- Default base-branch selection for `new`
+- Safety checks and fallback switching logic for `move`
+- A single command for "move this branch out of the main checkout and into the managed worktree layout"

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "arborista",
+  "version": "0.1.0",
+  "description": "Bun CLI for managing git worktrees in a repo-specific layout.",
+  "keywords": [
+    "bun",
+    "cli",
+    "git",
+    "worktree"
+  ],
+  "homepage": "https://github.com/markjaquith/arborista#readme",
+  "bugs": {
+    "url": "https://github.com/markjaquith/arborista/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markjaquith/arborista.git"
+  },
+  "bin": {
+    "arb": "./bin/arb.js",
+    "arborista": "./bin/arborista.js"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "check": "bunx tsc --noEmit -p tsconfig.json",
+    "knip": "knip --treat-config-hints-as-errors",
+    "start": "bun run src/index.ts",
+    "prepublishOnly": "bun run check",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "knip": "^6.3.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,653 @@
+#!/usr/bin/env bun
+
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { parse } from "jsonc-parser"
+
+type Config = {
+	root?: string
+}
+
+type RepoContext = {
+	name: string
+	path: string
+	managedRoot: string
+}
+
+type Worktree = {
+	path: string
+	branch: string | null
+	head: string
+	detached: boolean
+}
+
+type ParsedArgs = {
+	positionals: string[]
+	flags: Map<string, string | boolean>
+}
+
+const CONFIG_PATH = path.join(
+	os.homedir(),
+	".config",
+	"arborista",
+	"arborista.jsonc",
+)
+
+const EXECUTABLE_NAME = resolveExecutableName()
+
+function main() {
+	try {
+		const config = loadConfig()
+		const [, , ...argv] = Bun.argv
+		const command = argv[0]
+
+		if (!command || command === "help" || command === "--help" || command === "-h") {
+			printHelp()
+			return
+		}
+
+		switch (command) {
+			case "new":
+				handleNew(parseArgs(argv.slice(1)), config)
+				return
+			case "dir":
+				handleDir(parseArgs(argv.slice(1)), config)
+				return
+			case "list":
+			case "ls":
+				handleList(parseArgs(argv.slice(1)), config)
+				return
+			case "rm":
+				handleRemove(parseArgs(argv.slice(1)), config)
+				return
+			case "move":
+				handleMove(parseArgs(argv.slice(1)), config)
+				return
+			default:
+				fail(`Unknown command: ${command}`)
+		}
+	} catch (error) {
+		if (error instanceof ArboristaError) {
+			console.error(error.message)
+			process.exit(1)
+		}
+
+		throw error
+	}
+}
+
+class ArboristaError extends Error {}
+
+function parseArgs(argv: string[]): ParsedArgs {
+	const positionals: string[] = []
+	const flags = new Map<string, string | boolean>()
+
+	for (let index = 0; index < argv.length; index += 1) {
+		const value = argv[index]
+
+		if (!value.startsWith("--")) {
+			positionals.push(value)
+			continue
+		}
+
+		const [rawName, inlineValue] = value.slice(2).split("=", 2)
+
+		if (inlineValue !== undefined) {
+			flags.set(rawName, inlineValue)
+			continue
+		}
+
+		const nextValue = argv[index + 1]
+		if (nextValue && !nextValue.startsWith("--")) {
+			flags.set(rawName, nextValue)
+			index += 1
+			continue
+		}
+
+		flags.set(rawName, true)
+	}
+
+	return { positionals, flags }
+}
+
+function loadConfig(): Config {
+	if (!existsSync(CONFIG_PATH)) {
+		return {}
+	}
+
+	const rawConfig = readFileSync(CONFIG_PATH, "utf8")
+	const parsed = parse(rawConfig)
+
+	if (!parsed || typeof parsed !== "object") {
+		fail(`Invalid config file: ${CONFIG_PATH}`)
+	}
+
+	return parsed as Config
+}
+
+function handleNew(args: ParsedArgs, config: Config) {
+	const branch = args.positionals[0]
+	if (!branch) {
+		fail(`Usage: ${EXECUTABLE_NAME} new <branch> [--from <start-point>]`)
+	}
+
+	assertNoUnsupportedFlags(args, ["from"])
+	const repo = resolveRepoContext(config)
+	const worktreePath = managedWorktreePath(repo, branch)
+	const worktrees = getWorktrees(repo.path)
+	const matchingWorktree = worktrees.find((worktree) => worktree.branch === branch)
+
+	if (matchingWorktree) {
+		if (pathsEqual(matchingWorktree.path, worktreePath)) {
+			console.log(`Branch ${branch} is already managed at ${formatPath(matchingWorktree.path)}`)
+			return
+		}
+
+		fail(`Branch \"${branch}\" is already checked out at ${formatPath(matchingWorktree.path)}.`)
+	}
+
+	assertPathAvailable(worktreePath, worktrees)
+	ensureDirectory(path.dirname(worktreePath))
+
+	if (localBranchExists(repo.path, branch)) {
+		console.log(`Creating worktree at ${formatPath(worktreePath)}`)
+		runGit(repo.path, ["worktree", "add", worktreePath, branch])
+		return
+	}
+
+	const baseBranch = resolveBaseBranch(repo.path, getStringFlag(args, "from"))
+	console.log(`Creating branch ${branch} from ${baseBranch}`)
+	console.log(`Creating worktree at ${formatPath(worktreePath)}`)
+	runGit(repo.path, ["worktree", "add", "-b", branch, worktreePath, baseBranch])
+	configureBranchUpstream(repo.path, branch)
+}
+
+function handleDir(args: ParsedArgs, config: Config) {
+	const branch = args.positionals[0]
+	if (!branch) {
+		fail(`Usage: ${EXECUTABLE_NAME} dir <branch>`)
+	}
+
+	assertNoUnsupportedFlags(args, [])
+	const repo = resolveRepoContext(config)
+	const worktreePath = managedWorktreePath(repo, branch)
+	const worktrees = getWorktrees(repo.path)
+	const matchingWorktree = worktrees.find(
+		(worktree) => worktree.branch === branch && pathsEqual(worktree.path, worktreePath),
+	)
+
+	if (matchingWorktree) {
+		console.log(matchingWorktree.path)
+		return
+	}
+
+	const branchWorktree = worktrees.find((worktree) => worktree.branch === branch)
+	if (branchWorktree && pathsEqual(branchWorktree.path, repo.path)) {
+		fail(`No managed checkout found for branch \"${branch}\". Branch is checked out in primary repo at ${formatPath(repo.path)}. Run ${EXECUTABLE_NAME} move to move it into managed layout.`)
+	}
+
+	if (branchWorktree) {
+		fail(`No managed checkout found for branch \"${branch}\". Branch is checked out at ${formatPath(branchWorktree.path)}.`)
+	}
+
+	if (localBranchExists(repo.path, branch)) {
+		fail(`No managed checkout found for branch \"${branch}\". Run ${EXECUTABLE_NAME} new ${branch}.`)
+	}
+
+	fail(`Branch \"${branch}\" does not exist. Run ${EXECUTABLE_NAME} new ${branch}.`)
+}
+
+function handleList(args: ParsedArgs, config: Config) {
+	assertNoUnsupportedFlags(args, ["dir"])
+	const repo = resolveRepoContext(config)
+	const worktrees = getWorktrees(repo.path)
+	printRepoWorktrees(repo, worktrees, null, false, getBooleanFlag(args, "dir") ? "dir" : "branch")
+}
+
+function handleRemove(args: ParsedArgs, config: Config) {
+	const branch = args.positionals[0]
+	if (!branch) {
+		fail(`Usage: ${EXECUTABLE_NAME} rm <branch> [--branch]`)
+	}
+
+	assertNoUnsupportedFlags(args, ["branch"])
+	const repo = resolveRepoContext(config)
+	const worktreePath = managedWorktreePath(repo, branch)
+	const worktrees = getWorktrees(repo.path)
+	const worktree = worktrees.find(
+		(candidate) => candidate.branch === branch && pathsEqual(candidate.path, worktreePath),
+	)
+
+	const shouldDeleteBranch = getBooleanFlag(args, "branch")
+	const branchExists = shouldDeleteBranch ? localBranchExists(repo.path, branch) : false
+
+	if (!worktree && !branchExists) {
+		fail(
+			`No managed worktree found for branch \"${branch}\" in repo \"${repo.name}\".`,
+		)
+	}
+
+	if (worktree) {
+		console.log(`Removing worktree ${formatPath(worktree.path)}`)
+		const removeArgs = ["worktree", "remove"]
+		removeArgs.push(worktree.path)
+		runGit(repo.path, removeArgs)
+	}
+
+	if (branchExists) {
+		const branchArgs = ["branch", "-d", branch]
+		console.log(`Deleting branch ${branch}`)
+		runGit(repo.path, branchArgs)
+	}
+}
+
+function handleMove(args: ParsedArgs, config: Config) {
+	if (args.positionals.length > 0 || args.flags.size > 0) {
+		fail(`Usage: ${EXECUTABLE_NAME} move`)
+	}
+
+	const discoveredRepo = discoverGitRoot(process.cwd())
+	if (!discoveredRepo) {
+		fail("No repo context found.\nRun this inside a Git repository.")
+	}
+
+	const repo = resolveRepoContext(config)
+	const currentWorktreePath = getCurrentWorktreePath(discoveredRepo)
+	const currentBranch = getCurrentBranch(discoveredRepo)
+	if (!currentBranch) {
+		fail("Cannot move a detached HEAD. Check out a branch first.")
+	}
+
+	if (isWorktreeDirty(discoveredRepo)) {
+		fail(
+			`Current worktree has uncommitted changes on \"${currentBranch}\". Commit or stash them before running ${EXECUTABLE_NAME} move.`,
+		)
+	}
+
+	const targetPath = managedWorktreePath(repo, currentBranch)
+	if (pathsEqual(currentWorktreePath, targetPath)) {
+		console.log(`Branch ${currentBranch} is already managed at ${formatPath(targetPath)}`)
+		return
+	}
+
+	const worktrees = getWorktrees(discoveredRepo)
+	assertPathAvailable(targetPath, worktrees)
+	ensureDirectory(path.dirname(targetPath))
+
+	const switchTarget = chooseSafeSwitchTarget(discoveredRepo, currentBranch)
+	if (switchTarget) {
+		console.log(`Switching current worktree to ${switchTarget}`)
+		runGit(discoveredRepo, ["switch", switchTarget])
+	} else {
+		console.log("Detaching current worktree HEAD")
+		runGit(discoveredRepo, ["switch", "--detach", "HEAD"])
+	}
+
+	console.log(`Creating worktree at ${formatPath(targetPath)}`)
+	console.log(`Moving branch ${currentBranch} into managed layout`)
+	runGit(discoveredRepo, ["worktree", "add", targetPath, currentBranch])
+}
+
+function printRepoWorktrees(
+	repo: RepoContext,
+	worktrees: Worktree[],
+	currentWorktree: string | null,
+	includePrimary: boolean,
+	format: "branch" | "dir",
+) {
+	const rows = worktrees
+		.filter((worktree) => includePrimary || isManagedWorktree(repo, worktree.path))
+		.sort((left, right) => sortWorktrees(left, right, repo))
+
+	if (!includePrimary && rows.length === 0) {
+		console.log("No managed worktrees found.")
+		return
+	}
+
+	for (const worktree of rows) {
+		if (format === "dir") {
+			console.log(formatPath(worktree.path))
+			continue
+		}
+
+		console.log(worktree.branch ?? "(detached HEAD)")
+	}
+}
+
+function sortWorktrees(left: Worktree, right: Worktree, repo: RepoContext) {
+	const leftPrimary = pathsEqual(left.path, repo.path)
+	const rightPrimary = pathsEqual(right.path, repo.path)
+
+	if (leftPrimary && !rightPrimary) {
+		return -1
+	}
+
+	if (!leftPrimary && rightPrimary) {
+		return 1
+	}
+
+	return (left.branch ?? "").localeCompare(right.branch ?? "")
+}
+
+function resolveRepoContext(config: Config): RepoContext {
+	const managedRoot = configRoot(config)
+
+	const repoPath = discoverGitRoot(process.cwd())
+	if (!repoPath) {
+		fail("No repo context found.\nRun this inside a Git repository.")
+	}
+
+	return {
+		name: path.basename(repoPath),
+		path: repoPath,
+		managedRoot,
+	}
+}
+
+function configRoot(config: Config) {
+	return expandHome(config.root ?? "~/Dev/.arborista")
+}
+
+function managedWorktreePath(repo: RepoContext, branch: string) {
+	return path.join(repo.managedRoot, repo.name, slugifyBranch(branch))
+}
+
+function slugifyBranch(branch: string) {
+	return branch.replace(/[\\/]+/g, "-")
+}
+
+function resolveBaseBranch(repoPath: string, explicitBase?: string) {
+	if (explicitBase) {
+		return explicitBase
+	}
+
+	const remoteHead = runGit(repoPath, ["symbolic-ref", "refs/remotes/origin/HEAD"], {
+		allowFailure: true,
+	})
+	if (remoteHead.success) {
+		return remoteHead.stdout.replace(/^refs\/remotes\//, "")
+	}
+
+	for (const fallback of ["origin/main", "origin/master"]) {
+		if (refExists(repoPath, fallback)) {
+			return fallback
+		}
+	}
+
+	const repoName = path.basename(repoPath)
+	fail(`Could not determine the default base branch for repo \"${repoName}\".
+Tried:
+- refs/remotes/origin/HEAD
+- origin/main
+- origin/master
+
+Pass --from <branch>.`)
+}
+
+function chooseSafeSwitchTarget(repoPath: string, currentBranch: string) {
+	const candidates: string[] = []
+	let localBase: string | null = null
+
+	try {
+		const resolvedBase = resolveBaseBranch(repoPath)
+		localBase = resolvedBase.includes("/")
+			? resolvedBase.slice(resolvedBase.lastIndexOf("/") + 1)
+			: resolvedBase
+	} catch (error) {
+		if (!(error instanceof ArboristaError)) {
+			throw error
+		}
+	}
+
+	if (localBase && localBase !== currentBranch) {
+		candidates.push(localBase)
+	}
+
+	for (const fallback of ["main", "master"]) {
+		if (fallback !== currentBranch) {
+			candidates.push(fallback)
+		}
+	}
+
+	for (const branch of candidates) {
+		if (localBranchExists(repoPath, branch)) {
+			return branch
+		}
+	}
+
+	return null
+}
+
+function getWorktrees(repoPath: string): Worktree[] {
+	let worktrees = parseWorktrees(runGit(repoPath, ["worktree", "list", "--porcelain"]).stdout)
+
+	if (worktrees.some((worktree) => !existsSync(worktree.path))) {
+		runGit(repoPath, ["worktree", "prune", "--expire", "now"])
+		worktrees = parseWorktrees(runGit(repoPath, ["worktree", "list", "--porcelain"]).stdout)
+	}
+
+	return worktrees
+}
+
+function parseWorktrees(stdout: string) {
+	const blocks = stdout.trim().split("\n\n").filter(Boolean)
+
+	return blocks.map((block) => {
+		let worktreePath = ""
+		let branch: string | null = null
+		let head = ""
+		let detached = false
+
+		for (const line of block.split("\n")) {
+			if (line.startsWith("worktree ")) {
+				worktreePath = line.slice("worktree ".length)
+				continue
+			}
+
+			if (line.startsWith("branch ")) {
+				branch = line.slice("branch refs/heads/".length)
+				continue
+			}
+
+			if (line.startsWith("HEAD ")) {
+				head = line.slice("HEAD ".length)
+				continue
+			}
+
+			if (line === "detached") {
+				detached = true
+			}
+		}
+
+		return { path: worktreePath, branch, head, detached }
+	})
+}
+
+function getCurrentWorktreePath(repoPath: string) {
+	return runGit(repoPath, ["rev-parse", "--show-toplevel"]).stdout
+}
+
+function getCurrentBranch(repoPath: string) {
+	const result = runGit(repoPath, ["symbolic-ref", "--quiet", "--short", "HEAD"], {
+		allowFailure: true,
+	})
+
+	if (!result.success) {
+		return null
+	}
+
+	return result.stdout
+}
+
+function isWorktreeDirty(repoPath: string) {
+	const result = runGit(repoPath, ["status", "--porcelain"], { allowFailure: true })
+	return result.stdout.length > 0
+}
+
+function assertPathAvailable(worktreePath: string, worktrees: Worktree[]) {
+	if (!existsSync(worktreePath)) {
+		return
+	}
+
+	const existingWorktree = worktrees.find((worktree) => pathsEqual(worktree.path, worktreePath))
+	if (existingWorktree) {
+		fail(`Managed worktree path already exists at ${formatPath(worktreePath)}.`)
+	}
+
+	fail(
+		`Path ${formatPath(worktreePath)} already exists but is not a valid Git worktree. Remove it or choose a different branch name.`,
+	)
+}
+
+function localBranchExists(repoPath: string, branch: string) {
+	return runGit(repoPath, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], {
+		allowFailure: true,
+	}).success
+}
+
+function refExists(repoPath: string, ref: string) {
+	return runGit(repoPath, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
+		allowFailure: true,
+	}).success
+}
+
+function configureBranchUpstream(repoPath: string, branch: string) {
+	runGit(repoPath, ["config", `branch.${branch}.remote`, "origin"])
+	runGit(repoPath, ["config", `branch.${branch}.merge`, `refs/heads/${branch}`])
+}
+
+function isManagedWorktree(repo: RepoContext, worktreePath: string) {
+	const managedRepoPath = canonicalPath(path.join(repo.managedRoot, repo.name))
+	const resolvedWorktreePath = canonicalPath(worktreePath)
+	const managedPrefix = `${managedRepoPath}${path.sep}`
+
+	return resolvedWorktreePath === managedRepoPath
+		|| resolvedWorktreePath.startsWith(managedPrefix)
+}
+
+function discoverGitRoot(cwd: string) {
+	const result = runGit(cwd, ["rev-parse", "--show-toplevel"], { allowFailure: true })
+	if (!result.success) {
+		return null
+	}
+
+	return result.stdout
+}
+
+function runGit(
+	cwd: string,
+	args: string[],
+	options: { allowFailure?: boolean } = {},
+) {
+	const result = Bun.spawnSync({
+		cmd: ["git", ...args],
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+
+	const stdout = result.stdout.toString().trim()
+	const stderr = result.stderr.toString().trim()
+	const success = result.exitCode === 0
+
+	if (!success && !options.allowFailure) {
+		fail(stderr || `git ${args.join(" ")} failed`)
+	}
+
+	return { success, stdout, stderr }
+}
+
+function getStringFlag(args: ParsedArgs, name: string) {
+	const value = args.flags.get(name)
+	if (typeof value !== "string") {
+		return undefined
+	}
+
+	return value
+}
+
+function getBooleanFlag(args: ParsedArgs, name: string) {
+	return args.flags.get(name) === true
+}
+
+function assertNoUnsupportedFlags(args: ParsedArgs, allowedFlags: string[]) {
+	for (const flagName of args.flags.keys()) {
+		if (!allowedFlags.includes(flagName)) {
+			fail(`Unknown flag: --${flagName}`)
+		}
+	}
+}
+
+function ensureDirectory(directoryPath: string) {
+	mkdirSync(directoryPath, { recursive: true })
+}
+
+function expandHome(value: string) {
+	if (!value.startsWith("~/")) {
+		return value
+	}
+
+	return path.join(os.homedir(), value.slice(2))
+}
+
+function formatPath(value: string) {
+	const homeDir = os.homedir()
+	if (value === homeDir) {
+		return "~"
+	}
+
+	if (value.startsWith(`${homeDir}/`)) {
+		return `~/${value.slice(homeDir.length + 1)}`
+	}
+
+	return value
+}
+
+function pathsEqual(left: string, right: string) {
+	return canonicalPath(left) === canonicalPath(right)
+}
+
+function canonicalPath(value: string) {
+	const resolvedPath = path.resolve(value)
+
+	if (!existsSync(resolvedPath)) {
+		return resolvedPath
+	}
+
+	return realpathSync.native(resolvedPath)
+}
+
+function printHelp() {
+	console.log(`arborista: elegant git worktree oversight
+
+Usage:
+	  ${EXECUTABLE_NAME} list [--dir]
+	  ${EXECUTABLE_NAME} ls [--dir]
+	  ${EXECUTABLE_NAME} new <branch> [--from <start-point>]
+	  ${EXECUTABLE_NAME} dir <branch>
+	  ${EXECUTABLE_NAME} rm <branch> [--branch]
+	  ${EXECUTABLE_NAME} move`)
+}
+
+function resolveExecutableName() {
+	const configuredName = process.env.ARBORISTA_EXECUTABLE
+	if (configuredName === "arb" || configuredName === "arborista") {
+		return configuredName
+	}
+
+	const executablePath = Bun.argv[1]
+	const executableName = executablePath ? path.basename(executablePath) : "arborista"
+
+	if (executableName === "arb" || executableName === "arborista") {
+		return executableName
+	}
+
+	return "arborista"
+}
+
+function fail(message: string): never {
+	throw new ArboristaError(message)
+}
+
+main()