@clinebot/core 0.0.0

package/src/agents/agent-config-parser.ts

@@ -0,0 +1,191 @@
+import type { AgentConfig, Tool } from "@clinebot/agents";
+import YAML from "yaml";
+import { z } from "zod";
+import { ALL_DEFAULT_TOOL_NAMES, type DefaultToolName } from "../default-tools";
+
+const AgentConfigFrontmatterSchema = z.object({
+	name: z.string().trim().min(1),
+	description: z.string().trim().min(1),
+	modelId: z.string().trim().min(1).optional(),
+	tools: z.union([z.string(), z.array(z.string())]).optional(),
+	skills: z.union([z.string(), z.array(z.string())]).optional(),
+});
+
+const allowedToolNames = new Set<string>(ALL_DEFAULT_TOOL_NAMES);
+
+export interface AgentYamlConfig {
+	name: string;
+	description: string;
+	modelId?: string;
+	tools: DefaultToolName[];
+	skills?: string[];
+	systemPrompt: string;
+}
+
+export interface ParseYamlFrontmatterResult {
+	data: Record<string, unknown>;
+	body: string;
+	hadFrontmatter: boolean;
+	parseError?: string;
+}
+
+export interface BuildAgentConfigOverridesOptions {
+	availableTools?: ReadonlyArray<Tool>;
+}
+
+export function isAgentConfigYamlFile(fileName: string): boolean {
+	return /\.(yaml|yml)$/i.test(fileName);
+}
+
+export function normalizeAgentConfigName(name: string): string {
+	return name.trim().toLowerCase();
+}
+
+function parseYamlFrontmatter(markdown: string): ParseYamlFrontmatterResult {
+	const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+	const match = markdown.match(frontmatterRegex);
+	if (!match) {
+		return { data: {}, body: markdown, hadFrontmatter: false };
+	}
+
+	const [, yamlContent, body] = match;
+	try {
+		const parsed = YAML.parse(yamlContent);
+		const data =
+			parsed && typeof parsed === "object" && !Array.isArray(parsed)
+				? (parsed as Record<string, unknown>)
+				: {};
+		return { data, body, hadFrontmatter: true };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return {
+			data: {},
+			body: markdown,
+			hadFrontmatter: true,
+			parseError: message,
+		};
+	}
+}
+
+function normalizeToolName(toolName: string): DefaultToolName {
+	const trimmed = toolName.trim();
+	if (!trimmed) {
+		throw new Error("Tool name cannot be empty.");
+	}
+	if (!allowedToolNames.has(trimmed)) {
+		throw new Error(
+			`Unknown tool '${trimmed}'. Expected one of: ${ALL_DEFAULT_TOOL_NAMES.join(", ")}.`,
+		);
+	}
+	return trimmed as DefaultToolName;
+}
+
+function parseToolNames(
+	tools: string | string[] | undefined,
+): DefaultToolName[] {
+	if (!tools) {
+		return [];
+	}
+	const rawTools = Array.isArray(tools) ? tools : tools.split(",");
+	return Array.from(new Set(rawTools.map(normalizeToolName)));
+}
+
+function normalizeSkillName(skillName: string): string {
+	const trimmed = skillName.trim();
+	if (!trimmed) {
+		throw new Error("Skill name cannot be empty.");
+	}
+	return trimmed;
+}
+
+function parseSkills(
+	skills: string | string[] | undefined,
+): string[] | undefined {
+	if (skills === undefined) {
+		return undefined;
+	}
+	const rawSkills = Array.isArray(skills) ? skills : skills.split(",");
+	return Array.from(new Set(rawSkills.map(normalizeSkillName)));
+}
+
+export function parseAgentConfigFromYaml(content: string): AgentYamlConfig {
+	const { data, body, hadFrontmatter, parseError } =
+		parseYamlFrontmatter(content);
+	if (parseError) {
+		throw new Error(`Failed to parse YAML frontmatter: ${parseError}`);
+	}
+	if (!hadFrontmatter) {
+		throw new Error("Missing YAML frontmatter block in agent config file.");
+	}
+
+	const parsedFrontmatter = AgentConfigFrontmatterSchema.parse(data);
+	const systemPrompt = body.trim();
+	if (!systemPrompt) {
+		throw new Error("Missing system prompt body in agent config file.");
+	}
+
+	return {
+		name: parsedFrontmatter.name,
+		description: parsedFrontmatter.description,
+		modelId: parsedFrontmatter.modelId,
+		tools: parseToolNames(parsedFrontmatter.tools),
+		skills: parseSkills(parsedFrontmatter.skills),
+		systemPrompt,
+	};
+}
+
+export function resolveAgentTools(
+	toolNames: ReadonlyArray<DefaultToolName>,
+	availableTools: ReadonlyArray<Tool>,
+): Tool[] {
+	if (toolNames.length === 0) {
+		return [];
+	}
+
+	const toolIndex = new Map<string, Tool>(
+		availableTools.map((tool) => [tool.name, tool]),
+	);
+	return toolNames.map((toolName) => {
+		const resolved = toolIndex.get(toolName);
+		if (!resolved) {
+			throw new Error(
+				`Configured tool '${toolName}' is unavailable. Available tools: ${availableTools.map((tool) => tool.name).join(", ")}.`,
+			);
+		}
+		return resolved;
+	});
+}
+
+export function toPartialAgentConfig(
+	config: AgentYamlConfig,
+	options?: BuildAgentConfigOverridesOptions,
+): Partial<Pick<AgentConfig, "modelId" | "systemPrompt" | "tools">> {
+	const partial: Partial<
+		Pick<AgentConfig, "modelId" | "systemPrompt" | "tools">
+	> = {
+		systemPrompt: config.systemPrompt,
+	};
+
+	if (config.modelId) {
+		partial.modelId = config.modelId;
+	}
+
+	if (config.tools.length > 0) {
+		if (!options?.availableTools) {
+			throw new Error(
+				"Configured tools cannot be converted into AgentConfig.tools without availableTools.",
+			);
+		}
+		partial.tools = resolveAgentTools(config.tools, options.availableTools);
+	}
+
+	return partial;
+}
+
+export function parsePartialAgentConfigFromYaml(
+	content: string,
+	options?: BuildAgentConfigOverridesOptions,
+): Partial<Pick<AgentConfig, "modelId" | "systemPrompt" | "tools">> {
+	const parsed = parseAgentConfigFromYaml(content);
+	return toPartialAgentConfig(parsed, options);
+}

package/src/agents/hooks-config-loader.ts

@@ -0,0 +1,97 @@
+import { existsSync, readdirSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import type { HookEventName } from "@clinebot/agents";
+import {
+	HOOKS_CONFIG_DIRECTORY_NAME,
+	resolveDocumentsHooksDirectoryPath,
+	resolveHooksConfigSearchPaths as resolveHooksConfigSearchPathsFromShared,
+} from "@clinebot/shared/storage";
+
+export { HOOKS_CONFIG_DIRECTORY_NAME, resolveDocumentsHooksDirectoryPath };
+
+export function resolveHooksConfigSearchPaths(
+	workspacePath?: string,
+): string[] {
+	return resolveHooksConfigSearchPathsFromShared(workspacePath);
+}
+
+export enum HookConfigFileName {
+	TaskStart = "TaskStart",
+	TaskResume = "TaskResume",
+	TaskCancel = "TaskCancel",
+	TaskComplete = "TaskComplete",
+	PreToolUse = "PreToolUse",
+	PostToolUse = "PostToolUse",
+	UserPromptSubmit = "UserPromptSubmit",
+	PreCompact = "PreCompact",
+	SessionShutdown = "SessionShutdown",
+}
+
+export const HOOK_CONFIG_FILE_EVENT_MAP: Readonly<
+	Record<HookConfigFileName, HookEventName | undefined>
+> = {
+	[HookConfigFileName.TaskStart]: "agent_start",
+	[HookConfigFileName.TaskResume]: "agent_resume",
+	[HookConfigFileName.TaskCancel]: "agent_abort",
+	[HookConfigFileName.TaskComplete]: "agent_end",
+	[HookConfigFileName.PreToolUse]: "tool_call",
+	[HookConfigFileName.PostToolUse]: "tool_result",
+	[HookConfigFileName.UserPromptSubmit]: "prompt_submit",
+	[HookConfigFileName.PreCompact]: undefined,
+	[HookConfigFileName.SessionShutdown]: "session_shutdown",
+};
+
+const HOOK_CONFIG_FILE_LOOKUP = new Map<string, HookConfigFileName>(
+	Object.values(HookConfigFileName).map((name) => [name.toLowerCase(), name]),
+);
+
+export function toHookConfigFileName(
+	fileName: string,
+): HookConfigFileName | undefined {
+	const key = basename(fileName, extname(fileName)).trim().toLowerCase();
+	return HOOK_CONFIG_FILE_LOOKUP.get(key);
+}
+
+export interface HookConfigFileEntry {
+	fileName: HookConfigFileName;
+	hookEventName?: HookEventName;
+	path: string;
+}
+
+export function listHookConfigFiles(
+	workspacePath?: string,
+): HookConfigFileEntry[] {
+	const entries: HookConfigFileEntry[] = [];
+	const seen = new Set<string>();
+	const directories = resolveHooksConfigSearchPaths(workspacePath).filter(
+		(directory) => existsSync(directory),
+	);
+
+	for (const directory of directories) {
+		try {
+			for (const entry of readdirSync(directory, { withFileTypes: true })) {
+				if (!entry.isFile()) {
+					continue;
+				}
+				const fileName = toHookConfigFileName(entry.name);
+				if (!fileName) {
+					continue;
+				}
+				const path = join(directory, entry.name);
+				if (seen.has(path)) {
+					continue;
+				}
+				seen.add(path);
+				entries.push({
+					fileName,
+					hookEventName: HOOK_CONFIG_FILE_EVENT_MAP[fileName],
+					path,
+				});
+			}
+		} catch {
+			// Best-effort listing across config roots.
+		}
+	}
+
+	return entries.sort((a, b) => a.path.localeCompare(b.path));
+}

package/src/agents/index.ts

@@ -0,0 +1,84 @@
+export type {
+	AgentConfigWatcher,
+	AgentConfigWatcherEvent,
+	AgentYamlConfig,
+	BuildAgentConfigOverridesOptions,
+	CreateAgentConfigWatcherOptions,
+	ParseYamlFrontmatterResult,
+} from "./agent-config-loader";
+export {
+	AGENT_CONFIG_DIRECTORY_NAME,
+	createAgentConfigDefinition,
+	createAgentConfigWatcher,
+	parseAgentConfigFromYaml,
+	parsePartialAgentConfigFromYaml,
+	readAgentConfigsFromDisk,
+	resolveAgentConfigSearchPaths,
+	resolveAgentsConfigDirPath,
+	resolveAgentTools,
+	resolveDocumentsAgentConfigDirectoryPath,
+	toPartialAgentConfig,
+} from "./agent-config-loader";
+export {
+	HOOK_CONFIG_FILE_EVENT_MAP,
+	HOOKS_CONFIG_DIRECTORY_NAME,
+	type HookConfigFileEntry,
+	HookConfigFileName,
+	listHookConfigFiles,
+	resolveDocumentsHooksDirectoryPath,
+	resolveHooksConfigSearchPaths,
+	toHookConfigFileName,
+} from "./hooks-config-loader";
+export type { ResolveAgentPluginPathsOptions } from "./plugin-config-loader";
+export {
+	discoverPluginModulePaths,
+	resolveAgentPluginPaths,
+	resolveAndLoadAgentPlugins,
+	resolvePluginConfigSearchPaths,
+} from "./plugin-config-loader";
+export type { LoadAgentPluginFromPathOptions } from "./plugin-loader";
+export {
+	loadAgentPluginFromPath,
+	loadAgentPluginsFromPaths,
+} from "./plugin-loader";
+export type {
+	UnifiedConfigDefinition,
+	UnifiedConfigFileCandidate,
+	UnifiedConfigFileContext,
+	UnifiedConfigRecord,
+	UnifiedConfigWatcherEvent,
+	UnifiedConfigWatcherOptions,
+} from "./unified-config-file-watcher";
+export { UnifiedConfigFileWatcher } from "./unified-config-file-watcher";
+export type {
+	CreateInstructionWatcherOptions,
+	CreateRulesConfigDefinitionOptions,
+	CreateSkillsConfigDefinitionOptions,
+	CreateUserInstructionConfigWatcherOptions,
+	CreateWorkflowsConfigDefinitionOptions,
+	ParseMarkdownFrontmatterResult,
+	RuleConfig,
+	SkillConfig,
+	UserInstructionConfig,
+	UserInstructionConfigType,
+	UserInstructionConfigWatcher,
+	UserInstructionConfigWatcherEvent,
+	WorkflowConfig,
+} from "./user-instruction-config-loader";
+export {
+	createRulesConfigDefinition,
+	createSkillsConfigDefinition,
+	createUserInstructionConfigWatcher,
+	createWorkflowsConfigDefinition,
+	parseRuleConfigFromMarkdown,
+	parseSkillConfigFromMarkdown,
+	parseWorkflowConfigFromMarkdown,
+	RULES_CONFIG_DIRECTORY_NAME,
+	resolveDocumentsRulesDirectoryPath,
+	resolveDocumentsWorkflowsDirectoryPath,
+	resolveRulesConfigSearchPaths,
+	resolveSkillsConfigSearchPaths,
+	resolveWorkflowsConfigSearchPaths,
+	SKILLS_CONFIG_DIRECTORY_NAME,
+	WORKFLOWS_CONFIG_DIRECTORY_NAME,
+} from "./user-instruction-config-loader";

package/src/agents/plugin-config-loader.test.ts

@@ -0,0 +1,91 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setHomeDir } from "@clinebot/shared/storage";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	discoverPluginModulePaths,
+	resolveAgentPluginPaths,
+	resolvePluginConfigSearchPaths,
+} from "./plugin-config-loader";
+
+describe("plugin-config-loader", () => {
+	const envSnapshot = {
+		HOME: process.env.HOME,
+	};
+
+	afterEach(() => {
+		process.env.HOME = envSnapshot.HOME;
+		setHomeDir(envSnapshot.HOME ?? "~");
+	});
+
+	it("discovers plugin modules recursively", async () => {
+		const root = await mkdtemp(join(tmpdir(), "core-plugin-config-loader-"));
+		try {
+			const nested = join(root, "nested");
+			await mkdir(nested, { recursive: true });
+			await writeFile(join(root, "a.mjs"), "export default {}", "utf8");
+			await writeFile(join(nested, "b.ts"), "export default {}", "utf8");
+			await writeFile(join(root, "ignore.txt"), "noop", "utf8");
+
+			const discovered = discoverPluginModulePaths(root);
+			expect(discovered).toEqual([join(root, "a.mjs"), join(nested, "b.ts")]);
+		} finally {
+			await rm(root, { recursive: true, force: true });
+		}
+	});
+
+	it("resolves plugin paths from explicit files/directories", async () => {
+		const root = await mkdtemp(join(tmpdir(), "core-plugin-config-loader-"));
+		try {
+			const pluginsDir = join(root, "plugins");
+			await mkdir(pluginsDir, { recursive: true });
+			const filePath = join(root, "direct.mjs");
+			const dirPluginPath = join(pluginsDir, "dir-plugin.mjs");
+			await writeFile(filePath, "export default {}", "utf8");
+			await writeFile(dirPluginPath, "export default {}", "utf8");
+
+			const resolved = resolveAgentPluginPaths({
+				pluginPaths: ["./direct.mjs", "./plugins"],
+				workspacePath: join(root, "workspace"),
+				cwd: root,
+			});
+
+			expect(resolved).toEqual([filePath, dirPluginPath]);
+		} finally {
+			await rm(root, { recursive: true, force: true });
+		}
+	});
+
+	it("includes shared search-path plugins", async () => {
+		const home = await mkdtemp(
+			join(tmpdir(), "core-plugin-config-loader-home-"),
+		);
+		const workspace = await mkdtemp(
+			join(tmpdir(), "core-plugin-config-loader-workspace-"),
+		);
+		try {
+			process.env.HOME = home;
+			setHomeDir(home);
+			const workspacePlugins = join(workspace, ".clinerules", "plugins");
+			const userPlugins = join(home, ".cline", "plugins");
+			await mkdir(workspacePlugins, { recursive: true });
+			await mkdir(userPlugins, { recursive: true });
+			const workspacePlugin = join(workspacePlugins, "workspace.mjs");
+			const userPlugin = join(userPlugins, "user.mjs");
+			await writeFile(workspacePlugin, "export default {}", "utf8");
+			await writeFile(userPlugin, "export default {}", "utf8");
+
+			const searchPaths = resolvePluginConfigSearchPaths(workspace);
+			expect(searchPaths).toContain(workspacePlugins);
+			expect(searchPaths).toContain(userPlugins);
+
+			const resolved = resolveAgentPluginPaths({ workspacePath: workspace });
+			expect(resolved).toContain(workspacePlugin);
+			expect(resolved).toContain(userPlugin);
+		} finally {
+			await rm(home, { recursive: true, force: true });
+			await rm(workspace, { recursive: true, force: true });
+		}
+	});
+});

package/src/agents/plugin-config-loader.ts

@@ -0,0 +1,160 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { AgentConfig } from "@clinebot/agents";
+import { resolvePluginConfigSearchPaths as resolvePluginConfigSearchPathsFromShared } from "@clinebot/shared/storage";
+import { loadAgentPluginsFromPaths } from "./plugin-loader";
+import { loadSandboxedPlugins } from "./plugin-sandbox";
+
+const PLUGIN_MODULE_EXTENSIONS = new Set([
+	".js",
+	".mjs",
+	".cjs",
+	".ts",
+	".mts",
+	".cts",
+]);
+
+type AgentPlugin = NonNullable<AgentConfig["extensions"]>[number];
+
+export function resolvePluginConfigSearchPaths(
+	workspacePath?: string,
+): string[] {
+	return resolvePluginConfigSearchPathsFromShared(workspacePath);
+}
+
+function hasPluginModuleExtension(path: string): boolean {
+	const dot = path.lastIndexOf(".");
+	if (dot === -1) {
+		return false;
+	}
+	return PLUGIN_MODULE_EXTENSIONS.has(path.slice(dot));
+}
+
+export function discoverPluginModulePaths(directoryPath: string): string[] {
+	const root = resolve(directoryPath);
+	if (!existsSync(root)) {
+		return [];
+	}
+	const discovered: string[] = [];
+	const stack = [root];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (!current) {
+			continue;
+		}
+		for (const entry of readdirSync(current, { withFileTypes: true })) {
+			const candidate = join(current, entry.name);
+			if (entry.isDirectory()) {
+				stack.push(candidate);
+				continue;
+			}
+			if (entry.isFile() && hasPluginModuleExtension(candidate)) {
+				discovered.push(candidate);
+			}
+		}
+	}
+	return discovered.sort((a, b) => a.localeCompare(b));
+}
+
+function resolveConfiguredPluginPaths(
+	pluginPaths: ReadonlyArray<string>,
+	cwd: string,
+): string[] {
+	const resolvedPaths: string[] = [];
+	for (const pluginPath of pluginPaths) {
+		const trimmed = pluginPath.trim();
+		if (!trimmed) {
+			continue;
+		}
+		const absolutePath = resolve(cwd, trimmed);
+		if (!existsSync(absolutePath)) {
+			throw new Error(`Plugin path does not exist: ${absolutePath}`);
+		}
+		const stats = statSync(absolutePath);
+		if (stats.isDirectory()) {
+			resolvedPaths.push(...discoverPluginModulePaths(absolutePath));
+			continue;
+		}
+		if (!hasPluginModuleExtension(absolutePath)) {
+			throw new Error(
+				`Plugin file must use a supported extension (${[...PLUGIN_MODULE_EXTENSIONS].join(", ")}): ${absolutePath}`,
+			);
+		}
+		resolvedPaths.push(absolutePath);
+	}
+	return resolvedPaths;
+}
+
+export interface ResolveAgentPluginPathsOptions {
+	pluginPaths?: ReadonlyArray<string>;
+	workspacePath?: string;
+	cwd?: string;
+}
+
+export function resolveAgentPluginPaths(
+	options: ResolveAgentPluginPathsOptions = {},
+): string[] {
+	const cwd = options.cwd ?? process.cwd();
+	const discoveredFromSearchPaths = resolvePluginConfigSearchPaths(
+		options.workspacePath,
+	)
+		.flatMap((directoryPath) => discoverPluginModulePaths(directoryPath))
+		.filter((path) => existsSync(path));
+	const configuredPaths = resolveConfiguredPluginPaths(
+		options.pluginPaths ?? [],
+		cwd,
+	);
+
+	const deduped: string[] = [];
+	const seen = new Set<string>();
+	for (const path of [...configuredPaths, ...discoveredFromSearchPaths]) {
+		if (seen.has(path)) {
+			continue;
+		}
+		seen.add(path);
+		deduped.push(path);
+	}
+	return deduped;
+}
+
+export interface ResolveAndLoadAgentPluginsOptions
+	extends ResolveAgentPluginPathsOptions {
+	mode?: "sandbox" | "in_process";
+	exportName?: string;
+	importTimeoutMs?: number;
+	hookTimeoutMs?: number;
+	contributionTimeoutMs?: number;
+}
+
+export async function resolveAndLoadAgentPlugins(
+	options: ResolveAndLoadAgentPluginsOptions = {},
+): Promise<{
+	extensions: AgentPlugin[];
+	shutdown?: () => Promise<void>;
+}> {
+	const paths = resolveAgentPluginPaths(options);
+	if (paths.length === 0) {
+		return { extensions: [] };
+	}
+
+	if (options.mode === "in_process") {
+		return {
+			extensions: await loadAgentPluginsFromPaths(paths, {
+				cwd: options.cwd,
+				exportName: options.exportName,
+			}),
+		};
+	}
+
+	const sandboxed = await loadSandboxedPlugins({
+		pluginPaths: paths,
+		exportName: options.exportName,
+		importTimeoutMs: options.importTimeoutMs,
+		hookTimeoutMs: options.hookTimeoutMs,
+		contributionTimeoutMs: options.contributionTimeoutMs,
+	});
+	return {
+		extensions: sandboxed.extensions ?? [],
+		shutdown: sandboxed.shutdown,
+	};
+}