@nghyane/arcane 0.1.0

package/src/capability/rule.ts

@@ -0,0 +1,223 @@
+/**
+ * Rules Capability
+ *
+ * Project-specific rules from Cursor (.mdc), Windsurf (.md), and Cline formats.
+ * Translated to a canonical shape regardless of source format.
+ */
+import { defineCapability } from ".";
+import type { SourceMeta } from "./types";
+
+const CONDITION_GLOB_SCOPE_TOOLS = ["edit", "write"] as const;
+
+/**
+ * Parsed frontmatter from rule files.
+ */
+export interface RuleFrontmatter {
+	description?: string;
+	globs?: string[];
+	alwaysApply?: boolean;
+	/** New key for TTSR match conditions. */
+	condition?: string | string[];
+	/** New key for TTSR stream scope. */
+	scope?: string | string[];
+	/** Legacy key accepted for backward compatibility with existing rules. */
+	ttsr_trigger?: string | string[];
+	/** Legacy camelCase key accepted for backward compatibility with existing rules. */
+	ttsrTrigger?: string | string[];
+	[key: string]: unknown;
+}
+
+/**
+ * A rule providing project-specific guidance and constraints.
+ */
+export interface Rule {
+	/** Rule name (derived from filename) */
+	name: string;
+	/** Absolute path to rule file */
+	path: string;
+	/** Rule content (after frontmatter stripped) */
+	content: string;
+	/** Globs this rule applies to (if any) */
+	globs?: string[];
+	/** Whether to always include this rule */
+	alwaysApply?: boolean;
+	/** Description (for agent-requested rules) */
+	description?: string;
+	/** Regex condition(s) that can trigger TTSR interruption. */
+	condition?: string[];
+	/** Optional stream scope tokens (for example: text, thinking, tool:edit(*.ts)). */
+	scope?: string[];
+	/** Source metadata */
+	_source: SourceMeta;
+}
+
+function normalizeRuleField(value: unknown): string[] | undefined {
+	if (typeof value === "string") {
+		const token = value.trim();
+		return token.length > 0 ? [token] : undefined;
+	}
+	if (!Array.isArray(value)) {
+		return undefined;
+	}
+
+	const tokens = value
+		.filter((item): item is string => typeof item === "string")
+		.map(item => item.trim())
+		.filter(item => item.length > 0);
+	if (tokens.length === 0) {
+		return undefined;
+	}
+
+	return Array.from(new Set(tokens));
+}
+
+function splitScopeTokens(value: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let parenDepth = 0;
+	let bracketDepth = 0;
+	let braceDepth = 0;
+	let quote: '"' | "'" | undefined;
+	for (let i = 0; i < value.length; i++) {
+		const char = value[i];
+		if (quote) {
+			current += char;
+			if (char === quote && value[i - 1] !== "\\") {
+				quote = undefined;
+			}
+			continue;
+		}
+		if (char === '"' || char === "'") {
+			quote = char;
+			current += char;
+			continue;
+		}
+		if (char === "(") {
+			parenDepth++;
+			current += char;
+			continue;
+		}
+		if (char === ")") {
+			parenDepth = Math.max(0, parenDepth - 1);
+			current += char;
+			continue;
+		}
+		if (char === "[") {
+			bracketDepth++;
+			current += char;
+			continue;
+		}
+		if (char === "]") {
+			bracketDepth = Math.max(0, bracketDepth - 1);
+			current += char;
+			continue;
+		}
+		if (char === "{") {
+			braceDepth++;
+			current += char;
+			continue;
+		}
+		if (char === "}") {
+			braceDepth = Math.max(0, braceDepth - 1);
+			current += char;
+			continue;
+		}
+		if (char === "," && parenDepth === 0 && bracketDepth === 0 && braceDepth === 0) {
+			const token = current.trim();
+			if (token.length > 0) {
+				tokens.push(token);
+			}
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+
+	const tail = current.trim();
+	if (tail.length > 0) {
+		tokens.push(tail);
+	}
+
+	return tokens;
+}
+function normalizeScopeField(value: unknown): string[] | undefined {
+	const normalized = normalizeRuleField(value);
+	if (!normalized) {
+		return undefined;
+	}
+
+	const tokens = normalized.flatMap(splitScopeTokens).filter(item => item.length > 0);
+	if (tokens.length === 0) {
+		return undefined;
+	}
+	return Array.from(new Set(tokens));
+}
+/**
+ * Heuristic for condition shorthand that looks like a file glob (for example `*.rs`).
+ */
+function isLikelyFileGlob(value: string): boolean {
+	const token = value.trim();
+	if (token.length === 0) {
+		return false;
+	}
+	if (/[\\^$+|()]/.test(token)) {
+		return false;
+	}
+	if (!/[?*[\]{}]/.test(token)) {
+		return false;
+	}
+	if (token.includes("/")) {
+		return true;
+	}
+	return /^\*\.[^\s/]+$/.test(token);
+}
+
+/**
+ * Parse `condition` + `scope` from rule frontmatter.
+ *
+ * - `condition` accepts string or string[]
+ * - `scope` accepts string or string[]
+ * - legacy `ttsr_trigger` / `ttsrTrigger` are accepted as a `condition` fallback
+ * - condition tokens that look like file globs become scope shorthands:
+ *   `*.rs` => `tool:edit(*.rs)`, `tool:write(*.rs)` and a catch-all condition `.*`
+ */
+export function parseRuleConditionAndScope(frontmatter: RuleFrontmatter): Pick<Rule, "condition" | "scope"> {
+	const rawCondition = frontmatter.condition ?? frontmatter.ttsr_trigger ?? frontmatter.ttsrTrigger;
+	const parsedCondition = normalizeRuleField(rawCondition);
+	const parsedScope = normalizeScopeField(frontmatter.scope);
+
+	const inferredScope: string[] = [];
+	const condition: string[] = [];
+	for (const token of parsedCondition ?? []) {
+		if (isLikelyFileGlob(token)) {
+			for (const toolName of CONDITION_GLOB_SCOPE_TOOLS) {
+				inferredScope.push(`tool:${toolName}(${token})`);
+			}
+			continue;
+		}
+		condition.push(token);
+	}
+
+	if (condition.length === 0 && inferredScope.length > 0) {
+		condition.push(".*");
+	}
+
+	const scope = [...(parsedScope ?? []), ...inferredScope];
+	return {
+		condition: condition.length > 0 ? Array.from(new Set(condition)) : undefined,
+		scope: scope.length > 0 ? Array.from(new Set(scope)) : undefined,
+	};
+}
+
+export const ruleCapability = defineCapability<Rule>({
+	id: "rules",
+	displayName: "Rules",
+	description: "Project-specific rules and constraints (Cursor MDC, Windsurf, Cline formats)",
+	key: rule => rule.name,
+	validate: rule => {
+		if (!rule.name) return "Missing rule name";
+		if (!rule.path) return "Missing rule path";
+		if (!rule.content || typeof rule.content !== "string") return "Rule must have content";
+		return undefined;
+	},
+});

package/src/capability/settings.ts

@@ -0,0 +1,34 @@
+/**
+ * Settings Capability
+ *
+ * Configuration settings from various sources (JSON, TOML, etc.)
+ */
+import { defineCapability } from ".";
+import type { SourceMeta } from "./types";
+
+/**
+ * A settings file.
+ */
+export interface Settings {
+	/** Absolute path to settings file */
+	path: string;
+	/** Parsed settings data */
+	data: Record<string, unknown>;
+	/** Source level */
+	level: "user" | "project";
+	/** Source metadata */
+	_source: SourceMeta;
+}
+
+export const settingsCapability = defineCapability<Settings>({
+	id: "settings",
+	displayName: "Settings",
+	description: "Configuration settings from various sources",
+	// Settings are merged, not deduplicated by key
+	key: () => undefined,
+	validate: settings => {
+		if (!settings.path) return "Missing path";
+		if (!settings.data || typeof settings.data !== "object") return "Missing or invalid data";
+		return undefined;
+	},
+});

package/src/capability/skill.ts

@@ -0,0 +1,48 @@
+/**
+ * Skills Capability
+ *
+ * Skills provide specialized knowledge or workflows that extend agent capabilities.
+ */
+import { defineCapability } from ".";
+import type { SourceMeta } from "./types";
+
+/**
+ * Parsed frontmatter from a skill file.
+ */
+export interface SkillFrontmatter {
+	name?: string;
+	description?: string;
+	globs?: string[];
+	alwaysApply?: boolean;
+	[key: string]: unknown;
+}
+
+/**
+ * A skill that provides specialized knowledge or workflows.
+ */
+export interface Skill {
+	/** Skill name (unique key, derived from filename or frontmatter) */
+	name: string;
+	/** Absolute path to skill file */
+	path: string;
+	/** Skill content (markdown) */
+	content: string;
+	/** Parsed frontmatter */
+	frontmatter?: SkillFrontmatter;
+	/** Source level */
+	level: "user" | "project";
+	/** Source metadata */
+	_source: SourceMeta;
+}
+
+export const skillCapability = defineCapability<Skill>({
+	id: "skills",
+	displayName: "Skills",
+	description: "Specialized knowledge and workflow files that extend agent capabilities",
+	key: skill => skill.name,
+	validate: skill => {
+		if (!skill.name) return "Missing skill name";
+		if (!skill.path) return "Missing skill path";
+		return undefined;
+	},
+});

package/src/capability/slash-command.ts

@@ -0,0 +1,39 @@
+/**
+ * Slash Commands Capability
+ *
+ * File-based slash commands defined as markdown files.
+ */
+import { defineCapability } from ".";
+import type { SourceMeta } from "./types";
+
+/**
+ * A file-based slash command.
+ */
+export interface SlashCommand {
+	/** Command name (without leading slash) */
+	name: string;
+	/** Absolute path to command file */
+	path: string;
+	/** Command content (markdown template) */
+	content: string;
+	/** Source level */
+	level: "user" | "project" | "native";
+	/** Source metadata */
+	_source: SourceMeta;
+}
+
+export const slashCommandCapability = defineCapability<SlashCommand>({
+	id: "slash-commands",
+	displayName: "Slash Commands",
+	description: "Custom slash commands defined as markdown files",
+	key: cmd => cmd.name,
+	validate: cmd => {
+		if (!cmd.name) return "Missing name";
+		if (!cmd.path) return "Missing path";
+		if (cmd.content === undefined) return "Missing content";
+		if (cmd.level !== "user" && cmd.level !== "project" && cmd.level !== "native") {
+			return "Invalid level: must be 'user', 'project', or 'native'";
+		}
+		return undefined;
+	},
+});

package/src/capability/ssh.ts

@@ -0,0 +1,41 @@
+/**
+ * SSH Hosts Capability
+ *
+ * Canonical shape for SSH host entries, regardless of source format.
+ */
+import { defineCapability } from ".";
+import type { SourceMeta } from "./types";
+
+/**
+ * Canonical SSH host entry.
+ */
+export interface SSHHost {
+	/** Host name (config key) */
+	name: string;
+	/** Host address or DNS name */
+	host: string;
+	/** Optional username override */
+	username?: string;
+	/** Optional port override */
+	port?: number;
+	/** Optional identity key path */
+	keyPath?: string;
+	/** Optional host description */
+	description?: string;
+	/** Optional compatibility mode flag */
+	compat?: boolean;
+	/** Source metadata (added by loader) */
+	_source: SourceMeta;
+}
+
+export const sshCapability = defineCapability<SSHHost>({
+	id: "ssh",
+	displayName: "SSH Hosts",
+	description: "SSH host entries for remote command execution",
+	key: host => host.name,
+	validate: host => {
+		if (!host.name) return "Missing name";
+		if (!host.host) return "Missing host";
+		return undefined;
+	},
+});

package/src/capability/system-prompt.ts

@@ -0,0 +1,34 @@
+/**
+ * System Prompt Capability
+ *
+ * Custom system prompt files (SYSTEM.md) that modify the agent's base system prompt.
+ * Distinct from context-files which are user instructions shown in conversation.
+ */
+import { defineCapability } from ".";
+import type { SourceMeta } from "./types";
+
+/**
+ * A system prompt customization file.
+ */
+export interface SystemPrompt {
+	/** Absolute path to the file */
+	path: string;
+	/** File content */
+	content: string;
+	/** Which level this came from */
+	level: "user" | "project";
+	/** Source metadata */
+	_source: SourceMeta;
+}
+
+export const systemPromptCapability = defineCapability<SystemPrompt>({
+	id: "system-prompt",
+	displayName: "System Prompt",
+	description: "Custom system prompt files (SYSTEM.md) that modify agent behavior",
+	key: sp => sp.level,
+	validate: sp => {
+		if (!sp.path) return "Missing path";
+		if (sp.content === undefined) return "Missing content";
+		return undefined;
+	},
+});

package/src/capability/tool.ts

@@ -0,0 +1,37 @@
+/**
+ * Custom Tools Capability
+ *
+ * User-defined tools that extend agent capabilities.
+ */
+import { defineCapability } from ".";
+import type { SourceMeta } from "./types";
+
+/**
+ * A custom tool definition.
+ */
+export interface CustomTool {
+	/** Tool name (unique key) */
+	name: string;
+	/** Absolute path to tool definition file */
+	path: string;
+	/** Tool description */
+	description?: string;
+	/** Tool implementation (script path or inline) */
+	implementation?: string;
+	/** Source level */
+	level: "user" | "project";
+	/** Source metadata */
+	_source: SourceMeta;
+}
+
+export const toolCapability = defineCapability<CustomTool>({
+	id: "tools",
+	displayName: "Custom Tools",
+	description: "User-defined tools that extend agent capabilities",
+	key: tool => tool.name,
+	validate: tool => {
+		if (!tool.name) return "Missing name";
+		if (!tool.path) return "Missing path";
+		return undefined;
+	},
+});

package/src/capability/types.ts

@@ -0,0 +1,156 @@
+/**
+ * Core types for the capability-based config discovery system.
+ *
+ * This architecture inverts control: instead of callers knowing about paths like
+ * `.claude`, `.codex`, `.gemini`, they simply ask for `load("mcps")` and get back
+ * a unified array of MCP servers.
+ */
+
+/**
+ * Context passed to every provider loader.
+ */
+export interface LoadContext {
+	/** Current working directory (project root) */
+	cwd: string;
+	/** User home directory */
+	home: string;
+}
+
+/**
+ * Result from a provider's load function.
+ */
+export interface LoadResult<T> {
+	items: T[];
+	/** Warnings encountered during loading (parse errors, etc.) */
+	warnings?: string[];
+}
+
+/**
+ * A provider that can load items for a capability.
+ */
+export interface Provider<T> {
+	/** Unique provider ID (e.g., "claude", "arc", "mcp-json", "agents-md") */
+	id: string;
+
+	/** Human-readable name for UI display (e.g., "Claude Code", "OpenAI Codex") */
+	displayName: string;
+
+	/** Short description for settings UI (e.g., "Load config from ~/.claude and .claude/") */
+	description: string;
+
+	/**
+	 * Priority (higher = checked first, wins on conflicts).
+	 * Suggested ranges:
+	 *   100+ : Primary providers (arc, pi)
+	 *   50-99: Tool-specific providers (claude, codex, gemini)
+	 *   1-49 : Shared standards (mcp-json, agents-md)
+	 */
+	priority: number;
+
+	/**
+	 * Load items for this capability.
+	 * Returns items in provider's preferred order (usually project before user).
+	 */
+	load(ctx: LoadContext): Promise<LoadResult<T>>;
+}
+
+/**
+ * Options for loading a capability.
+ */
+export interface LoadOptions {
+	/** Only use these providers (by ID). Default: all registered */
+	providers?: string[];
+	/** Exclude these providers (by ID). Default: none */
+	excludeProviders?: string[];
+	/** Custom cwd. Default: getProjectDir() */
+	cwd?: string;
+	/** Include items even if they fail validation. Default: false */
+	includeInvalid?: boolean;
+}
+
+/**
+ * Source metadata attached to every loaded item.
+ */
+export interface SourceMeta {
+	/** Provider ID that loaded this item */
+	provider: string;
+	/** Provider display name (for UI) */
+	providerName: string;
+	/** Absolute path to the source file */
+	path: string;
+	/** Whether this came from user-level, project-level, or native config */
+	level: "user" | "project" | "native";
+}
+
+/**
+ * Merged result from loading a capability across all providers.
+ */
+export interface CapabilityResult<T> {
+	/** Deduplicated items in priority order */
+	items: Array<T & { _source: SourceMeta }>;
+	/** All items including shadowed duplicates (for diagnostics) */
+	all: Array<T & { _source: SourceMeta; _shadowed?: boolean }>;
+	/** Warnings from all providers */
+	warnings: string[];
+	/** Which providers contributed items (IDs) */
+	providers: string[];
+}
+
+/**
+ * Definition of a capability.
+ */
+export interface Capability<T> {
+	/** Capability ID (e.g., "mcps", "skills", "context-files") */
+	id: string;
+
+	/** Human-readable name for UI display (e.g., "MCP Servers", "Skills") */
+	displayName: string;
+
+	/** Short description for settings/status UI */
+	description: string;
+
+	/**
+	 * Extract a unique key from an item for deduplication.
+	 * Items with the same key: first one wins (highest priority provider).
+	 * Return undefined to never deduplicate (all items kept).
+	 */
+	key(item: T): string | undefined;
+
+	/**
+	 * Optional validation. Return error message if invalid, undefined if valid.
+	 */
+	validate?(item: T): string | undefined;
+
+	/** Registered providers, sorted by priority (highest first) */
+	providers: Provider<T>[];
+}
+
+/**
+ * Metadata about a capability (for introspection/UI).
+ */
+export interface CapabilityInfo {
+	id: string;
+	displayName: string;
+	description: string;
+	providers: Array<{
+		id: string;
+		displayName: string;
+		description: string;
+		priority: number;
+		enabled: boolean;
+	}>;
+}
+
+/**
+ * Metadata about a provider (for introspection/UI).
+ */
+export interface ProviderInfo {
+	id: string;
+	displayName: string;
+	description: string;
+	priority: number;
+	/** Which capabilities this provider is registered for */
+	capabilities: string[];
+	/** Whether this provider is currently enabled */
+	enabled: boolean;
+}