@residue/cli 0.0.2 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@residue/cli",
-	"version": "0.0.2",
+	"version": "0.0.4",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/butttons/residue",

package/src/commands/clear.ts

@@ -0,0 +1,42 @@
+import { ok, type ResultAsync, safeTry } from "neverthrow";
+import {
+	getPendingPath,
+	getProjectRoot,
+	readPending,
+	writePending,
+} from "@/lib/pending";
+import type { CliError } from "@/utils/errors";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("clear");
+
+export function clear(opts?: { id?: string }): ResultAsync<void, CliError> {
+	return safeTry(async function* () {
+		const projectRoot = yield* getProjectRoot();
+		const pendingPath = yield* getPendingPath(projectRoot);
+		const sessions = yield* readPending(pendingPath);
+
+		if (sessions.length === 0) {
+			log.info("No pending sessions to clear.");
+			return ok(undefined);
+		}
+
+		if (opts?.id) {
+			const targetId = opts.id;
+			const isFound = sessions.some((s) => s.id === targetId);
+			if (!isFound) {
+				log.info(`Session ${targetId} not found in pending queue.`);
+				return ok(undefined);
+			}
+			const remaining = sessions.filter((s) => s.id !== targetId);
+			yield* writePending({ path: pendingPath, sessions: remaining });
+			log.info(`Cleared session ${targetId}.`);
+			return ok(undefined);
+		}
+
+		const count = sessions.length;
+		yield* writePending({ path: pendingPath, sessions: [] });
+		log.info(`Cleared ${count} pending session(s).`);
+		return ok(undefined);
+	});
+}

package/src/commands/search.ts

@@ -0,0 +1,266 @@
+import { err, ok, ResultAsync, safeTry } from "neverthrow";
+import { resolveConfig } from "@/lib/config";
+import { CliError, toCliError } from "@/utils/errors";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("search");
+
+type SearchContentChunk = {
+	type: string;
+	text: string;
+};
+
+type SearchResultItem = {
+	file_id: string;
+	filename: string;
+	score: number;
+	attributes: Record<string, unknown>;
+	content: SearchContentChunk[];
+};
+
+type SearchResponse = {
+	object: string;
+	search_query: string;
+	data: SearchResultItem[];
+	has_more: boolean;
+	next_page: string | null;
+};
+
+type AiSearchResponse = SearchResponse & {
+	response: string;
+};
+
+type SessionCommit = {
+	commit_sha: string;
+	committed_at: number | null;
+	org: string;
+	repo: string;
+	branch: string | null;
+};
+
+function fetchSearch(opts: {
+	workerUrl: string;
+	token: string;
+	query: string;
+	isAi: boolean;
+}): ResultAsync<SearchResponse | AiSearchResponse, CliError> {
+	const path = opts.isAi ? "/api/search/ai" : "/api/search";
+	const url = `${opts.workerUrl}${path}?q=${encodeURIComponent(opts.query)}`;
+
+	return ResultAsync.fromPromise(
+		fetch(url, {
+			headers: { Authorization: `Bearer ${opts.token}` },
+		}).then(async (response) => {
+			if (!response.ok) {
+				const body = await response.text().catch(() => "");
+				throw new Error(`HTTP ${response.status}: ${body}`);
+			}
+			return response.json() as Promise<SearchResponse | AiSearchResponse>;
+		}),
+		toCliError({ message: "Search request failed", code: "NETWORK_ERROR" }),
+	);
+}
+
+function fetchSessionCommits(opts: {
+	workerUrl: string;
+	token: string;
+	sessionId: string;
+}): ResultAsync<SessionCommit[], CliError> {
+	const url = `${opts.workerUrl}/api/sessions/${opts.sessionId}/commits`;
+
+	return ResultAsync.fromPromise(
+		fetch(url, {
+			headers: { Authorization: `Bearer ${opts.token}` },
+		}).then(async (response) => {
+			if (!response.ok) return [];
+			const data = (await response.json()) as { commits: SessionCommit[] };
+			return data.commits;
+		}),
+		toCliError({
+			message: "Failed to fetch session commits",
+			code: "NETWORK_ERROR",
+		}),
+	).orElse(() => ok([] as SessionCommit[]));
+}
+
+/**
+ * Extract a session ID from an R2 filename like "sessions/<uuid>.json"
+ * or "search/<uuid>.txt".
+ */
+function extractSessionId(filename: string): string {
+	const match = filename.match(/(?:sessions|search)\/(.+?)\.(?:json|txt)$/);
+	return match ? match[1] : filename;
+}
+
+/**
+ * Truncate text to a max length, appending "..." if truncated.
+ */
+function truncate(opts: { text: string; maxLength: number }): string {
+	if (opts.text.length <= opts.maxLength) return opts.text;
+	return opts.text.slice(0, opts.maxLength) + "...";
+}
+
+/**
+ * Clean up a content chunk for display: collapse whitespace,
+ * strip JSON noise, and truncate.
+ */
+function formatSnippet(text: string): string {
+	const cleaned = text
+		.replace(/\\n/g, " ")
+		.replace(/\\"/g, '"')
+		.replace(/\s+/g, " ")
+		.trim();
+	return truncate({ text: cleaned, maxLength: 200 });
+}
+
+function buildCommitUrl(opts: {
+	workerUrl: string;
+	org: string;
+	repo: string;
+	sha: string;
+}): string {
+	return `${opts.workerUrl}/app/${opts.org}/${opts.repo}/${opts.sha}`;
+}
+
+function renderSearchResults(opts: {
+	results: SearchResponse;
+	commitMap: Map<string, SessionCommit[]>;
+	workerUrl: string;
+}): void {
+	if (opts.results.data.length === 0) {
+		log.info("No results found.");
+		return;
+	}
+
+	log.info(
+		`${opts.results.data.length} result(s) for "${opts.results.search_query}"\n`,
+	);
+
+	for (const item of opts.results.data) {
+		const sessionId = extractSessionId(item.filename);
+		const scorePercent = (item.score * 100).toFixed(1);
+
+		log.info(`  ${sessionId}  [${scorePercent}%]`);
+
+		const snippet = item.content[0]?.text;
+		if (snippet) {
+			log.info(`    ${formatSnippet(snippet)}`);
+		}
+
+		const commits = opts.commitMap.get(sessionId) ?? [];
+		if (commits.length > 0) {
+			for (const commit of commits) {
+				const url = buildCommitUrl({
+					workerUrl: opts.workerUrl,
+					org: commit.org,
+					repo: commit.repo,
+					sha: commit.commit_sha,
+				});
+				log.info(`    -> ${url}`);
+			}
+		}
+
+		log.info("");
+	}
+}
+
+function renderAiSearchResults(opts: {
+	results: AiSearchResponse;
+	commitMap: Map<string, SessionCommit[]>;
+	workerUrl: string;
+}): void {
+	if (opts.results.response) {
+		log.info(opts.results.response);
+		log.info("");
+	}
+
+	if (opts.results.data.length > 0) {
+		log.info(`--- Sources (${opts.results.data.length}) ---\n`);
+		for (const item of opts.results.data) {
+			const sessionId = extractSessionId(item.filename);
+			const scorePercent = (item.score * 100).toFixed(1);
+			log.info(`  ${sessionId}  [${scorePercent}%]`);
+
+			const commits = opts.commitMap.get(sessionId) ?? [];
+			if (commits.length > 0) {
+				for (const commit of commits) {
+					const url = buildCommitUrl({
+						workerUrl: opts.workerUrl,
+						org: commit.org,
+						repo: commit.repo,
+						sha: commit.commit_sha,
+					});
+					log.info(`    -> ${url}`);
+				}
+			}
+		}
+		log.info("");
+	}
+}
+
+function isAiSearchResponse(
+	response: SearchResponse | AiSearchResponse,
+): response is AiSearchResponse {
+	return "response" in response;
+}
+
+export function search(opts: {
+	query: string;
+	isAi?: boolean;
+}): ResultAsync<void, CliError> {
+	return safeTry(async function* () {
+		const config = yield* resolveConfig();
+		if (!config) {
+			return err(
+				new CliError({
+					message: "Not configured. Run 'residue login' first.",
+					code: "CONFIG_MISSING",
+				}),
+			);
+		}
+
+		const results = yield* fetchSearch({
+			workerUrl: config.worker_url,
+			token: config.token,
+			query: opts.query,
+			isAi: opts.isAi ?? false,
+		});
+
+		// Fetch commits for each session in parallel
+		const sessionIds = results.data.map((item) =>
+			extractSessionId(item.filename),
+		);
+		const uniqueSessionIds = [...new Set(sessionIds)];
+
+		const commitResults = yield* ResultAsync.combine(
+			uniqueSessionIds.map((sessionId) =>
+				fetchSessionCommits({
+					workerUrl: config.worker_url,
+					token: config.token,
+					sessionId,
+				}).map((commits) => ({ sessionId, commits })),
+			),
+		);
+
+		const commitMap = new Map<string, SessionCommit[]>();
+		for (const entry of commitResults) {
+			commitMap.set(entry.sessionId, entry.commits);
+		}
+
+		if (opts.isAi && isAiSearchResponse(results)) {
+			renderAiSearchResults({
+				results,
+				commitMap,
+				workerUrl: config.worker_url,
+			});
+		} else {
+			renderSearchResults({
+				results,
+				commitMap,
+				workerUrl: config.worker_url,
+			});
+		}
+
+		return ok(undefined);
+	});
+}

package/src/commands/status.ts

@@ -0,0 +1,180 @@
+import { readFile, stat } from "fs/promises";
+import { ok, okAsync, ResultAsync, safeTry } from "neverthrow";
+import { join } from "path";
+import { readConfig, readLocalConfig } from "@/lib/config";
+import { isGitRepo } from "@/lib/git";
+import { getPendingPath, getProjectRoot, readPending } from "@/lib/pending";
+import type { CliError } from "@/utils/errors";
+import { toCliError } from "@/utils/errors";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("status");
+
+function checkFileExists(path: string): ResultAsync<boolean, CliError> {
+	return ResultAsync.fromPromise(
+		stat(path).then(() => true),
+		toCliError({ message: "Failed to check file", code: "IO_ERROR" }),
+	).orElse(() => okAsync(false));
+}
+
+function checkHookInstalled(opts: {
+	gitDir: string;
+	hookName: string;
+	needle: string;
+}): ResultAsync<boolean, CliError> {
+	const hookPath = join(opts.gitDir, "hooks", opts.hookName);
+	return ResultAsync.fromPromise(
+		readFile(hookPath, "utf-8").then((content) =>
+			content.includes(opts.needle),
+		),
+		toCliError({ message: "Failed to read hook", code: "IO_ERROR" }),
+	).orElse(() => okAsync(false));
+}
+
+function getGitDir(): 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" }),
+	);
+}
+
+export function status(): ResultAsync<void, CliError> {
+	return safeTry(async function* () {
+		const isRepo = yield* isGitRepo();
+		if (!isRepo) {
+			log.info("Not a git repository.");
+			return ok(undefined);
+		}
+
+		const projectRoot = yield* getProjectRoot();
+
+		// -- Auth / Login state --
+		log.info("Login");
+
+		const globalConfig = yield* readConfig();
+		if (globalConfig) {
+			log.info(`  global: ${globalConfig.worker_url}`);
+		} else {
+			log.info("  global: not configured");
+		}
+
+		const localConfig = yield* readLocalConfig(projectRoot);
+		if (localConfig) {
+			log.info(`  local:  ${localConfig.worker_url}`);
+		} else {
+			log.info("  local:  not configured");
+		}
+
+		const isActiveConfig = localConfig ?? globalConfig;
+		if (isActiveConfig) {
+			log.info(`  active: ${isActiveConfig.worker_url}`);
+		} else {
+			log.info('  active: none (run "residue login" to configure)');
+		}
+
+		log.info("");
+
+		// -- Git hooks --
+		log.info("Hooks");
+
+		const gitDir = yield* getGitDir();
+
+		const isPostCommitInstalled = yield* checkHookInstalled({
+			gitDir,
+			hookName: "post-commit",
+			needle: "residue capture",
+		});
+		log.info(
+			`  post-commit: ${isPostCommitInstalled ? "installed" : "not installed"}`,
+		);
+
+		const isPrePushInstalled = yield* checkHookInstalled({
+			gitDir,
+			hookName: "pre-push",
+			needle: "residue sync",
+		});
+		log.info(
+			`  pre-push:    ${isPrePushInstalled ? "installed" : "not installed"}`,
+		);
+
+		if (!isPostCommitInstalled || !isPrePushInstalled) {
+			log.info('  run "residue init" to install missing hooks');
+		}
+
+		log.info("");
+
+		// -- Agent adapters --
+		log.info("Adapters");
+
+		const isClaudeSetup = yield* checkFileExists(
+			join(projectRoot, ".claude", "settings.json"),
+		);
+
+		let isClaudeHookConfigured = false;
+		if (isClaudeSetup) {
+			isClaudeHookConfigured = yield* ResultAsync.fromPromise(
+				readFile(join(projectRoot, ".claude", "settings.json"), "utf-8").then(
+					(content) => content.includes("residue hook claude-code"),
+				),
+				toCliError({
+					message: "Failed to read claude settings",
+					code: "IO_ERROR",
+				}),
+			).orElse(() => okAsync(false));
+		}
+
+		log.info(
+			`  claude-code: ${isClaudeHookConfigured ? "configured" : "not configured"}`,
+		);
+
+		const isPiSetup = yield* checkFileExists(
+			join(projectRoot, ".pi", "extensions", "residue.ts"),
+		);
+		log.info(`  pi:          ${isPiSetup ? "configured" : "not configured"}`);
+
+		log.info("");
+
+		// -- Pending sessions --
+		log.info("Sessions");
+
+		const pendingPath = yield* getPendingPath(projectRoot);
+		const sessions = yield* readPending(pendingPath);
+
+		if (sessions.length === 0) {
+			log.info("  no pending sessions");
+		} else {
+			const openSessions = sessions.filter((s) => s.status === "open");
+			const endedSessions = sessions.filter((s) => s.status === "ended");
+			const totalCommits = sessions.reduce(
+				(sum, s) => sum + s.commits.length,
+				0,
+			);
+			const sessionsWithCommits = sessions.filter((s) => s.commits.length > 0);
+
+			log.info(`  total:   ${sessions.length}`);
+			log.info(`  open:    ${openSessions.length}`);
+			log.info(`  ended:   ${endedSessions.length}`);
+			log.info(
+				`  commits: ${totalCommits} across ${sessionsWithCommits.length} session(s)`,
+			);
+
+			const isReadyToSync = sessionsWithCommits.length > 0;
+			if (isReadyToSync) {
+				log.info(
+					`  ${sessionsWithCommits.length} session(s) ready to sync on next push`,
+				);
+			} else {
+				log.info("  no sessions ready to sync (no commits captured yet)");
+			}
+		}
+
+		return ok(undefined);
+	});
+}

package/src/commands/sync.ts

@@ -8,6 +8,7 @@ import {
 	readPending,
 	writePending,
 } from "@/lib/pending";
+import { buildSearchText, getExtractor } from "@/lib/search-text";
 import { CliError, toCliError } from "@/utils/errors";
 import { createLogger } from "@/utils/logger";
 
@@ -30,6 +31,8 @@ type CommitPayload = {
 type UploadUrlResponse = {
 	url: string;
 	r2_key: string;
+	search_url: string;
+	search_r2_key: string;
 };
 
 function requestUploadUrl(opts: {
@@ -197,6 +200,62 @@ function closeStaleOpenSessions(opts: {
 	return ResultAsync.combine(checks).map(() => opts.sessions);
 }
 
+function generateSearchText(opts: {
+	session: PendingSession;
+	rawData: string;
+	commits: CommitPayload[];
+	org: string;
+	repo: string;
+}): string | null {
+	const extractor = getExtractor(opts.session.agent);
+	if (!extractor) {
+		log.debug(
+			"no search text extractor for agent %s, skipping",
+			opts.session.agent,
+		);
+		return null;
+	}
+
+	const searchLines = extractor(opts.rawData);
+	if (searchLines.length === 0) return null;
+
+	const branches = [
+		...new Set(opts.session.commits.map((c) => c.branch).filter(Boolean)),
+	];
+
+	return buildSearchText({
+		metadata: {
+			sessionId: opts.session.id,
+			agent: opts.session.agent,
+			commits: opts.commits.map((c) => c.sha.slice(0, 7)),
+			branch: branches[0] ?? "",
+			repo: `${opts.org}/${opts.repo}`,
+		},
+		lines: searchLines,
+	});
+}
+
+function uploadSearchText(opts: {
+	url: string;
+	data: string;
+}): ResultAsync<void, CliError> {
+	return ResultAsync.fromPromise(
+		fetch(opts.url, {
+			method: "PUT",
+			headers: { "Content-Type": "text/plain" },
+			body: opts.data,
+		}).then((response) => {
+			if (!response.ok) {
+				throw new Error(`R2 search upload failed: HTTP ${response.status}`);
+			}
+		}),
+		toCliError({
+			message: "Search text R2 upload failed",
+			code: "NETWORK_ERROR",
+		}),
+	);
+}
+
 function syncSessions(opts: {
 	sessions: PendingSession[];
 	workerUrl: string;
@@ -240,7 +299,7 @@ function syncSessions(opts: {
 					continue;
 				}
 
-				// Step 1: Get a presigned URL from the worker
+				// Step 1: Get presigned URLs from the worker (raw + search)
 				const uploadUrlResult = await requestUploadUrl({
 					workerUrl: opts.workerUrl,
 					token: opts.token,
@@ -271,6 +330,31 @@ function syncSessions(opts: {
 
 				log.debug("uploaded session %s data directly to R2", session.id);
 
+				// Step 2b: Generate and upload search text
+				const searchText = generateSearchText({
+					session,
+					rawData: data,
+					commits: commitsResult.value,
+					org: opts.org,
+					repo: opts.repo,
+				});
+
+				if (searchText && uploadUrlResult.value.search_url) {
+					const searchUploadResult = await uploadSearchText({
+						url: uploadUrlResult.value.search_url,
+						data: searchText,
+					});
+
+					if (searchUploadResult.isErr()) {
+						// Non-fatal: search upload failure should not block sync
+						log.warn(
+							`search text upload failed for session ${session.id}: ${searchUploadResult.error.message}`,
+						);
+					} else {
+						log.debug("uploaded search text for session %s", session.id);
+					}
+				}
+
 				// Step 3: POST metadata only (no inline data)
 				const metadataResult = await postSessionMetadata({
 					workerUrl: opts.workerUrl,

package/src/index.ts

@@ -2,22 +2,27 @@
 
 import { Command } from "commander";
 import { capture } from "@/commands/capture";
+import { clear } from "@/commands/clear";
 import { hookClaudeCode } from "@/commands/hook";
 import { init } from "@/commands/init";
 import { login } from "@/commands/login";
 import { push } from "@/commands/push";
+import { search } from "@/commands/search";
 import { sessionEnd } from "@/commands/session-end";
 import { sessionStart } from "@/commands/session-start";
 import { setup } from "@/commands/setup";
+import { status } from "@/commands/status";
 import { sync } from "@/commands/sync";
 import { wrapCommand, wrapHookCommand } from "@/utils/errors";
 
+import packageJson from "../package.json";
+
 const program = new Command();
 
 program
 	.name("residue")
 	.description("Capture AI agent conversations linked to git commits")
-	.version("0.0.1");
+	.version(packageJson.version);
 
 program
 	.command("login")
@@ -97,4 +102,26 @@ program
 	.description("Upload pending sessions to worker (manual trigger)")
 	.action(wrapCommand(() => push()));
 
+program
+	.command("clear")
+	.description("Remove pending sessions from the local queue")
+	.option("--id <session-id>", "Clear a specific session by ID")
+	.action(wrapCommand((opts: { id?: string }) => clear({ id: opts.id })));
+
+program
+	.command("status")
+	.description("Show current residue state for this project")
+	.action(wrapCommand(() => status()));
+
+program
+	.command("search")
+	.description("Search session history")
+	.argument("<query>", "Search query")
+	.option("--ai", "Use AI-powered search (generates an answer with citations)")
+	.action(
+		wrapCommand((query: string, opts: { ai?: boolean }) =>
+			search({ query, isAi: opts.ai }),
+		),
+	);
+
 program.parse();