@residue/cli 0.0.1

package/package.json

@@ -0,0 +1,24 @@
+{
+	"name": "@residue/cli",
+	"version": "0.0.1",
+	"type": "module",
+	"bin": {
+		"residue": "./dist/index.js"
+	},
+	"scripts": {
+		"dev": "bun run src/index.ts",
+		"build": "bun build src/index.ts --outfile dist/index.js --target bun",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"@types/debug": "^4.1.12",
+		"typescript": "^5.7.0"
+	},
+	"dependencies": {
+		"commander": "^14.0.3",
+		"debug": "^4.4.3",
+		"neverthrow": "^8.2.0"
+	}
+}

package/src/commands/capture.ts

@@ -0,0 +1,49 @@
+import { ok, ResultAsync, safeTry } from "neverthrow";
+import { getCurrentBranch, getCurrentSha } from "@/lib/git";
+import type { PendingSession } from "@/lib/pending";
+import {
+	getPendingPath,
+	getProjectRoot,
+	readPending,
+	writePending,
+} from "@/lib/pending";
+import type { CliError } from "@/utils/errors";
+
+/**
+ * Determine whether a session should be tagged with the current commit.
+ *
+ * - Open sessions: always tag (the agent is still active, the commit
+ *   may contain code produced by this session).
+ * - Ended sessions with zero commits: tag once (the session ended before
+ *   any capture ran, so the current commit is likely informed by it).
+ * - Ended sessions that already have commits: skip (they were already
+ *   captured and are just waiting for sync -- tagging them with every
+ *   subsequent commit would incorrectly link unrelated work).
+ */
+function shouldTag(session: PendingSession): boolean {
+	if (session.status === "open") return true;
+	return session.commits.length === 0;
+}
+
+export function capture(): ResultAsync<void, CliError> {
+	return safeTry(async function* () {
+		const [sha, branch] = yield* ResultAsync.combine([
+			getCurrentSha(),
+			getCurrentBranch(),
+		]);
+		const projectRoot = yield* getProjectRoot();
+		const pendingPath = yield* getPendingPath(projectRoot);
+		const sessions = yield* readPending(pendingPath);
+
+		for (const session of sessions) {
+			if (!shouldTag(session)) continue;
+			const isAlreadyTagged = session.commits.some((c) => c.sha === sha);
+			if (!isAlreadyTagged) {
+				session.commits.push({ sha, branch });
+			}
+		}
+
+		yield* writePending({ path: pendingPath, sessions });
+		return ok(undefined);
+	});
+}

package/src/commands/hook.ts

@@ -0,0 +1,222 @@
+import { ok, okAsync, Result, ResultAsync, safeTry } from "neverthrow";
+import {
+	addSession,
+	getPendingPath,
+	getProjectRoot,
+	getSession,
+	updateSession,
+} from "@/lib/pending";
+import { type CliError, toCliError } from "@/utils/errors";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("hook");
+
+import { mkdir, readFile, rm, stat, writeFile } from "fs/promises";
+import { join } from "path";
+
+type ClaudeHookInput = {
+	session_id: string;
+	transcript_path?: string;
+	cwd?: string;
+	hook_event_name: string;
+	source?: string;
+	[key: string]: unknown;
+};
+
+function readStdin(): ResultAsync<string, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			const chunks: Uint8Array[] = [];
+			const reader = Bun.stdin.stream().getReader();
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				chunks.push(value);
+			}
+			return Buffer.concat(chunks).toString("utf-8");
+		})(),
+		toCliError({ message: "Failed to read stdin", code: "IO_ERROR" }),
+	);
+}
+
+function parseInput(raw: string): Result<ClaudeHookInput, CliError> {
+	return Result.fromThrowable(
+		(input: string) => JSON.parse(input) as ClaudeHookInput,
+		toCliError({
+			message: "Failed to parse hook input JSON",
+			code: "PARSE_ERROR",
+		}),
+	)(raw);
+}
+
+function detectClaudeVersion(): ResultAsync<string, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			const proc = Bun.spawn(["claude", "--version"], {
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			const exitCode = await proc.exited;
+			if (exitCode !== 0) return "unknown";
+			const output = await new Response(proc.stdout).text();
+			return output.trim() || "unknown";
+		})(),
+		toCliError({
+			message: "Failed to detect Claude version",
+			code: "IO_ERROR",
+		}),
+	).orElse(() => okAsync("unknown"));
+}
+
+function getHooksDir(projectRoot: string): ResultAsync<string, CliError> {
+	const hooksDir = join(projectRoot, ".residue", "hooks");
+	return ResultAsync.fromPromise(
+		(async () => {
+			await mkdir(hooksDir, { recursive: true });
+			return hooksDir;
+		})(),
+		toCliError({
+			message: "Failed to create hooks state directory",
+			code: "IO_ERROR",
+		}),
+	);
+}
+
+function fileExists(path: string): ResultAsync<boolean, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			try {
+				await stat(path);
+				return true;
+			} catch {
+				return false;
+			}
+		})(),
+		toCliError({
+			message: "Failed to check file existence",
+			code: "IO_ERROR",
+		}),
+	);
+}
+
+function readFileContent(path: string): ResultAsync<string, CliError> {
+	return ResultAsync.fromPromise(
+		readFile(path, "utf-8"),
+		toCliError({ message: "Failed to read file", code: "IO_ERROR" }),
+	);
+}
+
+function handleSessionStart(opts: {
+	input: ClaudeHookInput;
+	projectRoot: string;
+}): ResultAsync<void, CliError> {
+	const { input, projectRoot } = opts;
+
+	if (input.source !== "startup") return okAsync(undefined);
+	if (!input.transcript_path) return okAsync(undefined);
+	if (!input.session_id) return okAsync(undefined);
+
+	const residueSessionId = crypto.randomUUID();
+	const claudeSessionId = input.session_id;
+
+	return safeTry(async function* () {
+		const pendingPath = yield* getPendingPath(projectRoot);
+
+		yield* addSession({
+			path: pendingPath,
+			session: {
+				id: residueSessionId,
+				agent: "claude-code",
+				agent_version: "unknown",
+				status: "open",
+				data_path: input.transcript_path!,
+				commits: [],
+			},
+		});
+
+		const version = yield* detectClaudeVersion();
+
+		yield* updateSession({
+			path: pendingPath,
+			id: residueSessionId,
+			updates: { agent_version: version },
+		});
+
+		const hooksDir = yield* getHooksDir(projectRoot);
+		const stateFile = join(hooksDir, `${claudeSessionId}.state`);
+
+		yield* ResultAsync.fromPromise(
+			writeFile(stateFile, residueSessionId),
+			toCliError({
+				message: "Failed to write hook state file",
+				code: "IO_ERROR",
+			}),
+		);
+
+		log.debug("session started for claude-code");
+		return ok(undefined);
+	});
+}
+
+function handleSessionEnd(opts: {
+	input: ClaudeHookInput;
+	projectRoot: string;
+}): ResultAsync<void, CliError> {
+	const { input, projectRoot } = opts;
+	const claudeSessionId = input.session_id;
+
+	if (!claudeSessionId) return okAsync(undefined);
+
+	return safeTry(async function* () {
+		const hooksDir = yield* getHooksDir(projectRoot);
+		const stateFile = join(hooksDir, `${claudeSessionId}.state`);
+
+		const isExists = yield* fileExists(stateFile);
+		if (!isExists) return ok(undefined);
+
+		const rawId = yield* readFileContent(stateFile);
+		const trimmedId = rawId.trim();
+		if (!trimmedId) return ok(undefined);
+
+		const pendingPath = yield* getPendingPath(projectRoot);
+		const session = yield* getSession({ path: pendingPath, id: trimmedId });
+
+		if (session) {
+			yield* updateSession({
+				path: pendingPath,
+				id: trimmedId,
+				updates: { status: "ended" },
+			});
+		}
+
+		yield* ResultAsync.fromPromise(
+			rm(stateFile, { force: true }),
+			toCliError({
+				message: "Failed to remove hook state file",
+				code: "IO_ERROR",
+			}),
+		);
+
+		log.debug("session %s ended", trimmedId);
+		return ok(undefined);
+	});
+}
+
+export function hookClaudeCode(): ResultAsync<void, CliError> {
+	return safeTry(async function* () {
+		const raw = yield* readStdin();
+		const input = yield* parseInput(raw);
+		const projectRoot = yield* getProjectRoot();
+
+		switch (input.hook_event_name) {
+			case "SessionStart":
+				yield* handleSessionStart({ input, projectRoot });
+				break;
+			case "SessionEnd":
+				yield* handleSessionEnd({ input, projectRoot });
+				break;
+		}
+
+		return ok(undefined);
+	});
+}

package/src/commands/init.ts

@@ -0,0 +1,146 @@
+import { err, ok, ResultAsync, safeTry } from "neverthrow";
+import { isGitRepo } from "@/lib/git";
+import { getProjectRoot, getResidueDir } from "@/lib/pending";
+import { CliError, toCliError } from "@/utils/errors";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("init");
+
+import {
+	appendFile,
+	chmod,
+	mkdir,
+	readFile,
+	stat,
+	writeFile,
+} from "fs/promises";
+import { join } from "path";
+
+const POST_COMMIT_LINE = "residue capture >/dev/null 2>&1 &";
+const PRE_PUSH_LINE = 'residue sync --remote-url "$2"';
+
+function installHook(opts: {
+	hooksDir: string;
+	filename: string;
+	line: string;
+}): ResultAsync<string, CliError> {
+	const hookPath = join(opts.hooksDir, opts.filename);
+
+	return ResultAsync.fromPromise(
+		(async () => {
+			let isExisting = false;
+			try {
+				await stat(hookPath);
+				isExisting = true;
+			} catch {
+				// file does not exist
+			}
+
+			if (isExisting) {
+				const content = await readFile(hookPath, "utf-8");
+				if (content.includes(opts.line)) {
+					return `${opts.filename}: already installed`;
+				}
+				await writeFile(hookPath, content.trimEnd() + "\n" + opts.line + "\n");
+				await chmod(hookPath, 0o755);
+				return `${opts.filename}: appended`;
+			}
+
+			await writeFile(hookPath, `#!/bin/sh\n${opts.line}\n`);
+			await chmod(hookPath, 0o755);
+			return `${opts.filename}: created`;
+		})(),
+		toCliError({
+			message: `Failed to install hook ${opts.filename}`,
+			code: "IO_ERROR",
+		}),
+	);
+}
+
+function getGitDirForInit(): ResultAsync<string, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			const proc = Bun.spawn(["git", "rev-parse", "--git-dir"], {
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			await proc.exited;
+			return (await new Response(proc.stdout).text()).trim();
+		})(),
+		toCliError({ message: "Failed to get git directory", code: "GIT_ERROR" }),
+	);
+}
+
+function ensureGitignore(projectRoot: string): ResultAsync<void, CliError> {
+	const gitignorePath = join(projectRoot, ".gitignore");
+
+	return ResultAsync.fromPromise(
+		(async () => {
+			let content = "";
+			try {
+				content = await readFile(gitignorePath, "utf-8");
+			} catch {
+				// file does not exist yet
+			}
+
+			if (content.includes(".residue")) {
+				return;
+			}
+
+			const line =
+				content.length > 0 && !content.endsWith("\n")
+					? "\n.residue/\n"
+					: ".residue/\n";
+			await appendFile(gitignorePath, line);
+		})(),
+		toCliError({ message: "Failed to update .gitignore", code: "IO_ERROR" }),
+	);
+}
+
+export function init(): ResultAsync<void, CliError> {
+	return safeTry(async function* () {
+		const isRepo = yield* isGitRepo();
+		if (!isRepo) {
+			return err(
+				new CliError({ message: "not a git repository", code: "GIT_ERROR" }),
+			);
+		}
+
+		const [projectRoot, gitDir] = yield* ResultAsync.combine([
+			getProjectRoot(),
+			getGitDirForInit(),
+		]);
+
+		const hooksDir = join(gitDir, "hooks");
+
+		yield* ResultAsync.combine([
+			getResidueDir(projectRoot),
+			ResultAsync.fromPromise(
+				mkdir(hooksDir, { recursive: true }),
+				toCliError({
+					message: "Failed to create hooks directory",
+					code: "IO_ERROR",
+				}),
+			),
+		]);
+
+		const [postCommit, prePush] = yield* ResultAsync.combine([
+			installHook({
+				hooksDir,
+				filename: "post-commit",
+				line: POST_COMMIT_LINE,
+			}),
+			installHook({
+				hooksDir,
+				filename: "pre-push",
+				line: PRE_PUSH_LINE,
+			}),
+			ensureGitignore(projectRoot),
+		]);
+
+		log.info("Initialized residue in this repository.");
+		log.info(`  ${postCommit}`);
+		log.info(`  ${prePush}`);
+		return ok(undefined);
+	});
+}

package/src/commands/login.ts

@@ -0,0 +1,26 @@
+import { errAsync, type ResultAsync } from "neverthrow";
+import { writeConfig } from "@/lib/config";
+import { CliError } from "@/utils/errors";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("login");
+
+export function login(opts: {
+	url: string;
+	token: string;
+}): ResultAsync<void, CliError> {
+	if (!opts.url.startsWith("http://") && !opts.url.startsWith("https://")) {
+		return errAsync(
+			new CliError({
+				message: "URL must start with http:// or https://",
+				code: "VALIDATION_ERROR",
+			}),
+		);
+	}
+
+	const cleanUrl = opts.url.replace(/\/+$/, "");
+
+	return writeConfig({ worker_url: cleanUrl, token: opts.token }).map(() => {
+		log.info(`Logged in to ${cleanUrl}`);
+	});
+}

package/src/commands/push.ts

@@ -0,0 +1,3 @@
+import { sync } from "@/commands/sync";
+
+export const push = sync;

package/src/commands/session-end.ts

@@ -0,0 +1,38 @@
+import type { ResultAsync } from "neverthrow";
+import { err, ok, safeTry } from "neverthrow";
+import {
+	getPendingPath,
+	getProjectRoot,
+	getSession,
+	updateSession,
+} from "@/lib/pending";
+import { CliError } from "@/utils/errors";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("session");
+
+export function sessionEnd(opts: { id: string }): ResultAsync<void, CliError> {
+	return safeTry(async function* () {
+		const projectRoot = yield* getProjectRoot();
+		const pendingPath = yield* getPendingPath(projectRoot);
+		const session = yield* getSession({ path: pendingPath, id: opts.id });
+
+		if (!session) {
+			return err(
+				new CliError({
+					message: `Session not found: ${opts.id}`,
+					code: "SESSION_NOT_FOUND",
+				}),
+			);
+		}
+
+		yield* updateSession({
+			path: pendingPath,
+			id: opts.id,
+			updates: { status: "ended" },
+		});
+
+		log.debug("session %s ended", opts.id);
+		return ok(undefined);
+	});
+}

package/src/commands/session-start.ts

@@ -0,0 +1,35 @@
+import type { ResultAsync } from "neverthrow";
+import { addSession, getPendingPath, getProjectRoot } from "@/lib/pending";
+import type { CliError } from "@/utils/errors";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("session");
+
+export function sessionStart(opts: {
+	agent: string;
+	data: string;
+	agentVersion: string;
+}): ResultAsync<void, CliError> {
+	const id = crypto.randomUUID();
+
+	return getProjectRoot()
+		.andThen(getPendingPath)
+		.andThen((pendingPath) =>
+			addSession({
+				path: pendingPath,
+				session: {
+					id,
+					agent: opts.agent,
+					agent_version: opts.agentVersion,
+					status: "open",
+					data_path: opts.data,
+					commits: [],
+				},
+			}),
+		)
+		.map(() => {
+			// Only the session ID goes to stdout so adapters can capture it
+			process.stdout.write(id);
+			log.debug("session started for %s", opts.agent);
+		});
+}

package/src/commands/setup.ts

@@ -0,0 +1,148 @@
+import { errAsync, okAsync, ResultAsync } from "neverthrow";
+import { getProjectRoot } from "@/lib/pending";
+import { CliError, toCliError } from "@/utils/errors";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("setup");
+
+import { mkdir, readFile, stat, writeFile } from "fs/promises";
+import { join } from "path";
+// Embedded at build time so the binary doesn't need to resolve a file path at runtime
+import piAdapterSource from "../../adapters/pi/extension.ts.txt" with {
+	type: "text",
+};
+
+type HookHandler = {
+	type: string;
+	command: string;
+	timeout?: number;
+};
+
+type HookEntry = {
+	matcher: string;
+	hooks: HookHandler[];
+};
+
+type ClaudeSettings = {
+	hooks?: Record<string, HookEntry[]>;
+	[key: string]: unknown;
+};
+
+const CLAUDE_HOOK_COMMAND = "residue hook claude-code";
+
+function hasResidueHook(entries: HookEntry[]): boolean {
+	return entries.some((entry) =>
+		entry.hooks.some((h) => h.command === CLAUDE_HOOK_COMMAND),
+	);
+}
+
+function setupClaudeCode(projectRoot: string): ResultAsync<void, CliError> {
+	const claudeDir = join(projectRoot, ".claude");
+	const settingsPath = join(claudeDir, "settings.json");
+
+	return ResultAsync.fromPromise(
+		(async () => {
+			await mkdir(claudeDir, { recursive: true });
+
+			let settings: ClaudeSettings = {};
+			try {
+				await stat(settingsPath);
+				const raw = await readFile(settingsPath, "utf-8");
+				settings = JSON.parse(raw) as ClaudeSettings;
+			} catch {
+				// file does not exist or is invalid
+			}
+
+			if (!settings.hooks) {
+				settings.hooks = {};
+			}
+
+			let isChanged = false;
+
+			// SessionStart hook
+			if (!settings.hooks.SessionStart) {
+				settings.hooks.SessionStart = [];
+			}
+			if (!hasResidueHook(settings.hooks.SessionStart)) {
+				settings.hooks.SessionStart.push({
+					matcher: "startup",
+					hooks: [
+						{ type: "command", command: CLAUDE_HOOK_COMMAND, timeout: 10 },
+					],
+				});
+				isChanged = true;
+			}
+
+			// SessionEnd hook
+			if (!settings.hooks.SessionEnd) {
+				settings.hooks.SessionEnd = [];
+			}
+			if (!hasResidueHook(settings.hooks.SessionEnd)) {
+				settings.hooks.SessionEnd.push({
+					matcher: "",
+					hooks: [
+						{ type: "command", command: CLAUDE_HOOK_COMMAND, timeout: 10 },
+					],
+				});
+				isChanged = true;
+			}
+
+			if (!isChanged) {
+				log.info("residue hooks already configured in .claude/settings.json");
+				return;
+			}
+
+			await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+			log.info("Configured Claude Code hooks in .claude/settings.json");
+		})(),
+		toCliError({ message: "Failed to setup Claude Code", code: "IO_ERROR" }),
+	);
+}
+
+function setupPi(projectRoot: string): ResultAsync<void, CliError> {
+	const extensionDir = join(projectRoot, ".pi", "extensions");
+	const targetPath = join(extensionDir, "residue.ts");
+
+	return ResultAsync.fromPromise(
+		(async () => {
+			await mkdir(extensionDir, { recursive: true });
+
+			let isExisting = false;
+			try {
+				await stat(targetPath);
+				isExisting = true;
+			} catch {
+				// does not exist
+			}
+
+			if (isExisting) {
+				log.info(
+					"residue extension already exists at .pi/extensions/residue.ts",
+				);
+				return;
+			}
+
+			await writeFile(targetPath, piAdapterSource);
+			log.info("Installed pi extension at .pi/extensions/residue.ts");
+		})(),
+		toCliError({ message: "Failed to setup pi", code: "IO_ERROR" }),
+	);
+}
+
+export function setup(opts: { agent: string }): ResultAsync<void, CliError> {
+	return getProjectRoot().andThen((projectRoot) => {
+		switch (opts.agent) {
+			case "claude-code":
+				return setupClaudeCode(projectRoot);
+			case "pi":
+				return setupPi(projectRoot);
+			default:
+				return errAsync(
+					new CliError({
+						message: `Unknown agent: ${opts.agent}. Supported: claude-code, pi`,
+						code: "VALIDATION_ERROR",
+					}),
+				);
+		}
+	});
+}