@nghyane/arcane 0.1.0

package/src/cli/web-search-cli.ts

@@ -0,0 +1,143 @@
+/**
+ * Web search CLI command handlers.
+ *
+ * Handles \`arc q`/\`arc web-search` subcommands for testing web search providers.
+ */
+
+import { APP_NAME } from "@nghyane/arcane-utils/dirs";
+import chalk from "chalk";
+import { initTheme, theme } from "../modes/theme/theme";
+import { runSearchQuery, type SearchParams } from "../web/search/index";
+import { SEARCH_PROVIDER_ORDER } from "../web/search/provider";
+import { renderSearchResult } from "../web/search/render";
+import type { SearchProviderId } from "../web/search/types";
+
+export interface SearchCommandArgs {
+	query: string;
+	provider?: SearchProviderId | "auto";
+	recency?: "day" | "week" | "month" | "year";
+	limit?: number;
+	expanded: boolean;
+}
+
+const PROVIDERS: Array<SearchProviderId | "auto"> = ["auto", ...SEARCH_PROVIDER_ORDER];
+
+const RECENCY_OPTIONS: SearchCommandArgs["recency"][] = ["day", "week", "month", "year"];
+
+/**
+ * Parse web search subcommand arguments.
+ * Returns undefined if not a web search command.
+ */
+export function parseSearchArgs(args: string[]): SearchCommandArgs | undefined {
+	if (args.length === 0 || (args[0] !== "q" && args[0] !== "web-search")) {
+		return undefined;
+	}
+
+	const result: SearchCommandArgs = {
+		query: "",
+		expanded: true,
+	};
+
+	const positional: string[] = [];
+
+	for (let i = 1; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--provider") {
+			result.provider = args[++i] as SearchCommandArgs["provider"];
+		} else if (arg === "--recency") {
+			result.recency = args[++i] as SearchCommandArgs["recency"];
+		} else if (arg === "--limit" || arg === "-l") {
+			result.limit = Number.parseInt(args[++i], 10);
+		} else if (arg === "--compact") {
+			result.expanded = false;
+		} else if (!arg.startsWith("-")) {
+			positional.push(arg);
+		}
+	}
+
+	if (positional.length > 0) {
+		result.query = positional.join(" ");
+	}
+
+	return result;
+}
+
+export async function runSearchCommand(cmd: SearchCommandArgs): Promise<void> {
+	if (!cmd.query) {
+		writeStderr(chalk.red("Error: Query is required"));
+		process.exit(1);
+	}
+
+	if (cmd.provider && !PROVIDERS.includes(cmd.provider)) {
+		writeStderr(chalk.red(`Error: Unknown provider "${cmd.provider}"`));
+		writeStderr(chalk.dim(`Valid providers: ${PROVIDERS.join(", ")}`));
+		process.exit(1);
+	}
+
+	if (cmd.recency && !RECENCY_OPTIONS.includes(cmd.recency)) {
+		writeStderr(chalk.red(`Error: Invalid recency "${cmd.recency}"`));
+		writeStderr(chalk.dim(`Valid recency values: ${RECENCY_OPTIONS.join(", ")}`));
+		process.exit(1);
+	}
+
+	if (cmd.limit !== undefined && Number.isNaN(cmd.limit)) {
+		writeStderr(chalk.red("Error: --limit must be a number"));
+		process.exit(1);
+	}
+
+	await initTheme();
+
+	const params: SearchParams = {
+		query: cmd.query,
+		provider: cmd.provider,
+		recency: cmd.recency,
+		limit: cmd.limit,
+		no_fallback: cmd.provider !== undefined && cmd.provider !== "auto",
+	};
+
+	const result = await runSearchQuery(params);
+	const component = renderSearchResult(result, { expanded: cmd.expanded, isPartial: false }, theme, {
+		query: cmd.query,
+		provider: cmd.provider,
+		allowLongAnswer: true,
+		maxAnswerLines: cmd.expanded ? undefined : 6,
+	});
+
+	const width = Math.max(60, process.stdout.columns ?? 100);
+	writeStdout(component.render(width).join("\n"));
+
+	if (result.details?.error) {
+		process.exitCode = 1;
+	}
+}
+
+export function printSearchHelp(): void {
+	writeStdout(`${chalk.bold(`${APP_NAME} q`)} - Test web search providers
+
+${chalk.bold("Usage:")}
+  ${APP_NAME} q [options] <query>
+  ${APP_NAME} web-search [options] <query>
+
+${chalk.bold("Arguments:")}
+  query      Search query text
+
+${chalk.bold("Options:")}
+  --provider <name>   Provider: ${PROVIDERS.join(", ")}
+  --recency <value>   Recency filter (Brave/Perplexity): ${RECENCY_OPTIONS.join(", ")}
+  -l, --limit <n>     Max results to return
+  --compact           Render condensed output
+  -h, --help          Show this help
+
+${chalk.bold("Examples:")}
+  ${APP_NAME} q --provider=exa "what's the color of the sky"
+  ${APP_NAME} q --provider=brave --recency=week "latest TypeScript 5.7 changes"
+`);
+}
+
+function writeStdout(message: string): void {
+	process.stdout.write(`${message}\n`);
+}
+
+function writeStderr(message: string): void {
+	process.stderr.write(`${message}\n`);
+}

package/src/cli.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry point — registers all commands explicitly and delegates to the
+ * lightweight CLI runner from pi-utils.
+ */
+import { type CommandEntry, run } from "@nghyane/arcane-utils/cli";
+import { APP_NAME, VERSION } from "@nghyane/arcane-utils/dirs";
+
+// Detect known Bun errata that cause TUI crashes (e.g. Bun.stringWidth mishandling OSC sequences).
+if (Bun.stringWidth("\x1b[0m\x1b]8;;\x07") !== 0) {
+	process.stderr.write(`error: Bun runtime errata detected (v${Bun.version}). Please update Bun: bun upgrade\n`);
+	process.exit(1);
+}
+
+process.title = APP_NAME;
+
+const commands: CommandEntry[] = [
+	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
+	{ name: "commit", load: () => import("./commands/commit").then(m => m.default) },
+	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
+	{ name: "grep", load: () => import("./commands/grep").then(m => m.default) },
+	{ name: "jupyter", load: () => import("./commands/jupyter").then(m => m.default) },
+	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
+	{ name: "setup", load: () => import("./commands/setup").then(m => m.default) },
+	{ name: "shell", load: () => import("./commands/shell").then(m => m.default) },
+	{ name: "ssh", load: () => import("./commands/ssh").then(m => m.default) },
+	{ name: "stats", load: () => import("./commands/stats").then(m => m.default) },
+	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
+	{ name: "search", load: () => import("./commands/web-search").then(m => m.default), aliases: ["q"] },
+];
+
+async function showHelp(config: import("@nghyane/arcane-utils/cli").CliConfig): Promise<void> {
+	const { renderRootHelp } = await import("@nghyane/arcane-utils/cli");
+	const { getExtraHelpText } = await import("./cli/args");
+	renderRootHelp(config);
+	const extra = getExtraHelpText();
+	if (extra.trim().length > 0) {
+		process.stdout.write(`\n${extra}\n`);
+	}
+}
+
+/**
+ * Determine whether argv[0] is a known subcommand name.
+ * If not, the entire argv is treated as args to the default "launch" command.
+ */
+function isSubcommand(first: string | undefined): boolean {
+	if (!first || first.startsWith("-") || first.startsWith("@")) return false;
+	return commands.some(e => e.name === first || e.aliases?.includes(first));
+}
+
+/** Run the CLI with the given argv (no `process.argv` prefix). */
+export function runCli(argv: string[]): Promise<void> {
+	// --help and --version are handled by run() directly, don't rewrite those.
+	// Everything else that isn't a known subcommand routes to "launch".
+	const first = argv[0];
+	const runArgv =
+		first === "--help" || first === "-h" || first === "--version" || first === "-v" || first === "help"
+			? argv
+			: isSubcommand(first)
+				? argv
+				: ["launch", ...argv];
+	return run({ bin: APP_NAME, version: VERSION, argv: runArgv, commands, help: showHelp });
+}
+
+await runCli(process.argv.slice(2));

package/src/commands/commit.ts

@@ -0,0 +1,36 @@
+/**
+ * Generate and optionally push a commit with changelog updates.
+ */
+import { Command, Flags } from "@nghyane/arcane-utils/cli";
+import { runCommitCommand } from "../commit";
+import type { CommitCommandArgs } from "../commit/types";
+import { initTheme } from "../modes/theme/theme";
+
+export default class Commit extends Command {
+	static description = "Generate a commit message and update changelogs";
+
+	static flags = {
+		push: Flags.boolean({ description: "Push after committing" }),
+		"dry-run": Flags.boolean({ description: "Preview without committing" }),
+		"no-changelog": Flags.boolean({ description: "Skip changelog updates" }),
+		legacy: Flags.boolean({ description: "Use legacy deterministic pipeline" }),
+		context: Flags.string({ char: "c", description: "Additional context for the model" }),
+		model: Flags.string({ char: "m", description: "Override model selection" }),
+	};
+
+	async run(): Promise<void> {
+		const { flags } = await this.parse(Commit);
+
+		const cmd: CommitCommandArgs = {
+			push: flags.push ?? false,
+			dryRun: flags["dry-run"] ?? false,
+			noChangelog: flags["no-changelog"] ?? false,
+			legacy: flags.legacy,
+			context: flags.context,
+			model: flags.model,
+		};
+
+		await initTheme();
+		await runCommitCommand(cmd);
+	}
+}

package/src/commands/config.ts

@@ -0,0 +1,51 @@
+/**
+ * Manage configuration settings.
+ */
+import { Args, Command, Flags } from "@nghyane/arcane-utils/cli";
+import { type ConfigAction, type ConfigCommandArgs, runConfigCommand } from "../cli/config-cli";
+import { initTheme } from "../modes/theme/theme";
+
+const ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path"];
+
+export default class Config extends Command {
+	static description = "Manage configuration settings";
+
+	static args = {
+		action: Args.string({
+			description: "Config action",
+			required: false,
+			options: ACTIONS,
+		}),
+		key: Args.string({
+			description: "Setting key",
+			required: false,
+		}),
+		value: Args.string({
+			description: "Value (for set/reset)",
+			required: false,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Config);
+		const action = (args.action ?? "list") as ConfigAction;
+		const value = Array.isArray(args.value) ? args.value.join(" ") : args.value;
+
+		const cmd: ConfigCommandArgs = {
+			action,
+			key: args.key,
+			value,
+			flags: {
+				json: flags.json,
+			},
+		};
+
+		await initTheme();
+		await runConfigCommand(cmd);
+	}
+}

package/src/commands/grep.ts

@@ -0,0 +1,41 @@
+/**
+ * Test grep tool.
+ */
+import { Args, Command, Flags } from "@nghyane/arcane-utils/cli";
+import { type GrepCommandArgs, runGrepCommand } from "../cli/grep-cli";
+import { initTheme } from "../modes/theme/theme";
+
+export default class Grep extends Command {
+	static description = "Test grep tool";
+
+	static args = {
+		pattern: Args.string({ description: "Regex pattern to search for", required: false }),
+		path: Args.string({ description: "Directory or file to search", required: false }),
+	};
+
+	static flags = {
+		glob: Flags.string({ char: "g", description: "Filter files by glob pattern" }),
+		limit: Flags.integer({ char: "l", description: "Max matches", default: 20 }),
+		context: Flags.integer({ char: "C", description: "Context lines", default: 2 }),
+		files: Flags.boolean({ char: "f", description: "Output file names only" }),
+		count: Flags.boolean({ char: "c", description: "Output match counts per file" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Grep);
+
+		const mode: GrepCommandArgs["mode"] = flags.count ? "count" : flags.files ? "filesWithMatches" : "content";
+
+		const cmd: GrepCommandArgs = {
+			pattern: args.pattern ?? "",
+			path: args.path ?? ".",
+			glob: flags.glob,
+			limit: flags.limit,
+			context: flags.context,
+			mode,
+		};
+
+		await initTheme();
+		await runGrepCommand(cmd);
+	}
+}

package/src/commands/jupyter.ts

@@ -0,0 +1,32 @@
+/**
+ * Manage the shared Jupyter gateway.
+ */
+import { Args, Command } from "@nghyane/arcane-utils/cli";
+import { type JupyterAction, type JupyterCommandArgs, runJupyterCommand } from "../cli/jupyter-cli";
+import { initTheme } from "../modes/theme/theme";
+
+const ACTIONS: JupyterAction[] = ["kill", "status"];
+
+export default class Jupyter extends Command {
+	static description = "Manage the shared Jupyter gateway";
+
+	static args = {
+		action: Args.string({
+			description: "Jupyter action",
+			required: false,
+			options: ACTIONS,
+		}),
+	};
+
+	async run(): Promise<void> {
+		const { args } = await this.parse(Jupyter);
+		const action = (args.action ?? "status") as JupyterAction;
+
+		const cmd: JupyterCommandArgs = {
+			action,
+		};
+
+		await initTheme();
+		await runJupyterCommand(cmd);
+	}
+}

package/src/commands/launch.ts

@@ -0,0 +1,139 @@
+/**
+ * Root command for the coding agent CLI.
+ */
+import { Args, Command, Flags } from "@nghyane/arcane-utils/cli";
+import { APP_NAME } from "@nghyane/arcane-utils/dirs";
+import { parseArgs } from "../cli/args";
+import { runRootCommand } from "../main";
+
+export default class Index extends Command {
+	static description = "AI coding assistant";
+	static hidden = true;
+
+	static args = {
+		messages: Args.string({
+			description: "Messages to send (prefix files with @)",
+			required: false,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		model: Flags.string({
+			description: 'Model to use (fuzzy match: "opus", "gpt-5.2", or "p-openai/gpt-5.2")',
+		}),
+		fast: Flags.string({
+			description: "Fast model for lightweight tasks (or ARCANE_FAST_MODEL env)",
+		}),
+		slow: Flags.string({
+			description: "Slow/reasoning model for thorough analysis (or ARCANE_SLOW_MODEL env)",
+		}),
+		plan: Flags.string({
+			description: "Plan model for architectural planning (or ARCANE_PLAN_MODEL env)",
+		}),
+		provider: Flags.string({
+			description: "Provider to use (legacy; prefer --model)",
+		}),
+		"api-key": Flags.string({
+			description: "API key (defaults to env vars)",
+		}),
+		"system-prompt": Flags.string({
+			description: "System prompt (default: coding assistant prompt)",
+		}),
+		"append-system-prompt": Flags.string({
+			description: "Append text or file contents to the system prompt",
+		}),
+		"allow-home": Flags.boolean({
+			description: "Allow starting in ~ without auto-switching to a temp dir",
+		}),
+		mode: Flags.string({
+			description: "Output mode: text (default), json, or rpc",
+			options: ["text", "json", "rpc"],
+		}),
+		print: Flags.boolean({
+			char: "p",
+			description: "Non-interactive mode: process prompt and exit",
+		}),
+		continue: Flags.boolean({
+			char: "c",
+			description: "Continue previous session",
+		}),
+		resume: Flags.string({
+			char: "r",
+			description: "Resume a session (by ID prefix, path, or picker if omitted)",
+		}),
+		"session-dir": Flags.string({
+			description: "Directory for session storage and lookup",
+		}),
+		"no-session": Flags.boolean({
+			description: "Don't save session (ephemeral)",
+		}),
+		models: Flags.string({
+			description: "Comma-separated model patterns for Ctrl+P cycling",
+		}),
+		"no-tools": Flags.boolean({
+			description: "Disable all built-in tools",
+		}),
+		"no-lsp": Flags.boolean({
+			description: "Disable LSP tools, formatting, and diagnostics",
+		}),
+		"no-pty": Flags.boolean({
+			description: "Disable PTY-based interactive bash execution",
+		}),
+		tools: Flags.string({
+			description: "Comma-separated list of tools to enable (default: all)",
+		}),
+		thinking: Flags.string({
+			description: "Set thinking level: off, minimal, low, medium, high, xhigh",
+			options: ["off", "minimal", "low", "medium", "high", "xhigh"],
+		}),
+		hook: Flags.string({
+			description: "Load a hook/extension file (can be used multiple times)",
+			multiple: true,
+		}),
+		extension: Flags.string({
+			char: "e",
+			description: "Load an extension file (can be used multiple times)",
+			multiple: true,
+		}),
+		"no-extensions": Flags.boolean({
+			description: "Disable extension discovery (explicit -e paths still work)",
+		}),
+		"no-skills": Flags.boolean({
+			description: "Disable skills discovery and loading",
+		}),
+		skills: Flags.string({
+			description: "Comma-separated glob patterns to filter skills (e.g., git-*,docker)",
+		}),
+		"no-rules": Flags.boolean({
+			description: "Disable rules discovery and loading",
+		}),
+		export: Flags.string({
+			description: "Export session file to HTML and exit",
+		}),
+		"list-models": Flags.string({
+			description: "List available models (with optional fuzzy search)",
+		}),
+		"no-title": Flags.boolean({
+			description: "Disable title auto-generation",
+		}),
+	};
+
+	static examples = [
+		`# Interactive mode\n  ${APP_NAME}`,
+		`# Interactive mode with initial prompt\n  ${APP_NAME} "List all .ts files in src/"`,
+		`# Include files in initial message\n  ${APP_NAME} @prompt.md @image.png "What color is the sky?"`,
+		`# Non-interactive mode (process and exit)\n  ${APP_NAME} -p "List all .ts files in src/"`,
+		`# Continue previous session\n  ${APP_NAME} --continue "What did we discuss?"`,
+		`# Use different model (fuzzy matching)\n  ${APP_NAME} --model opus "Help me refactor this code"`,
+		`# Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o`,
+		`# Export a session file to HTML\n  ${APP_NAME} --export ~/.arcane/agent/sessions/--path--/session.jsonl`,
+	];
+
+	static strict = false;
+
+	async run(): Promise<void> {
+		const parsed = parseArgs(this.argv);
+		await runRootCommand(parsed, this.argv);
+	}
+}

package/src/commands/plugin.ts

@@ -0,0 +1,70 @@
+/**
+ * Manage plugins (install, uninstall, list, etc.).
+ */
+import { Args, Command, Flags } from "@nghyane/arcane-utils/cli";
+import { type PluginAction, type PluginCommandArgs, runPluginCommand } from "../cli/plugin-cli";
+import { initTheme } from "../modes/theme/theme";
+
+const ACTIONS: PluginAction[] = [
+	"install",
+	"uninstall",
+	"list",
+	"link",
+	"doctor",
+	"features",
+	"config",
+	"enable",
+	"disable",
+];
+
+export default class Plugin extends Command {
+	static description = "Manage plugins (install, uninstall, list, etc.)";
+
+	static args = {
+		action: Args.string({
+			description: "Plugin action",
+			required: false,
+			options: ACTIONS,
+		}),
+		targets: Args.string({
+			description: "Packages, paths, or plugin names",
+			required: false,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON" }),
+		fix: Flags.boolean({ description: "Attempt to fix issues (doctor)" }),
+		force: Flags.boolean({ description: "Force install" }),
+		"dry-run": Flags.boolean({ description: "Show actions without applying changes" }),
+		local: Flags.boolean({ char: "l", description: "Operate on local plugin directory" }),
+		enable: Flags.string({ description: "Enable a feature" }),
+		disable: Flags.string({ description: "Disable a feature" }),
+		set: Flags.string({ description: "Set plugin config (key=value)" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Plugin);
+		const action = (args.action ?? "list") as PluginAction;
+
+		const targets = Array.isArray(args.targets) ? args.targets : args.targets ? [args.targets] : [];
+		const cmd: PluginCommandArgs = {
+			action,
+			args: targets,
+			flags: {
+				json: flags.json,
+				fix: flags.fix,
+				force: flags.force,
+				dryRun: flags["dry-run"],
+				local: flags.local,
+				enable: flags.enable,
+				disable: flags.disable,
+				set: flags.set,
+			},
+		};
+
+		await initTheme();
+		await runPluginCommand(cmd);
+	}
+}

package/src/commands/setup.ts

@@ -0,0 +1,42 @@
+/**
+ * Install dependencies for optional features.
+ */
+import { Args, Command, Flags, renderCommandHelp } from "@nghyane/arcane-utils/cli";
+import { runSetupCommand, type SetupCommandArgs, type SetupComponent } from "../cli/setup-cli";
+import { initTheme } from "../modes/theme/theme";
+
+const COMPONENTS: SetupComponent[] = ["python", "stt"];
+
+export default class Setup extends Command {
+	static description = "Install dependencies for optional features";
+
+	static args = {
+		component: Args.string({
+			description: "Component to install",
+			required: false,
+			options: COMPONENTS,
+		}),
+	};
+
+	static flags = {
+		check: Flags.boolean({ char: "c", description: "Check if dependencies are installed" }),
+		json: Flags.boolean({ description: "Output status as JSON" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Setup);
+		if (!args.component) {
+			renderCommandHelp("arc", "setup", Setup);
+			return;
+		}
+		const cmd: SetupCommandArgs = {
+			component: args.component as SetupComponent,
+			flags: {
+				json: flags.json,
+				check: flags.check,
+			},
+		};
+		await initTheme();
+		await runSetupCommand(cmd);
+	}
+}

package/src/commands/shell.ts

@@ -0,0 +1,29 @@
+/**
+ * Interactive shell console.
+ */
+import { Command, Flags } from "@nghyane/arcane-utils/cli";
+import { runShellCommand, type ShellCommandArgs } from "../cli/shell-cli";
+import { initTheme } from "../modes/theme/theme";
+
+export default class Shell extends Command {
+	static description = "Interactive shell console";
+
+	static flags = {
+		cwd: Flags.string({ char: "C", description: "Set working directory for commands" }),
+		timeout: Flags.integer({ char: "t", description: "Timeout per command in milliseconds" }),
+		"no-snapshot": Flags.boolean({ description: "Skip sourcing snapshot from user shell" }),
+	};
+
+	async run(): Promise<void> {
+		const { flags } = await this.parse(Shell);
+
+		const cmd: ShellCommandArgs = {
+			cwd: flags.cwd,
+			timeoutMs: flags.timeout,
+			noSnapshot: flags["no-snapshot"],
+		};
+
+		await initTheme();
+		await runShellCommand(cmd);
+	}
+}