@residue/cli 0.0.1

package/src/commands/sync.ts

@@ -0,0 +1,354 @@
+import { err, ok, okAsync, ResultAsync, safeTry } from "neverthrow";
+import { readConfig } from "@/lib/config";
+import { getCommitMeta, getRemoteUrl, parseRemote } from "@/lib/git";
+import type { CommitRef, PendingSession } from "@/lib/pending";
+import {
+	getPendingPath,
+	getProjectRoot,
+	readPending,
+	writePending,
+} from "@/lib/pending";
+import { CliError, toCliError } from "@/utils/errors";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("sync");
+
+import { stat } from "fs/promises";
+
+const STALE_THRESHOLD_MS = 30 * 60 * 1000; // 30 minutes
+
+type CommitPayload = {
+	sha: string;
+	org: string;
+	repo: string;
+	message: string;
+	author: string;
+	committed_at: number;
+	branch: string;
+};
+
+type UploadUrlResponse = {
+	url: string;
+	r2_key: string;
+};
+
+function requestUploadUrl(opts: {
+	workerUrl: string;
+	token: string;
+	sessionId: string;
+}): ResultAsync<UploadUrlResponse, CliError> {
+	return ResultAsync.fromPromise(
+		fetch(`${opts.workerUrl}/api/sessions/upload-url`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${opts.token}`,
+			},
+			body: JSON.stringify({ session_id: opts.sessionId }),
+		}).then(async (response) => {
+			if (!response.ok) {
+				throw new Error(`HTTP ${response.status}`);
+			}
+			return response.json() as Promise<UploadUrlResponse>;
+		}),
+		toCliError({
+			message: "Failed to request upload URL",
+			code: "NETWORK_ERROR",
+		}),
+	);
+}
+
+function uploadToPresignedUrl(opts: {
+	url: string;
+	data: string;
+}): ResultAsync<void, CliError> {
+	return ResultAsync.fromPromise(
+		fetch(opts.url, {
+			method: "PUT",
+			headers: { "Content-Type": "application/json" },
+			body: opts.data,
+		}).then((response) => {
+			if (!response.ok) {
+				throw new Error(`R2 upload failed: HTTP ${response.status}`);
+			}
+		}),
+		toCliError({ message: "Direct R2 upload failed", code: "NETWORK_ERROR" }),
+	);
+}
+
+function postSessionMetadata(opts: {
+	workerUrl: string;
+	token: string;
+	session: {
+		id: string;
+		agent: string;
+		agent_version: string;
+		status: string;
+	};
+	commits: CommitPayload[];
+}): ResultAsync<void, CliError> {
+	return ResultAsync.fromPromise(
+		fetch(`${opts.workerUrl}/api/sessions`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${opts.token}`,
+			},
+			body: JSON.stringify({
+				session: opts.session,
+				commits: opts.commits,
+			}),
+		}).then((response) => {
+			if (!response.ok) {
+				throw new Error(`HTTP ${response.status}`);
+			}
+		}),
+		toCliError({ message: "Metadata upload failed", code: "NETWORK_ERROR" }),
+	);
+}
+
+function readSessionData(
+	dataPath: string,
+): ResultAsync<string | null, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			const file = Bun.file(dataPath);
+			const isExists = await file.exists();
+			if (!isExists) return null;
+			return file.text();
+		})(),
+		toCliError({ message: "Failed to read session data", code: "IO_ERROR" }),
+	);
+}
+
+function buildCommitMeta(opts: {
+	commitRefs: CommitRef[];
+	org: string;
+	repo: string;
+}): ResultAsync<CommitPayload[], CliError> {
+	return ResultAsync.fromSafePromise(
+		(async () => {
+			const commits: CommitPayload[] = [];
+			for (const ref of opts.commitRefs) {
+				const metaResult = await getCommitMeta(ref.sha);
+				if (metaResult.isErr()) {
+					log.warn(metaResult.error);
+					continue;
+				}
+				commits.push({
+					sha: ref.sha,
+					org: opts.org,
+					repo: opts.repo,
+					message: metaResult.value.message,
+					author: metaResult.value.author,
+					committed_at: metaResult.value.committed_at,
+					branch: ref.branch,
+				});
+			}
+			return commits;
+		})(),
+	);
+}
+
+function getFileMtimeMs(path: string): ResultAsync<number | null, CliError> {
+	return ResultAsync.fromPromise(
+		stat(path).then((s) => s.mtimeMs),
+		toCliError({ message: "Failed to stat file", code: "IO_ERROR" }),
+	).orElse(() => okAsync(null));
+}
+
+/**
+ * Mark open sessions as ended if their data file hasn't been modified
+ * in the last 30 minutes. This handles dangling sessions from crashed
+ * or closed agent processes that never called session-end.
+ */
+function closeStaleOpenSessions(opts: {
+	sessions: PendingSession[];
+}): ResultAsync<PendingSession[], CliError> {
+	const now = Date.now();
+	const openSessions = opts.sessions.filter((s) => s.status === "open");
+
+	if (openSessions.length === 0) {
+		return okAsync(opts.sessions);
+	}
+
+	const checks = openSessions.map((session) =>
+		getFileMtimeMs(session.data_path).map((mtimeMs) => {
+			if (mtimeMs === null) {
+				session.status = "ended";
+				log.debug(
+					"auto-closed session %s (data file not accessible)",
+					session.id,
+				);
+			} else {
+				const msSinceModified = now - mtimeMs;
+				if (msSinceModified > STALE_THRESHOLD_MS) {
+					session.status = "ended";
+					log.debug(
+						"auto-closed stale session %s (data file unchanged for %dm)",
+						session.id,
+						Math.round(msSinceModified / 60_000),
+					);
+				}
+			}
+		}),
+	);
+
+	return ResultAsync.combine(checks).map(() => opts.sessions);
+}
+
+function syncSessions(opts: {
+	sessions: PendingSession[];
+	workerUrl: string;
+	token: string;
+	org: string;
+	repo: string;
+}): ResultAsync<PendingSession[], CliError> {
+	return ResultAsync.fromSafePromise(
+		(async () => {
+			const remaining: PendingSession[] = [];
+
+			for (const session of opts.sessions) {
+				if (session.commits.length === 0) {
+					remaining.push(session);
+					continue;
+				}
+
+				const dataResult = await readSessionData(session.data_path);
+				if (dataResult.isErr()) {
+					log.warn(dataResult.error);
+					remaining.push(session);
+					continue;
+				}
+
+				const data = dataResult.value;
+				if (data === null) {
+					log.warn(
+						`dropping session ${session.id}: data file missing at ${session.data_path}`,
+					);
+					continue;
+				}
+
+				const commitsResult = await buildCommitMeta({
+					commitRefs: session.commits,
+					org: opts.org,
+					repo: opts.repo,
+				});
+				if (commitsResult.isErr()) {
+					log.warn(commitsResult.error);
+					remaining.push(session);
+					continue;
+				}
+
+				// Step 1: Get a presigned URL from the worker
+				const uploadUrlResult = await requestUploadUrl({
+					workerUrl: opts.workerUrl,
+					token: opts.token,
+					sessionId: session.id,
+				});
+
+				if (uploadUrlResult.isErr()) {
+					log.warn(
+						`failed to get upload URL for session ${session.id}: ${uploadUrlResult.error.message}`,
+					);
+					remaining.push(session);
+					continue;
+				}
+
+				// Step 2: Upload session data directly to R2
+				const directUploadResult = await uploadToPresignedUrl({
+					url: uploadUrlResult.value.url,
+					data,
+				});
+
+				if (directUploadResult.isErr()) {
+					log.warn(
+						`R2 upload failed for session ${session.id}: ${directUploadResult.error.message}`,
+					);
+					remaining.push(session);
+					continue;
+				}
+
+				log.debug("uploaded session %s data directly to R2", session.id);
+
+				// Step 3: POST metadata only (no inline data)
+				const metadataResult = await postSessionMetadata({
+					workerUrl: opts.workerUrl,
+					token: opts.token,
+					session: {
+						id: session.id,
+						agent: session.agent,
+						agent_version: session.agent_version,
+						status: session.status,
+					},
+					commits: commitsResult.value,
+				});
+
+				if (metadataResult.isErr()) {
+					log.warn(
+						`metadata upload failed for session ${session.id}: ${metadataResult.error.message}`,
+					);
+					remaining.push(session);
+					continue;
+				}
+
+				if (session.status === "open") {
+					remaining.push(session);
+				}
+
+				log.debug("synced session %s", session.id);
+			}
+
+			return remaining;
+		})(),
+	);
+}
+
+function resolveRemote(
+	remoteUrl?: string,
+): ResultAsync<{ org: string; repo: string }, CliError> {
+	if (remoteUrl && remoteUrl.length > 0) {
+		const result = parseRemote(remoteUrl);
+		if (result.isOk()) {
+			return okAsync(result.value);
+		}
+	}
+	return getRemoteUrl().andThen(parseRemote);
+}
+
+export function sync(opts?: {
+	remoteUrl?: string;
+}): ResultAsync<void, CliError> {
+	return safeTry(async function* () {
+		const config = yield* readConfig();
+		if (!config) {
+			return err(
+				new CliError({
+					message: "Not configured. Run 'residue login' first.",
+					code: "CONFIG_MISSING",
+				}),
+			);
+		}
+
+		const projectRoot = yield* getProjectRoot();
+		const pendingPath = yield* getPendingPath(projectRoot);
+		const sessions = yield* readPending(pendingPath);
+
+		if (sessions.length === 0) {
+			return ok(undefined);
+		}
+
+		const updatedSessions = yield* closeStaleOpenSessions({ sessions });
+		const { org, repo } = yield* resolveRemote(opts?.remoteUrl);
+		const remaining = yield* syncSessions({
+			sessions: updatedSessions,
+			workerUrl: config.worker_url,
+			token: config.token,
+			org,
+			repo,
+		});
+
+		yield* writePending({ path: pendingPath, sessions: remaining });
+		return ok(undefined);
+	});
+}

package/src/index.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+import { capture } from "@/commands/capture";
+import { hookClaudeCode } from "@/commands/hook";
+import { init } from "@/commands/init";
+import { login } from "@/commands/login";
+import { push } from "@/commands/push";
+import { sessionEnd } from "@/commands/session-end";
+import { sessionStart } from "@/commands/session-start";
+import { setup } from "@/commands/setup";
+import { sync } from "@/commands/sync";
+import { wrapCommand, wrapHookCommand } from "@/utils/errors";
+
+const program = new Command();
+
+program
+	.name("residue")
+	.description("Capture AI agent conversations linked to git commits")
+	.version("0.0.1");
+
+program
+	.command("login")
+	.description("Save worker URL and auth token")
+	.requiredOption("--url <worker_url>", "Worker URL")
+	.requiredOption("--token <auth_token>", "Auth token")
+	.action(
+		wrapCommand((opts: { url: string; token: string }) =>
+			login({ url: opts.url, token: opts.token }),
+		),
+	);
+
+program
+	.command("init")
+	.description("Install git hooks in current repo")
+	.action(wrapCommand(() => init()));
+
+program
+	.command("setup")
+	.description("Configure an agent adapter for this project")
+	.argument("<agent>", "Agent to set up (claude-code, pi)")
+	.action(wrapCommand((agent: string) => setup({ agent })));
+
+const hook = program
+	.command("hook")
+	.description("Agent hook handlers (called by agent plugins)");
+
+hook
+	.command("claude-code")
+	.description("Handle Claude Code hook events (reads JSON from stdin)")
+	.action(wrapHookCommand(() => hookClaudeCode()));
+
+const session = program.command("session").description("Manage agent sessions");
+
+session
+	.command("start")
+	.description("Start tracking an agent session")
+	.requiredOption("--agent <name>", "Agent name")
+	.requiredOption("--data <path>", "Path to raw session file")
+	.option("--agent-version <semver>", "Agent version", "unknown")
+	.action(
+		wrapCommand((opts: { agent: string; data: string; agentVersion: string }) =>
+			sessionStart({
+				agent: opts.agent,
+				data: opts.data,
+				agentVersion: opts.agentVersion,
+			}),
+		),
+	);
+
+session
+	.command("end")
+	.description("Mark an agent session as ended")
+	.requiredOption("--id <session-id>", "Session ID to end")
+	.action(wrapCommand((opts: { id: string }) => sessionEnd({ id: opts.id })));
+
+program
+	.command("capture")
+	.description(
+		"Tag pending sessions with current commit SHA (called by post-commit hook)",
+	)
+	.action(wrapHookCommand(() => capture()));
+
+program
+	.command("sync")
+	.description("Upload pending sessions to worker (called by pre-push hook)")
+	.option("--remote-url <url>", "Remote URL (passed by pre-push hook)")
+	.action(
+		wrapHookCommand((opts: { remoteUrl?: string }) =>
+			sync({ remoteUrl: opts.remoteUrl }),
+		),
+	);
+
+program
+	.command("push")
+	.description("Upload pending sessions to worker (manual trigger)")
+	.action(wrapCommand(() => push()));
+
+program.parse();

package/src/lib/config.ts

@@ -0,0 +1,61 @@
+/**
+ * Config management for the residue CLI.
+ * Manages ~/.residue/config (JSON file).
+ */
+
+import { mkdir } from "fs/promises";
+import { ResultAsync } from "neverthrow";
+import { join } from "path";
+import type { CliError } from "@/utils/errors";
+import { toCliError } from "@/utils/errors";
+
+export type ResidueConfig = {
+	worker_url: string;
+	token: string;
+};
+
+function home(): string {
+	return process.env.HOME || process.env.USERPROFILE || "/";
+}
+
+export function getConfigDir(): string {
+	return join(home(), ".residue");
+}
+
+export function getConfigPath(): string {
+	return join(getConfigDir(), "config");
+}
+
+export function readConfig(): ResultAsync<ResidueConfig | null, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			const path = getConfigPath();
+			const file = Bun.file(path);
+			const isExists = await file.exists();
+			if (!isExists) return null;
+			const text = await file.text();
+			return JSON.parse(text) as ResidueConfig;
+		})(),
+		toCliError({ message: "Failed to read config", code: "CONFIG_ERROR" }),
+	);
+}
+
+export function writeConfig(
+	config: ResidueConfig,
+): ResultAsync<void, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			const dir = getConfigDir();
+			await mkdir(dir, { recursive: true });
+			await Bun.write(getConfigPath(), JSON.stringify(config, null, 2));
+		})(),
+		toCliError({ message: "Failed to write config", code: "CONFIG_ERROR" }),
+	);
+}
+
+export function configExists(): ResultAsync<boolean, CliError> {
+	return ResultAsync.fromPromise(
+		Bun.file(getConfigPath()).exists(),
+		toCliError({ message: "Failed to check config", code: "CONFIG_ERROR" }),
+	);
+}

package/src/lib/git.ts

@@ -0,0 +1,95 @@
+/**
+ * Git utility functions for the residue CLI.
+ */
+import { err, ok, type Result, ResultAsync } from "neverthrow";
+import { CliError, toCliError } from "@/utils/errors";
+
+function runGitCommand(opts: {
+	args: string[];
+	errorMessage: string;
+}): ResultAsync<string, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			const proc = Bun.spawn(["git", ...opts.args], {
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			const exitCode = await proc.exited;
+			if (exitCode !== 0) {
+				const stderr = await new Response(proc.stderr).text();
+				throw new Error(stderr.trim() || `exit code ${exitCode}`);
+			}
+			return (await new Response(proc.stdout).text()).trim();
+		})(),
+		toCliError({ message: opts.errorMessage, code: "GIT_ERROR" }),
+	);
+}
+
+export function parseRemote(
+	remoteUrl: string,
+): Result<{ org: string; repo: string }, CliError> {
+	const match = remoteUrl.match(/[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
+	if (!match) {
+		return err(
+			new CliError({
+				message: `Cannot parse git remote URL: ${remoteUrl}`,
+				code: "GIT_PARSE_ERROR",
+			}),
+		);
+	}
+	return ok({ org: match[1], repo: match[2] });
+}
+
+export function getRemoteUrl(): ResultAsync<string, CliError> {
+	return runGitCommand({
+		args: ["remote", "get-url", "origin"],
+		errorMessage: "Failed to get git remote URL",
+	});
+}
+
+export function getCurrentBranch(): ResultAsync<string, CliError> {
+	return runGitCommand({
+		args: ["rev-parse", "--abbrev-ref", "HEAD"],
+		errorMessage: "Failed to get current branch",
+	});
+}
+
+export function getCurrentSha(): ResultAsync<string, CliError> {
+	return runGitCommand({
+		args: ["rev-parse", "HEAD"],
+		errorMessage: "Failed to get current commit SHA",
+	});
+}
+
+export function getCommitMeta(
+	sha: string,
+): ResultAsync<
+	{ message: string; author: string; committed_at: number },
+	CliError
+> {
+	return runGitCommand({
+		args: ["log", "-1", "--format=%s%n%an%n%ct", sha],
+		errorMessage: `Failed to get commit metadata for ${sha}`,
+	}).map((text) => {
+		const lines = text.split("\n");
+		return {
+			message: lines[0] || "",
+			author: lines[1] || "",
+			committed_at: parseInt(lines[2] || "0", 10),
+		};
+	});
+}
+
+export function isGitRepo(): ResultAsync<boolean, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			const proc = Bun.spawn(["git", "rev-parse", "--git-dir"], {
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			const exitCode = await proc.exited;
+			return exitCode === 0;
+		})(),
+		toCliError({ message: "Failed to check git repo", code: "GIT_ERROR" }),
+	);
+}