@nghyane/arcane 0.1.0

package/src/cli/ssh-cli.ts

@@ -0,0 +1,179 @@
+/**
+ * SSH CLI command handlers.
+ *
+ * Handles \`arc ssh <command>` subcommands for SSH host configuration management.
+ */
+
+import { getSSHConfigPath } from "@nghyane/arcane-utils/dirs";
+import chalk from "chalk";
+import { addSSHHost, readSSHConfigFile, removeSSHHost, type SSHHostConfig } from "../ssh/config-writer";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type SSHAction = "add" | "remove" | "list";
+
+export interface SSHCommandArgs {
+	action: SSHAction;
+	args: string[];
+	flags: {
+		json?: boolean;
+		host?: string;
+		user?: string;
+		port?: string;
+		key?: string;
+		desc?: string;
+		compat?: boolean;
+		scope?: "project" | "user";
+	};
+}
+
+// =============================================================================
+// Main dispatcher
+// =============================================================================
+
+export async function runSSHCommand(cmd: SSHCommandArgs): Promise<void> {
+	switch (cmd.action) {
+		case "add":
+			await handleAdd(cmd);
+			break;
+		case "remove":
+			await handleRemove(cmd);
+			break;
+		case "list":
+			await handleList(cmd);
+			break;
+		default:
+			process.stdout.write(chalk.red(`Unknown action: ${cmd.action}\n`));
+			process.stdout.write(`Valid actions: add, remove, list\n`);
+			process.exitCode = 1;
+	}
+}
+
+// =============================================================================
+// Handlers
+// =============================================================================
+
+async function handleAdd(cmd: SSHCommandArgs): Promise<void> {
+	const name = cmd.args[0];
+	if (!name) {
+		process.stdout.write(chalk.red("Error: Host name required\n"));
+		process.stdout.write(
+			chalk.dim("Usage: arcane ssh add <name> --host <address> [--user <user>] [--port <port>] [--key <path>]\n"),
+		);
+		process.exitCode = 1;
+		return;
+	}
+
+	const host = cmd.flags.host;
+	if (!host) {
+		process.stdout.write(chalk.red("Error: --host is required\n"));
+		process.stdout.write(chalk.dim("Usage: arcane ssh add <name> --host <address>\n"));
+		process.exitCode = 1;
+		return;
+	}
+
+	// Validate port if provided
+	if (cmd.flags.port !== undefined) {
+		const port = Number.parseInt(cmd.flags.port, 10);
+		if (Number.isNaN(port) || port < 1 || port > 65535) {
+			process.stdout.write(chalk.red("Error: Port must be an integer between 1 and 65535\n"));
+			process.exitCode = 1;
+			return;
+		}
+	}
+
+	const hostConfig: SSHHostConfig = { host };
+	if (cmd.flags.user) hostConfig.username = cmd.flags.user;
+	if (cmd.flags.port) hostConfig.port = Number.parseInt(cmd.flags.port, 10);
+	if (cmd.flags.key) hostConfig.keyPath = cmd.flags.key;
+	if (cmd.flags.desc) hostConfig.description = cmd.flags.desc;
+	if (cmd.flags.compat) hostConfig.compat = true;
+
+	const scope = cmd.flags.scope ?? "project";
+	const filePath = getSSHConfigPath(scope);
+
+	try {
+		await addSSHHost(filePath, name, hostConfig);
+		process.stdout.write(chalk.green(`Added SSH host "${name}" to ${scope} config\n`));
+	} catch (err) {
+		process.stdout.write(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}\n`));
+		process.exitCode = 1;
+	}
+}
+
+async function handleRemove(cmd: SSHCommandArgs): Promise<void> {
+	const name = cmd.args[0];
+	if (!name) {
+		process.stdout.write(chalk.red("Error: Host name required\n"));
+		process.stdout.write(chalk.dim("Usage: arcane ssh remove <name> [--scope project|user]\n"));
+		process.exitCode = 1;
+		return;
+	}
+
+	const scope = cmd.flags.scope ?? "project";
+	const filePath = getSSHConfigPath(scope);
+
+	try {
+		await removeSSHHost(filePath, name);
+		process.stdout.write(chalk.green(`Removed SSH host "${name}" from ${scope} config\n`));
+	} catch (err) {
+		process.stdout.write(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}\n`));
+		process.exitCode = 1;
+	}
+}
+
+async function handleList(cmd: SSHCommandArgs): Promise<void> {
+	const projectPath = getSSHConfigPath("project");
+	const userPath = getSSHConfigPath("user");
+
+	const [projectConfig, userConfig] = await Promise.all([readSSHConfigFile(projectPath), readSSHConfigFile(userPath)]);
+
+	const projectHosts = projectConfig.hosts ?? {};
+	const userHosts = userConfig.hosts ?? {};
+
+	if (cmd.flags.json) {
+		process.stdout.write(JSON.stringify({ project: projectHosts, user: userHosts }, null, 2));
+		process.stdout.write("\n");
+		return;
+	}
+
+	const hasProject = Object.keys(projectHosts).length > 0;
+	const hasUser = Object.keys(userHosts).length > 0;
+
+	if (!hasProject && !hasUser) {
+		process.stdout.write(chalk.dim("No SSH hosts configured\n"));
+		process.stdout.write(chalk.dim("Add one with: arcane ssh add <name> --host <address>\n"));
+		return;
+	}
+
+	if (hasProject) {
+		process.stdout.write(chalk.bold("Project SSH Hosts (.arcane/ssh.json):\n"));
+		printHosts(projectHosts);
+	}
+
+	if (hasProject && hasUser) {
+		process.stdout.write("\n");
+	}
+
+	if (hasUser) {
+		process.stdout.write(chalk.bold("User SSH Hosts (~/.arcane/agent/ssh.json):\n"));
+		printHosts(userHosts);
+	}
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function printHosts(hosts: Record<string, SSHHostConfig>): void {
+	for (const [name, config] of Object.entries(hosts)) {
+		const parts = [chalk.cyan(name), config.host];
+		if (config.username) parts.push(chalk.dim(config.username));
+		if (config.port && config.port !== 22) parts.push(chalk.dim(`port:${config.port}`));
+		if (config.keyPath) parts.push(chalk.dim(config.keyPath));
+		if (config.description) parts.push(chalk.dim(`- ${config.description}`));
+		process.stdout.write(`  ${parts.join("  ")}\n`);
+	}
+}

package/src/cli/stats-cli.ts

@@ -0,0 +1,197 @@
+/**
+ * Stats CLI command handlers.
+ *
+ * Handles \`arc stats` subcommand for viewing AI usage statistics.
+ */
+
+import { APP_NAME } from "@nghyane/arcane-utils/dirs";
+import chalk from "chalk";
+import { openPath } from "../utils/open";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface StatsCommandArgs {
+	port: number;
+	json: boolean;
+	summary: boolean;
+}
+
+// =============================================================================
+// Argument Parser
+// =============================================================================
+
+/**
+ * Parse stats subcommand arguments.
+ * Returns undefined if not a stats command.
+ */
+export function parseStatsArgs(args: string[]): StatsCommandArgs | undefined {
+	if (args.length === 0 || args[0] !== "stats") {
+		return undefined;
+	}
+
+	const result: StatsCommandArgs = {
+		port: 3847,
+		json: false,
+		summary: false,
+	};
+
+	for (let i = 1; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--json" || arg === "-j") {
+			result.json = true;
+		} else if (arg === "--summary" || arg === "-s") {
+			result.summary = true;
+		} else if ((arg === "--port" || arg === "-p") && i + 1 < args.length) {
+			result.port = parseInt(args[++i], 10);
+		} else if (arg.startsWith("--port=")) {
+			result.port = parseInt(arg.split("=")[1], 10);
+		}
+	}
+
+	return result;
+}
+
+// =============================================================================
+// Formatting Helpers
+// =============================================================================
+
+function formatNumber(n: number): string {
+	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+	return n.toFixed(0);
+}
+
+function formatCost(n: number): string {
+	if (n < 0.01) return `$${n.toFixed(4)}`;
+	if (n < 1) return `$${n.toFixed(3)}`;
+	return `$${n.toFixed(2)}`;
+}
+
+function formatDuration(ms: number | null): string {
+	if (ms === null) return "-";
+	if (ms < 1000) return `${ms.toFixed(0)}ms`;
+	return `${(ms / 1000).toFixed(1)}s`;
+}
+
+function formatPercent(n: number): string {
+	return `${(n * 100).toFixed(1)}%`;
+}
+
+// =============================================================================
+// Command Handler
+// =============================================================================
+
+export async function runStatsCommand(cmd: StatsCommandArgs): Promise<void> {
+	// Lazy import to avoid loading stats module when not needed
+	const { getDashboardStats, syncAllSessions, getTotalMessageCount, startServer, closeDb } = await import(
+		"@nghyane/arcane-stats"
+	);
+
+	// Sync session files first
+	console.log("Syncing session files...");
+	const { processed, files } = await syncAllSessions();
+	const total = await getTotalMessageCount();
+	console.log(`Synced ${processed} new entries from ${files} files (${total} total)\n`);
+
+	if (cmd.json) {
+		const stats = await getDashboardStats();
+		console.log(JSON.stringify(stats, null, 2));
+		return;
+	}
+
+	if (cmd.summary) {
+		await printStatsSummary();
+		return;
+	}
+
+	// Start the dashboard server
+	const { port } = await startServer(cmd.port);
+	console.log(chalk.green(`Dashboard available at: http://localhost:${port}`));
+
+	// Open browser
+	const url = `http://localhost:${port}`;
+	openPath(url);
+
+	console.log("Press Ctrl+C to stop\n");
+
+	// Keep process running
+	process.on("SIGINT", () => {
+		console.log("\nShutting down...");
+		closeDb();
+		process.exit(0);
+	});
+
+	// Keep the process alive
+	await new Promise(() => {});
+}
+
+async function printStatsSummary(): Promise<void> {
+	const { getDashboardStats } = await import("@nghyane/arcane-stats");
+	const stats = await getDashboardStats();
+	const { overall, byModel, byFolder } = stats;
+
+	console.log(chalk.bold("\n=== AI Usage Statistics ===\n"));
+
+	console.log(chalk.bold("Overall:"));
+	console.log(`  Requests: ${formatNumber(overall.totalRequests)} (${formatNumber(overall.failedRequests)} errors)`);
+	console.log(`  Error Rate: ${formatPercent(overall.errorRate)}`);
+	console.log(`  Total Tokens: ${formatNumber(overall.totalInputTokens + overall.totalOutputTokens)}`);
+	console.log(`  Cache Rate: ${formatPercent(overall.cacheRate)}`);
+	console.log(`  Total Cost: ${formatCost(overall.totalCost)}`);
+	console.log(`  Avg Duration: ${formatDuration(overall.avgDuration)}`);
+	console.log(`  Avg TTFT: ${formatDuration(overall.avgTtft)}`);
+	if (overall.avgTokensPerSecond !== null) {
+		console.log(`  Avg Tokens/s: ${overall.avgTokensPerSecond.toFixed(1)}`);
+	}
+
+	if (byModel.length > 0) {
+		console.log(chalk.bold("\nBy Model:"));
+		for (const m of byModel.slice(0, 10)) {
+			console.log(
+				`  ${m.model}: ${formatNumber(m.totalRequests)} reqs, ${formatCost(m.totalCost)}, ${formatPercent(m.cacheRate)} cache`,
+			);
+		}
+	}
+
+	if (byFolder.length > 0) {
+		console.log(chalk.bold("\nBy Folder:"));
+		for (const f of byFolder.slice(0, 10)) {
+			console.log(`  ${f.folder}: ${formatNumber(f.totalRequests)} reqs, ${formatCost(f.totalCost)}`);
+		}
+	}
+
+	console.log("");
+}
+
+// =============================================================================
+// Help
+// =============================================================================
+
+export function printStatsHelp(): void {
+	console.log(`${chalk.bold(`${APP_NAME} stats`)} - AI Usage Statistics Dashboard
+
+${chalk.bold("Usage:")}
+  ${APP_NAME} stats [options]
+
+${chalk.bold("Options:")}
+  -p, --port <port>  Port for the dashboard server (default: 3847)
+  -j, --json         Output stats as JSON and exit
+  -s, --summary      Print summary to console and exit
+  -h, --help         Show this help message
+
+${chalk.bold("Examples:")}
+  ${APP_NAME} stats              # Start dashboard server
+  ${APP_NAME} stats --json       # Print stats as JSON
+  ${APP_NAME} stats --summary    # Print summary to console
+  ${APP_NAME} stats --port 8080  # Start on custom port
+
+${chalk.bold("Metrics:")}
+  - Total requests and error rate
+  - Token usage (input, output, cache)
+  - Cost breakdown
+  - Average duration and time to first token (TTFT)
+  - Tokens per second throughput
+`);
+}

package/src/cli/update-cli.ts

@@ -0,0 +1,286 @@
+/**
+ * Update CLI command handler.
+ *
+ * Handles \`arc update` to check for and install updates.
+ * Uses bun if available, otherwise downloads binary from GitHub releases.
+ */
+import { execSync, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import { pipeline } from "node:stream/promises";
+import { isEnoent } from "@nghyane/arcane-utils";
+import { APP_NAME, VERSION } from "@nghyane/arcane-utils/dirs";
+import chalk from "chalk";
+import { theme } from "../modes/theme/theme";
+
+/**
+ * Detect if we're running as a Bun compiled binary.
+ */
+const isBunBinary =
+	Bun.env.ARCANE_COMPILED ||
+	import.meta.url.includes("$bunfs") ||
+	import.meta.url.includes("~BUN") ||
+	import.meta.url.includes("%7EBUN");
+
+const REPO = "nghyane/arcane";
+const PACKAGE = "@nghyane/arcane";
+
+interface ReleaseInfo {
+	tag: string;
+	version: string;
+	assets: Array<{ name: string; url: string }>;
+}
+
+/**
+ * Parse update subcommand arguments.
+ * Returns undefined if not an update command.
+ */
+export function parseUpdateArgs(args: string[]): { force: boolean; check: boolean } | undefined {
+	if (args.length === 0 || args[0] !== "update") {
+		return undefined;
+	}
+
+	return {
+		force: args.includes("--force") || args.includes("-f"),
+		check: args.includes("--check") || args.includes("-c"),
+	};
+}
+
+/**
+ * Check if bun is available in PATH.
+ */
+function hasBun(): boolean {
+	try {
+		const result = spawnSync("bun", ["--version"], { encoding: "utf-8", stdio: "pipe" });
+		return result.status === 0;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Get the latest release info from the npm registry.
+ * Uses npm instead of GitHub API to avoid unauthenticated rate limiting.
+ */
+async function getLatestRelease(): Promise<ReleaseInfo> {
+	const response = await fetch(`https://registry.npmjs.org/${PACKAGE}/latest`);
+	if (!response.ok) {
+		throw new Error(`Failed to fetch release info: ${response.statusText}`);
+	}
+
+	const data = (await response.json()) as { version: string };
+	const version = data.version;
+	const tag = `v${version}`;
+
+	// Construct deterministic GitHub release download URLs for the current platform
+	const makeAsset = (name: string) => ({
+		name,
+		url: `https://github.com/${REPO}/releases/download/${tag}/${name}`,
+	});
+	return {
+		tag,
+		version,
+		assets: [makeAsset(getBinaryName())],
+	};
+}
+
+/**
+ * Compare semver versions. Returns:
+ * - negative if a < b
+ * - 0 if a == b
+ * - positive if a > b
+ */
+function compareVersions(a: string, b: string): number {
+	const pa = a.split(".").map(Number);
+	const pb = b.split(".").map(Number);
+
+	for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+		const na = pa[i] || 0;
+		const nb = pb[i] || 0;
+		if (na !== nb) return na - nb;
+	}
+	return 0;
+}
+
+/**
+ * Get the appropriate binary name for this platform.
+ */
+function getBinaryName(): string {
+	const platform = process.platform;
+	const arch = process.arch;
+
+	let os: string;
+	switch (platform) {
+		case "linux":
+			os = "linux";
+			break;
+		case "darwin":
+			os = "darwin";
+			break;
+		case "win32":
+			os = "windows";
+			break;
+		default:
+			throw new Error(`Unsupported platform: ${platform}`);
+	}
+
+	let archName: string;
+	switch (arch) {
+		case "x64":
+			archName = "x64";
+			break;
+		case "arm64":
+			archName = "arm64";
+			break;
+		default:
+			throw new Error(`Unsupported architecture: ${arch}`);
+	}
+
+	if (os === "windows") {
+		return `${APP_NAME}-${os}-${archName}.exe`;
+	}
+	return `${APP_NAME}-${os}-${archName}`;
+}
+
+/**
+ * Update via bun package manager.
+ */
+async function updateViaBun(expectedVersion: string): Promise<void> {
+	console.log(chalk.dim("Updating via bun..."));
+	try {
+		execSync(`bun install -g ${PACKAGE}@${expectedVersion}`, { stdio: "inherit" });
+	} catch (error) {
+		throw new Error("bun install failed", { cause: error });
+	}
+
+	// Verify the update actually took effect
+	try {
+		const result = spawnSync("bun", ["pm", "ls", "-g"], { encoding: "utf-8", stdio: "pipe" });
+		const output = result.stdout || "";
+		const match = output.match(new RegExp(`${PACKAGE.replace("/", "\\/")}@(\\S+)`));
+		if (match) {
+			const installedVersion = match[1];
+			if (compareVersions(installedVersion, expectedVersion) < 0) {
+				console.log(
+					chalk.yellow(`\nWarning: bun reports ${installedVersion} installed, expected ${expectedVersion}`),
+				);
+				console.log(chalk.yellow(`Try: bun install -g ${PACKAGE}@latest`));
+				return;
+			}
+		}
+	} catch {
+		// Verification is best-effort, don't fail the update
+	}
+	console.log(chalk.green(`\n${theme.status.success} Update complete`));
+}
+
+/**
+ * Update by downloading binary from GitHub releases.
+ */
+async function updateViaBinary(release: ReleaseInfo): Promise<void> {
+	const binaryName = getBinaryName();
+	const asset = release.assets.find(a => a.name === binaryName);
+	if (!asset) {
+		throw new Error(`No binary found for ${binaryName}`);
+	}
+	const execPath = process.execPath;
+	const tempPath = `${execPath}.new`;
+	const backupPath = `${execPath}.bak`;
+	console.log(chalk.dim(`Downloading ${binaryName}…`));
+
+	// Download binary to temp file
+	const response = await fetch(asset.url, { redirect: "follow" });
+	if (!response.ok || !response.body) {
+		throw new Error(`Download failed: ${response.statusText}`);
+	}
+	const fileStream = fs.createWriteStream(tempPath, { mode: 0o755 });
+	await pipeline(response.body, fileStream);
+	// Replace current binary
+	console.log(chalk.dim("Installing update..."));
+	try {
+		try {
+			await fs.promises.unlink(backupPath);
+		} catch (err) {
+			if (!isEnoent(err)) throw err;
+		}
+		await fs.promises.rename(execPath, backupPath);
+		await fs.promises.rename(tempPath, execPath);
+		await fs.promises.unlink(backupPath);
+
+		console.log(chalk.green(`\n${theme.status.success} Updated to ${release.version}`));
+		console.log(chalk.dim(`Restart ${APP_NAME} to use the new version`));
+	} catch (err) {
+		if (fs.existsSync(backupPath) && !fs.existsSync(execPath)) {
+			await fs.promises.rename(backupPath, execPath);
+		}
+		if (fs.existsSync(tempPath)) {
+			await fs.promises.unlink(tempPath);
+		}
+		throw err;
+	}
+}
+
+/**
+ * Run the update command.
+ */
+export async function runUpdateCommand(opts: { force: boolean; check: boolean }): Promise<void> {
+	console.log(chalk.dim(`Current version: ${VERSION}`));
+
+	// Check for updates
+	let release: ReleaseInfo;
+	try {
+		release = await getLatestRelease();
+	} catch (err) {
+		console.error(chalk.red(`Failed to check for updates: ${err}`));
+		process.exit(1);
+	}
+
+	const comparison = compareVersions(release.version, VERSION);
+
+	if (comparison <= 0 && !opts.force) {
+		console.log(chalk.green(`${theme.status.success} Already up to date`));
+		return;
+	}
+
+	if (comparison > 0) {
+		console.log(chalk.cyan(`New version available: ${release.version}`));
+	} else {
+		console.log(chalk.yellow(`Forcing reinstall of ${release.version}`));
+	}
+
+	if (opts.check) {
+		// Just check, don't install
+		return;
+	}
+
+	// Choose update method
+	try {
+		if (!isBunBinary && hasBun()) {
+			await updateViaBun(release.version);
+		} else {
+			await updateViaBinary(release);
+		}
+	} catch (err) {
+		console.error(chalk.red(`Update failed: ${err}`));
+		process.exit(1);
+	}
+}
+
+/**
+ * Print update command help.
+ */
+export function printUpdateHelp(): void {
+	console.log(`${chalk.bold(`${APP_NAME} update`)} - Check for and install updates
+
+${chalk.bold("Usage:")}
+  ${APP_NAME} update [options]
+
+${chalk.bold("Options:")}
+  -c, --check   Check for updates without installing
+  -f, --force   Force reinstall even if up to date
+
+${chalk.bold("Examples:")}
+  ${APP_NAME} update           Update to latest version
+  ${APP_NAME} update --check   Check if updates are available
+  ${APP_NAME} update --force   Force reinstall
+`);
+}