@oomfware/cgr 0.1.1 → 0.1.3

package/src/commands/clean.ts

@@ -1,16 +1,17 @@
-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';
 
-import { getRepoCachePath, getReposDir } from '../lib/paths.ts';
+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,138 +77,178 @@ 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
  */
 export const handler = async (args: Args): Promise<void> => {
 	const reposDir = getReposDir();
+	const sessionsDir = getSessionsDir();
 
-	// clean all
+	// #region clean all
 	if (args.all) {
-		if (!existsSync(reposDir)) {
-			console.log('no cached repositories found');
+		const reposExist = await exists(reposDir);
+		const sessionsExist = await exists(sessionsDir);
+
+		if (!reposExist && !sessionsExist) {
+			console.log('no cached data found');
 			return;
 		}
-		const size = getDirSize(reposDir);
-		console.log(`removing all cached repositories (${formatSize(size)})`);
-		await rm(reposDir, { recursive: true });
+
+		let totalSize = 0;
+		if (reposExist) {
+			totalSize += await getDirSize(reposDir);
+		}
+		if (sessionsExist) {
+			totalSize += await getDirSize(sessionsDir);
+		}
+
+		if (!args.yes) {
+			const confirmed = await confirm({
+				message: `remove all cached data? (${formatSize(totalSize)})`,
+				default: false,
+			});
+			if (!confirmed) {
+				return;
+			}
+		}
+
+		if (reposExist) {
+			await rm(reposDir, { recursive: true });
+		}
+		if (sessionsExist) {
+			await rm(sessionsDir, { recursive: true });
+		}
 		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();
-	if (repos.length === 0) {
-		console.log('no cached repositories found');
+	// #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;
+	}
+
+	// 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 (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;
 	}
 
-	console.log('cached repositories:\n');
+	// calculate total size of selected items
 	let totalSize = 0;
-	for (const repo of repos) {
-		console.log(`  ${repo.displayPath.padEnd(50)} ${formatSize(repo.size)}`);
-		totalSize += repo.size;
+	for (const path of selected) {
+		totalSize += await getDirSize(path);
 	}
-	console.log(`\n  total: ${formatSize(totalSize)}`);
-	console.log();
 
-	const confirmed = await confirm('remove all cached repositories?');
-	if (confirmed) {
-		await rm(reposDir, { recursive: true });
-		console.log('done');
+	if (!args.yes) {
+		const confirmed = await confirm({
+			message: `remove ${selected.length} item(s)? (${formatSize(totalSize)})`,
+			default: false,
+		});
+		if (!confirmed) {
+			return;
+		}
+	}
+
+	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,35 @@ 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 and returns the result.
+ * 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',
+			stdio: debugEnabled ? 'inherit' : ['inherit', 'pipe', 'pipe'],
 		});
+		let stderr = '';
+		if (!debugEnabled) {
+			proc.stderr!.on('data', (data: Buffer) => {
+				stderr += data.toString();
+			});
+		}
 		proc.on('close', (code) => {
 			if (code === 0) {
 				resolve();
 			} else {
+				if (stderr) {
+					process.stderr.write(stderr);
+				}
 				reject(new Error(`git ${args[0]} failed with code ${code}`));
 			}
 		});
@@ -26,25 +39,36 @@ const git = (args: string[], cwd?: string): Promise<void> =>
 	});
 
 /**
- * executes a git command and captures stdout.
+ * 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', 'inherit'],
+			stdio: ['inherit', 'pipe', debugEnabled ? 'inherit' : 'pipe'],
 		});
 		let output = '';
+		let stderr = '';
 		proc.stdout!.on('data', (data: Buffer) => {
 			output += data.toString();
 		});
+		if (!debugEnabled) {
+			proc.stderr!.on('data', (data: Buffer) => {
+				stderr += data.toString();
+			});
+		}
 		proc.on('close', (code) => {
 			if (code === 0) {
 				resolve(output.trim());
 			} else {
+				if (stderr) {
+					process.stderr.write(stderr);
+				}
 				reject(new Error(`git ${args[0]} failed with code ${code}`));
 			}
 		});

package/src/lib/paths.ts

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, rm } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
@@ -26,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
@@ -88,5 +132,45 @@ 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));
+};
+
+/**
+ * parses `remote#branch` syntax.
+ * @param input the input string, e.g. `github.com/owner/repo#develop`
+ * @returns object with remote and optional branch
+ */
+export const parseRemoteWithBranch = (input: string): { remote: string; branch?: string } => {
+	const hashIndex = input.lastIndexOf('#');
+	if (hashIndex === -1) {
+		return { remote: input };
+	}
+	return {
+		remote: input.slice(0, hashIndex),
+		branch: input.slice(hashIndex + 1),
+	};
+};
+
+/**
+ * returns the sessions directory within the cache.
+ * @returns the sessions directory path
+ */
+export const getSessionsDir = (): string => join(getCacheDir(), 'sessions');
+
+/**
+ * creates a new session directory with a random UUID.
+ * @returns the path to the created session directory
+ */
+export const createSessionDir = async (): Promise<string> => {
+	const sessionPath = join(getSessionsDir(), randomUUID());
+	await mkdir(sessionPath, { recursive: true });
+	return sessionPath;
+};
+
+/**
+ * removes a session directory.
+ * @param sessionPath the session directory path
+ */
+export const cleanupSessionDir = async (sessionPath: string): Promise<void> => {
+	await rm(sessionPath, { recursive: true, force: true });
 };

package/src/lib/symlink.ts

@@ -0,0 +1,49 @@
+import { symlink } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+/** parsed remote information */
+export type ParsedRemote = { host: string; path: string };
+
+/** repository entry with all metadata needed for symlinking */
+export type RepoEntry = {
+	remote: string;
+	parsed: ParsedRemote;
+	cachePath: string;
+	branch?: string;
+};
+
+/**
+ * builds symlinks in a session directory for all repositories.
+ * handles name conflicts by appending `-2`, `-3`, etc.
+ * @param sessionPath the session directory path
+ * @param repos array of repository entries to symlink
+ * @returns map of directory name -> repo entry
+ */
+export const buildSymlinkDir = async (
+	sessionPath: string,
+	repos: RepoEntry[],
+): Promise<Map<string, RepoEntry>> => {
+	const result = new Map<string, RepoEntry>();
+	const usedNames = new Set<string>();
+
+	for (const repo of repos) {
+		// 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 = `${repoName}-${suffix}`;
+		}
+
+		usedNames.add(name);
+		result.set(name, repo);
+
+		const linkPath = join(sessionPath, name);
+		await symlink(repo.cachePath, linkPath);
+	}
+
+	return result;
+};