@nghyane/arcane 0.1.0

package/src/extensibility/plugins/parser.ts

@@ -0,0 +1,105 @@
+/**
+ * Feature bracket parser for plugin specifiers.
+ *
+ * Supports syntax like:
+ * - "my-plugin" -> base features (null)
+ * - "my-plugin[search,web]" -> specific features
+ * - "my-plugin[*]" -> all features
+ * - "my-plugin[]" -> no optional features
+ * - "@scope/plugin@1.2.3[feat]" -> scoped with version and features
+ */
+
+export interface ParsedPluginSpec {
+	/** Package name (may include version specifier like @1.0.0) */
+	packageName: string;
+	/**
+	 * Feature selection:
+	 * - null: use defaults (base features on first install, preserve on reinstall)
+	 * - "*": all features
+	 * - string[]: specific features (empty array = no optional features)
+	 */
+	features: string[] | null | "*";
+}
+
+/**
+ * Parse plugin specifier with feature bracket syntax.
+ *
+ * @example
+ * parsePluginSpec("my-plugin") // { packageName: "my-plugin", features: null }
+ * parsePluginSpec("my-plugin[search,web]") // { packageName: "my-plugin", features: ["search", "web"] }
+ * parsePluginSpec("my-plugin[*]") // { packageName: "my-plugin", features: "*" }
+ * parsePluginSpec("my-plugin[]") // { packageName: "my-plugin", features: [] }
+ * parsePluginSpec("@scope/pkg@1.2.3[feat]") // { packageName: "@scope/pkg@1.2.3", features: ["feat"] }
+ */
+export function parsePluginSpec(spec: string): ParsedPluginSpec {
+	// Find the last bracket pair (to handle version specifiers like @1.0.0)
+	const bracketStart = spec.lastIndexOf("[");
+	const bracketEnd = spec.lastIndexOf("]");
+
+	// No brackets or malformed -> base features
+	if (bracketStart === -1 || bracketEnd === -1 || bracketEnd < bracketStart) {
+		return { packageName: spec, features: null };
+	}
+
+	const packageName = spec.slice(0, bracketStart);
+	const featureStr = spec.slice(bracketStart + 1, bracketEnd).trim();
+
+	// All features
+	if (featureStr === "*") {
+		return { packageName, features: "*" };
+	}
+
+	// No optional features
+	if (featureStr === "") {
+		return { packageName, features: [] };
+	}
+
+	// Specific features (comma-separated)
+	const features = featureStr
+		.split(",")
+		.map(f => f.trim())
+		.filter(Boolean);
+
+	return { packageName, features };
+}
+
+/**
+ * Format a parsed plugin spec back to string form.
+ *
+ * @example
+ * formatPluginSpec({ packageName: "pkg", features: null }) // "pkg"
+ * formatPluginSpec({ packageName: "pkg", features: "*" }) // "pkg[*]"
+ * formatPluginSpec({ packageName: "pkg", features: [] }) // "pkg[]"
+ * formatPluginSpec({ packageName: "pkg", features: ["a", "b"] }) // "pkg[a,b]"
+ */
+export function formatPluginSpec(spec: ParsedPluginSpec): string {
+	if (spec.features === null) {
+		return spec.packageName;
+	}
+	if (spec.features === "*") {
+		return `${spec.packageName}[*]`;
+	}
+	if (spec.features.length === 0) {
+		return `${spec.packageName}[]`;
+	}
+	return `${spec.packageName}[${spec.features.join(",")}]`;
+}
+
+/**
+ * Extract the base package name without version specifier.
+ * Used for path lookups after npm install.
+ *
+ * @example
+ * extractPackageName("lodash@4.17.21") // "lodash"
+ * extractPackageName("@scope/pkg@1.0.0") // "@scope/pkg"
+ * extractPackageName("@scope/pkg") // "@scope/pkg"
+ */
+export function extractPackageName(specifier: string): string {
+	// Handle scoped packages: @scope/name@version -> @scope/name
+	if (specifier.startsWith("@")) {
+		const match = specifier.match(/^(@[^/]+\/[^@]+)/);
+		return match ? match[1] : specifier;
+	}
+	// Unscoped: name@version -> name
+	return specifier.replace(/@[^@]+$/, "");
+}

package/src/extensibility/plugins/types.ts

@@ -0,0 +1,190 @@
+// =============================================================================
+// Plugin Manifest Types (from package.json arc/pi field)
+// =============================================================================
+
+/**
+ * Feature definition for selective plugin installation.
+ * Features allow plugins to expose optional functionality.
+ */
+export interface PluginFeature {
+	/** Human-readable description */
+	description?: string;
+	/** Whether this feature is enabled by default */
+	default?: boolean;
+	/** Additional tool entry points provided by this feature */
+	tools?: string[];
+	/** Additional hook entry points provided by this feature */
+	hooks?: string[];
+	/** Additional command files provided by this feature */
+	commands?: string[];
+}
+
+/**
+ * Plugin manifest from package.json arcane or pi field.
+ */
+export interface PluginManifest {
+	/** Plugin display name (defaults to package name) */
+	name?: string;
+	/** Plugin version (copied from package.json version) */
+	version: string;
+	/** Human-readable description */
+	description?: string;
+
+	/** Entry point for base tools (relative path from package root) */
+	tools?: string;
+	/** Entry point for base hooks (relative path from package root) */
+	hooks?: string;
+	/** Command files (relative paths from package root) */
+	commands?: string[];
+
+	/** Feature definitions for selective installation */
+	features?: Record<string, PluginFeature>;
+
+	/** Settings schema for plugin configuration */
+	settings?: Record<string, PluginSettingSchema>;
+}
+
+// =============================================================================
+// Plugin Settings Schema Types
+// =============================================================================
+
+export type PluginSettingType = "string" | "number" | "boolean" | "enum";
+
+interface PluginSettingBase {
+	/** Setting type */
+	type: PluginSettingType;
+	/** Human-readable description */
+	description?: string;
+	/** If true, mask value in UI and logs */
+	secret?: boolean;
+	/** Environment variable to use as fallback value */
+	env?: string;
+}
+
+export interface StringSetting extends PluginSettingBase {
+	type: "string";
+	default?: string;
+}
+
+export interface NumberSetting extends PluginSettingBase {
+	type: "number";
+	default?: number;
+	min?: number;
+	max?: number;
+	step?: number;
+}
+
+export interface BooleanSetting extends PluginSettingBase {
+	type: "boolean";
+	default?: boolean;
+}
+
+export interface EnumSetting extends PluginSettingBase {
+	type: "enum";
+	/** Allowed values */
+	values: string[];
+	default?: string;
+}
+
+export type PluginSettingSchema = StringSetting | NumberSetting | BooleanSetting | EnumSetting;
+
+// =============================================================================
+// Installed Plugin Types
+// =============================================================================
+
+/**
+ * Represents an installed plugin with full metadata.
+ */
+export interface InstalledPlugin {
+	/** npm package name */
+	name: string;
+	/** Installed version */
+	version: string;
+	/** Absolute path to package directory */
+	path: string;
+	/** Parsed arc/pi manifest */
+	manifest: PluginManifest;
+	/**
+	 * Enabled features:
+	 * - null: use defaults (all features with default: true)
+	 * - string[]: specific features enabled
+	 */
+	enabledFeatures: string[] | null;
+	/** Whether the plugin is enabled */
+	enabled: boolean;
+}
+
+// =============================================================================
+// Runtime Config Types (stored in arcane-plugins.lock.json)
+// =============================================================================
+
+/**
+ * Per-plugin runtime state stored in lock file.
+ */
+export interface PluginRuntimeState {
+	/** Installed version */
+	version: string;
+	/** Enabled features (null = defaults) */
+	enabledFeatures: string[] | null;
+	/** Whether the plugin is enabled */
+	enabled: boolean;
+}
+
+/**
+ * Runtime configuration persisted to arcane-plugins.lock.json.
+ * Tracks plugin states and settings across sessions.
+ */
+export interface PluginRuntimeConfig {
+	/** Plugin states keyed by package name */
+	plugins: Record<string, PluginRuntimeState>;
+	/** Plugin settings keyed by package name, then setting key */
+	settings: Record<string, Record<string, unknown>>;
+}
+
+// =============================================================================
+// Project Override Types
+// =============================================================================
+
+/**
+ * Project-local plugin overrides (stored in .arcane/plugin-overrides.json).
+ * Allows per-project plugin configuration without modifying global state.
+ */
+export interface ProjectPluginOverrides {
+	/** Plugins to disable in this project */
+	disabled?: string[];
+	/** Per-plugin feature overrides */
+	features?: Record<string, string[]>;
+	/** Per-plugin setting overrides */
+	settings?: Record<string, Record<string, unknown>>;
+}
+
+// =============================================================================
+// Doctor Types
+// =============================================================================
+
+export interface DoctorCheck {
+	/** Check identifier */
+	name: string;
+	/** Check result status */
+	status: "ok" | "warning" | "error";
+	/** Human-readable message */
+	message: string;
+	/** Whether --fix resolved this issue */
+	fixed?: boolean;
+}
+
+// =============================================================================
+// Install Options Types
+// =============================================================================
+
+export interface InstallOptions {
+	/** Overwrite existing without prompting */
+	force?: boolean;
+	/** Preview changes without applying */
+	dryRun?: boolean;
+}
+
+export interface DoctorOptions {
+	/** Attempt automatic fixes */
+	fix?: boolean;
+}

package/src/extensibility/skills.ts

@@ -0,0 +1,385 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { logger } from "@nghyane/arcane-utils";
+import { getProjectDir } from "@nghyane/arcane-utils/dirs";
+import { skillCapability } from "../capability/skill";
+import type { SourceMeta } from "../capability/types";
+import type { SkillsSettings } from "../config/settings";
+import type { Skill as CapabilitySkill, SkillFrontmatter as ImportedSkillFrontmatter } from "../discovery";
+import { loadCapability } from "../discovery";
+import { parseFrontmatter } from "../utils/frontmatter";
+import { addIgnoreRules, createIgnoreMatcher, type IgnoreMatcher, shouldIgnore } from "../utils/ignore-files";
+
+// Re-export SkillFrontmatter for backward compatibility
+export type { ImportedSkillFrontmatter as SkillFrontmatter };
+
+export interface Skill {
+	name: string;
+	description: string;
+	filePath: string;
+	baseDir: string;
+	source: string;
+	/** Source metadata for display */
+	_source?: SourceMeta;
+}
+
+export interface SkillWarning {
+	skillPath: string;
+	message: string;
+}
+
+export interface LoadSkillsResult {
+	skills: Skill[];
+	warnings: SkillWarning[];
+}
+
+export interface LoadSkillsFromDirOptions {
+	/** Directory to scan for skills */
+	dir: string;
+	/** Source identifier for these skills */
+	source: string;
+}
+
+async function readFileContent(filePath: string): Promise<string | null> {
+	try {
+		return await fs.readFile(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Load skills from a directory recursively.
+ * Skills are directories containing a SKILL.md file with frontmatter including a description.
+ * Respects .gitignore, .ignore, and .fdignore files.
+ */
+export async function loadSkillsFromDir(options: LoadSkillsFromDirOptions): Promise<LoadSkillsResult> {
+	const skills: Skill[] = [];
+	const warnings: SkillWarning[] = [];
+	const seenPaths = new Set<string>();
+	const rootDir = options.dir;
+
+	async function addSkill(skillFile: string, skillDir: string, dirName: string): Promise<void> {
+		if (seenPaths.has(skillFile)) return;
+		try {
+			const content = await fs.readFile(skillFile, "utf-8");
+			const { frontmatter } = parseFrontmatter(content, { source: skillFile });
+			const name = (frontmatter.name as string) || dirName;
+			const description = frontmatter.description as string;
+
+			if (description) {
+				seenPaths.add(skillFile);
+				skills.push({
+					name,
+					description,
+					filePath: skillFile,
+					baseDir: skillDir,
+					source: options.source,
+				});
+			}
+		} catch (error) {
+			logger.warn("Failed to load skill", { path: skillFile, error: String(error) });
+		}
+	}
+
+	async function scanDir(dir: string, ig: IgnoreMatcher): Promise<void> {
+		try {
+			// Add ignore rules from this directory
+			await addIgnoreRules(ig, dir, rootDir, readFileContent);
+
+			// First check if this directory itself is a skill
+			const selfSkillFile = path.join(dir, "SKILL.md");
+			try {
+				const s = await fs.stat(selfSkillFile);
+				if (s.isFile()) {
+					await addSkill(selfSkillFile, dir, path.basename(dir));
+					// This directory is a skill, don't recurse
+					return;
+				}
+			} catch {
+				// No SKILL.md in this directory
+			}
+
+			// Recurse into subdirectories
+			const entries = await fs.readdir(dir, { withFileTypes: true });
+
+			for (const entry of entries) {
+				if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+
+				const fullPath = path.join(dir, entry.name);
+				const isDir = entry.isDirectory();
+
+				// Check if this entry should be ignored
+				if (shouldIgnore(ig, rootDir, fullPath, isDir)) continue;
+
+				if (isDir) {
+					await scanDir(fullPath, ig);
+				}
+			}
+		} catch (err) {
+			warnings.push({ skillPath: dir, message: `Failed to read directory: ${err}` });
+		}
+	}
+
+	const ig = createIgnoreMatcher();
+	await scanDir(options.dir, ig);
+
+	return { skills, warnings };
+}
+
+/**
+ * Scan a directory for SKILL.md files recursively.
+ * Used internally by loadSkills for custom directories.
+ * Respects .gitignore, .ignore, and .fdignore files.
+ */
+async function scanDirectoryForSkills(dir: string): Promise<LoadSkillsResult> {
+	const skills: Skill[] = [];
+	const warnings: SkillWarning[] = [];
+	const seenPaths = new Set<string>();
+	const rootDir = dir;
+
+	async function addSkill(skillFile: string, skillDir: string, dirName: string): Promise<void> {
+		if (seenPaths.has(skillFile)) return;
+		try {
+			const content = await fs.readFile(skillFile, "utf-8");
+			const { frontmatter } = parseFrontmatter(content, { source: skillFile });
+			const name = (frontmatter.name as string) || dirName;
+			const description = frontmatter.description as string;
+
+			if (description) {
+				seenPaths.add(skillFile);
+				skills.push({
+					name,
+					description,
+					filePath: skillFile,
+					baseDir: skillDir,
+					source: "custom",
+				});
+			}
+		} catch (error) {
+			logger.warn("Failed to load skill", { path: skillFile, error: String(error) });
+		}
+	}
+
+	async function scanDir(currentDir: string, ig: IgnoreMatcher): Promise<void> {
+		try {
+			// Add ignore rules from this directory
+			await addIgnoreRules(ig, currentDir, rootDir, readFileContent);
+
+			// First check if this directory itself is a skill
+			const selfSkillFile = path.join(currentDir, "SKILL.md");
+			try {
+				const s = await fs.stat(selfSkillFile);
+				if (s.isFile()) {
+					await addSkill(selfSkillFile, currentDir, path.basename(currentDir));
+					// This directory is a skill, don't recurse
+					return;
+				}
+			} catch {
+				// No SKILL.md in this directory
+			}
+
+			// Recurse into subdirectories
+			const entries = await fs.readdir(currentDir, { withFileTypes: true });
+
+			for (const entry of entries) {
+				if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+
+				const fullPath = path.join(currentDir, entry.name);
+				const isDir = entry.isDirectory();
+
+				// Check if this entry should be ignored
+				if (shouldIgnore(ig, rootDir, fullPath, isDir)) continue;
+
+				if (isDir) {
+					await scanDir(fullPath, ig);
+				}
+			}
+		} catch (err) {
+			warnings.push({ skillPath: currentDir, message: `Failed to read directory: ${err}` });
+		}
+	}
+
+	const ig = createIgnoreMatcher();
+	await scanDir(dir, ig);
+
+	return { skills, warnings };
+}
+
+export interface LoadSkillsOptions extends SkillsSettings {
+	/** Working directory for project-local skills. Default: getProjectDir() */
+	cwd?: string;
+}
+
+/**
+ * Load skills from all configured locations.
+ * Returns skills and any validation warnings.
+ */
+export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadSkillsResult> {
+	const {
+		cwd = getProjectDir(),
+		enabled = true,
+		enableCodexUser = true,
+		enableClaudeUser = true,
+		enableClaudeProject = true,
+		enablePiUser = true,
+		enablePiProject = true,
+		customDirectories = [],
+		ignoredSkills = [],
+		includeSkills = [],
+	} = options;
+
+	// Early return if skills are disabled
+	if (!enabled) {
+		return { skills: [], warnings: [] };
+	}
+
+	const anyBuiltInSkillSourceEnabled =
+		enableCodexUser || enableClaudeUser || enableClaudeProject || enablePiUser || enablePiProject;
+	// Helper to check if a source is enabled
+	function isSourceEnabled(source: SourceMeta): boolean {
+		const { provider, level } = source;
+		if (provider === "codex" && level === "user") return enableCodexUser;
+		if (provider === "claude" && level === "user") return enableClaudeUser;
+		if (provider === "claude" && level === "project") return enableClaudeProject;
+		if (provider === "native" && level === "user") return enablePiUser;
+		if (provider === "native" && level === "project") return enablePiProject;
+		// For other providers (agents, claude-plugins, etc.), treat them as built-in skill sources.
+		return anyBuiltInSkillSourceEnabled;
+	}
+
+	// Use capability API to load all skills
+	const result = await loadCapability<CapabilitySkill>(skillCapability.id, { cwd });
+
+	const skillMap = new Map<string, Skill>();
+	const realPathSet = new Set<string>();
+	const collisionWarnings: SkillWarning[] = [];
+
+	// Check if skill name matches any of the include patterns
+	function matchesIncludePatterns(name: string): boolean {
+		if (includeSkills.length === 0) return true;
+		return includeSkills.some(pattern => new Bun.Glob(pattern).match(name));
+	}
+
+	// Check if skill name matches any of the ignore patterns
+	function matchesIgnorePatterns(name: string): boolean {
+		if (ignoredSkills.length === 0) return false;
+		return ignoredSkills.some(pattern => new Bun.Glob(pattern).match(name));
+	}
+
+	// Filter skills by source and patterns first
+	const filteredSkills = result.items.filter(capSkill => {
+		if (!isSourceEnabled(capSkill._source)) return false;
+		if (matchesIgnorePatterns(capSkill.name)) return false;
+		if (!matchesIncludePatterns(capSkill.name)) return false;
+		return true;
+	});
+
+	// Batch resolve all real paths in parallel
+	const realPaths = await Promise.all(
+		filteredSkills.map(async capSkill => {
+			try {
+				return await fs.realpath(capSkill.path);
+			} catch {
+				return capSkill.path;
+			}
+		}),
+	);
+
+	// Process skills with resolved paths
+	for (let i = 0; i < filteredSkills.length; i++) {
+		const capSkill = filteredSkills[i];
+		const resolvedPath = realPaths[i];
+
+		// Skip silently if we've already loaded this exact file (via symlink)
+		if (realPathSet.has(resolvedPath)) {
+			continue;
+		}
+
+		const existing = skillMap.get(capSkill.name);
+		if (existing) {
+			collisionWarnings.push({
+				skillPath: capSkill.path,
+				message: `name collision: "${capSkill.name}" already loaded from ${existing.filePath}, skipping this one`,
+			});
+		} else {
+			// Transform capability skill to legacy format
+			const skill: Skill = {
+				name: capSkill.name,
+				description: capSkill.frontmatter?.description || "",
+				filePath: capSkill.path,
+				baseDir: capSkill.path.replace(/\/SKILL\.md$/, ""),
+				source: `${capSkill._source.provider}:${capSkill.level}`,
+				_source: capSkill._source,
+			};
+			skillMap.set(capSkill.name, skill);
+			realPathSet.add(resolvedPath);
+		}
+	}
+
+	// Process custom directories - scan directly without using full provider system
+	const allCustomSkills: Array<{ skill: Skill; path: string }> = [];
+	const customScanResults = await Promise.all(
+		customDirectories.map(dir => {
+			let resolved = dir;
+			if (resolved.startsWith("~/")) {
+				resolved = path.join(os.homedir(), resolved.slice(2));
+			} else if (resolved === "~") {
+				resolved = os.homedir();
+			}
+			return scanDirectoryForSkills(resolved);
+		}),
+	);
+	for (const customSkills of customScanResults) {
+		for (const s of customSkills.skills) {
+			if (matchesIgnorePatterns(s.name)) continue;
+			if (!matchesIncludePatterns(s.name)) continue;
+			allCustomSkills.push({
+				skill: {
+					name: s.name,
+					description: s.description,
+					filePath: s.filePath,
+					baseDir: s.filePath.replace(/\/SKILL\.md$/, ""),
+					source: "custom:user",
+					_source: { provider: "custom", providerName: "Custom", path: s.filePath, level: "user" },
+				},
+				path: s.filePath,
+			});
+		}
+		collisionWarnings.push(...customSkills.warnings);
+	}
+
+	// Batch resolve custom skill paths
+	const customRealPaths = await Promise.all(
+		allCustomSkills.map(async ({ path }) => {
+			try {
+				return await fs.realpath(path);
+			} catch {
+				return path;
+			}
+		}),
+	);
+
+	for (let i = 0; i < allCustomSkills.length; i++) {
+		const { skill } = allCustomSkills[i];
+		const resolvedPath = customRealPaths[i];
+		if (realPathSet.has(resolvedPath)) continue;
+
+		const existing = skillMap.get(skill.name);
+		if (existing) {
+			collisionWarnings.push({
+				skillPath: skill.filePath,
+				message: `name collision: "${skill.name}" already loaded from ${existing.filePath}, skipping this one`,
+			});
+		} else {
+			skillMap.set(skill.name, skill);
+			realPathSet.add(resolvedPath);
+		}
+	}
+
+	return {
+		skills: Array.from(skillMap.values()),
+		warnings: [...result.warnings.map(w => ({ skillPath: "", message: w })), ...collisionWarnings],
+	};
+}