@f0rbit/overview 0.1.0

package/README.md

@@ -0,0 +1,242 @@
+# overview
+
+A terminal UI that scans a directory tree for git repositories, displays them in a hierarchical list with per-repo health indicators, and provides a split-pane detail view with an embedded git graph and widget-based stats panel.
+
+## Why use this
+
+If you work across many git repositories, it is hard to know which ones have uncommitted changes, unpushed commits, or are behind their remote. `overview` gives you a single dashboard that answers "what is the state of all my repos?" at a glance, with the ability to drill into any repo for its full commit graph and metadata -- or launch directly into your editor, ggi, or a tmux session.
+
+## Interface
+
+Three-panel split layout: a hierarchical repo list on the left, a git graph (top-right), and a scrollable widget panel (bottom-right). The repo list shows inline health badges -- selecting a repo loads its graph and widgets on demand.
+
+```
+┌─ overview ──────────────────── ~/dev ──── 28 repos ── scanning... ──┐
+│                                                                     │
+├─────────────────────────┬───────────────────────────────────────────┤
+│  ~/dev                  │ ┌─ git graph ───────────────────────────┐ │
+│  ├── algorithms/     ✓  │ │ * 4a2f1c3 (HEAD -> main) fix: t...     │ │
+│  ├── bases.nvim/     ✓  │ │ * 8b3e2d1 feat: add treesitter...      │ │
+│  ├── burning-blends/ ✓  │ │ * c7f9a0e refactor: extract pa...      │ │
+│  ├── byron-kastelic/ ✓  │ │ | * 2d4e6f8 (origin/dev) wip:...       │ │
+│  ├── chamber/       ↑3  │ │ | |/                                  │ │
+│  ├── corpus/        ↑1  │ │ * | a1b2c3d merge: dev into m...       │ │
+│  ├── cs-club-websit… ✓  │ │ |\ \                                  │ │
+│  ├── database/       ✓  │ │ | * 5f6g7h8 fix: query perfor...       │ │
+│  ├── dev-blog-go/    ✓  │ │ * | 9i0j1k2 chore: bump deps          │ │
+│  ├── dev-blog/       ✓  │ │ |/                                    │ │
+│  ├── devpad/      * ↑2  │ │ * l3m4n5o v2.1.0 release              │ │
+│ >├── dotfiles/      ~3  │ │                                       │ │
+│  ├── forbit-astro/   ✓  │ └───────────────────────────────────────┘ │
+│  ├── gallery/        ✓  │ ┌─ widgets: dotfiles ──────────────────┐  │
+│  ├── gm-server/      ✓  │ │                                      │  │
+│  ├── hackertui/     ↑1  │ │  branch   main                       │  │
+│  ├── key-grip/       ✓  │ │  remote   origin (github.com/...)     │  │
+│  ├── media-timeline/ ✓  │ │                                      │  │
+│  ├── mycelia/        ✓  │ │  ~ 3 modified  + 0 staged            │  │
+│  ├── ocn/            ✓  │ │  ? 1 untracked  ! 0 conflicts        │  │
+│  ├── rollette/       ✓  │ │                                      │  │
+│  ├── runbook/     > ↑5  │ │  last commit  2h ago                 │  │
+│  ├── studdy-buddy/   ✓  │ │  contributors 3                      │  │
+│  ├── todo-tracker/   ✓  │ │  branches     4 local / 6 remote     │  │
+│  └── ui/            ↑1  │ │  tags         v1.0, v1.1, v2.0       │  │
+│                         │ │                                      │  │
+│                         │ └──────────────────────────────────────┘  │
+├─────────────────────────┴───────────────────────────────────────────┤
+│ [NORMAL] j/k:nav  Enter:detail  g:ggi  r:refresh  q:quit  ?:help   │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Status badges
+
+| Badge | Meaning |
+|-------|---------|
+| `*` | OpenCode session active (busy) |
+| `>` | OpenCode session needs input |
+| `!` | OpenCode session errored / merge conflicts |
+| `✓` | Clean -- nothing to commit, up to date |
+| `↑3` | 3 commits ahead (unpushed) |
+| `↓2` | 2 commits behind remote |
+| `~3` | 3 uncommitted changes |
+| `?` | Untracked files only |
+
+## Install and run
+
+Requires [Bun](https://bun.sh) >= 1.0 and `git`. Optional: `fzf` + `delta` for [ggi](https://github.com/f0rbit/ggi) integration, `gh` CLI for GitHub widgets.
+
+```sh
+# run without installing
+bunx @f0rbit/overview
+
+# or install globally
+bun add -g @f0rbit/overview
+overview
+```
+
+CLI flags override config values:
+
+```sh
+overview --dir ~/workplace --depth 2 --sort status --filter dirty
+```
+
+### Development
+
+```sh
+git clone https://github.com/f0rbit/overview.git
+cd overview
+bun install
+
+bun run dev       # run in dev mode
+bun run build     # compile standalone binary
+./overview
+```
+
+### Configuration
+
+Config lives at `~/.config/overview/config.toml`. A default is created on first run. Key options:
+
+```toml
+scan_dirs = ["~/dev"]
+depth = 3
+refresh_interval = 30
+sort = "name"           # name | status | last-commit
+filter = "all"          # all | dirty | clean | ahead | behind
+
+[layout]
+left_width_pct = 35
+graph_height_pct = 45
+
+[actions]
+ggi = "ggi"
+editor = "$EDITOR"
+sessionizer = ""        # path to tmux-sessionizer script
+```
+
+## Keybindings
+
+### Normal mode
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Navigate repo list |
+| `Enter` / `l` | Enter detail mode (focus right panels) |
+| `Tab` | Cycle focus: list / graph / stats |
+| `f` | Cycle filter: all / dirty / clean / ahead / behind |
+| `s` | Cycle sort: name / status / last-commit |
+| `r` | Refresh selected repo |
+| `R` | Full rescan (re-walk directory tree) |
+| `g` | Launch ggi in selected repo |
+| `o` | Open selected repo in `$EDITOR` |
+| `t` | Open tmux session for selected repo |
+| `?` | Toggle help overlay |
+| `q` / `Esc` | Quit |
+
+### Detail mode
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Scroll focused panel / navigate widgets in stats |
+| `h` | Move left (graph, or exit to list if on graph) |
+| `l` | Move right (stats) |
+| `g` | Launch ggi |
+| `o` | Open in `$EDITOR` |
+| `t` | Open tmux session |
+| `r` | Refresh details |
+| `q` / `Esc` | Back to normal mode |
+
+## Widget system
+
+The stats panel is composed of configurable widgets laid out in a responsive grid. Widgets can span the full panel width, half, or a third. Enable/disable and reorder widgets via `~/.config/overview/widgets.json`.
+
+| Widget | Span | Description |
+|--------|------|-------------|
+| Git Status | third | Working tree status, staged/modified/untracked counts |
+| Repo Meta | third | Commits, contributors, repo size, latest tag |
+| GitHub CI | third | Recent workflow runs and their status |
+| Commit Activity | third | 14-day commit sparkline |
+| Latest Release | third | Latest GitHub release and commits since |
+| Devpad Milestones | half | Project milestones from devpad |
+| GitHub PRs | half | Open pull requests |
+| GitHub Issues | half | Open issues |
+| File Changes | half | Modified/staged/untracked file list |
+| Branches | half | Local and remote branches |
+| Devpad Tasks | full | Task list from devpad |
+
+## OpenCode integration
+
+Overview reads [OpenCode](https://github.com/sst/opencode) session state files from `~/.local/state/ocn/` and shows per-repo status indicators in the repo list (`*` busy, `>` needs input, `!` errored). This requires the [ocn](https://github.com/f0rbit/ocn) OpenCode plugin to be installed. Overview works fine without it -- the badges simply won't appear.
+
+## Architecture
+
+Bun workspace monorepo with two packages:
+
+```
+overview/
+├── packages/
+│   ├── core/           # git operations, scanning, file watching
+│   │   └── src/
+│   │       ├── scanner.ts       # directory tree walker, repo discovery
+│   │       ├── worktree.ts      # worktree detection and grouping
+│   │       ├── git-status.ts    # parallel status collection via Bun.spawn
+│   │       ├── git-graph.ts     # git log --graph capture (ANSI passthrough)
+│   │       ├── git-stats.ts     # heavyweight stats (on-demand)
+│   │       ├── concurrency.ts   # subprocess pool (capped at 8)
+│   │       ├── ocn.ts           # OpenCode session status reader
+│   │       ├── watcher.ts       # fs.watch on .git dirs for live updates
+│   │       └── types.ts         # core data model
+│   └── render/         # TUI components, screens, theming
+│       └── src/
+│           ├── overview.tsx      # entry point
+│           ├── screens/
+│           ├── components/       # repo list, git graph, widgets
+│           ├── lib/
+│           │   ├── widget-grid.ts     # grid layout computation
+│           │   ├── widget-state.ts    # widget config persistence
+│           │   ├── fetch-context.ts   # request deduplication
+│           │   └── filter.ts          # repo filtering/sorting
+│           ├── config/
+│           └── theme/            # Tokyo Night color scheme
+├── package.json
+└── tsconfig.json
+```
+
+Data flows one direction: `core` scans and collects git data, `render` subscribes to it via SolidJS signals. The git graph panel renders `git log --graph --color=always` output directly -- no DAG parsing. Press `g` to launch ggi for interactive graph exploration (suspends the TUI, resumes on exit).
+
+## Performance
+
+- Debounced repo selection (250ms) with request cancellation
+- Capped subprocess concurrency (pool of 8)
+- Deduplicated GitHub and Devpad API calls via in-flight tracking
+- Memoized computations to avoid redundant re-renders
+
+## Dependencies
+
+### Runtime
+
+| Dependency | Purpose |
+|------------|---------|
+| [Bun](https://bun.sh) | Runtime, bundler, test runner |
+| [@opentui/solid](https://github.com/anomalyco/opentui) | TUI rendering framework ([docs](https://opentui.com)) |
+| [SolidJS](https://www.solidjs.com/) | Reactive UI primitives |
+| [@f0rbit/corpus](https://github.com/f0rbit/corpus) | `Result<T, E>` error handling -- no thrown exceptions |
+| [@devpad/api](https://github.com/f0rbit/devpad) | Devpad project/task management client |
+
+### System (optional)
+
+| Tool | Purpose |
+|------|---------|
+| `git` | Core data source (required) |
+| `gh` | GitHub CLI for PR, issue, CI, and release widgets |
+| [`fzf`](https://github.com/junegunn/fzf) | Interactive filtering for ggi integration |
+| [`delta`](https://github.com/dandavison/delta) | Diff rendering for ggi integration |
+
+### Dev
+
+| Dependency | Purpose |
+|------------|---------|
+| TypeScript | Type checking |
+| [Biome](https://biomejs.dev/) | Linting and formatting |
+
+## License
+
+MIT

package/bunfig.toml

@@ -0,0 +1,7 @@
+preload = ["@opentui/solid/preload"]
+
+[compilerOptions]
+jsxImportSource = "solid-js"
+jsx = "preserve"
+
+[test]

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@f0rbit/overview",
+  "version": "0.1.0",
+  "description": "Terminal UI dashboard for multi-repo git health",
+  "workspaces": ["packages/*"],
+  "bin": {
+    "overview": "packages/render/src/overview.tsx"
+  },
+  "files": [
+    "packages/",
+    "bunfig.toml",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "dev": "bun run --filter @overview/render dev",
+    "typecheck": "bun run --filter '*' typecheck",
+    "lint": "biome check .",
+    "test": "bun test",
+    "build": "bun build packages/render/src/overview.tsx --compile --outfile overview"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/f0rbit/overview.git"
+  },
+  "license": "MIT",
+  "keywords": ["git", "tui", "terminal", "dashboard", "bun", "solidjs"],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/bun": "latest",
+    "@biomejs/biome": "^1.9.0"
+  },
+  "dependencies": {
+    "@devpad/api": "^2.0.4",
+    "@f0rbit/corpus": "^0.3.5",
+    "@opentui/core": "^0.1.80",
+    "@opentui/solid": "^0.1.80",
+    "solid-js": "^1.9.11"
+  }
+}

package/packages/core/__tests__/concurrency.test.ts

@@ -0,0 +1,111 @@
+import { describe, test, expect } from "bun:test";
+import { createPool } from "../src/concurrency";
+
+describe("createPool", () => {
+	test("respects concurrency limit", async () => {
+		const pool = createPool(2);
+		let max_concurrent = 0;
+		let current = 0;
+
+		const task = async () => {
+			current++;
+			max_concurrent = Math.max(max_concurrent, current);
+			await Bun.sleep(30);
+			current--;
+		};
+
+		await Promise.all([
+			pool.run(task),
+			pool.run(task),
+			pool.run(task),
+			pool.run(task),
+			pool.run(task),
+		]);
+
+		expect(max_concurrent).toBe(2);
+		expect(current).toBe(0);
+	});
+
+	test("all tasks complete", async () => {
+		const pool = createPool(3);
+		const results: number[] = [];
+
+		const tasks = Array.from({ length: 10 }, (_, i) =>
+			pool.run(async () => {
+				await Bun.sleep(10);
+				results.push(i);
+				return i;
+			}),
+		);
+
+		const returned = await Promise.all(tasks);
+
+		expect(returned).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+		expect(results).toHaveLength(10);
+	});
+
+	test("errors propagate correctly", async () => {
+		const pool = createPool(2);
+
+		const failing = pool.run(async () => {
+			throw new Error("boom");
+		});
+
+		await expect(failing).rejects.toThrow("boom");
+
+		// Pool should still work after error
+		const result = await pool.run(async () => "ok");
+		expect(result).toBe("ok");
+	});
+
+	test("queued tasks run as active tasks complete", async () => {
+		const pool = createPool(1);
+		const order: string[] = [];
+
+		const p1 = pool.run(async () => {
+			await Bun.sleep(30);
+			order.push("first");
+		});
+
+		const p2 = pool.run(async () => {
+			order.push("second");
+		});
+
+		await Promise.all([p1, p2]);
+		expect(order).toEqual(["first", "second"]);
+	});
+
+	test("active_count and queue_length track state", async () => {
+		const pool = createPool(2);
+		const started: Array<() => void> = [];
+
+		// Create tasks that block until we release them
+		const make_blocking = () =>
+			pool.run(() => new Promise<void>((resolve) => { started.push(resolve); }));
+
+		const p1 = make_blocking();
+		const p2 = make_blocking();
+		const p3 = make_blocking();
+
+		// Wait for first two to start
+		await Bun.sleep(10);
+
+		expect(pool.active_count).toBe(2);
+		expect(pool.queue_length).toBe(1);
+
+		// Release first task
+		started[0]!();
+		await Bun.sleep(10);
+
+		expect(pool.active_count).toBe(2); // third task started
+		expect(pool.queue_length).toBe(0);
+
+		// Release remaining
+		started[1]!();
+		started[2]!();
+		await Promise.all([p1, p2, p3]);
+
+		expect(pool.active_count).toBe(0);
+		expect(pool.queue_length).toBe(0);
+	});
+});

package/packages/core/__tests__/helpers.ts

@@ -0,0 +1,60 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+async function run(args: string[], cwd: string): Promise<void> {
+	const proc = Bun.spawn(args, { cwd, stdout: "pipe", stderr: "pipe" });
+	const code = await proc.exited;
+	if (code !== 0) {
+		const stderr = await new Response(proc.stderr).text();
+		throw new Error(`Command failed: ${args.join(" ")}\n${stderr}`);
+	}
+}
+
+export async function createTempDir(): Promise<string> {
+	return mkdtemp(join(tmpdir(), "overview-test-"));
+}
+
+export async function cleanupTempDir(dir: string): Promise<void> {
+	await rm(dir, { recursive: true, force: true });
+}
+
+export async function initRepo(dir: string, name: string): Promise<string> {
+	const repo_path = join(dir, name);
+	await Bun.spawn(["mkdir", "-p", repo_path]).exited;
+	await run(["git", "init"], repo_path);
+	await run(["git", "config", "user.email", "test@test.com"], repo_path);
+	await run(["git", "config", "user.name", "Test User"], repo_path);
+	await Bun.write(join(repo_path, "README.md"), "# " + name);
+	await run(["git", "add", "."], repo_path);
+	await run(["git", "commit", "-m", "initial commit"], repo_path);
+	return repo_path;
+}
+
+export async function addCommit(
+	repoPath: string,
+	filename: string,
+	content: string,
+	message: string,
+): Promise<void> {
+	await Bun.write(join(repoPath, filename), content);
+	await run(["git", "add", filename], repoPath);
+	await run(["git", "commit", "-m", message], repoPath);
+}
+
+export async function createBranch(repoPath: string, branchName: string): Promise<void> {
+	await run(["git", "checkout", "-b", branchName], repoPath);
+}
+
+export async function modifyFile(repoPath: string, filename: string, content: string): Promise<void> {
+	await Bun.write(join(repoPath, filename), content);
+}
+
+export async function addUntracked(repoPath: string, filename: string, content: string): Promise<void> {
+	await Bun.write(join(repoPath, filename), content);
+}
+
+export async function stashChanges(repoPath: string): Promise<void> {
+	await Bun.write(join(repoPath, "README.md"), "stash content");
+	await run(["git", "stash"], repoPath);
+}

package/packages/core/__tests__/integration/git-status.test.ts

@@ -0,0 +1,62 @@
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { collectStatus } from "../../src/git-status";
+import {
+	createTempDir,
+	cleanupTempDir,
+	initRepo,
+	stashChanges,
+} from "../helpers";
+
+describe("git-status integration", () => {
+	let temp_dir: string;
+
+	beforeAll(async () => {
+		temp_dir = await createTempDir();
+	});
+
+	afterAll(async () => {
+		await cleanupTempDir(temp_dir);
+	});
+
+	test("parses branch info", async () => {
+		const dir = join(temp_dir, "branch-test");
+		await mkdir(dir, { recursive: true });
+		const repo_path = await initRepo(dir, "branch-repo");
+
+		const result = await collectStatus(repo_path, dir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		// git init may default to "main" or "master"
+		expect(["main", "master"]).toContain(result.value.current_branch);
+	});
+
+	test("detects stashes", async () => {
+		const dir = join(temp_dir, "stash-test");
+		await mkdir(dir, { recursive: true });
+		const repo_path = await initRepo(dir, "stash-repo");
+		await stashChanges(repo_path);
+
+		const result = await collectStatus(repo_path, dir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		expect(result.value.stash_count).toBeGreaterThan(0);
+	});
+
+	test("handles repo with no remote", async () => {
+		const dir = join(temp_dir, "no-remote-test");
+		await mkdir(dir, { recursive: true });
+		const repo_path = await initRepo(dir, "no-remote-repo");
+
+		const result = await collectStatus(repo_path, dir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		expect(result.value.remote_url).toBeNull();
+		expect(result.value.ahead).toBe(0);
+		expect(result.value.behind).toBe(0);
+	});
+});

package/packages/core/__tests__/integration/scanner.test.ts

@@ -0,0 +1,140 @@
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { scanDirectory, scanAndCollect } from "../../src/index";
+import {
+	createTempDir,
+	cleanupTempDir,
+	initRepo,
+	addCommit,
+	modifyFile,
+	addUntracked,
+} from "../helpers";
+
+describe("scanner integration", () => {
+	let temp_dir: string;
+
+	beforeAll(async () => {
+		temp_dir = await createTempDir();
+	});
+
+	afterAll(async () => {
+		await cleanupTempDir(temp_dir);
+	});
+
+	test("discovers repos at root level", async () => {
+		const dir = join(temp_dir, "root-level");
+		await mkdir(dir, { recursive: true });
+		await initRepo(dir, "repo-a");
+		await initRepo(dir, "repo-b");
+		await initRepo(dir, "repo-c");
+
+		const result = await scanDirectory(dir, { depth: 1, ignore: [] });
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const repos = result.value.filter((n) => n.type === "repo");
+		expect(repos.length).toBe(3);
+		expect(repos.map((r) => r.name).sort()).toEqual(["repo-a", "repo-b", "repo-c"]);
+	});
+
+	test("discovers nested repos", async () => {
+		const dir = join(temp_dir, "nested");
+		await mkdir(dir, { recursive: true });
+		const nested_path = join(dir, "a", "b");
+		await mkdir(nested_path, { recursive: true });
+		await initRepo(nested_path, "repo1");
+
+		const result = await scanDirectory(dir, { depth: 4, ignore: [] });
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const find_repo = (nodes: typeof result.value): boolean =>
+			nodes.some((n) => (n.type === "repo" && n.name === "repo1") || find_repo(n.children));
+
+		expect(find_repo(result.value)).toBe(true);
+	});
+
+	test("ignores directories matching ignore patterns", async () => {
+		const dir = join(temp_dir, "ignore-test");
+		await mkdir(dir, { recursive: true });
+		await initRepo(dir, "good-repo");
+		const nm_dir = join(dir, "node_modules");
+		await mkdir(nm_dir, { recursive: true });
+		await initRepo(nm_dir, "hidden-repo");
+
+		const result = await scanDirectory(dir, { depth: 2, ignore: ["node_modules"] });
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const all_names = flatNames(result.value);
+		expect(all_names).toContain("good-repo");
+		expect(all_names).not.toContain("node_modules");
+		expect(all_names).not.toContain("hidden-repo");
+	});
+
+	test("collects status for clean repo", async () => {
+		const dir = join(temp_dir, "clean-test");
+		await mkdir(dir, { recursive: true });
+		await initRepo(dir, "clean-repo");
+		await addCommit(join(dir, "clean-repo"), "file.txt", "content", "add file");
+
+		const result = await scanAndCollect(dir, { depth: 1, ignore: [] });
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const repo = result.value.find((n) => n.name === "clean-repo");
+		expect(repo).toBeDefined();
+		expect(repo!.status).not.toBeNull();
+		expect(repo!.status!.is_clean).toBe(true);
+		expect(repo!.status!.health).toBe("clean");
+	});
+
+	test("detects dirty state", async () => {
+		const dir = join(temp_dir, "dirty-test");
+		await mkdir(dir, { recursive: true });
+		const repo_path = await initRepo(dir, "dirty-repo");
+		await addCommit(repo_path, "file.txt", "original", "add file");
+		await modifyFile(repo_path, "file.txt", "modified content");
+
+		const result = await scanAndCollect(dir, { depth: 1, ignore: [] });
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const repo = result.value.find((n) => n.name === "dirty-repo");
+		expect(repo).toBeDefined();
+		expect(repo!.status).not.toBeNull();
+		expect(repo!.status!.modified_count).toBeGreaterThan(0);
+		expect(repo!.status!.health).toBe("dirty");
+	});
+
+	test("detects untracked files", async () => {
+		const dir = join(temp_dir, "untracked-test");
+		await mkdir(dir, { recursive: true });
+		const repo_path = await initRepo(dir, "untracked-repo");
+		await addUntracked(repo_path, "new-file.txt", "untracked content");
+
+		const result = await scanAndCollect(dir, { depth: 1, ignore: [] });
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const repo = result.value.find((n) => n.name === "untracked-repo");
+		expect(repo).toBeDefined();
+		expect(repo!.status).not.toBeNull();
+		expect(repo!.status!.untracked_count).toBeGreaterThan(0);
+	});
+
+	test("returns empty array for empty directory", async () => {
+		const dir = join(temp_dir, "empty-test");
+		await mkdir(dir, { recursive: true });
+
+		const result = await scanDirectory(dir, { depth: 1, ignore: [] });
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		expect(result.value).toEqual([]);
+	});
+});
+
+function flatNames(nodes: { name: string; children: typeof nodes }[]): string[] {
+	return nodes.flatMap((n) => [n.name, ...flatNames(n.children)]);
+}