@nghyane/arcane 0.1.0

package/src/config.ts

@@ -0,0 +1,414 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { isEnoent, logger } from "@nghyane/arcane-utils";
+import { CONFIG_DIR_NAME, getAgentDir, getProjectDir } from "@nghyane/arcane-utils/dirs";
+import type { TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { Ajv, type ErrorObject, type ValidateFunction } from "ajv";
+import { JSONC, YAML } from "bun";
+
+const priorityList = [
+	{ dir: CONFIG_DIR_NAME, globalAgentDir: `${CONFIG_DIR_NAME}/agent` },
+	{ dir: ".claude" },
+	{ dir: ".codex" },
+	{ dir: ".gemini" },
+];
+
+// =============================================================================
+// Package Directory (for optional external docs/examples)
+// =============================================================================
+
+/**
+ * Get the base directory for resolving optional package assets (docs, examples).
+ * Walk up from import.meta.dir until we find package.json, or fall back to cwd.
+ */
+export function getPackageDir(): string {
+	// Allow override via environment variable (useful for Nix/Guix where store paths tokenize poorly)
+	const envDir = process.env.ARCANE_PACKAGE_DIR;
+	if (envDir) {
+		if (envDir === "~") return os.homedir();
+		if (envDir.startsWith("~/")) return os.homedir() + envDir.slice(1);
+		return envDir;
+	}
+
+	let dir = import.meta.dir;
+	while (dir !== path.dirname(dir)) {
+		if (fs.existsSync(path.join(dir, "package.json"))) {
+			return dir;
+		}
+		dir = path.dirname(dir);
+	}
+	// Fallback to project dir (docs/examples won't be found, but that's fine)
+	return getProjectDir();
+}
+
+/** Get path to CHANGELOG.md (optional, may not exist in binary) */
+export function getChangelogPath(): string {
+	return path.resolve(path.join(getPackageDir(), "CHANGELOG.md"));
+}
+
+// =============================================================================
+// User Config Paths (~/.arcane/agent/*)
+// =============================================================================
+
+function migrateJsonToYml(jsonPath: string, ymlPath: string) {
+	try {
+		if (fs.existsSync(ymlPath)) return;
+		if (!fs.existsSync(jsonPath)) return;
+
+		const content = fs.readFileSync(jsonPath, "utf-8");
+		const parsed = JSON.parse(content);
+		if (!parsed) {
+			logger.warn("migrateJsonToYml: invalid json structure", { path: jsonPath });
+			return;
+		}
+		fs.writeFileSync(ymlPath, YAML.stringify(parsed, null, 2));
+	} catch (error) {
+		logger.warn("migrateJsonToYml: migration failed", { error: String(error) });
+	}
+}
+
+export interface IConfigFile<T> {
+	readonly id: string;
+	readonly schema: TSchema;
+	path?(): string;
+	load(): T | null;
+	invalidate?(): void;
+}
+
+export class ConfigError extends Error {
+	readonly #message: string;
+	constructor(
+		public readonly id: string,
+		public readonly schemaErrors: ErrorObject[] | null | undefined,
+		public readonly other?: { err: unknown; stage: string },
+	) {
+		let messages: string[] | undefined;
+		let cause: any | undefined;
+		let klass: string;
+
+		if (schemaErrors) {
+			klass = "Schema";
+			messages = schemaErrors.map(e => `${e.instancePath || "root"}: ${e.message}`);
+		} else if (other) {
+			klass = other.stage;
+			if (other.err instanceof Error) {
+				messages = [other.err.message];
+				cause = other.err;
+			} else {
+				messages = [String(other.err)];
+			}
+		} else {
+			klass = "Unknown";
+		}
+
+		const title = `Failed to load config file ${id}, ${klass} error:`;
+		let message: string;
+		switch (messages?.length ?? 0) {
+			case 0:
+				message = title.slice(0, -1);
+				break;
+			case 1:
+				message = `${title} ${messages![0]}`;
+				break;
+			default:
+				message = `${title}\n${messages!.map(m => `  - ${m}`).join("\n")}`;
+				break;
+		}
+
+		super(message, { cause });
+		this.name = "LoadError";
+		this.#message = message;
+	}
+
+	get message(): string {
+		return this.#message;
+	}
+
+	toString(): string {
+		return this.message;
+	}
+}
+
+export type LoadStatus = "ok" | "error" | "not-found";
+
+export type LoadResult<T> =
+	| { value?: null; error: ConfigError; status: "error" }
+	| { value: T; error?: undefined; status: "ok" }
+	| { value?: null; error?: unknown; status: "not-found" };
+
+const ajv = new Ajv();
+export class ConfigFile<T> implements IConfigFile<T> {
+	readonly #basePath: string;
+	#cache?: LoadResult<T>;
+	#auxValidate?: (value: T) => void;
+
+	constructor(
+		readonly id: string,
+		readonly schema: TSchema,
+		configPath: string = path.join(getAgentDir(), `${id}.yml`),
+	) {
+		this.#basePath = configPath;
+		if (configPath.endsWith(".yml")) {
+			const jsonPath = `${configPath.slice(0, -4)}.json`;
+			migrateJsonToYml(jsonPath, configPath);
+		} else if (configPath.endsWith(".yaml")) {
+			const jsonPath = `${configPath.slice(0, -5)}.json`;
+			migrateJsonToYml(jsonPath, configPath);
+		} else if (configPath.endsWith(".json") || configPath.endsWith(".jsonc")) {
+			// JSON configs are still supported without migration.
+		} else {
+			throw new Error(`Invalid config file path: ${configPath}`);
+		}
+	}
+
+	relocate(path?: string): ConfigFile<T> {
+		if (!path || path === this.#basePath) return this;
+		const result = new ConfigFile<T>(this.id, this.schema, path);
+		result.#auxValidate = this.#auxValidate;
+		return result;
+	}
+
+	withValidation(name: string, validate: (value: T) => void): this {
+		const prev = this.#auxValidate;
+		this.#auxValidate = (value: T) => {
+			prev?.(value);
+			try {
+				validate(value);
+			} catch (error) {
+				throw new ConfigError(this.id, undefined, { err: error, stage: `Validate(${name})` });
+			}
+		};
+		return this;
+	}
+
+	createDefault() {
+		return Value.Default(this.schema, [], undefined) as T;
+	}
+
+	#storeCache(result: LoadResult<T>): LoadResult<T> {
+		this.#cache = result;
+		return result;
+	}
+
+	tryLoad(): LoadResult<T> {
+		if (this.#cache) return this.#cache;
+
+		try {
+			const content = fs.readFileSync(this.path(), "utf-8").trim();
+
+			let parsed: unknown;
+			if (this.#basePath.endsWith(".json") || this.#basePath.endsWith(".jsonc")) {
+				parsed = JSONC.parse(content);
+			} else if (this.#basePath.endsWith(".yml") || this.#basePath.endsWith(".yaml")) {
+				parsed = YAML.parse(content);
+			} else {
+				throw new Error(`Invalid config file path: ${this.#basePath}`);
+			}
+
+			const validate = ajv.compile(this.schema) as ValidateFunction<T>;
+			if (!validate(parsed)) {
+				const error = new ConfigError(this.id, validate.errors);
+				logger.warn("Failed to parse config file", { path: this.path(), error });
+				return this.#storeCache({ error, status: "error" });
+			}
+			return this.#storeCache({ value: parsed, status: "ok" });
+		} catch (error) {
+			if (isEnoent(error)) {
+				return this.#storeCache({ status: "not-found" });
+			}
+			logger.warn("Failed to parse config file", { path: this.path(), error });
+			return this.#storeCache({
+				error: new ConfigError(this.id, undefined, { err: error, stage: "Unexpected" }),
+				status: "error",
+			});
+		}
+	}
+
+	load(): T | null {
+		return this.tryLoad().value ?? null;
+	}
+
+	loadOrDefault(): T {
+		return this.tryLoad().value ?? this.createDefault();
+	}
+
+	path(): string {
+		return this.#basePath;
+	}
+
+	invalidate() {
+		this.#cache = undefined;
+	}
+}
+
+// =============================================================================
+// Multi-Config Directory Helpers
+// =============================================================================
+
+/**
+ * Config directory bases in priority order (highest first).
+ * User-level: ~/.arcane/agent, ~/.claude, ~/.codex, ~/.gemini
+ * Project-level: .arcane, .claude, .codex, .gemini
+ */
+const USER_CONFIG_BASES = priorityList.map(({ dir, globalAgentDir }) => ({
+	base: () => path.join(os.homedir(), globalAgentDir ?? dir),
+	name: dir,
+}));
+
+const PROJECT_CONFIG_BASES = priorityList.map(({ dir }) => ({
+	base: dir,
+	name: dir,
+}));
+
+export interface ConfigDirEntry {
+	path: string;
+	source: string; // e.g., ".arcane", ".claude"
+	level: "user" | "project";
+}
+
+export interface GetConfigDirsOptions {
+	/** Include user-level directories (~/.arcane/agent/...). Default: true */
+	user?: boolean;
+	/** Include project-level directories (.arcane/...). Default: true */
+	project?: boolean;
+	/** Current working directory for project paths. Default: getProjectDir() */
+	cwd?: string;
+	/** Only return directories that exist. Default: false */
+	existingOnly?: boolean;
+}
+
+/**
+ * Get all config directories for a subpath, ordered by priority (highest first).
+ *
+ * @param subpath - Subpath within config dirs (e.g., "commands", "hooks", "agents")
+ * @param options - Options for filtering
+ * @returns Array of directory entries, highest priority first
+ *
+ * @example
+ * // Get all command directories
+ * getConfigDirs("commands")
+ * // → [{ path: "~/.arcane/agent/commands", source: ".arcane", level: "user" }, ...]
+ *
+ * @example
+ * // Get only existing project skill directories
+ * getConfigDirs("skills", { user: false, existingOnly: true })
+ */
+export function getConfigDirs(subpath: string, options: GetConfigDirsOptions = {}): ConfigDirEntry[] {
+	const { user = true, project = true, cwd = getProjectDir(), existingOnly = false } = options;
+	const results: ConfigDirEntry[] = [];
+
+	// User-level directories (highest priority)
+	if (user) {
+		for (const { base, name } of USER_CONFIG_BASES) {
+			const resolvedPath = path.resolve(base(), subpath);
+			if (!existingOnly || fs.existsSync(resolvedPath)) {
+				results.push({ path: resolvedPath, source: name, level: "user" });
+			}
+		}
+	}
+
+	// Project-level directories
+	if (project) {
+		for (const { base, name } of PROJECT_CONFIG_BASES) {
+			const resolvedPath = path.resolve(cwd, base, subpath);
+			if (!existingOnly || fs.existsSync(resolvedPath)) {
+				results.push({ path: resolvedPath, source: name, level: "project" });
+			}
+		}
+	}
+
+	return results;
+}
+
+/**
+ * Get all config directory paths for a subpath (convenience wrapper).
+ * Returns just the paths, highest priority first.
+ */
+export function getConfigDirPaths(subpath: string, options: GetConfigDirsOptions = {}): string[] {
+	return getConfigDirs(subpath, options).map(e => e.path);
+}
+
+export interface ConfigFileResult<T> {
+	path: string;
+	source: string;
+	level: "user" | "project";
+	content: T;
+}
+
+/**
+ * Find the first existing config file (for non-JSON files like SYSTEM.md).
+ * Returns just the path, or undefined if not found.
+ */
+export function findConfigFile(subpath: string, options: GetConfigDirsOptions = {}): string | undefined {
+	const dirs = getConfigDirs("", { ...options, existingOnly: false });
+
+	for (const { path: base } of dirs) {
+		const filePath = path.join(base, subpath);
+		if (fs.existsSync(filePath)) {
+			return filePath;
+		}
+	}
+
+	return undefined;
+}
+
+/**
+ * Find the first existing config file with metadata.
+ */
+export function findConfigFileWithMeta(
+	subpath: string,
+	options: GetConfigDirsOptions = {},
+): Omit<ConfigFileResult<never>, "content"> | undefined {
+	const dirs = getConfigDirs("", { ...options, existingOnly: false });
+
+	for (const { path: base, source, level } of dirs) {
+		const filePath = path.join(base, subpath);
+		if (fs.existsSync(filePath)) {
+			return { path: filePath, source, level };
+		}
+	}
+
+	return undefined;
+}
+
+// =============================================================================
+// Walk-Up Config Discovery (for monorepo scenarios)
+// =============================================================================
+
+/**
+ * Find all nearest config directories by walking up from cwd.
+ * Returns one entry per config base (.arcane, .claude) - the nearest one found.
+ * Results are in priority order (highest first).
+ */
+export function findAllNearestProjectConfigDirs(subpath: string, cwd: string = getProjectDir()): ConfigDirEntry[] {
+	const results: ConfigDirEntry[] = [];
+	const foundBases = new Set<string>();
+
+	let currentDir = cwd;
+
+	while (foundBases.size < PROJECT_CONFIG_BASES.length) {
+		for (const { base, name } of PROJECT_CONFIG_BASES) {
+			if (foundBases.has(name)) continue;
+
+			const candidate = path.join(currentDir, base, subpath);
+			try {
+				if (fs.statSync(candidate).isDirectory()) {
+					results.push({ path: candidate, source: name, level: "project" });
+					foundBases.add(name);
+				}
+			} catch {}
+		}
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) break;
+		currentDir = parentDir;
+	}
+
+	// Sort by priority order
+	const order = PROJECT_CONFIG_BASES.map(b => b.name);
+	results.sort((a, b) => order.indexOf(a.source) - order.indexOf(b.source));
+
+	return results;
+}

package/src/cursor.ts

@@ -0,0 +1,239 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import type {
+	AgentEvent,
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+} from "@nghyane/arcane-agent";
+import type { CursorMcpCall, CursorExecHandlers as ICursorExecHandlers, ToolResultMessage } from "@nghyane/arcane-ai";
+import { resolveToCwd } from "./tools/path-utils";
+
+interface CursorExecBridgeOptions {
+	cwd: string;
+	tools: Map<string, AgentTool>;
+	getToolContext?: () => AgentToolContext | undefined;
+	emitEvent?: (event: AgentEvent) => void;
+}
+
+function createToolResultMessage(
+	toolCallId: string,
+	toolName: string,
+	result: AgentToolResult<unknown>,
+	isError: boolean,
+): ToolResultMessage {
+	return {
+		role: "toolResult",
+		toolCallId,
+		toolName,
+		content: result.content,
+		details: result.details,
+		isError,
+		timestamp: Date.now(),
+	};
+}
+
+function buildToolErrorResult(message: string): AgentToolResult<unknown> {
+	return {
+		content: [{ type: "text", text: message }],
+		details: {},
+	};
+}
+
+async function executeTool(
+	options: CursorExecBridgeOptions,
+	toolName: string,
+	toolCallId: string,
+	args: Record<string, unknown>,
+): Promise<ToolResultMessage> {
+	const tool = options.tools.get(toolName);
+	if (!tool) {
+		const result = buildToolErrorResult(`Tool "${toolName}" not available`);
+		return createToolResultMessage(toolCallId, toolName, result, true);
+	}
+
+	options.emitEvent?.({ type: "tool_execution_start", toolCallId, toolName, args });
+
+	let result: AgentToolResult<unknown>;
+	let isError = false;
+
+	const onUpdate: AgentToolUpdateCallback<unknown> | undefined = options.emitEvent
+		? partialResult => {
+				options.emitEvent?.({
+					type: "tool_execution_update",
+					toolCallId,
+					toolName,
+					args,
+					partialResult,
+				});
+			}
+		: undefined;
+
+	try {
+		result = await tool.execute(
+			toolCallId,
+			args as Record<string, unknown>,
+			undefined,
+			onUpdate,
+			options.getToolContext?.(),
+		);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		result = buildToolErrorResult(message);
+		isError = true;
+	}
+
+	options.emitEvent?.({ type: "tool_execution_end", toolCallId, toolName, result, isError });
+
+	return createToolResultMessage(toolCallId, toolName, result, isError);
+}
+
+async function executeDelete(options: CursorExecBridgeOptions, pathArg: string, toolCallId: string) {
+	const toolName = "delete";
+	options.emitEvent?.({ type: "tool_execution_start", toolCallId, toolName, args: { path: pathArg } });
+
+	const absolutePath = resolveToCwd(pathArg, options.cwd);
+	let isError = false;
+	let result: AgentToolResult<unknown>;
+
+	try {
+		let fileStat: fs.Stats | undefined;
+		try {
+			fileStat = fs.statSync(absolutePath);
+		} catch {
+			throw new Error(`File not found: ${pathArg}`);
+		}
+		if (!fileStat.isFile()) {
+			throw new Error(`Path is not a file: ${pathArg}`);
+		}
+
+		fs.rmSync(absolutePath);
+
+		const sizeText = fileStat.size ? ` (${fileStat.size} bytes)` : "";
+		const message = `Deleted ${pathArg}${sizeText}`;
+		result = { content: [{ type: "text", text: message }], details: {} };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		result = buildToolErrorResult(message);
+		isError = true;
+	}
+
+	options.emitEvent?.({ type: "tool_execution_end", toolCallId, toolName, result, isError });
+	return createToolResultMessage(toolCallId, toolName, result, isError);
+}
+
+function decodeToolCallId(toolCallId?: string): string {
+	return toolCallId && toolCallId.length > 0 ? toolCallId : randomUUID();
+}
+
+function decodeMcpArgs(rawArgs: Record<string, Uint8Array>): Record<string, unknown> {
+	const decoded: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(rawArgs)) {
+		const text = new TextDecoder().decode(value);
+		try {
+			decoded[key] = JSON.parse(text);
+		} catch {
+			decoded[key] = text;
+		}
+	}
+	return decoded;
+}
+
+function formatMcpToolErrorMessage(toolName: string, availableTools: string[]): string {
+	const list = availableTools.length > 0 ? availableTools.join(", ") : "none";
+	return `MCP tool "${toolName}" not found. Available tools: ${list}`;
+}
+
+export class CursorExecHandlers implements ICursorExecHandlers {
+	constructor(private options: CursorExecBridgeOptions) {}
+
+	async read(args: Parameters<NonNullable<ICursorExecHandlers["read"]>>[0]) {
+		const toolCallId = decodeToolCallId(args.toolCallId);
+		const toolResultMessage = await executeTool(this.options, "read", toolCallId, { path: args.path });
+		return toolResultMessage;
+	}
+
+	async ls(args: Parameters<NonNullable<ICursorExecHandlers["ls"]>>[0]) {
+		const toolCallId = decodeToolCallId(args.toolCallId);
+		// Redirect ls to read tool, which handles directories
+		const toolResultMessage = await executeTool(this.options, "read", toolCallId, { path: args.path });
+		return toolResultMessage;
+	}
+
+	async grep(args: Parameters<NonNullable<ICursorExecHandlers["grep"]>>[0]) {
+		const toolCallId = decodeToolCallId(args.toolCallId);
+		const toolResultMessage = await executeTool(this.options, "grep", toolCallId, {
+			pattern: args.pattern,
+			path: args.path || undefined,
+			glob: args.glob || undefined,
+			mode: args.outputMode || undefined,
+			context: args.context ?? args.contextBefore ?? args.contextAfter ?? undefined,
+			ignore_case: args.caseInsensitive || undefined,
+			type: args.type || undefined,
+			limit: args.headLimit ?? undefined,
+			multiline: args.multiline || undefined,
+		});
+		return toolResultMessage;
+	}
+
+	async write(args: Parameters<NonNullable<ICursorExecHandlers["write"]>>[0]) {
+		const toolCallId = decodeToolCallId(args.toolCallId);
+		const content = args.fileText ?? new TextDecoder().decode(args.fileBytes ?? new Uint8Array());
+		const toolResultMessage = await executeTool(this.options, "write", toolCallId, {
+			path: args.path,
+			content,
+		});
+		return toolResultMessage;
+	}
+
+	async delete(args: Parameters<NonNullable<ICursorExecHandlers["delete"]>>[0]) {
+		const toolCallId = decodeToolCallId(args.toolCallId);
+		const toolResultMessage = await executeDelete(this.options, args.path, toolCallId);
+		return toolResultMessage;
+	}
+
+	async shell(args: Parameters<NonNullable<ICursorExecHandlers["shell"]>>[0]) {
+		const toolCallId = decodeToolCallId(args.toolCallId);
+		const timeoutSeconds = args.timeout && args.timeout > 0 ? args.timeout : undefined;
+		const toolResultMessage = await executeTool(this.options, "bash", toolCallId, {
+			command: args.command,
+			workdir: args.workingDirectory || undefined,
+			timeout: timeoutSeconds,
+		});
+		return toolResultMessage;
+	}
+
+	async diagnostics(args: Parameters<NonNullable<ICursorExecHandlers["diagnostics"]>>[0]) {
+		const toolCallId = decodeToolCallId(args.toolCallId);
+		const toolResultMessage = await executeTool(this.options, "lsp", toolCallId, {
+			action: "diagnostics",
+			file: args.path,
+		});
+		return toolResultMessage;
+	}
+
+	async mcp(call: CursorMcpCall) {
+		const toolName = call.toolName || call.name;
+		const toolCallId = decodeToolCallId(call.toolCallId);
+		const tool = this.options.tools.get(toolName);
+		if (!tool) {
+			const availableTools = Array.from(this.options.tools.keys()).filter(name => name.startsWith("mcp_"));
+			const message = formatMcpToolErrorMessage(toolName, availableTools);
+			const toolResult: ToolResultMessage = {
+				role: "toolResult",
+				toolCallId,
+				toolName,
+				content: [{ type: "text", text: message }],
+				details: {},
+				isError: true,
+				timestamp: Date.now(),
+			};
+			return toolResult;
+		}
+
+		const args = Object.keys(call.args ?? {}).length > 0 ? call.args : decodeMcpArgs(call.rawArgs ?? {});
+		const toolResultMessage = await executeTool(this.options, toolName, toolCallId, args);
+		return toolResultMessage;
+	}
+}