@residue/cli 0.0.1

package/src/lib/pending.ts

@@ -0,0 +1,190 @@
+/**
+ * Pending queue management for the residue CLI.
+ * Manages .residue/pending.json in the project root.
+ */
+
+import { mkdir } from "fs/promises";
+import { errAsync, ResultAsync } from "neverthrow";
+import { join } from "path";
+import { CliError, toCliError } from "@/utils/errors";
+
+export type CommitRef = {
+	sha: string;
+	branch: string;
+};
+
+export type PendingSession = {
+	id: string;
+	agent: string;
+	agent_version: string;
+	status: "open" | "ended";
+	data_path: string;
+	commits: CommitRef[];
+};
+
+/**
+ * Get the project root via git rev-parse --show-toplevel.
+ */
+export function getProjectRoot(): ResultAsync<string, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			const proc = Bun.spawn(["git", "rev-parse", "--show-toplevel"], {
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			const exitCode = await proc.exited;
+			if (exitCode !== 0) {
+				throw new Error("not a git repository");
+			}
+			return (await new Response(proc.stdout).text()).trim();
+		})(),
+		toCliError({ message: "Not a git repository", code: "GIT_ERROR" }),
+	);
+}
+
+/**
+ * Get the .residue directory path, creating it if needed.
+ */
+export function getResidueDir(
+	projectRoot: string,
+): ResultAsync<string, CliError> {
+	const residueDir = join(projectRoot, ".residue");
+	return ResultAsync.fromPromise(
+		(async () => {
+			await mkdir(residueDir, { recursive: true });
+			return residueDir;
+		})(),
+		toCliError({
+			message: "Failed to create .residue directory",
+			code: "IO_ERROR",
+		}),
+	);
+}
+
+/**
+ * Get the path to .residue/pending.json, creating the directory if needed.
+ */
+export function getPendingPath(
+	projectRoot: string,
+): ResultAsync<string, CliError> {
+	return getResidueDir(projectRoot).map((residueDir) =>
+		join(residueDir, "pending.json"),
+	);
+}
+
+/**
+ * Migrate old format where commits was string[] to CommitRef[].
+ */
+function migratePending(sessions: PendingSession[]): PendingSession[] {
+	for (const session of sessions) {
+		if (session.commits.length > 0 && typeof session.commits[0] === "string") {
+			session.commits = (session.commits as unknown as string[]).map((sha) => ({
+				sha,
+				branch: "unknown",
+			}));
+		}
+	}
+	return sessions;
+}
+
+/**
+ * Read pending sessions from disk. Returns [] if file doesn't exist.
+ * Handles backward compat: old format had commits as string[] (just SHAs).
+ */
+export function readPending(
+	pendingPath: string,
+): ResultAsync<PendingSession[], CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			const file = Bun.file(pendingPath);
+			const isExists = await file.exists();
+			if (!isExists) return [];
+			const text = await file.text();
+			const sessions = JSON.parse(text) as PendingSession[];
+			return migratePending(sessions);
+		})(),
+		toCliError({
+			message: "Failed to read pending queue",
+			code: "STATE_ERROR",
+		}),
+	);
+}
+
+/**
+ * Write pending sessions to disk.
+ */
+export function writePending(opts: {
+	path: string;
+	sessions: PendingSession[];
+}): ResultAsync<void, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			await Bun.write(opts.path, JSON.stringify(opts.sessions, null, 2));
+		})(),
+		toCliError({
+			message: "Failed to write pending queue",
+			code: "STATE_ERROR",
+		}),
+	);
+}
+
+/**
+ * Add a session to the pending queue.
+ */
+export function addSession(opts: {
+	path: string;
+	session: PendingSession;
+}): ResultAsync<void, CliError> {
+	return readPending(opts.path).andThen((sessions) => {
+		sessions.push(opts.session);
+		return writePending({ path: opts.path, sessions });
+	});
+}
+
+/**
+ * Update a session by ID with partial updates.
+ */
+export function updateSession(opts: {
+	path: string;
+	id: string;
+	updates: Partial<PendingSession>;
+}): ResultAsync<void, CliError> {
+	return readPending(opts.path).andThen((sessions) => {
+		const index = sessions.findIndex((s) => s.id === opts.id);
+		if (index === -1) {
+			return errAsync(
+				new CliError({
+					message: `Session not found: ${opts.id}`,
+					code: "SESSION_NOT_FOUND",
+				}),
+			);
+		}
+		sessions[index] = { ...sessions[index], ...opts.updates };
+		return writePending({ path: opts.path, sessions });
+	});
+}
+
+/**
+ * Remove a session by ID.
+ */
+export function removeSession(opts: {
+	path: string;
+	id: string;
+}): ResultAsync<void, CliError> {
+	return readPending(opts.path).andThen((sessions) => {
+		const filtered = sessions.filter((s) => s.id !== opts.id);
+		return writePending({ path: opts.path, sessions: filtered });
+	});
+}
+
+/**
+ * Get a session by ID.
+ */
+export function getSession(opts: {
+	path: string;
+	id: string;
+}): ResultAsync<PendingSession | undefined, CliError> {
+	return readPending(opts.path).map((sessions) =>
+		sessions.find((s) => s.id === opts.id),
+	);
+}

package/src/types/text-import.d.ts

@@ -0,0 +1,4 @@
+declare module "*.txt" {
+	const content: string;
+	export default content;
+}

package/src/utils/errors.ts

@@ -0,0 +1,75 @@
+import type { ResultAsync } from "neverthrow";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("cli");
+
+type CliErrorCode =
+	| "GIT_ERROR"
+	| "GIT_PARSE_ERROR"
+	| "CONFIG_ERROR"
+	| "CONFIG_MISSING"
+	| "STATE_ERROR"
+	| "SESSION_NOT_FOUND"
+	| "IO_ERROR"
+	| "NETWORK_ERROR"
+	| "VALIDATION_ERROR"
+	| "PARSE_ERROR";
+
+class CliError extends Error {
+	readonly _tag = "CliError" as const;
+	readonly code: CliErrorCode;
+
+	constructor(opts: { message: string; code: CliErrorCode; cause?: unknown }) {
+		super(opts.message, { cause: opts.cause });
+		this.name = "CliError";
+		this.code = opts.code;
+	}
+}
+
+const isCliError = (error: unknown): error is CliError => {
+	return error instanceof CliError;
+};
+
+/**
+ * Creates an error handler for ResultAsync.fromPromise that wraps
+ * the caught value into a CliError.
+ */
+const toCliError =
+	(opts: { message: string; code: CliErrorCode }) =>
+	(cause: unknown): CliError =>
+		new CliError({ ...opts, cause });
+
+type CommandFn = (...args: never[]) => ResultAsync<void, CliError>;
+
+// Wraps a command that returns ResultAsync<void, CliError> with consistent error handling.
+// On Err, prints to stderr and exits with the given code.
+function wrapCommand<T extends CommandFn>(
+	fn: T,
+	opts?: { exitCode?: number },
+): (...args: Parameters<T>) => Promise<void> {
+	const exitCode = opts?.exitCode ?? 1;
+	return async (...args: Parameters<T>) => {
+		const result = await fn(...args);
+		if (result.isErr()) {
+			log.error(result.error);
+			process.exit(exitCode);
+		}
+	};
+}
+
+// Wraps a command that should never block git operations (hooks).
+// Errors are printed as warnings and exit 0 so git proceeds.
+function wrapHookCommand<T extends CommandFn>(
+	fn: T,
+): (...args: Parameters<T>) => Promise<void> {
+	return wrapCommand(fn, { exitCode: 0 });
+}
+
+export {
+	CliError,
+	type CliErrorCode,
+	isCliError,
+	toCliError,
+	wrapCommand,
+	wrapHookCommand,
+};

package/src/utils/logger.ts

@@ -0,0 +1,51 @@
+import createDebug from "debug";
+
+const BASE_NAMESPACE = "residue";
+
+type Loggable = string | Error;
+
+function formatMessage(value: Loggable): string {
+	if (typeof value === "string") return value;
+	return value.message;
+}
+
+/**
+ * Lightweight CLI logger wrapping the `debug` package.
+ *
+ * Levels:
+ *   log.debug(msg)        -- only visible when DEBUG=residue:* or DEBUG=residue:<ns>
+ *   log.info(msg)         -- always printed to stderr, plain message
+ *   log.warn(msg | error) -- always printed to stderr, prefixed with "Warning:"
+ *   log.error(msg | error)-- always printed to stderr, prefixed with "Error:"
+ *
+ * warn() and error() accept a string or an Error (including CliError).
+ * When given an Error, the .message is extracted automatically.
+ *
+ * All output goes to stderr so stdout stays clean for machine-readable
+ * data (e.g. session IDs piped back to agent adapters).
+ */
+function createLogger(namespace: string) {
+	const debug = createDebug(`${BASE_NAMESPACE}:${namespace}`);
+
+	return {
+		/** Diagnostic message. Only visible when DEBUG includes this namespace. */
+		debug,
+
+		/** User-facing status message. Always printed to stderr. */
+		info(message: string) {
+			process.stderr.write(`${message}\n`);
+		},
+
+		/** Warning. Always printed to stderr. Accepts a string or Error. */
+		warn(value: Loggable) {
+			process.stderr.write(`Warning: ${formatMessage(value)}\n`);
+		},
+
+		/** Error. Always printed to stderr. Accepts a string or Error. */
+		error(value: Loggable) {
+			process.stderr.write(`Error: ${formatMessage(value)}\n`);
+		},
+	};
+}
+
+export { createLogger, type Loggable };

package/test/commands/capture.test.ts

@@ -0,0 +1,206 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { readPending } from "@/lib/pending";
+
+let tempDir: string;
+
+const cliDir = join(import.meta.dir, "../..");
+const entry = join(cliDir, "src/index.ts");
+
+async function gitExec(args: string[]) {
+	const proc = Bun.spawn(["git", ...args], {
+		cwd: tempDir,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	await proc.exited;
+	return (await new Response(proc.stdout).text()).trim();
+}
+
+beforeEach(async () => {
+	tempDir = await mkdtemp(join(tmpdir(), "residue-capture-test-"));
+	await gitExec(["init"]);
+	await gitExec(["config", "user.email", "test@test.com"]);
+	await gitExec(["config", "user.name", "Test"]);
+	await writeFile(join(tempDir, "README.md"), "init");
+	await gitExec(["add", "."]);
+	await gitExec(["commit", "-m", "initial"]);
+});
+
+afterEach(async () => {
+	await rm(tempDir, { recursive: true, force: true });
+});
+
+function cli(args: string[]) {
+	return Bun.spawn(["bun", entry, ...args], {
+		cwd: tempDir,
+		stdout: "pipe",
+		stderr: "pipe",
+		env: { ...process.env },
+	});
+}
+
+describe("capture command", () => {
+	test("tags pending sessions with current commit SHA", async () => {
+		const startProc = cli([
+			"session",
+			"start",
+			"--agent",
+			"claude-code",
+			"--data",
+			"/tmp/s.jsonl",
+		]);
+		await startProc.exited;
+
+		await writeFile(join(tempDir, "file.txt"), "hello");
+		await gitExec(["add", "."]);
+		await gitExec(["commit", "-m", "test commit"]);
+		const sha = await gitExec(["rev-parse", "HEAD"]);
+
+		const captureProc = cli(["capture"]);
+		const exitCode = await captureProc.exited;
+
+		expect(exitCode).toBe(0);
+
+		const pendingPath = join(tempDir, ".residue/pending.json");
+		const sessions = (await readPending(pendingPath))._unsafeUnwrap();
+		expect(sessions).toHaveLength(1);
+		expect(sessions[0].commits.some((c) => c.sha === sha)).toBe(true);
+		expect(sessions[0].commits[0].branch).toBeDefined();
+	});
+
+	test("does not duplicate SHA on repeated capture", async () => {
+		const startProc = cli([
+			"session",
+			"start",
+			"--agent",
+			"claude-code",
+			"--data",
+			"/tmp/s.jsonl",
+		]);
+		await startProc.exited;
+
+		const c1 = cli(["capture"]);
+		await c1.exited;
+		const c2 = cli(["capture"]);
+		await c2.exited;
+
+		const pendingPath = join(tempDir, ".residue/pending.json");
+		const sessions = (await readPending(pendingPath))._unsafeUnwrap();
+		const sha = await gitExec(["rev-parse", "HEAD"]);
+		const count = sessions[0].commits.filter((c) => c.sha === sha).length;
+		expect(count).toBe(1);
+	});
+
+	test("tags ended sessions with zero commits (first capture after ending)", async () => {
+		const s1 = cli([
+			"session",
+			"start",
+			"--agent",
+			"claude-code",
+			"--data",
+			"/tmp/s1.jsonl",
+		]);
+		await s1.exited;
+		const id1 = (await new Response(s1.stdout).text()).trim();
+
+		const s2 = cli([
+			"session",
+			"start",
+			"--agent",
+			"claude-code",
+			"--data",
+			"/tmp/s2.jsonl",
+		]);
+		await s2.exited;
+
+		const endProc = cli(["session", "end", "--id", id1]);
+		await endProc.exited;
+
+		await writeFile(join(tempDir, "file.txt"), "hello");
+		await gitExec(["add", "."]);
+		await gitExec(["commit", "-m", "test commit"]);
+		const sha = await gitExec(["rev-parse", "HEAD"]);
+
+		const captureProc = cli(["capture"]);
+		await captureProc.exited;
+
+		const pendingPath = join(tempDir, ".residue/pending.json");
+		const sessions = (await readPending(pendingPath))._unsafeUnwrap();
+
+		expect(sessions).toHaveLength(2);
+		// Ended session with zero commits gets tagged (first capture after ending)
+		const ended = sessions.find((s: { id: string }) => s.id === id1);
+		expect(ended!.commits.some((c) => c.sha === sha)).toBe(true);
+		// Open session always gets tagged
+		const open = sessions.find((s: { id: string }) => s.id !== id1);
+		expect(open!.commits.some((c) => c.sha === sha)).toBe(true);
+	});
+
+	test("does not tag ended sessions that already have commits", async () => {
+		const s1 = cli([
+			"session",
+			"start",
+			"--agent",
+			"claude-code",
+			"--data",
+			"/tmp/s1.jsonl",
+		]);
+		await s1.exited;
+		const id1 = (await new Response(s1.stdout).text()).trim();
+
+		// First commit while session is open -- capture tags it
+		await writeFile(join(tempDir, "file.txt"), "hello");
+		await gitExec(["add", "."]);
+		await gitExec(["commit", "-m", "commit 1"]);
+		const sha1 = await gitExec(["rev-parse", "HEAD"]);
+
+		const c1 = cli(["capture"]);
+		await c1.exited;
+
+		// End the session
+		const endProc = cli(["session", "end", "--id", id1]);
+		await endProc.exited;
+
+		// Second commit after session ended -- capture should NOT tag the ended session
+		await writeFile(join(tempDir, "file2.txt"), "world");
+		await gitExec(["add", "."]);
+		await gitExec(["commit", "-m", "commit 2"]);
+		const sha2 = await gitExec(["rev-parse", "HEAD"]);
+
+		const c2 = cli(["capture"]);
+		await c2.exited;
+
+		const pendingPath = join(tempDir, ".residue/pending.json");
+		const sessions = (await readPending(pendingPath))._unsafeUnwrap();
+
+		expect(sessions).toHaveLength(1);
+		const ended = sessions.find((s: { id: string }) => s.id === id1);
+		expect(ended!.commits.some((c) => c.sha === sha1)).toBe(true);
+		expect(ended!.commits.some((c) => c.sha === sha2)).toBe(false);
+	});
+
+	test("records branch name with commit SHA", async () => {
+		const startProc = cli([
+			"session",
+			"start",
+			"--agent",
+			"claude-code",
+			"--data",
+			"/tmp/s.jsonl",
+		]);
+		await startProc.exited;
+
+		const captureProc = cli(["capture"]);
+		await captureProc.exited;
+
+		const pendingPath = join(tempDir, ".residue/pending.json");
+		const sessions = (await readPending(pendingPath))._unsafeUnwrap();
+		const branch = sessions[0].commits[0].branch;
+		expect(typeof branch).toBe("string");
+		expect(branch.length).toBeGreaterThan(0);
+		expect(branch).not.toBe("unknown");
+	});
+});