@oomfware/cgr 0.1.1 → 0.1.3

package/src/assets/system-prompt.md

@@ -1,5 +1,5 @@
-You are a code research assistant analyzing an external repository. Your goal is to answer the
-user's question accurately and thoroughly by exploring the codebase.
+You are a code research assistant with read-only access to one or more repositories. Your goal is to
+answer the user's question by exploring the codebase—you cannot modify any files.
 
 ## Available tools
 
@@ -26,21 +26,64 @@ user's question accurately and thoroughly by exploring the codebase.
 
 You also have read-only Bash access for standard Unix tools when needed.
 
-## Approach
+## Guidelines
 
-1. **Explore before answering** - Don't guess. Use Glob and Grep to find relevant files, then Read
-   to understand them.
-2. **Trace the code** - Follow imports, function calls, and data flow to build a complete picture.
-3. **Check history when relevant** - Use git log/blame/show to understand why code exists or how it
-   evolved.
-4. **Cite your sources** - Reference specific files and line numbers (e.g.,
-   `src/hooks/useState.ts:42`).
-5. **Use web resources** - If the codebase references external concepts or you need context, search
-   for documentation.
+- **Explore first** - Don't guess. Use Glob and Grep to find relevant files, then Read to understand
+  them. Trace imports, function calls, and data flow.
+- **Cite your sources** - Back up claims with evidence:
+  1. Add footnotes referencing where a statement is sourced:
 
-## Response style
+     ```
+     The cache is invalidated whenever a user updates their profile. [^1]
 
-- Be thorough but focused on the question asked
-- Include code snippets when they help explain concepts
-- Explain the "why" not just the "what"
-- If you're uncertain about something, say so and explain what you did find
+     [^1]: **`src/services/user.ts:89`** - updateProfile() calls cache.invalidate()
+     ```
+
+     ```
+     The popover flips to the opposite side when it would overflow the viewport. [^2]
+
+     [^2]: **`src/utils/useAnchorPositioning.ts:215-220`** - flip middleware from Floating UI
+     ```
+
+  2. Reference file paths and line numbers directly in prose:
+
+     ```
+     As shown in `src/config/database.ts:12`, the connection pool defaults to 10.
+     ```
+
+     ```
+     The `useSignal` hook in `packages/react/src/index.ts:53` returns a stable reference.
+     ```
+
+  3. Include code snippets when they help illustrate the point:
+
+     ```
+     Signals track dependencies automatically when accessed inside an effect:
+
+     **`packages/core/src/index.ts:152-158`**
+
+         if (evalContext !== undefined) {
+           let node = evalContext._sources;
+           // Subscribe to the signal
+           node._source._subscribe(node);
+         }
+     ```
+
+     ```
+     Errors are wrapped with context before being rethrown:
+
+     **`src/utils/errors.ts:22-26`**
+
+         catch (err) {
+           throw new AppError(`Failed to ${operation}`, { cause: err });
+         }
+     ```
+
+  If examining multiple repositories, prefix paths with the repository name.
+
+- **Explain the why** - Don't just describe what code does; explain why it exists and how it fits
+  into the larger picture.
+- **Compare implementations** - When examining multiple repositories, highlight differences in
+  approach. Tables work well for summarizing tradeoffs.
+- **Use history** - When relevant, use git log/blame/show to understand how code evolved.
+- **Admit uncertainty** - If you're unsure about something, say so and explain what you did find.

package/src/commands/ask.ts

@@ -2,10 +2,18 @@ import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 
 import { argument, choice, constant, type InferValue, message, object, option, string } from '@optique/core';
-import { optional, withDefault } from '@optique/core/modifiers';
+import { multiple, optional, withDefault } from '@optique/core/modifiers';
 
 import { ensureRepo } from '../lib/git.ts';
-import { getRepoCachePath, normalizeRemote, parseRemote } from '../lib/paths.ts';
+import {
+	cleanupSessionDir,
+	createSessionDir,
+	getRepoCachePath,
+	normalizeRemote,
+	parseRemote,
+	parseRemoteWithBranch,
+} from '../lib/paths.ts';
+import { buildSymlinkDir, type RepoEntry } from '../lib/symlink.ts';
 
 // resolve asset paths relative to the bundle (dist/index.mjs -> dist/assets/)
 const assetsDir = join(import.meta.dirname, 'assets');
@@ -20,13 +28,22 @@ export const schema = object({
 		}),
 		'haiku',
 	),
+	// TODO: deprecated in favor of #branch syntax, remove in future version
 	branch: optional(
 		option('-b', '--branch', string(), {
-			description: message`branch to checkout`,
+			description: message`branch to checkout (deprecated: use repo#branch instead)`,
 		}),
 	),
+	with: withDefault(
+		multiple(
+			option('-w', '--with', string(), {
+				description: message`additional repository to include`,
+			}),
+		),
+		[],
+	),
 	remote: argument(string({ metavar: 'REPO' }), {
-		description: message`git remote URL (HTTP/HTTPS/SSH)`,
+		description: message`git remote URL (HTTP/HTTPS/SSH), optionally with #branch`,
 	}),
 	question: argument(string({ metavar: 'QUESTION' }), {
 		description: message`question to ask about the repository`,
@@ -35,70 +52,183 @@ export const schema = object({
 
 export type Args = InferValue<typeof schema>;
 
+/**
+ * prints an error message for invalid remote URL and exits.
+ * @param remote the invalid remote URL
+ */
+const exitInvalidRemote = (remote: string): never => {
+	console.error(`error: invalid remote URL: ${remote}`);
+	console.error('expected format: host/path, e.g.:');
+	console.error('  github.com/user/repo');
+	console.error('  gitlab.com/group/subgroup/repo');
+	console.error('  https://github.com/user/repo');
+	console.error('  git@github.com:user/repo.git');
+	process.exit(1);
+};
+
+/**
+ * validates and parses a remote string (with optional #branch).
+ * @param input the remote string, possibly with #branch suffix
+ * @returns parsed repo entry or exits on error
+ */
+const parseRepoInput = (input: string): RepoEntry => {
+	const { remote, branch } = parseRemoteWithBranch(input);
+	const parsed = parseRemote(remote);
+	if (!parsed) {
+		return exitInvalidRemote(remote);
+	}
+	const cachePath = getRepoCachePath(remote);
+	if (!cachePath) {
+		console.error(`error: could not determine cache path for: ${remote}`);
+		process.exit(1);
+	}
+	return { remote, parsed, cachePath, branch };
+};
+
+/**
+ * builds a context prompt for a single repository.
+ * @param repo the repo entry
+ * @returns context prompt string
+ */
+const buildSingleRepoContext = (repo: RepoEntry): string => {
+	const repoDisplay = `${repo.parsed.host}/${repo.parsed.path}`;
+	const branchDisplay = repo.branch ?? 'default branch';
+	return `You are examining ${repoDisplay} (checked out on ${branchDisplay}).`;
+};
+
+/**
+ * builds a context prompt for multiple repositories.
+ * @param dirMap map of directory name -> repo entry
+ * @returns context prompt string
+ */
+const buildMultiRepoContext = (dirMap: Map<string, RepoEntry>): string => {
+	const lines = ['You are examining multiple repositories:', ''];
+	for (const [dirName, repo] of dirMap) {
+		const repoDisplay = `${repo.parsed.host}/${repo.parsed.path}`;
+		const branchDisplay = repo.branch ?? 'default branch';
+		lines.push(`- ${dirName}/ -> ${repoDisplay} (checked out on ${branchDisplay})`);
+	}
+	return lines.join('\n');
+};
+
+/**
+ * spawns Claude Code and waits for it to exit.
+ * @param cwd working directory
+ * @param contextPrompt context prompt for Claude
+ * @param args command arguments
+ * @returns promise that resolves with exit code
+ */
+const spawnClaude = (cwd: string, contextPrompt: string, args: Args): Promise<number> =>
+	new Promise((resolve, reject) => {
+		const claudeArgs = [
+			'-p',
+			args.question,
+			'--model',
+			args.model,
+			'--settings',
+			settingsPath,
+			'--system-prompt-file',
+			systemPromptPath,
+			'--append-system-prompt',
+			contextPrompt,
+		];
+
+		console.error('spawning claude...');
+		const claude = spawn('claude', claudeArgs, {
+			cwd,
+			stdio: 'inherit',
+		});
+
+		claude.on('close', (code) => {
+			resolve(code ?? 0);
+		});
+
+		claude.on('error', (err) => {
+			reject(new Error(`failed to spawn claude: ${err}`));
+		});
+	});
+
 /**
  * handles the ask command.
  * clones/updates the repository and spawns Claude Code to answer the question.
  * @param args parsed command arguments
  */
 export const handler = async (args: Args): Promise<void> => {
-	// validate remote URL
-	const parsed = parseRemote(args.remote);
-	if (!parsed) {
-		console.error(`error: invalid remote URL: ${args.remote}`);
-		console.error('expected format: host/owner/repo, e.g.:');
-		console.error('  github.com/user/repo');
-		console.error('  https://github.com/user/repo');
-		console.error('  git@github.com:user/repo.git');
-		process.exit(1);
+	// parse main remote (with optional #branch)
+	const mainRepo = parseRepoInput(args.remote);
+
+	// #branch takes precedence over -b flag
+	if (!mainRepo.branch && args.branch) {
+		mainRepo.branch = args.branch;
 	}
 
-	// get cache path
-	const cachePath = getRepoCachePath(args.remote);
-	if (!cachePath) {
-		console.error(`error: could not determine cache path for: ${args.remote}`);
-		process.exit(1);
+	// #region single repo mode
+	if (args.with.length === 0) {
+		// clone or update repository
+		const remoteUrl = normalizeRemote(mainRepo.remote);
+		console.error(`preparing repository: ${mainRepo.parsed.host}/${mainRepo.parsed.path}`);
+		try {
+			await ensureRepo(remoteUrl, mainRepo.cachePath, mainRepo.branch);
+		} catch (err) {
+			console.error(`error: failed to prepare repository: ${err}`);
+			process.exit(1);
+		}
+
+		const contextPrompt = buildSingleRepoContext(mainRepo);
+		const exitCode = await spawnClaude(mainRepo.cachePath, contextPrompt, args);
+		process.exit(exitCode);
 	}
+	// #endregion
 
-	// clone or update repository
-	const remoteUrl = normalizeRemote(args.remote);
-	console.error(`preparing repository: ${parsed.host}/${parsed.owner}/${parsed.repo}`);
-	try {
-		await ensureRepo(remoteUrl, cachePath, args.branch);
-	} catch (err) {
-		console.error(`error: failed to prepare repository: ${err}`);
+	// #region multi repo mode
+	// parse all -w remotes
+	const additionalRepos = args.with.map(parseRepoInput);
+	const allRepos = [mainRepo, ...additionalRepos];
+
+	// clone/update all repos in parallel
+	console.error('preparing repositories...');
+	const prepareResults = await Promise.allSettled(
+		allRepos.map(async (repo) => {
+			const remoteUrl = normalizeRemote(repo.remote);
+			const display = `${repo.parsed.host}/${repo.parsed.path}`;
+			console.error(`  preparing: ${display}`);
+			await ensureRepo(remoteUrl, repo.cachePath, repo.branch);
+			return repo;
+		}),
+	);
+
+	// check for failures
+	const failures: string[] = [];
+	for (let i = 0; i < prepareResults.length; i++) {
+		const result = prepareResults[i]!;
+		if (result.status === 'rejected') {
+			const repo = allRepos[i]!;
+			const display = `${repo.parsed.host}/${repo.parsed.path}`;
+			failures.push(`  ${display}: ${result.reason}`);
+		}
+	}
+
+	if (failures.length > 0) {
+		console.error('error: failed to prepare repositories:');
+		for (const failure of failures) {
+			console.error(failure);
+		}
 		process.exit(1);
 	}
 
-	// build context for append prompt
-	const repoDisplay = `${parsed.host}/${parsed.owner}/${parsed.repo}`;
-	const branchDisplay = args.branch ?? 'default branch';
-	const contextPrompt = `You are examining ${repoDisplay} (checked out on ${branchDisplay}).`;
-
-	// spawn Claude Code
-	const claudeArgs = [
-		'-p',
-		args.question,
-		'--model',
-		args.model,
-		'--settings',
-		settingsPath,
-		'--system-prompt-file',
-		systemPromptPath,
-		'--append-system-prompt',
-		contextPrompt,
-	];
-
-	const claude = spawn('claude', claudeArgs, {
-		cwd: cachePath,
-		stdio: 'inherit',
-	});
+	// create session directory and symlinks
+	const sessionPath = await createSessionDir();
+	let exitCode = 1;
 
-	claude.on('close', (code) => {
-		process.exit(code ?? 0);
-	});
+	try {
+		const dirMap = await buildSymlinkDir(sessionPath, allRepos);
+		const contextPrompt = buildMultiRepoContext(dirMap);
+		exitCode = await spawnClaude(sessionPath, contextPrompt, args);
+	} finally {
+		// always clean up session directory
+		await cleanupSessionDir(sessionPath);
+	}
 
-	claude.on('error', (err) => {
-		console.error(`error: failed to spawn claude: ${err}`);
-		process.exit(1);
-	});
+	process.exit(exitCode);
+	// #endregion
 };