@f0rbit/overview 0.1.0

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

@@ -0,0 +1,164 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { readOcnStates } from "../src/ocn";
+
+describe("readOcnStates", () => {
+	let temp_dir: string;
+	const original_env = process.env.OCN_STATE_DIR;
+
+	beforeEach(async () => {
+		temp_dir = await mkdtemp(join(tmpdir(), "ocn-test-"));
+		process.env.OCN_STATE_DIR = temp_dir;
+	});
+
+	afterEach(async () => {
+		if (original_env !== undefined) {
+			process.env.OCN_STATE_DIR = original_env;
+		} else {
+			delete process.env.OCN_STATE_DIR;
+		}
+		await rm(temp_dir, { recursive: true, force: true });
+	});
+
+	test("returns empty map when state dir is empty", async () => {
+		const result = await readOcnStates();
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.size).toBe(0);
+		}
+	});
+
+	test("returns empty map when state dir does not exist", async () => {
+		process.env.OCN_STATE_DIR = join(temp_dir, "nonexistent");
+		const result = await readOcnStates();
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.size).toBe(0);
+		}
+	});
+
+	test("reads valid state file with alive PID", async () => {
+		const pid = process.pid; // current process is always alive
+		const state = {
+			pid,
+			directory: "/Users/tom/dev/test-repo",
+			project: "test-repo",
+			status: "busy",
+			last_transition: "2026-01-01T00:00:00Z",
+			session_id: "ses_test123",
+		};
+		await writeFile(join(temp_dir, `${pid}.json`), JSON.stringify(state));
+
+		const result = await readOcnStates();
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.size).toBe(1);
+			const entry = result.value.get("/Users/tom/dev/test-repo");
+			expect(entry).toBeDefined();
+			expect(entry!.pid).toBe(pid);
+			expect(entry!.status).toBe("busy");
+			expect(entry!.session_id).toBe("ses_test123");
+		}
+	});
+
+	test("filters out stale PIDs", async () => {
+		const state = {
+			pid: 99999999, // very unlikely to be a running process
+			directory: "/Users/tom/dev/stale-repo",
+			project: "stale-repo",
+			status: "busy",
+			last_transition: "2026-01-01T00:00:00Z",
+			session_id: "ses_stale",
+		};
+		await writeFile(join(temp_dir, "99999999.json"), JSON.stringify(state));
+
+		const result = await readOcnStates();
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.size).toBe(0);
+		}
+	});
+
+	test("skips malformed JSON files", async () => {
+		await writeFile(join(temp_dir, "bad.json"), "not json {{{");
+		// Also write a valid one with alive PID
+		const pid = process.pid;
+		const state = {
+			pid,
+			directory: "/Users/tom/dev/good-repo",
+			project: "good-repo",
+			status: "idle",
+			last_transition: "2026-01-01T00:00:00Z",
+			session_id: "ses_good",
+		};
+		await writeFile(join(temp_dir, `${pid}.json`), JSON.stringify(state));
+
+		const result = await readOcnStates();
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.size).toBe(1);
+			expect(result.value.has("/Users/tom/dev/good-repo")).toBe(true);
+		}
+	});
+
+	test("skips files with invalid status values", async () => {
+		const pid = process.pid;
+		const state = {
+			pid,
+			directory: "/Users/tom/dev/invalid",
+			project: "invalid",
+			status: "unknown_status",
+			last_transition: "2026-01-01T00:00:00Z",
+			session_id: "ses_invalid",
+		};
+		await writeFile(join(temp_dir, `${pid}.json`), JSON.stringify(state));
+
+		const result = await readOcnStates();
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.size).toBe(0);
+		}
+	});
+
+	test("skips non-json files", async () => {
+		await writeFile(join(temp_dir, "readme.txt"), "not a state file");
+		const result = await readOcnStates();
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.size).toBe(0);
+		}
+	});
+
+	test("reads multiple state files", async () => {
+		const pid = process.pid;
+		const state1 = {
+			pid,
+			directory: "/Users/tom/dev/repo-a",
+			project: "repo-a",
+			status: "busy",
+			last_transition: "2026-01-01T00:00:00Z",
+			session_id: "ses_a",
+		};
+		const state2 = {
+			pid,
+			directory: "/Users/tom/dev/repo-b",
+			project: "repo-b",
+			status: "prompting",
+			last_transition: "2026-01-01T00:00:00Z",
+			session_id: "ses_b",
+		};
+		// Use different filenames (same pid but different entries)
+		await writeFile(join(temp_dir, `${pid}.json`), JSON.stringify(state1));
+		await writeFile(join(temp_dir, `${pid}_2.json`), JSON.stringify(state2));
+
+		const result = await readOcnStates();
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.size).toBe(2);
+			expect(result.value.get("/Users/tom/dev/repo-a")?.status).toBe("busy");
+			expect(result.value.get("/Users/tom/dev/repo-b")?.status).toBe("prompting");
+		}
+	});
+});

package/packages/core/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@overview/core",
+  "version": "0.1.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@f0rbit/corpus": "link:@f0rbit/corpus",
+    "@devpad/api": "link:@devpad/api"
+  }
+}

package/packages/core/src/cache.ts

@@ -0,0 +1,31 @@
+export interface CacheEntry<T> {
+	data: T;
+	fetched_at: number;
+	ttl_ms: number;
+}
+
+export class DataCache<T> {
+	private entries = new Map<string, CacheEntry<T>>();
+
+	get(key: string): T | null {
+		const entry = this.entries.get(key);
+		if (!entry) return null;
+		if (Date.now() - entry.fetched_at > entry.ttl_ms) {
+			this.entries.delete(key);
+			return null;
+		}
+		return entry.data;
+	}
+
+	set(key: string, data: T, ttl_ms: number): void {
+		this.entries.set(key, { data, fetched_at: Date.now(), ttl_ms });
+	}
+
+	invalidate(key: string): void {
+		this.entries.delete(key);
+	}
+
+	clear(): void {
+		this.entries.clear();
+	}
+}

package/packages/core/src/concurrency.ts

@@ -0,0 +1,44 @@
+/**
+ * Concurrency pool — limits the number of concurrent async operations.
+ *
+ * Use when spawning many parallel subprocesses (e.g., scanning 50+ repos at startup)
+ * to avoid overwhelming the system.
+ */
+export function createPool(concurrency: number) {
+	let active = 0;
+	const queue: Array<() => void> = [];
+
+	function release() {
+		active--;
+		const next = queue.shift();
+		if (next) {
+			active++;
+			next();
+		}
+	}
+
+	return {
+		/** Run an async function within the concurrency limit */
+		async run<T>(fn: () => Promise<T>): Promise<T> {
+			if (active < concurrency) {
+				active++;
+				try {
+					return await fn();
+				} finally {
+					release();
+				}
+			}
+			return new Promise<T>((resolve, reject) => {
+				queue.push(() => {
+					fn().then(resolve, reject).finally(release);
+				});
+			});
+		},
+
+		/** Current number of active tasks */
+		get active_count() { return active; },
+
+		/** Current number of queued tasks */
+		get queue_length() { return queue.length; },
+	};
+}

package/packages/core/src/devpad.ts

@@ -0,0 +1,61 @@
+export interface DevpadProject {
+	id: string;
+	project_id: string;
+	name: string;
+	description: string | null;
+	status: string;
+	repo_url: string | null;
+}
+
+export interface DevpadTask {
+	id: string;
+	title: string;
+	description: string | null;
+	priority: "LOW" | "MEDIUM" | "HIGH";
+	progress: "UNSTARTED" | "IN_PROGRESS" | "COMPLETED";
+	project_id: string | null;
+	tags: string[];
+}
+
+export interface DevpadMilestone {
+	id: string;
+	name: string;
+	target_version: string | null;
+	target_time: string | null;
+	finished_at: string | null;
+	goals_total: number;
+	goals_completed: number;
+}
+
+export interface DevpadRepoData {
+	project: DevpadProject | null;
+	tasks: DevpadTask[];
+	milestones: DevpadMilestone[];
+}
+
+export function normalizeGitUrl(url: string): string {
+	let normalized = url
+		.trim()
+		.replace(/\.git$/, "")
+		.replace(/\/$/, "");
+	const ssh_match = normalized.match(/^git@([^:]+):(.+)$/);
+	if (ssh_match) {
+		normalized = `https://${ssh_match[1]}/${ssh_match[2]}`;
+	}
+	return normalized.toLowerCase();
+}
+
+export function matchRepoToProject(
+	remote_url: string | null,
+	repo_name: string,
+	projects: DevpadProject[],
+): DevpadProject | null {
+	if (remote_url) {
+		const normalized = normalizeGitUrl(remote_url);
+		const match = projects.find(
+			(p) => p.repo_url && normalizeGitUrl(p.repo_url) === normalized,
+		);
+		if (match) return match;
+	}
+	return projects.find((p) => p.project_id === repo_name) ?? null;
+}

package/packages/core/src/git-graph.ts

@@ -0,0 +1,54 @@
+import { ok, err, type Result } from "@f0rbit/corpus";
+import type { GitGraphOutput } from "./types";
+
+export type GitGraphError = { kind: "graph_failed"; path: string; cause: string };
+
+const DEFAULT_LIMIT = 40;
+
+// Strip ANSI escape codes in case git config forces color
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+const stripAnsi = (s: string): string => s.replace(ANSI_RE, "");
+
+const stripTrailingEmpty = (lines: string[]): string[] => {
+	let end = lines.length;
+	while (end > 0 && lines[end - 1]!.trim() === "") end--;
+	return lines.slice(0, end);
+};
+
+export async function captureGraph(
+	repoPath: string,
+	options?: { limit?: number },
+): Promise<Result<GitGraphOutput, GitGraphError>> {
+	const limit = options?.limit ?? DEFAULT_LIMIT;
+
+	const proc = Bun.spawn(
+		["git", "log", "--graph", "--all", "--decorate", "--oneline", `-n`, `${limit}`, "--color=never"],
+		{
+			cwd: repoPath,
+			stdout: "pipe",
+			stderr: "pipe",
+		},
+	);
+
+	const [stdout, stderr, exit_code] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+
+	if (exit_code !== 0) {
+		// empty repo (no commits) exits non-zero — treat as empty
+		if (stderr.includes("does not have any commits")) {
+			return ok({ lines: [], total_lines: 0, repo_path: repoPath });
+		}
+		return err({ kind: "graph_failed", path: repoPath, cause: stderr.trim() });
+	}
+
+	const lines = stripTrailingEmpty(stdout.split("\n").map(stripAnsi));
+
+	return ok({
+		lines,
+		total_lines: lines.length,
+		repo_path: repoPath,
+	});
+}

package/packages/core/src/git-stats.ts

@@ -0,0 +1,201 @@
+// Heavyweight on-demand git stats
+import { ok, err, type Result } from "@f0rbit/corpus";
+import type { RecentCommit } from "./types";
+
+export type GitStatsError =
+	| { kind: "not_a_repo"; path: string }
+	| { kind: "stats_failed"; path: string; cause: string };
+
+export interface ExtendedStats {
+	contributor_count: number;
+	contributors: string[];
+	repo_size_bytes: number;
+	tags: string[];
+	recent_commits: RecentCommit[];
+	total_commits: number;
+}
+
+async function git(args: string[], cwd: string): Promise<Result<string, GitStatsError>> {
+	try {
+		const proc = Bun.spawn(["git", ...args], {
+			cwd,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+
+		const [stdout, stderr, exit_code] = await Promise.all([
+			new Response(proc.stdout).text(),
+			new Response(proc.stderr).text(),
+			proc.exited,
+		]);
+
+		if (exit_code !== 0) {
+			if (stderr.includes("not a git repository")) {
+				return err({ kind: "not_a_repo", path: cwd });
+			}
+			return err({ kind: "stats_failed", path: cwd, cause: stderr.trim() });
+		}
+
+		return ok(stdout);
+	} catch (e) {
+		return err({
+			kind: "stats_failed",
+			path: cwd,
+			cause: e instanceof Error ? e.message : String(e),
+		});
+	}
+}
+
+export function parseSize(size_str: string): number {
+	const trimmed = size_str.trim();
+	if (trimmed === "0 bytes" || trimmed === "0") return 0;
+
+	const match = trimmed.match(/^([\d.]+)\s*(\w+)?$/);
+	if (!match) return 0;
+
+	const value = parseFloat(match[1] ?? "0");
+	const unit = (match[2] ?? "bytes").toLowerCase();
+
+	const multipliers: Record<string, number> = {
+		bytes: 1,
+		kib: 1024,
+		mib: 1024 * 1024,
+		gib: 1024 * 1024 * 1024,
+	};
+
+	return Math.round(value * (multipliers[unit] ?? 1));
+}
+
+function parseContributors(output: string): { contributors: string[]; contributor_count: number } {
+	const contributors = output
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0)
+		.map((line) => line.replace(/^\d+\t/, ""));
+
+	return { contributors, contributor_count: contributors.length };
+}
+
+function parseRepoSize(output: string): number {
+	const lines = output.split("\n");
+	let total = 0;
+
+	for (const line of lines) {
+		if (line.startsWith("size:") || line.startsWith("size-pack:")) {
+			const size_str = line.replace(/^size(?:-pack)?:/, "").trim();
+			total += parseSize(size_str);
+		}
+	}
+
+	return total;
+}
+
+function parseTags(output: string): string[] {
+	return output
+		.split("\n")
+		.map((t) => t.trim())
+		.filter((t) => t.length > 0);
+}
+
+function parseRecentCommits(output: string): RecentCommit[] {
+	return output
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0)
+		.map((line) => {
+			const [hash, message, author, time_str] = line.split(":");
+			return {
+				hash: hash ?? "",
+				message: message ?? "",
+				author: author ?? "",
+				time: parseInt(time_str ?? "0", 10),
+			};
+		});
+}
+
+function parseTotalCommits(output: string): number {
+	const n = parseInt(output.trim(), 10);
+	return isNaN(n) ? 0 : n;
+}
+
+export interface CommitActivity {
+	daily_counts: number[];
+	total_this_week: number;
+	total_last_week: number;
+}
+
+function bucketIntoDays(timestamps: number[]): number[] {
+	const now = new Date();
+	const today_start = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+	const counts = new Array<number>(14).fill(0);
+
+	for (const ts of timestamps) {
+		const ms = ts * 1000;
+		const days_ago = Math.floor((today_start - ms) / (24 * 60 * 60 * 1000));
+		const index = 13 - days_ago;
+		if (index >= 0 && index < 14) counts[index] = (counts[index] ?? 0) + 1;
+	}
+
+	return counts;
+}
+
+export async function collectCommitActivity(
+	repo_path: string,
+): Promise<Result<CommitActivity, GitStatsError>> {
+	const log_r = await git(["log", "--format=%at", "--since=14 days ago", "--all"], repo_path);
+
+	if (!log_r.ok) return err(log_r.error);
+
+	const timestamps = log_r.value
+		.split("\n")
+		.map((l) => l.trim())
+		.filter((l) => l.length > 0)
+		.map((l) => parseInt(l, 10))
+		.filter((n) => !isNaN(n));
+
+	const daily_counts = bucketIntoDays(timestamps);
+	const total_last_week = daily_counts.slice(0, 7).reduce((a, b) => a + b, 0);
+	const total_this_week = daily_counts.slice(7).reduce((a, b) => a + b, 0);
+
+	return ok({ daily_counts, total_this_week, total_last_week });
+}
+
+export async function collectStats(
+	repoPath: string,
+): Promise<Result<ExtendedStats, GitStatsError>> {
+	const [shortlog_r, count_objects_r, tags_r, log_r, rev_list_r] = await Promise.all([
+		git(["shortlog", "-sn", "--all"], repoPath),
+		git(["count-objects", "-vH"], repoPath),
+		git(["tag", "--list", "--sort=-version:refname"], repoPath),
+		git(["log", "-5", "--format=%h:%s:%an:%at"], repoPath),
+		git(["rev-list", "--count", "HEAD"], repoPath),
+	]);
+
+	// not_a_repo is fatal — check any result for it
+	for (const r of [shortlog_r, count_objects_r, tags_r, log_r, rev_list_r]) {
+		if (!r.ok && r.error.kind === "not_a_repo") return err(r.error);
+	}
+
+	const { contributors, contributor_count } = shortlog_r.ok
+		? parseContributors(shortlog_r.value)
+		: { contributors: [], contributor_count: 0 };
+
+	const repo_size_bytes = count_objects_r.ok
+		? parseRepoSize(count_objects_r.value)
+		: 0;
+
+	const tags = tags_r.ok ? parseTags(tags_r.value) : [];
+
+	const recent_commits = log_r.ok ? parseRecentCommits(log_r.value) : [];
+
+	const total_commits = rev_list_r.ok ? parseTotalCommits(rev_list_r.value) : 0;
+
+	return ok({
+		contributor_count,
+		contributors,
+		repo_size_bytes,
+		tags,
+		recent_commits,
+		total_commits,
+	});
+}