@oomfware/cgr 0.1.2 → 0.1.3

package/README.md

@@ -42,7 +42,7 @@ cgr clean --all
 ## commands
 
 ```
-cgr ask [-m opus|sonnet|haiku] [-w repo#branch ...] <repo#branch> <question>
+cgr ask [-m opus|sonnet|haiku] [-w repo[#branch] ...] <repo>[#branch] <question>
 cgr clean [--all | <repo>]
 ```
 
@@ -78,11 +78,11 @@ alternatively, a more structured prompt:
 
 You can use `@oomfware/cgr` to ask questions about external repositories.
 
-    npx @oomfware/cgr ask [options] <repo#branch> <question>
+    npx @oomfware/cgr ask [options] <repo>[#branch] <question>
 
     options:
-      -m, --model <model>  model to use: opus, sonnet, haiku (default: haiku)
-      -w, --with <repo>    additional repository to include (can be repeated)
+      -m, --model <model>   model to use: opus, sonnet, haiku (default: haiku)
+      -w, --with <repo>     additional repository to include, supports #branch (repeatable)
 
 Useful repositories:
 

package/dist/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
 
@@ -30,21 +30,60 @@ You also have read-only Bash access for standard Unix tools when needed.
 
 - **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** - Reference file paths and line numbers. When specifics matter, include
-  actual code snippets rather than paraphrasing.
-- **Explain the why** - Don't just describe what code does; explain why it exists and how it fits
-  into the larger picture.
-- **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.
+- **Cite your sources** - Back up claims with evidence:
+  1. Add footnotes referencing where a statement is sourced:
+
+     ```
+     The cache is invalidated whenever a user updates their profile. [^1]
+
+     [^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.
+     ```
 
-When citing code, use this format:
+     ```
+     The `useSignal` hook in `packages/react/src/index.ts:53` returns a stable reference.
+     ```
 
-**`path/to/file.ts:42-50`**
+  3. Include code snippets when they help illustrate the point:
 
-```typescript
-function example() {
-	return 'actual code from the file';
-}
-```
+     ```
+     Signals track dependencies automatically when accessed inside an effect:
 
-If examining multiple repositories, prefix paths with the repository name.
+     **`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/dist/index.mjs

@@ -2,32 +2,46 @@
 import { argument, choice, command, constant, message, object, option, or, string } from "@optique/core";
 import { run } from "@optique/run";
 import { spawn } from "node:child_process";
-import { dirname, join } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 import { multiple, optional, withDefault } from "@optique/core/modifiers";
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { mkdir, rm, symlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { mkdir, readdir, rm, stat, symlink } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
-import { createInterface } from "node:readline";
+import checkbox from "@inquirer/checkbox";
+import confirm from "@inquirer/confirm";
 
+//#region src/lib/debug.ts
+const debugEnabled = process.env.DEBUG === "1" || process.env.CGR_DEBUG === "1";
+/**
+* logs a debug message to stderr if DEBUG=1 or CGR_DEBUG=1.
+* @param message the message to log
+*/
+const debug = (message$1) => {
+	if (debugEnabled) console.error(`[debug] ${message$1}`);
+};
+
+//#endregion
 //#region src/lib/git.ts
 /**
 * executes a git command silently, only showing output on failure.
+* when debug is enabled, inherits stdio to show git progress.
 * @param args git command arguments
 * @param cwd working directory
 * @returns promise that resolves when the command completes
 */
 const git = (args, cwd) => new Promise((resolve, reject) => {
+	debug(`git ${args.join(" ")}${cwd ? ` (in ${cwd})` : ""}`);
 	const proc = spawn("git", args, {
 		cwd,
-		stdio: [
+		stdio: debugEnabled ? "inherit" : [
 			"inherit",
 			"pipe",
 			"pipe"
 		]
 	});
 	let stderr = "";
-	proc.stderr.on("data", (data) => {
+	if (!debugEnabled) proc.stderr.on("data", (data) => {
 		stderr += data.toString();
 	});
 	proc.on("close", (code) => {
@@ -41,17 +55,19 @@ const git = (args, cwd) => new Promise((resolve, reject) => {
 });
 /**
 * executes a git command and captures stdout, only showing stderr on failure.
+* when debug is enabled, inherits stderr to show git progress.
 * @param args git command arguments
 * @param cwd working directory
 * @returns promise that resolves with stdout
 */
 const gitOutput = (args, cwd) => new Promise((resolve, reject) => {
+	debug(`git ${args.join(" ")}${cwd ? ` (in ${cwd})` : ""}`);
 	const proc = spawn("git", args, {
 		cwd,
 		stdio: [
 			"inherit",
 			"pipe",
-			"pipe"
+			debugEnabled ? "inherit" : "pipe"
 		]
 	});
 	let output = "";
@@ -59,7 +75,7 @@ const gitOutput = (args, cwd) => new Promise((resolve, reject) => {
 	proc.stdout.on("data", (data) => {
 		output += data.toString();
 	});
-	proc.stderr.on("data", (data) => {
+	if (!debugEnabled) proc.stderr.on("data", (data) => {
 		stderr += data.toString();
 	});
 	proc.on("close", (code) => {
@@ -143,34 +159,52 @@ const getCacheDir = () => {
 * @returns the repos directory path
 */
 const getReposDir = () => join(getCacheDir(), "repos");
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+const UNSAFE_CHARS = /[<>:"|?*\\]/g;
 /**
-* parses a git remote URL and extracts host, owner, and repo.
+* sanitizes a path segment to be safe on all filesystems.
+* encodes unsafe characters using percent-encoding and handles windows reserved names.
+* @param segment the path segment to sanitize
+* @returns sanitized segment
+*/
+const sanitizeSegment = (segment) => {
+	let safe = segment.replace(/%/g, "%25").replace(UNSAFE_CHARS, (c) => `%${c.charCodeAt(0).toString(16).padStart(2, "0")}`).replace(/[. ]+$/, (m) => m.split("").map((c) => `%${c.charCodeAt(0).toString(16).padStart(2, "0")}`).join(""));
+	if (WINDOWS_RESERVED.test(safe)) safe = `${safe}_`;
+	return safe;
+};
+/**
+* parses a git remote URL and extracts host and path.
 * supports HTTP(S), SSH, and bare URLs (assumes HTTPS).
 * @param remote the remote URL to parse
 * @returns parsed components or null if invalid
 */
 const parseRemote = (remote) => {
-	const httpMatch = remote.match(/^https?:\/\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+	const httpMatch = remote.match(/^https?:\/\/([^/]+)\/(.+?)(?:\.git)?$/);
 	if (httpMatch) return {
 		host: httpMatch[1],
-		owner: httpMatch[2],
-		repo: httpMatch[3]
+		path: httpMatch[2]
 	};
-	const sshMatch = remote.match(/^git@([^:]+):([^/]+)\/([^/]+?)(?:\.git)?$/);
+	const sshMatch = remote.match(/^git@([^:]+):(.+?)(?:\.git)?$/);
 	if (sshMatch) return {
 		host: sshMatch[1],
-		owner: sshMatch[2],
-		repo: sshMatch[3]
+		path: sshMatch[2]
 	};
-	const bareMatch = remote.match(/^([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+	const bareMatch = remote.match(/^([^/]+)\/(.+?)(?:\.git)?$/);
 	if (bareMatch) return {
 		host: bareMatch[1],
-		owner: bareMatch[2],
-		repo: bareMatch[3]
+		path: bareMatch[2]
 	};
 	return null;
 };
 /**
+* sanitizes a parsed remote path for safe filesystem storage.
+* @param parsed the parsed remote (host + path)
+* @returns sanitized path segments joined with the system separator
+*/
+const sanitizeRemotePath = (parsed) => {
+	return join(sanitizeSegment(parsed.host.toLowerCase()), ...parsed.path.toLowerCase().split("/").map(sanitizeSegment));
+};
+/**
 * normalizes a remote URL by prepending https:// if no protocol is present.
 * @param remote the remote URL to normalize
 * @returns normalized URL with protocol
@@ -187,7 +221,7 @@ const normalizeRemote = (remote) => {
 const getRepoCachePath = (remote) => {
 	const parsed = parseRemote(remote);
 	if (!parsed) return null;
-	return join(getReposDir(), parsed.host, parsed.owner, parsed.repo);
+	return join(getReposDir(), sanitizeRemotePath(parsed));
 };
 /**
 * parses `remote#branch` syntax.
@@ -240,11 +274,12 @@ const buildSymlinkDir = async (sessionPath, repos) => {
 	const result$1 = /* @__PURE__ */ new Map();
 	const usedNames = /* @__PURE__ */ new Set();
 	for (const repo of repos) {
-		let name = repo.parsed.repo;
+		const repoName = basename(repo.parsed.path);
+		let name = repoName;
 		let suffix = 1;
 		while (usedNames.has(name)) {
 			suffix++;
-			name = `${repo.parsed.repo}-${suffix}`;
+			name = `${repoName}-${suffix}`;
 		}
 		usedNames.add(name);
 		result$1.set(name, repo);
@@ -277,8 +312,9 @@ const schema$1 = object({
 */
 const exitInvalidRemote = (remote) => {
 	console.error(`error: invalid remote URL: ${remote}`);
-	console.error("expected format: host/owner/repo, e.g.:");
+	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);
@@ -310,7 +346,7 @@ const parseRepoInput = (input) => {
 * @returns context prompt string
 */
 const buildSingleRepoContext = (repo) => {
-	return `You are examining ${`${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`} (checked out on ${repo.branch ?? "default branch"}).`;
+	return `You are examining ${`${repo.parsed.host}/${repo.parsed.path}`} (checked out on ${repo.branch ?? "default branch"}).`;
 };
 /**
 * builds a context prompt for multiple repositories.
@@ -320,7 +356,7 @@ const buildSingleRepoContext = (repo) => {
 const buildMultiRepoContext = (dirMap) => {
 	const lines = ["You are examining multiple repositories:", ""];
 	for (const [dirName, repo] of dirMap) {
-		const repoDisplay = `${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`;
+		const repoDisplay = `${repo.parsed.host}/${repo.parsed.path}`;
 		const branchDisplay = repo.branch ?? "default branch";
 		lines.push(`- ${dirName}/ -> ${repoDisplay} (checked out on ${branchDisplay})`);
 	}
@@ -368,7 +404,7 @@ const handler$1 = async (args) => {
 	if (!mainRepo.branch && args.branch) mainRepo.branch = args.branch;
 	if (args.with.length === 0) {
 		const remoteUrl = normalizeRemote(mainRepo.remote);
-		console.error(`preparing repository: ${mainRepo.parsed.host}/${mainRepo.parsed.owner}/${mainRepo.parsed.repo}`);
+		console.error(`preparing repository: ${mainRepo.parsed.host}/${mainRepo.parsed.path}`);
 		try {
 			await ensureRepo(remoteUrl, mainRepo.cachePath, mainRepo.branch);
 		} catch (err) {
@@ -383,7 +419,7 @@ const handler$1 = async (args) => {
 	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.owner}/${repo.parsed.repo}`;
+		const display = `${repo.parsed.host}/${repo.parsed.path}`;
 		console.error(`  preparing: ${display}`);
 		await ensureRepo(remoteUrl, repo.cachePath, repo.branch);
 		return repo;
@@ -393,7 +429,7 @@ const handler$1 = async (args) => {
 		const result$1 = prepareResults[i];
 		if (result$1.status === "rejected") {
 			const repo = allRepos[i];
-			const display = `${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`;
+			const display = `${repo.parsed.host}/${repo.parsed.path}`;
 			failures.push(`  ${display}: ${result$1.reason}`);
 		}
 	}
@@ -417,9 +453,23 @@ const handler$1 = async (args) => {
 const schema = object({
 	command: constant("clean"),
 	all: option("--all", { description: message`remove all cached repositories` }),
+	yes: option("-y", "--yes", { description: message`skip confirmation prompts` }),
 	remote: optional(argument(string({ metavar: "URL" }), { description: message`specific remote URL to clean` }))
 });
 /**
+* checks if a path exists.
+* @param path the path to check
+* @returns true if the path exists
+*/
+const exists = async (path) => {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+};
+/**
 * formats a byte size in human-readable form.
 * @param bytes size in bytes
 * @returns formatted string
@@ -435,69 +485,53 @@ const formatSize = (bytes) => {
 * @param dir directory path
 * @returns total size in bytes
 */
-const getDirSize = (dir) => {
+const getDirSize = async (dir) => {
 	let size = 0;
 	try {
-		const entries = readdirSync(dir, { withFileTypes: true });
+		const entries = await readdir(dir, { withFileTypes: true });
 		for (const entry of entries) {
 			const fullPath = join(dir, entry.name);
-			if (entry.isDirectory()) size += getDirSize(fullPath);
-			else size += statSync(fullPath).size;
+			if (entry.isDirectory()) size += await getDirSize(fullPath);
+			else {
+				const s = await stat(fullPath);
+				size += s.size;
+			}
 		}
 	} catch {}
 	return size;
 };
 /**
+* recursively finds git repositories within a directory.
+* yields directories that contain a .git subdirectory.
+* @param dir directory to search
+*/
+async function* findRepos(dir) {
+	try {
+		const entries = await readdir(dir, { withFileTypes: true });
+		if (entries.some((e) => e.name === ".git" && e.isDirectory())) yield dir;
+		else for (const entry of entries) if (entry.isDirectory()) yield* findRepos(join(dir, entry.name));
+	} catch {}
+}
+/**
 * lists all cached repositories with their sizes.
 * @returns array of { path, displayPath, size } objects
 */
-const listCachedRepos = () => {
+const listCachedRepos = async () => {
 	const reposDir = getReposDir();
+	if (!await exists(reposDir)) return [];
 	const repos = [];
-	if (!existsSync(reposDir)) return repos;
-	for (const host of readdirSync(reposDir)) {
-		const hostPath = join(reposDir, host);
-		if (!statSync(hostPath).isDirectory()) continue;
-		for (const owner of readdirSync(hostPath)) {
-			const ownerPath = join(hostPath, owner);
-			if (!statSync(ownerPath).isDirectory()) continue;
-			for (const repo of readdirSync(ownerPath)) {
-				const repoPath = join(ownerPath, repo);
-				if (!statSync(repoPath).isDirectory()) continue;
-				repos.push({
-					path: repoPath,
-					displayPath: `${host}/${owner}/${repo}`,
-					size: getDirSize(repoPath)
-				});
-			}
-		}
+	for await (const repoPath of findRepos(reposDir)) {
+		const displayPath = relative(reposDir, repoPath);
+		const size = await getDirSize(repoPath);
+		repos.push({
+			path: repoPath,
+			displayPath,
+			size
+		});
 	}
 	return repos;
 };
 /**
-* prompts the user for confirmation.
-* @param msg the prompt message
-* @returns promise that resolves to true if confirmed, or exits on interrupt
-*/
-const confirm = (msg) => new Promise((resolve) => {
-	let answered = false;
-	const rl = createInterface({
-		input: process.stdin,
-		output: process.stdout
-	});
-	rl.on("close", () => {
-		if (!answered) {
-			console.log();
-			process.exit(130);
-		}
-	});
-	rl.question(`${msg} [y/N] `, (answer) => {
-		answered = true;
-		rl.close();
-		resolve(answer.toLowerCase() === "y");
-	});
-});
-/**
 * handles the clean command.
 * @param args parsed command arguments
 */
@@ -505,16 +539,21 @@ const handler = async (args) => {
 	const reposDir = getReposDir();
 	const sessionsDir = getSessionsDir();
 	if (args.all) {
-		const reposExist = existsSync(reposDir);
-		const sessionsExist$1 = existsSync(sessionsDir);
+		const reposExist = await exists(reposDir);
+		const sessionsExist$1 = await exists(sessionsDir);
 		if (!reposExist && !sessionsExist$1) {
 			console.log("no cached data found");
 			return;
 		}
 		let totalSize$1 = 0;
-		if (reposExist) totalSize$1 += getDirSize(reposDir);
-		if (sessionsExist$1) totalSize$1 += getDirSize(sessionsDir);
-		console.log(`removing all cached data (${formatSize(totalSize$1)})`);
+		if (reposExist) totalSize$1 += await getDirSize(reposDir);
+		if (sessionsExist$1) totalSize$1 += await getDirSize(sessionsDir);
+		if (!args.yes) {
+			if (!await confirm({
+				message: `remove all cached data? (${formatSize(totalSize$1)})`,
+				default: false
+			})) return;
+		}
 		if (reposExist) await rm(reposDir, { recursive: true });
 		if (sessionsExist$1) await rm(sessionsDir, { recursive: true });
 		console.log("done");
@@ -526,43 +565,51 @@ const handler = async (args) => {
 			console.error(`error: invalid remote URL: ${args.remote}`);
 			process.exit(1);
 		}
-		if (!existsSync(cachePath)) {
+		if (!await exists(cachePath)) {
 			console.error(`error: repository not cached: ${args.remote}`);
 			process.exit(1);
 		}
-		const size = getDirSize(cachePath);
-		console.log(`removing ${cachePath} (${formatSize(size)})`);
+		const size = await getDirSize(cachePath);
+		if (!args.yes) {
+			if (!await confirm({
+				message: `remove ${args.remote}? (${formatSize(size)})`,
+				default: false
+			})) return;
+		}
 		await rm(cachePath, { recursive: true });
 		console.log("done");
 		return;
 	}
-	const repos = listCachedRepos();
-	const sessionsExist = existsSync(sessionsDir);
-	const sessionsSize = sessionsExist ? getDirSize(sessionsDir) : 0;
+	const repos = await listCachedRepos();
+	const sessionsExist = await exists(sessionsDir);
+	const sessionsSize = sessionsExist ? await getDirSize(sessionsDir) : 0;
 	if (repos.length === 0 && !sessionsExist) {
 		console.log("no cached data found");
 		return;
 	}
+	const choices = repos.map((repo) => ({
+		name: `${repo.displayPath.padEnd(50)} ${formatSize(repo.size)}`,
+		value: repo.path
+	}));
+	if (sessionsExist && sessionsSize > 0) choices.push({
+		name: `${"(sessions)".padEnd(50)} ${formatSize(sessionsSize)}`,
+		value: sessionsDir
+	});
+	const selected = await checkbox({
+		message: "select items to remove",
+		choices
+	});
+	if (selected.length === 0) return;
 	let totalSize = 0;
-	if (repos.length > 0) {
-		console.log("cached repositories:\n");
-		for (const repo of repos) {
-			console.log(`  ${repo.displayPath.padEnd(50)} ${formatSize(repo.size)}`);
-			totalSize += repo.size;
-		}
-	}
-	if (sessionsExist && sessionsSize > 0) {
-		if (repos.length > 0) console.log();
-		console.log(`sessions: ${formatSize(sessionsSize)}`);
-		totalSize += sessionsSize;
-	}
-	console.log(`\n  total: ${formatSize(totalSize)}`);
-	console.log();
-	if (await confirm("remove all cached data?")) {
-		if (repos.length > 0) await rm(reposDir, { recursive: true });
-		if (sessionsExist) await rm(sessionsDir, { recursive: true });
-		console.log("done");
+	for (const path of selected) totalSize += await getDirSize(path);
+	if (!args.yes) {
+		if (!await confirm({
+			message: `remove ${selected.length} item(s)? (${formatSize(totalSize)})`,
+			default: false
+		})) return;
 	}
+	for (const path of selected) await rm(path, { recursive: true });
+	console.log("done");
 };
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomfware/cgr",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "ask questions about git repositories using Claude Code",
   "license": "0BSD",
   "repository": {
@@ -21,6 +21,8 @@
     "access": "public"
   },
   "dependencies": {
+    "@inquirer/checkbox": "5.0.4",
+    "@inquirer/confirm": "6.0.4",
     "@optique/core": "^0.9.1",
     "@optique/run": "^0.9.1"
   },

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
 
@@ -30,21 +30,60 @@ You also have read-only Bash access for standard Unix tools when needed.
 
 - **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** - Reference file paths and line numbers. When specifics matter, include
-  actual code snippets rather than paraphrasing.
-- **Explain the why** - Don't just describe what code does; explain why it exists and how it fits
-  into the larger picture.
-- **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.
+- **Cite your sources** - Back up claims with evidence:
+  1. Add footnotes referencing where a statement is sourced:
+
+     ```
+     The cache is invalidated whenever a user updates their profile. [^1]
+
+     [^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.
+     ```
 
-When citing code, use this format:
+     ```
+     The `useSignal` hook in `packages/react/src/index.ts:53` returns a stable reference.
+     ```
 
-**`path/to/file.ts:42-50`**
+  3. Include code snippets when they help illustrate the point:
 
-```typescript
-function example() {
-	return 'actual code from the file';
-}
-```
+     ```
+     Signals track dependencies automatically when accessed inside an effect:
 
-If examining multiple repositories, prefix paths with the repository name.
+     **`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

@@ -58,8 +58,9 @@ export type Args = InferValue<typeof schema>;
  */
 const exitInvalidRemote = (remote: string): never => {
 	console.error(`error: invalid remote URL: ${remote}`);
-	console.error('expected format: host/owner/repo, e.g.:');
+	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);
@@ -90,7 +91,7 @@ const parseRepoInput = (input: string): RepoEntry => {
  * @returns context prompt string
  */
 const buildSingleRepoContext = (repo: RepoEntry): string => {
-	const repoDisplay = `${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`;
+	const repoDisplay = `${repo.parsed.host}/${repo.parsed.path}`;
 	const branchDisplay = repo.branch ?? 'default branch';
 	return `You are examining ${repoDisplay} (checked out on ${branchDisplay}).`;
 };
@@ -103,7 +104,7 @@ const buildSingleRepoContext = (repo: RepoEntry): 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.owner}/${repo.parsed.repo}`;
+		const repoDisplay = `${repo.parsed.host}/${repo.parsed.path}`;
 		const branchDisplay = repo.branch ?? 'default branch';
 		lines.push(`- ${dirName}/ -> ${repoDisplay} (checked out on ${branchDisplay})`);
 	}
@@ -165,9 +166,7 @@ export const handler = async (args: Args): Promise<void> => {
 	if (args.with.length === 0) {
 		// clone or update repository
 		const remoteUrl = normalizeRemote(mainRepo.remote);
-		console.error(
-			`preparing repository: ${mainRepo.parsed.host}/${mainRepo.parsed.owner}/${mainRepo.parsed.repo}`,
-		);
+		console.error(`preparing repository: ${mainRepo.parsed.host}/${mainRepo.parsed.path}`);
 		try {
 			await ensureRepo(remoteUrl, mainRepo.cachePath, mainRepo.branch);
 		} catch (err) {
@@ -191,7 +190,7 @@ export const handler = async (args: Args): Promise<void> => {
 	const prepareResults = await Promise.allSettled(
 		allRepos.map(async (repo) => {
 			const remoteUrl = normalizeRemote(repo.remote);
-			const display = `${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`;
+			const display = `${repo.parsed.host}/${repo.parsed.path}`;
 			console.error(`  preparing: ${display}`);
 			await ensureRepo(remoteUrl, repo.cachePath, repo.branch);
 			return repo;
@@ -204,7 +203,7 @@ export const handler = async (args: Args): Promise<void> => {
 		const result = prepareResults[i]!;
 		if (result.status === 'rejected') {
 			const repo = allRepos[i]!;
-			const display = `${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`;
+			const display = `${repo.parsed.host}/${repo.parsed.path}`;
 			failures.push(`  ${display}: ${result.reason}`);
 		}
 	}

package/src/commands/clean.ts

@@ -1,8 +1,8 @@
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import { rm } from 'node:fs/promises';
-import { join } from 'node:path';
-import { createInterface } from 'node:readline';
+import { readdir, rm, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
 
+import checkbox from '@inquirer/checkbox';
+import confirm from '@inquirer/confirm';
 import { argument, constant, type InferValue, message, object, option, string } from '@optique/core';
 import { optional } from '@optique/core/modifiers';
 
@@ -11,6 +11,7 @@ import { getRepoCachePath, getReposDir, getSessionsDir } from '../lib/paths.ts';
 export const schema = object({
 	command: constant('clean'),
 	all: option('--all', { description: message`remove all cached repositories` }),
+	yes: option('-y', '--yes', { description: message`skip confirmation prompts` }),
 	remote: optional(
 		argument(string({ metavar: 'URL' }), {
 			description: message`specific remote URL to clean`,
@@ -20,6 +21,20 @@ export const schema = object({
 
 export type Args = InferValue<typeof schema>;
 
+/**
+ * checks if a path exists.
+ * @param path the path to check
+ * @returns true if the path exists
+ */
+const exists = async (path: string): Promise<boolean> => {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+};
+
 /**
  * formats a byte size in human-readable form.
  * @param bytes size in bytes
@@ -43,16 +58,17 @@ const formatSize = (bytes: number): string => {
  * @param dir directory path
  * @returns total size in bytes
  */
-const getDirSize = (dir: string): number => {
+const getDirSize = async (dir: string): Promise<number> => {
 	let size = 0;
 	try {
-		const entries = readdirSync(dir, { withFileTypes: true });
+		const entries = await readdir(dir, { withFileTypes: true });
 		for (const entry of entries) {
 			const fullPath = join(dir, entry.name);
 			if (entry.isDirectory()) {
-				size += getDirSize(fullPath);
+				size += await getDirSize(fullPath);
 			} else {
-				size += statSync(fullPath).size;
+				const s = await stat(fullPath);
+				size += s.size;
 			}
 		}
 	} catch {
@@ -61,81 +77,50 @@ const getDirSize = (dir: string): number => {
 	return size;
 };
 
+/**
+ * recursively finds git repositories within a directory.
+ * yields directories that contain a .git subdirectory.
+ * @param dir directory to search
+ */
+async function* findRepos(dir: string): AsyncGenerator<string> {
+	try {
+		const entries = await readdir(dir, { withFileTypes: true });
+		const hasGit = entries.some((e) => e.name === '.git' && e.isDirectory());
+
+		if (hasGit) {
+			yield dir;
+		} else {
+			for (const entry of entries) {
+				if (entry.isDirectory()) {
+					yield* findRepos(join(dir, entry.name));
+				}
+			}
+		}
+	} catch {
+		// ignore errors (e.g., permission denied)
+	}
+}
+
 /**
  * lists all cached repositories with their sizes.
  * @returns array of { path, displayPath, size } objects
  */
-const listCachedRepos = (): {
-	path: string;
-	displayPath: string;
-	size: number;
-}[] => {
+const listCachedRepos = async (): Promise<{ path: string; displayPath: string; size: number }[]> => {
 	const reposDir = getReposDir();
-	const repos: { path: string; displayPath: string; size: number }[] = [];
 
-	if (!existsSync(reposDir)) {
-		return repos;
+	if (!(await exists(reposDir))) {
+		return [];
 	}
 
-	// iterate hosts
-	for (const host of readdirSync(reposDir)) {
-		const hostPath = join(reposDir, host);
-		if (!statSync(hostPath).isDirectory()) {
-			continue;
-		}
-
-		// iterate owners
-		for (const owner of readdirSync(hostPath)) {
-			const ownerPath = join(hostPath, owner);
-			if (!statSync(ownerPath).isDirectory()) {
-				continue;
-			}
-
-			// iterate repos
-			for (const repo of readdirSync(ownerPath)) {
-				const repoPath = join(ownerPath, repo);
-				if (!statSync(repoPath).isDirectory()) {
-					continue;
-				}
-
-				repos.push({
-					path: repoPath,
-					displayPath: `${host}/${owner}/${repo}`,
-					size: getDirSize(repoPath),
-				});
-			}
-		}
+	const repos: { path: string; displayPath: string; size: number }[] = [];
+	for await (const repoPath of findRepos(reposDir)) {
+		const displayPath = relative(reposDir, repoPath);
+		const size = await getDirSize(repoPath);
+		repos.push({ path: repoPath, displayPath, size });
 	}
-
 	return repos;
 };
 
-/**
- * prompts the user for confirmation.
- * @param msg the prompt message
- * @returns promise that resolves to true if confirmed, or exits on interrupt
- */
-const confirm = (msg: string): Promise<boolean> =>
-	new Promise((resolve) => {
-		let answered = false;
-		const rl = createInterface({
-			input: process.stdin,
-			output: process.stdout,
-		});
-		rl.on('close', () => {
-			if (!answered) {
-				// handle Ctrl+C or stream close
-				console.log();
-				process.exit(130);
-			}
-		});
-		rl.question(`${msg} [y/N] `, (answer) => {
-			answered = true;
-			rl.close();
-			resolve(answer.toLowerCase() === 'y');
-		});
-	});
-
 /**
  * handles the clean command.
  * @param args parsed command arguments
@@ -144,10 +129,10 @@ export const handler = async (args: Args): Promise<void> => {
 	const reposDir = getReposDir();
 	const sessionsDir = getSessionsDir();
 
-	// clean all
+	// #region clean all
 	if (args.all) {
-		const reposExist = existsSync(reposDir);
-		const sessionsExist = existsSync(sessionsDir);
+		const reposExist = await exists(reposDir);
+		const sessionsExist = await exists(sessionsDir);
 
 		if (!reposExist && !sessionsExist) {
 			console.log('no cached data found');
@@ -156,13 +141,22 @@ export const handler = async (args: Args): Promise<void> => {
 
 		let totalSize = 0;
 		if (reposExist) {
-			totalSize += getDirSize(reposDir);
+			totalSize += await getDirSize(reposDir);
 		}
 		if (sessionsExist) {
-			totalSize += getDirSize(sessionsDir);
+			totalSize += await getDirSize(sessionsDir);
+		}
+
+		if (!args.yes) {
+			const confirmed = await confirm({
+				message: `remove all cached data? (${formatSize(totalSize)})`,
+				default: false,
+			});
+			if (!confirmed) {
+				return;
+			}
 		}
 
-		console.log(`removing all cached data (${formatSize(totalSize)})`);
 		if (reposExist) {
 			await rm(reposDir, { recursive: true });
 		}
@@ -172,64 +166,89 @@ export const handler = async (args: Args): Promise<void> => {
 		console.log('done');
 		return;
 	}
+	// #endregion
 
-	// clean specific remote
+	// #region clean specific remote
 	if (args.remote) {
 		const cachePath = getRepoCachePath(args.remote);
 		if (!cachePath) {
 			console.error(`error: invalid remote URL: ${args.remote}`);
 			process.exit(1);
 		}
-		if (!existsSync(cachePath)) {
+		if (!(await exists(cachePath))) {
 			console.error(`error: repository not cached: ${args.remote}`);
 			process.exit(1);
 		}
-		const size = getDirSize(cachePath);
-		console.log(`removing ${cachePath} (${formatSize(size)})`);
+
+		const size = await getDirSize(cachePath);
+
+		if (!args.yes) {
+			const confirmed = await confirm({
+				message: `remove ${args.remote}? (${formatSize(size)})`,
+				default: false,
+			});
+			if (!confirmed) {
+				return;
+			}
+		}
+
 		await rm(cachePath, { recursive: true });
 		console.log('done');
 		return;
 	}
+	// #endregion
 
-	// list repos and prompt for confirmation
-	const repos = listCachedRepos();
-	const sessionsExist = existsSync(sessionsDir);
-	const sessionsSize = sessionsExist ? getDirSize(sessionsDir) : 0;
+	// #region interactive selection
+	const repos = await listCachedRepos();
+	const sessionsExist = await exists(sessionsDir);
+	const sessionsSize = sessionsExist ? await getDirSize(sessionsDir) : 0;
 
 	if (repos.length === 0 && !sessionsExist) {
 		console.log('no cached data found');
 		return;
 	}
 
-	let totalSize = 0;
+	// build choices for checkbox
+	const choices: { name: string; value: string }[] = repos.map((repo) => ({
+		name: `${repo.displayPath.padEnd(50)} ${formatSize(repo.size)}`,
+		value: repo.path,
+	}));
 
-	if (repos.length > 0) {
-		console.log('cached repositories:\n');
-		for (const repo of repos) {
-			console.log(`  ${repo.displayPath.padEnd(50)} ${formatSize(repo.size)}`);
-			totalSize += repo.size;
-		}
+	if (sessionsExist && sessionsSize > 0) {
+		choices.push({
+			name: `${'(sessions)'.padEnd(50)} ${formatSize(sessionsSize)}`,
+			value: sessionsDir,
+		});
 	}
 
-	if (sessionsExist && sessionsSize > 0) {
-		if (repos.length > 0) {
-			console.log();
-		}
-		console.log(`sessions: ${formatSize(sessionsSize)}`);
-		totalSize += sessionsSize;
+	const selected = await checkbox({
+		message: 'select items to remove',
+		choices,
+	});
+
+	if (selected.length === 0) {
+		return;
 	}
 
-	console.log(`\n  total: ${formatSize(totalSize)}`);
-	console.log();
+	// calculate total size of selected items
+	let totalSize = 0;
+	for (const path of selected) {
+		totalSize += await getDirSize(path);
+	}
 
-	const confirmed = await confirm('remove all cached data?');
-	if (confirmed) {
-		if (repos.length > 0) {
-			await rm(reposDir, { recursive: true });
-		}
-		if (sessionsExist) {
-			await rm(sessionsDir, { recursive: true });
+	if (!args.yes) {
+		const confirmed = await confirm({
+			message: `remove ${selected.length} item(s)? (${formatSize(totalSize)})`,
+			default: false,
+		});
+		if (!confirmed) {
+			return;
 		}
-		console.log('done');
 	}
+
+	for (const path of selected) {
+		await rm(path, { recursive: true });
+	}
+	console.log('done');
+	// #endregion
 };

package/src/lib/debug.ts

@@ -0,0 +1,11 @@
+export const debugEnabled = process.env.DEBUG === '1' || process.env.CGR_DEBUG === '1';
+
+/**
+ * logs a debug message to stderr if DEBUG=1 or CGR_DEBUG=1.
+ * @param message the message to log
+ */
+export const debug = (message: string): void => {
+	if (debugEnabled) {
+		console.error(`[debug] ${message}`);
+	}
+};

package/src/lib/git.ts

@@ -3,22 +3,28 @@ import { existsSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
 
+import { debug, debugEnabled } from './debug.ts';
+
 /**
  * executes a git command silently, only showing output on failure.
+ * when debug is enabled, inherits stdio to show git progress.
  * @param args git command arguments
  * @param cwd working directory
  * @returns promise that resolves when the command completes
  */
 const git = (args: string[], cwd?: string): Promise<void> =>
 	new Promise((resolve, reject) => {
+		debug(`git ${args.join(' ')}${cwd ? ` (in ${cwd})` : ''}`);
 		const proc = spawn('git', args, {
 			cwd,
-			stdio: ['inherit', 'pipe', 'pipe'],
+			stdio: debugEnabled ? 'inherit' : ['inherit', 'pipe', 'pipe'],
 		});
 		let stderr = '';
-		proc.stderr!.on('data', (data: Buffer) => {
-			stderr += data.toString();
-		});
+		if (!debugEnabled) {
+			proc.stderr!.on('data', (data: Buffer) => {
+				stderr += data.toString();
+			});
+		}
 		proc.on('close', (code) => {
 			if (code === 0) {
 				resolve();
@@ -34,24 +40,28 @@ const git = (args: string[], cwd?: string): Promise<void> =>
 
 /**
  * executes a git command and captures stdout, only showing stderr on failure.
+ * when debug is enabled, inherits stderr to show git progress.
  * @param args git command arguments
  * @param cwd working directory
  * @returns promise that resolves with stdout
  */
 const gitOutput = (args: string[], cwd?: string): Promise<string> =>
 	new Promise((resolve, reject) => {
+		debug(`git ${args.join(' ')}${cwd ? ` (in ${cwd})` : ''}`);
 		const proc = spawn('git', args, {
 			cwd,
-			stdio: ['inherit', 'pipe', 'pipe'],
+			stdio: ['inherit', 'pipe', debugEnabled ? 'inherit' : 'pipe'],
 		});
 		let output = '';
 		let stderr = '';
 		proc.stdout!.on('data', (data: Buffer) => {
 			output += data.toString();
 		});
-		proc.stderr!.on('data', (data: Buffer) => {
-			stderr += data.toString();
-		});
+		if (!debugEnabled) {
+			proc.stderr!.on('data', (data: Buffer) => {
+				stderr += data.toString();
+			});
+		}
 		proc.on('close', (code) => {
 			if (code === 0) {
 				resolve(output.trim());

package/src/lib/paths.ts

@@ -28,46 +28,88 @@ export const getCacheDir = (): string => {
  */
 export const getReposDir = (): string => join(getCacheDir(), 'repos');
 
+// windows reserved names that cannot be used as filenames
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+
+// characters that are invalid in windows filenames
+const UNSAFE_CHARS = /[<>:"|?*\\]/g;
+
 /**
- * parses a git remote URL and extracts host, owner, and repo.
+ * sanitizes a path segment to be safe on all filesystems.
+ * encodes unsafe characters using percent-encoding and handles windows reserved names.
+ * @param segment the path segment to sanitize
+ * @returns sanitized segment
+ */
+const sanitizeSegment = (segment: string): string => {
+	let safe = segment
+		// encode percent first to avoid double-encoding
+		.replace(/%/g, '%25')
+		// encode windows-unsafe characters
+		.replace(UNSAFE_CHARS, (c) => `%${c.charCodeAt(0).toString(16).padStart(2, '0')}`)
+		// trim trailing dots and spaces (windows doesn't allow them)
+		.replace(/[. ]+$/, (m) =>
+			m
+				.split('')
+				.map((c) => `%${c.charCodeAt(0).toString(16).padStart(2, '0')}`)
+				.join(''),
+		);
+
+	// handle windows reserved names by appending an underscore
+	if (WINDOWS_RESERVED.test(safe)) {
+		safe = `${safe}_`;
+	}
+
+	return safe;
+};
+
+/**
+ * parses a git remote URL and extracts host and path.
  * supports HTTP(S), SSH, and bare URLs (assumes HTTPS).
  * @param remote the remote URL to parse
  * @returns parsed components or null if invalid
  */
-export const parseRemote = (remote: string): { host: string; owner: string; repo: string } | null => {
-	// HTTP(S): https://github.com/user/repo or https://github.com/user/repo.git
-	const httpMatch = remote.match(/^https?:\/\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+export const parseRemote = (remote: string): { host: string; path: string } | null => {
+	// HTTP(S): https://github.com/user/repo[/more/paths] or ending with .git
+	const httpMatch = remote.match(/^https?:\/\/([^/]+)\/(.+?)(?:\.git)?$/);
 	if (httpMatch) {
 		return {
 			host: httpMatch[1]!,
-			owner: httpMatch[2]!,
-			repo: httpMatch[3]!,
+			path: httpMatch[2]!,
 		};
 	}
 
-	// SSH: git@github.com:user/repo.git or git@github.com:user/repo
-	const sshMatch = remote.match(/^git@([^:]+):([^/]+)\/([^/]+?)(?:\.git)?$/);
+	// SSH: git@github.com:path/to/repo.git or git@github.com:path/to/repo
+	const sshMatch = remote.match(/^git@([^:]+):(.+?)(?:\.git)?$/);
 	if (sshMatch) {
 		return {
 			host: sshMatch[1]!,
-			owner: sshMatch[2]!,
-			repo: sshMatch[3]!,
+			path: sshMatch[2]!,
 		};
 	}
 
 	// bare URL: github.com/user/repo (assumes HTTPS)
-	const bareMatch = remote.match(/^([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+	const bareMatch = remote.match(/^([^/]+)\/(.+?)(?:\.git)?$/);
 	if (bareMatch) {
 		return {
 			host: bareMatch[1]!,
-			owner: bareMatch[2]!,
-			repo: bareMatch[3]!,
+			path: bareMatch[2]!,
 		};
 	}
 
 	return null;
 };
 
+/**
+ * sanitizes a parsed remote path for safe filesystem storage.
+ * @param parsed the parsed remote (host + path)
+ * @returns sanitized path segments joined with the system separator
+ */
+export const sanitizeRemotePath = (parsed: { host: string; path: string }): string => {
+	const host = sanitizeSegment(parsed.host.toLowerCase());
+	const pathSegments = parsed.path.toLowerCase().split('/').map(sanitizeSegment);
+	return join(host, ...pathSegments);
+};
+
 /**
  * normalizes a remote URL by prepending https:// if no protocol is present.
  * @param remote the remote URL to normalize
@@ -90,7 +132,7 @@ export const getRepoCachePath = (remote: string): string | null => {
 	if (!parsed) {
 		return null;
 	}
-	return join(getReposDir(), parsed.host, parsed.owner, parsed.repo);
+	return join(getReposDir(), sanitizeRemotePath(parsed));
 };
 
 /**

package/src/lib/symlink.ts

@@ -1,8 +1,8 @@
 import { symlink } from 'node:fs/promises';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 
 /** parsed remote information */
-export type ParsedRemote = { host: string; owner: string; repo: string };
+export type ParsedRemote = { host: string; path: string };
 
 /** repository entry with all metadata needed for symlinking */
 export type RepoEntry = {
@@ -27,13 +27,15 @@ export const buildSymlinkDir = async (
 	const usedNames = new Set<string>();
 
 	for (const repo of repos) {
-		let name = repo.parsed.repo;
+		// use the last component of the path as the directory name
+		const repoName = basename(repo.parsed.path);
+		let name = repoName;
 		let suffix = 1;
 
 		// handle name conflicts
 		while (usedNames.has(name)) {
 			suffix++;
-			name = `${repo.parsed.repo}-${suffix}`;
+			name = `${repoName}-${suffix}`;
 		}
 
 		usedNames.add(name);