@nghyane/arcane 0.1.0

package/src/cli/args.ts

@@ -0,0 +1,259 @@
+/**
+ * CLI argument parsing and help display
+ */
+import type { ThinkingLevel } from "@nghyane/arcane-agent";
+import { logger } from "@nghyane/arcane-utils";
+import { APP_NAME, CONFIG_DIR_NAME } from "@nghyane/arcane-utils/dirs";
+import chalk from "chalk";
+import { BUILTIN_TOOLS } from "../tools";
+
+export type Mode = "text" | "json" | "rpc";
+
+export interface Args {
+	cwd?: string;
+	allowHome?: boolean;
+	provider?: string;
+	model?: string;
+	fast?: string;
+	slow?: string;
+	plan?: string;
+	apiKey?: string;
+	systemPrompt?: string;
+	appendSystemPrompt?: string;
+	thinking?: ThinkingLevel;
+	continue?: boolean;
+	resume?: string | true;
+	help?: boolean;
+	version?: boolean;
+	mode?: Mode;
+	noSession?: boolean;
+	sessionDir?: string;
+	models?: string[];
+	tools?: string[];
+	noTools?: boolean;
+	noLsp?: boolean;
+	noPty?: boolean;
+	hooks?: string[];
+	extensions?: string[];
+	noExtensions?: boolean;
+	print?: boolean;
+	export?: string;
+	noSkills?: boolean;
+	skills?: string[];
+	noRules?: boolean;
+	listModels?: string | true;
+	noTitle?: boolean;
+	messages: string[];
+	fileArgs: string[];
+	/** Unknown flags (potentially extension flags) - map of flag name to value */
+	unknownFlags: Map<string, boolean | string>;
+}
+
+const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
+export function isValidThinkingLevel(level: string): level is ThinkingLevel {
+	return VALID_THINKING_LEVELS.includes(level as ThinkingLevel);
+}
+
+export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "boolean" | "string" }>): Args {
+	const result: Args = {
+		messages: [],
+		fileArgs: [],
+		unknownFlags: new Map(),
+	};
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+
+		if (arg === "--help" || arg === "-h") {
+			result.help = true;
+		} else if (arg === "--version" || arg === "-v") {
+			result.version = true;
+		} else if (arg === "--allow-home") {
+			result.allowHome = true;
+		} else if (arg === "--mode" && i + 1 < args.length) {
+			const mode = args[++i];
+			if (mode === "text" || mode === "json" || mode === "rpc") {
+				result.mode = mode;
+			}
+		} else if (arg === "--continue" || arg === "-c") {
+			result.continue = true;
+		} else if (arg === "--resume" || arg === "-r" || arg === "--session") {
+			const next = args[i + 1];
+			if (next && !next.startsWith("-")) {
+				result.resume = args[++i];
+			} else {
+				result.resume = true;
+			}
+		} else if (arg === "--provider" && i + 1 < args.length) {
+			result.provider = args[++i];
+		} else if (arg === "--model" && i + 1 < args.length) {
+			result.model = args[++i];
+		} else if (arg === "--fast" && i + 1 < args.length) {
+			result.fast = args[++i];
+		} else if (arg === "--slow" && i + 1 < args.length) {
+			result.slow = args[++i];
+		} else if (arg === "--plan" && i + 1 < args.length) {
+			result.plan = args[++i];
+		} else if (arg === "--api-key" && i + 1 < args.length) {
+			result.apiKey = args[++i];
+		} else if (arg === "--system-prompt" && i + 1 < args.length) {
+			result.systemPrompt = args[++i];
+		} else if (arg === "--append-system-prompt" && i + 1 < args.length) {
+			result.appendSystemPrompt = args[++i];
+		} else if (arg === "--no-session") {
+			result.noSession = true;
+		} else if (arg === "--session-dir" && i + 1 < args.length) {
+			result.sessionDir = args[++i];
+		} else if (arg === "--models" && i + 1 < args.length) {
+			result.models = args[++i].split(",").map(s => s.trim());
+		} else if (arg === "--no-tools") {
+			result.noTools = true;
+		} else if (arg === "--no-lsp") {
+			result.noLsp = true;
+		} else if (arg === "--no-pty") {
+			result.noPty = true;
+		} else if (arg === "--tools" && i + 1 < args.length) {
+			const toolNames = args[++i].split(",").map(s => s.trim());
+			const validTools: string[] = [];
+			for (const name of toolNames) {
+				if (name in BUILTIN_TOOLS) {
+					validTools.push(name);
+				} else {
+					logger.warn("Unknown tool passed to --tools", {
+						tool: name,
+						validTools: Object.keys(BUILTIN_TOOLS),
+					});
+				}
+			}
+			result.tools = validTools;
+		} else if (arg === "--thinking" && i + 1 < args.length) {
+			const level = args[++i];
+			if (isValidThinkingLevel(level)) {
+				result.thinking = level;
+			} else {
+				logger.warn("Invalid thinking level passed to --thinking", {
+					level,
+					validThinkingLevels: [...VALID_THINKING_LEVELS],
+				});
+			}
+		} else if (arg === "--print" || arg === "-p") {
+			result.print = true;
+		} else if (arg === "--export" && i + 1 < args.length) {
+			result.export = args[++i];
+		} else if (arg === "--hook" && i + 1 < args.length) {
+			result.hooks = result.hooks ?? [];
+			result.hooks.push(args[++i]);
+		} else if ((arg === "--extension" || arg === "-e") && i + 1 < args.length) {
+			result.extensions = result.extensions ?? [];
+			result.extensions.push(args[++i]);
+		} else if (arg === "--no-extensions") {
+			result.noExtensions = true;
+		} else if (arg === "--no-skills") {
+			result.noSkills = true;
+		} else if (arg === "--no-rules") {
+			result.noRules = true;
+		} else if (arg === "--no-title") {
+			result.noTitle = true;
+		} else if (arg === "--skills" && i + 1 < args.length) {
+			// Comma-separated glob patterns for skill filtering
+			result.skills = args[++i].split(",").map(s => s.trim());
+		} else if (arg === "--list-models") {
+			// Check if next arg is a search pattern (not a flag or file arg)
+			if (i + 1 < args.length && !args[i + 1].startsWith("-") && !args[i + 1].startsWith("@")) {
+				result.listModels = args[++i];
+			} else {
+				result.listModels = true;
+			}
+		} else if (arg.startsWith("@")) {
+			result.fileArgs.push(arg.slice(1)); // Remove @ prefix
+		} else if (arg.startsWith("--") && extensionFlags) {
+			// Check if it's an extension-registered flag
+			const flagName = arg.slice(2);
+			const extFlag = extensionFlags.get(flagName);
+			if (extFlag) {
+				if (extFlag.type === "boolean") {
+					result.unknownFlags.set(flagName, true);
+				} else if (extFlag.type === "string" && i + 1 < args.length) {
+					result.unknownFlags.set(flagName, args[++i]);
+				}
+			}
+			// Unknown flags without extensionFlags are silently ignored (first pass)
+		} else if (!arg.startsWith("-")) {
+			result.messages.push(arg);
+		}
+	}
+
+	return result;
+}
+
+export function getExtraHelpText(): string {
+	return `${chalk.bold("Environment Variables:")}
+  ${chalk.dim("# Core Providers")}
+  ANTHROPIC_AARCANE_KEY          - Anthropic Claude models
+  ANTHROPIC_OAUTH_TOKEN      - Anthropic OAuth (takes precedence over API key)
+  OPENAI_AARCANE_KEY             - OpenAI GPT models
+  GEMINI_AARCANE_KEY             - Google Gemini models
+  GITHUB_TOKEN               - GitHub Copilot (or GH_TOKEN, COPILOT_GITHUB_TOKEN)
+
+  ${chalk.dim("# Additional LLM Providers")}
+  AZURE_OPENAI_AARCANE_KEY       - Azure OpenAI models
+  GROQ_AARCANE_KEY               - Groq models
+  CEREBRAS_AARCANE_KEY           - Cerebras models
+  XAI_AARCANE_KEY                - xAI Grok models
+  OPENROUTER_AARCANE_KEY         - OpenRouter aggregated models
+  MISTRAL_AARCANE_KEY            - Mistral models
+  ZAI_AARCANE_KEY                - z.ai models (ZhipuAI/GLM)
+  MINIMAX_AARCANE_KEY            - MiniMax models
+  OPENCODE_AARCANE_KEY           - OpenCode models
+  CURSOR_ACCESS_TOKEN        - Cursor AI models
+  AI_GATEWAY_AARCANE_KEY         - Vercel AI Gateway
+
+  ${chalk.dim("# Cloud Providers")}
+  AWS_PROFILE                - AWS Bedrock (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
+  GOOGLE_CLOUD_PROJECT       - Google Vertex AI (requires GOOGLE_CLOUD_LOCATION)
+  GOOGLE_APPLICATION_CREDENTIALS - Service account for Vertex AI
+
+  ${chalk.dim("# Search & Tools")}
+  EXA_AARCANE_KEY                - Exa web search
+  BRAVE_AARCANE_KEY              - Brave web search
+  PERPLEXITY_AARCANE_KEY         - Perplexity web search
+  ANTHROPIC_SEARCH_AARCANE_KEY   - Anthropic search provider
+
+  ${chalk.dim("# Configuration")}
+  ARCANE_CODING_AGENT_DIR        - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)
+  ARCANE_PACKAGE_DIR             - Override package directory (for Nix/Guix store paths)
+  ARCANE_FAST_MODEL              - Override fast model (see --fast)
+  ARCANE_SLOW_MODEL              - Override slow/reasoning model (see --slow)
+  ARCANE_PLAN_MODEL              - Override planning model (see --plan)
+  ARCANE_NO_PTY                  - Disable PTY-based interactive bash execution
+
+  For complete environment variable reference, see:
+  ${chalk.dim("docs/environment-variables.md")}
+${chalk.bold("Available Tools (all enabled by default):")}
+  read       - Read file contents
+  bash       - Execute bash commands
+  edit       - Edit files with find/replace
+  write      - Write files (creates/overwrites)
+  grep       - Search file contents
+  find       - Find files by glob pattern
+  lsp        - Language server protocol (code intelligence)
+  python     - Execute Python code (requires: ${APP_NAME} setup python)
+  notebook   - Edit Jupyter notebooks
+  browser    - Browser automation (Puppeteer)
+  task       - Launch sub-agents for parallel tasks
+  todo_write - Manage todo/task lists
+  fetch      - Fetch and process URLs
+  web_search - Search the web
+  ask        - Ask user questions (interactive mode only)
+`;
+}
+
+export function printHelp(): void {
+	process.stdout.write(
+		`${chalk.bold(APP_NAME)} - AI coding assistant\n\n` +
+			`Run ${APP_NAME} --help for full command and option details.\n` +
+			`Run ${APP_NAME} <command> --help for command-specific help.\n\n` +
+			`${getExtraHelpText()}\n`,
+	);
+}

package/src/cli/config-cli.ts

@@ -0,0 +1,357 @@
+/**
+ * Config CLI command handlers.
+ *
+ * Handles \`arc config <command>` subcommands for managing settings.
+ * Uses settings-defs as the source of truth for available settings.
+ */
+
+import { APP_NAME, getAgentDir } from "@nghyane/arcane-utils/dirs";
+import chalk from "chalk";
+import {
+	getDefault,
+	getEnumValues,
+	getType,
+	type SettingPath,
+	Settings,
+	type SettingValue,
+	settings,
+} from "../config/settings";
+import { getAllSettingDefs, type SettingDef } from "../modes/components/settings-defs";
+import { theme } from "../modes/theme/theme";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type ConfigAction = "list" | "get" | "set" | "reset" | "path";
+
+export interface ConfigCommandArgs {
+	action: ConfigAction;
+	key?: string;
+	value?: string;
+	flags: {
+		json?: boolean;
+	};
+}
+
+// =============================================================================
+// Setting Filtering
+// =============================================================================
+
+/** Find setting definition by path */
+function findSettingDef(path: string): SettingDef | undefined {
+	return getAllSettingDefs().find(def => def.path === path);
+}
+
+/** Get available values for a setting */
+function getSettingValues(def: SettingDef): readonly string[] | undefined {
+	if (def.type === "enum") {
+		return def.values;
+	}
+	if (def.type === "submenu") {
+		const options = def.options;
+		if (options.length > 0) {
+			return options.map(o => o.value);
+		}
+	}
+	return undefined;
+}
+
+// =============================================================================
+// Argument Parser
+// =============================================================================
+
+const VALID_ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path"];
+
+/**
+ * Parse config subcommand arguments.
+ * Returns undefined if not a config command.
+ */
+export function parseConfigArgs(args: string[]): ConfigCommandArgs | undefined {
+	if (args.length === 0 || args[0] !== "config") {
+		return undefined;
+	}
+
+	if (args.length < 2 || args[1] === "--help" || args[1] === "-h") {
+		return { action: "list", flags: {} };
+	}
+
+	const action = args[1];
+	if (!VALID_ACTIONS.includes(action as ConfigAction)) {
+		console.error(chalk.red(`Unknown config command: ${action}`));
+		console.error(`Valid commands: ${VALID_ACTIONS.join(", ")}`);
+		process.exit(1);
+	}
+
+	const result: ConfigCommandArgs = {
+		action: action as ConfigAction,
+		flags: {},
+	};
+
+	const positionalArgs: string[] = [];
+	for (let i = 2; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--json") {
+			result.flags.json = true;
+		} else if (!arg.startsWith("-")) {
+			positionalArgs.push(arg);
+		}
+	}
+
+	if (positionalArgs.length > 0) {
+		result.key = positionalArgs[0];
+	}
+	if (positionalArgs.length > 1) {
+		result.value = positionalArgs.slice(1).join(" ");
+	}
+
+	return result;
+}
+
+// =============================================================================
+// Value Formatting
+// =============================================================================
+
+function formatValue(value: unknown): string {
+	if (value === undefined || value === null) {
+		return chalk.dim("(not set)");
+	}
+	if (typeof value === "boolean") {
+		return value ? chalk.green("true") : chalk.red("false");
+	}
+	if (typeof value === "number") {
+		return chalk.cyan(String(value));
+	}
+	return chalk.yellow(String(value));
+}
+
+function getTypeDisplay(def: SettingDef): string {
+	if (def.type === "boolean") {
+		return "(boolean)";
+	}
+	const values = getSettingValues(def);
+	if (values && values.length > 0) {
+		return `(${values.join("|")})`;
+	}
+	return "(string)";
+}
+
+// =============================================================================
+// Schema-Driven Value Parsing
+// =============================================================================
+
+function parseAndSetValue(path: SettingPath, rawValue: string): void {
+	const schemaType = getType(path);
+	let parsedValue: unknown;
+
+	const trimmed = rawValue.trim();
+	switch (schemaType) {
+		case "boolean": {
+			const lower = trimmed.toLowerCase();
+			if (["true", "1", "yes", "on"].includes(lower)) parsedValue = true;
+			else if (["false", "0", "no", "off"].includes(lower)) parsedValue = false;
+			else throw new Error(`Invalid boolean value: ${rawValue}. Use true/false, yes/no, on/off, or 1/0`);
+			break;
+		}
+		case "number":
+			parsedValue = Number(trimmed);
+			if (!Number.isFinite(parsedValue)) throw new Error(`Invalid number: ${rawValue}`);
+			break;
+		case "enum": {
+			const valid = getEnumValues(path);
+			if (valid && !valid.includes(trimmed)) {
+				throw new Error(`Invalid value: ${rawValue}. Valid values: ${valid.join(", ")}`);
+			}
+			parsedValue = trimmed;
+			break;
+		}
+		default:
+			parsedValue = trimmed;
+	}
+
+	settings.set(path, parsedValue as SettingValue<typeof path>);
+}
+
+// =============================================================================
+// Command Handlers
+// =============================================================================
+
+export async function runConfigCommand(cmd: ConfigCommandArgs): Promise<void> {
+	await Settings.init();
+
+	switch (cmd.action) {
+		case "list":
+			handleList(cmd.flags);
+			break;
+		case "get":
+			handleGet(cmd.key, cmd.flags);
+			break;
+		case "set":
+			await handleSet(cmd.key, cmd.value, cmd.flags);
+			break;
+		case "reset":
+			await handleReset(cmd.key, cmd.flags);
+			break;
+		case "path":
+			handlePath();
+			break;
+	}
+}
+
+function handleList(flags: { json?: boolean }): void {
+	const defs = getAllSettingDefs();
+
+	if (flags.json) {
+		const result: Record<string, { value: unknown; type: string; description: string }> = {};
+		for (const def of defs) {
+			result[def.path] = {
+				value: settings.get(def.path as SettingPath),
+				type: def.type,
+				description: def.description,
+			};
+		}
+		console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+
+	console.log(chalk.bold("Settings:\n"));
+
+	const groups: Record<string, SettingDef[]> = {};
+	for (const def of defs) {
+		if (!groups[def.tab]) {
+			groups[def.tab] = [];
+		}
+		groups[def.tab].push(def);
+	}
+
+	const sortedGroups = Object.keys(groups).sort((a, b) => {
+		if (a === "config") return -1;
+		if (b === "config") return 1;
+		return a.localeCompare(b);
+	});
+
+	for (const group of sortedGroups) {
+		console.log(chalk.bold.blue(`[${group}]`));
+		for (const def of groups[group]) {
+			const value = settings.get(def.path as SettingPath);
+			const valueStr = formatValue(value);
+			const typeStr = getTypeDisplay(def);
+			console.log(`  ${chalk.white(def.path)} = ${valueStr} ${chalk.dim(typeStr)}`);
+		}
+		console.log("");
+	}
+}
+
+function handleGet(key: string | undefined, flags: { json?: boolean }): void {
+	if (!key) {
+		console.error(chalk.red(`Usage: ${APP_NAME} config get <key>`));
+		console.error(chalk.dim(`\nRun '${APP_NAME} config list' to see available keys`));
+		process.exit(1);
+	}
+
+	const def = findSettingDef(key);
+	if (!def) {
+		console.error(chalk.red(`Unknown setting: ${key}`));
+		console.error(chalk.dim(`\nRun '${APP_NAME} config list' to see available keys`));
+		process.exit(1);
+	}
+
+	const value = settings.get(def.path as SettingPath);
+
+	if (flags.json) {
+		console.log(JSON.stringify({ key: def.path, value, type: def.type, description: def.description }, null, 2));
+		return;
+	}
+
+	console.log(formatValue(value));
+}
+
+async function handleSet(key: string | undefined, value: string | undefined, flags: { json?: boolean }): Promise<void> {
+	if (!key || value === undefined) {
+		console.error(chalk.red(`Usage: ${APP_NAME} config set <key> <value>`));
+		console.error(chalk.dim(`\nRun '${APP_NAME} config list' to see available keys`));
+		process.exit(1);
+	}
+
+	const def = findSettingDef(key);
+	if (!def) {
+		console.error(chalk.red(`Unknown setting: ${key}`));
+		console.error(chalk.dim(`\nRun '${APP_NAME} config list' to see available keys`));
+		process.exit(1);
+	}
+
+	try {
+		parseAndSetValue(def.path as SettingPath, value);
+	} catch (err) {
+		console.error(chalk.red(String(err)));
+		process.exit(1);
+	}
+
+	const newValue = settings.get(def.path as SettingPath);
+
+	if (flags.json) {
+		console.log(JSON.stringify({ key: def.path, value: newValue }));
+	} else {
+		console.log(chalk.green(`${theme.status.success} Set ${def.path} = ${formatValue(newValue)}`));
+	}
+}
+
+async function handleReset(key: string | undefined, flags: { json?: boolean }): Promise<void> {
+	if (!key) {
+		console.error(chalk.red(`Usage: ${APP_NAME} config reset <key>`));
+		console.error(chalk.dim(`\nRun '${APP_NAME} config list' to see available keys`));
+		process.exit(1);
+	}
+
+	const def = findSettingDef(key);
+	if (!def) {
+		console.error(chalk.red(`Unknown setting: ${key}`));
+		console.error(chalk.dim(`\nRun '${APP_NAME} config list' to see available keys`));
+		process.exit(1);
+	}
+
+	const path = def.path as SettingPath;
+	const defaultValue = getDefault(path);
+	settings.set(path, defaultValue as SettingValue<typeof path>);
+
+	if (flags.json) {
+		console.log(JSON.stringify({ key: def.path, value: defaultValue }));
+	} else {
+		console.log(chalk.green(`${theme.status.success} Reset ${def.path} to ${formatValue(defaultValue)}`));
+	}
+}
+
+function handlePath(): void {
+	console.log(getAgentDir());
+}
+
+// =============================================================================
+// Help
+// =============================================================================
+
+export function printConfigHelp(): void {
+	console.log(`${chalk.bold(`${APP_NAME} config`)} - Manage settings
+
+${chalk.bold("Commands:")}
+  list               List all settings with current values
+  get <key>          Get a specific setting value
+  set <key> <value>  Set a setting value
+  reset <key>        Reset a setting to its default value
+  path               Print the config directory path
+
+${chalk.bold("Options:")}
+  --json             Output as JSON
+
+${chalk.bold("Examples:")}
+  ${APP_NAME} config list
+  ${APP_NAME} config get theme
+  ${APP_NAME} config set theme catppuccin-mocha
+  ${APP_NAME} config set compaction.enabled false
+  ${APP_NAME} config set defaultThinkingLevel medium
+  ${APP_NAME} config reset steeringMode
+  ${APP_NAME} config list --json
+
+${chalk.bold("Boolean Values:")}
+  true, false, yes, no, on, off, 1, 0
+`);
+}