@nghyane/arcane 0.1.0

package/src/cli/file-processor.ts

@@ -0,0 +1,124 @@
+/**
+ * Process @file CLI arguments into text content and image attachments
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ImageContent } from "@nghyane/arcane-ai";
+import { isEnoent } from "@nghyane/arcane-utils";
+import { getProjectDir } from "@nghyane/arcane-utils/dirs";
+import chalk from "chalk";
+import { formatBytes } from "../session/streaming-output";
+import { resolveReadPath } from "../tools/path-utils";
+import { formatDimensionNote, resizeImage } from "../utils/image-resize";
+import { detectSupportedImageMimeTypeFromFile } from "../utils/mime";
+
+// Keep CLI startup responsive and avoid OOM when users pass huge files.
+// If a file exceeds these limits, we include it as a path-only <file/> block.
+const MAX_CLI_TEXT_BYTES = 5 * 1024 * 1024; // 5MB
+const MAX_CLI_IMAGE_BYTES = 25 * 1024 * 1024; // 25MB
+
+export interface ProcessedFiles {
+	text: string;
+	images: ImageContent[];
+}
+
+export interface ProcessFileOptions {
+	/** Whether to auto-resize images to 2000x2000 max. Default: true */
+	autoResizeImages?: boolean;
+}
+
+/** Process @file arguments into text content and image attachments */
+export async function processFileArguments(fileArgs: string[], options?: ProcessFileOptions): Promise<ProcessedFiles> {
+	const autoResizeImages = options?.autoResizeImages ?? true;
+	let text = "";
+	const images: ImageContent[] = [];
+
+	for (const fileArg of fileArgs) {
+		// Expand and resolve path (handles ~ expansion and macOS screenshot Unicode spaces)
+		const absolutePath = path.resolve(resolveReadPath(fileArg, getProjectDir()));
+
+		const stat = fs.statSync(absolutePath, { throwIfNoEntry: false });
+		if (!stat) {
+			console.error(chalk.red(`Error: File not found: ${absolutePath}`));
+			process.exit(1);
+		}
+
+		const mimeType = await detectSupportedImageMimeTypeFromFile(absolutePath);
+		const maxBytes = mimeType ? MAX_CLI_IMAGE_BYTES : MAX_CLI_TEXT_BYTES;
+		if (stat.size > maxBytes) {
+			console.error(
+				chalk.yellow(`Warning: Skipping file contents (too large: ${formatBytes(stat.size)}): ${absolutePath}`),
+			);
+			text += `<file name="${absolutePath}">(skipped: too large, ${formatBytes(stat.size)})</file>\n`;
+			continue;
+		}
+
+		// Read file, handling not-found gracefully
+		let buffer: Uint8Array;
+		try {
+			buffer = await Bun.file(absolutePath).bytes();
+		} catch (err) {
+			if (isEnoent(err)) {
+				console.error(chalk.red(`Error: File not found: ${absolutePath}`));
+				process.exit(1);
+			}
+			throw err;
+		}
+		if (buffer.length === 0) {
+			continue;
+		}
+
+		if (mimeType) {
+			// Handle image file
+			const base64Content = buffer.toBase64();
+			let attachment: ImageContent;
+			let dimensionNote: string | undefined;
+
+			if (autoResizeImages) {
+				try {
+					const resized = await resizeImage({ type: "image", data: base64Content, mimeType });
+					dimensionNote = formatDimensionNote(resized);
+					attachment = {
+						type: "image",
+						mimeType: resized.mimeType,
+						data: resized.data,
+					};
+				} catch {
+					// Fall back to original image on resize failure
+					attachment = {
+						type: "image",
+						mimeType,
+						data: base64Content,
+					};
+				}
+			} else {
+				attachment = {
+					type: "image",
+					mimeType,
+					data: base64Content,
+				};
+			}
+
+			images.push(attachment);
+
+			// Add text reference to image with optional dimension note
+			if (dimensionNote) {
+				text += `<file name="${absolutePath}">${dimensionNote}</file>\n`;
+			} else {
+				text += `<file name="${absolutePath}"></file>\n`;
+			}
+		} else {
+			// Handle text file
+			try {
+				const content = new TextDecoder().decode(buffer);
+				text += `<file name="${absolutePath}">\n${content}\n</file>\n`;
+			} catch (error: unknown) {
+				const message = error instanceof Error ? error.message : String(error);
+				console.error(chalk.red(`Error: Could not read file ${absolutePath}: ${message}`));
+				process.exit(1);
+			}
+		}
+	}
+
+	return { text, images };
+}

package/src/cli/grep-cli.ts

@@ -0,0 +1,152 @@
+/**
+ * Grep CLI command handlers.
+ *
+ * Handles \`arc grep` subcommand for testing grep tool on Windows.
+ */
+import * as path from "node:path";
+import { grep } from "@nghyane/arcane-natives";
+import { APP_NAME } from "@nghyane/arcane-utils/dirs";
+import chalk from "chalk";
+
+export interface GrepCommandArgs {
+	pattern: string;
+	path: string;
+	glob?: string;
+	limit: number;
+	context: number;
+	mode: "content" | "filesWithMatches" | "count";
+}
+
+/**
+ * Parse grep subcommand arguments.
+ * Returns undefined if not a grep command.
+ */
+export function parseGrepArgs(args: string[]): GrepCommandArgs | undefined {
+	if (args.length === 0 || args[0] !== "grep") {
+		return undefined;
+	}
+
+	const result: GrepCommandArgs = {
+		pattern: "",
+		path: ".",
+		limit: 20,
+		context: 2,
+		mode: "content",
+	};
+
+	const positional: string[] = [];
+
+	for (let i = 1; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--glob" || arg === "-g") {
+			result.glob = args[++i];
+		} else if (arg === "--limit" || arg === "-l") {
+			result.limit = parseInt(args[++i], 10);
+		} else if (arg === "--context" || arg === "-C") {
+			result.context = parseInt(args[++i], 10);
+		} else if (arg === "--files" || arg === "-f") {
+			result.mode = "filesWithMatches";
+		} else if (arg === "--count" || arg === "-c") {
+			result.mode = "count";
+		} else if (!arg.startsWith("-")) {
+			positional.push(arg);
+		}
+	}
+
+	if (positional.length >= 1) {
+		result.pattern = positional[0];
+	}
+	if (positional.length >= 2) {
+		result.path = positional[1];
+	}
+
+	return result;
+}
+
+export async function runGrepCommand(cmd: GrepCommandArgs): Promise<void> {
+	if (!cmd.pattern) {
+		console.error(chalk.red("Error: Pattern is required"));
+		process.exit(1);
+	}
+
+	const searchPath = path.resolve(cmd.path);
+	console.log(chalk.dim(`Searching in: ${searchPath}`));
+	console.log(chalk.dim(`Pattern: ${cmd.pattern}`));
+	console.log(chalk.dim(`Mode: ${cmd.mode}, Limit: ${cmd.limit}, Context: ${cmd.context}`));
+
+	console.log("");
+
+	try {
+		const result = await grep({
+			pattern: cmd.pattern,
+			path: searchPath,
+			glob: cmd.glob,
+			mode: cmd.mode,
+			maxCount: cmd.limit,
+			context: cmd.mode === "content" ? cmd.context : undefined,
+			hidden: true,
+		});
+
+		console.log(chalk.green(`Total matches: ${result.totalMatches}`));
+		console.log(chalk.green(`Files with matches: ${result.filesWithMatches}`));
+		console.log(chalk.green(`Files searched: ${result.filesSearched}`));
+		if (result.limitReached) {
+			console.log(chalk.yellow(`Limit reached: true`));
+		}
+		console.log("");
+
+		for (const match of result.matches) {
+			const displayPath = match.path.replace(/\\/g, "/");
+
+			if (cmd.mode === "content") {
+				if (match.contextBefore) {
+					for (const ctx of match.contextBefore) {
+						console.log(chalk.dim(`${displayPath}-${ctx.lineNumber}- ${ctx.line}`));
+					}
+				}
+				console.log(`${chalk.cyan(displayPath)}:${chalk.yellow(String(match.lineNumber))}: ${match.line}`);
+				if (match.contextAfter) {
+					for (const ctx of match.contextAfter) {
+						console.log(chalk.dim(`${displayPath}-${ctx.lineNumber}- ${ctx.line}`));
+					}
+				}
+				console.log("");
+			} else if (cmd.mode === "count") {
+				console.log(`${chalk.cyan(displayPath)}: ${match.matchCount ?? 0} matches`);
+			} else {
+				console.log(chalk.cyan(displayPath));
+			}
+		}
+	} catch (err) {
+		console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+		process.exit(1);
+	}
+}
+
+export function printGrepHelp(): void {
+	console.log(`${chalk.bold(`${APP_NAME} grep`)} - Test grep tool
+
+${chalk.bold("Usage:")}
+  ${APP_NAME} grep <pattern> [path] [options]
+
+${chalk.bold("Arguments:")}
+  pattern   Regex pattern to search for
+  path      Directory or file to search (default: .)
+
+${chalk.bold("Options:")}
+  -g, --glob <pattern>  Filter files by glob pattern
+  -l, --limit <n>       Max matches (default: 20)
+  -C, --context <n>     Context lines (default: 2)
+  -f, --files           Output file names only
+  -c, --count           Output match counts per file
+  -h, --help            Show this help
+
+${chalk.bold("Environment:")}
+  ARCANE_GREP_WORKERS=0    Disable worker pool (use single-threaded mode)
+
+${chalk.bold("Examples:")}
+  ${APP_NAME} grep "import" src/
+  ${APP_NAME} grep "TODO" . --glob "*.ts"
+  ${APP_NAME} grep "function" --files
+`);
+}

package/src/cli/jupyter-cli.ts

@@ -0,0 +1,106 @@
+/**
+ * Jupyter CLI command handlers.
+ *
+ * Handles \`arc jupyter` subcommand for managing the shared Python gateway.
+ */
+
+import { APP_NAME } from "@nghyane/arcane-utils/dirs";
+import chalk from "chalk";
+import { getGatewayStatus, shutdownSharedGateway } from "../ipy/gateway-coordinator";
+
+export type JupyterAction = "kill" | "status";
+
+export interface JupyterCommandArgs {
+	action: JupyterAction;
+}
+
+export function parseJupyterArgs(args: string[]): JupyterCommandArgs | undefined {
+	if (args.length === 0 || args[0] !== "jupyter") {
+		return undefined;
+	}
+
+	const action = args[1] as JupyterAction | undefined;
+	if (!action || !["kill", "status"].includes(action)) {
+		return { action: "status" };
+	}
+
+	return { action };
+}
+
+export async function runJupyterCommand(cmd: JupyterCommandArgs): Promise<void> {
+	switch (cmd.action) {
+		case "kill":
+			await runKill();
+			break;
+		case "status":
+			await runStatus();
+			break;
+	}
+}
+
+async function runKill(): Promise<void> {
+	const status = await getGatewayStatus();
+
+	if (!status.active) {
+		console.log(chalk.dim("No Jupyter gateway is running"));
+		return;
+	}
+
+	console.log(`Killing Jupyter gateway (PID ${status.pid})...`);
+	await shutdownSharedGateway();
+	console.log(chalk.green("Jupyter gateway stopped"));
+}
+
+async function runStatus(): Promise<void> {
+	const status = await getGatewayStatus();
+
+	if (!status.active) {
+		console.log(chalk.dim("No Jupyter gateway is running"));
+		return;
+	}
+
+	console.log(chalk.bold("Jupyter Gateway Status\n"));
+	console.log(`  ${chalk.green("●")} Running`);
+	console.log(`  PID:    ${status.pid}`);
+	console.log(`  URL:    ${status.url}`);
+	if (status.uptime !== null) {
+		console.log(`  Uptime: ${formatUptime(status.uptime)}`);
+	}
+	if (status.pythonPath) {
+		console.log(`  Python: ${status.pythonPath}`);
+	}
+	if (status.venvPath) {
+		console.log(`  Venv:   ${status.venvPath}`);
+	}
+}
+
+function formatUptime(ms: number): string {
+	const seconds = Math.floor(ms / 1000);
+	const minutes = Math.floor(seconds / 60);
+	const hours = Math.floor(minutes / 60);
+
+	if (hours > 0) {
+		return `${hours}h ${minutes % 60}m`;
+	}
+	if (minutes > 0) {
+		return `${minutes}m ${seconds % 60}s`;
+	}
+	return `${seconds}s`;
+}
+
+export function printJupyterHelp(): void {
+	console.log(`${chalk.bold(`${APP_NAME} jupyter`)} - Manage the shared Jupyter gateway
+
+${chalk.bold("Usage:")}
+  ${APP_NAME} jupyter <command>
+
+${chalk.bold("Commands:")}
+  status    Show gateway status (default)
+  kill      Stop the running gateway
+
+${chalk.bold("Examples:")}
+  ${APP_NAME} jupyter           # Show status
+  ${APP_NAME} jupyter status    # Show status
+  ${APP_NAME} jupyter kill      # Stop the gateway
+`);
+}

package/src/cli/list-models.ts

@@ -0,0 +1,103 @@
+/**
+ * List available models with optional fuzzy search
+ */
+import type { Api, Model } from "@nghyane/arcane-ai";
+import type { ModelRegistry } from "../config/model-registry";
+import { fuzzyFilter } from "../utils/fuzzy";
+
+/**
+ * Format a number as human-readable (e.g., 200000 -> "200K", 1000000 -> "1M")
+ */
+function formatTokenCount(count: number): string {
+	if (count >= 1_000_000) {
+		const millions = count / 1_000_000;
+		return millions % 1 === 0 ? `${millions}M` : `${millions.toFixed(1)}M`;
+	}
+	if (count >= 1_000) {
+		const thousands = count / 1_000;
+		return thousands % 1 === 0 ? `${thousands}K` : `${thousands.toFixed(1)}K`;
+	}
+	return count.toString();
+}
+
+/**
+ * List available models, optionally filtered by search pattern
+ */
+export async function listModels(modelRegistry: ModelRegistry, searchPattern?: string): Promise<void> {
+	const models = modelRegistry.getAvailable();
+
+	if (models.length === 0) {
+		console.log("No models available. Set API keys in environment variables.");
+		return;
+	}
+
+	// Apply fuzzy filter if search pattern provided
+	let filteredModels: Model<Api>[] = models;
+	if (searchPattern) {
+		filteredModels = fuzzyFilter(models, searchPattern, m => `${m.provider} ${m.id}`);
+	}
+
+	if (filteredModels.length === 0) {
+		console.log(`No models matching "${searchPattern}"`);
+		return;
+	}
+
+	// Sort by provider, then by model id
+	filteredModels.sort((a, b) => {
+		const providerCmp = a.provider.localeCompare(b.provider);
+		if (providerCmp !== 0) return providerCmp;
+		return a.id.localeCompare(b.id);
+	});
+
+	// Calculate column widths
+	const rows = filteredModels.map(m => ({
+		provider: m.provider,
+		model: m.id,
+		context: formatTokenCount(m.contextWindow),
+		maxOut: formatTokenCount(m.maxTokens),
+		thinking: m.reasoning ? "yes" : "no",
+		images: m.input.includes("image") ? "yes" : "no",
+	}));
+
+	const headers = {
+		provider: "provider",
+		model: "model",
+		context: "context",
+		maxOut: "max-out",
+		thinking: "thinking",
+		images: "images",
+	};
+
+	const widths = {
+		provider: Math.max(headers.provider.length, ...rows.map(r => r.provider.length)),
+		model: Math.max(headers.model.length, ...rows.map(r => r.model.length)),
+		context: Math.max(headers.context.length, ...rows.map(r => r.context.length)),
+		maxOut: Math.max(headers.maxOut.length, ...rows.map(r => r.maxOut.length)),
+		thinking: Math.max(headers.thinking.length, ...rows.map(r => r.thinking.length)),
+		images: Math.max(headers.images.length, ...rows.map(r => r.images.length)),
+	};
+
+	// Print header
+	const headerLine = [
+		headers.provider.padEnd(widths.provider),
+		headers.model.padEnd(widths.model),
+		headers.context.padEnd(widths.context),
+		headers.maxOut.padEnd(widths.maxOut),
+		headers.thinking.padEnd(widths.thinking),
+		headers.images.padEnd(widths.images),
+	].join("  ");
+	console.log(headerLine);
+
+	// Print rows
+	for (const row of rows) {
+		const line = [
+			row.provider.padEnd(widths.provider),
+			row.model.padEnd(widths.model),
+			row.context.padEnd(widths.context),
+			row.maxOut.padEnd(widths.maxOut),
+			row.thinking.padEnd(widths.thinking),
+			row.images.padEnd(widths.images),
+		].join("  ");
+		console.log(line);
+	}
+}