@clinebot/core 0.0.22 → 0.0.23

package/src/agents/user-instruction-config-loader.test.ts

@@ -0,0 +1,158 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	createUserInstructionConfigWatcher,
+	parseRuleConfigFromMarkdown,
+	parseSkillConfigFromMarkdown,
+	parseWorkflowConfigFromMarkdown,
+	resolveRulesConfigSearchPaths,
+	resolveSkillsConfigSearchPaths,
+	resolveWorkflowsConfigSearchPaths,
+	type UserInstructionConfigWatcherEvent,
+} from "./user-instruction-config-loader";
+
+const WAIT_TIMEOUT_MS = 4_000;
+const WAIT_INTERVAL_MS = 25;
+
+async function waitForEvent(
+	events: Array<UserInstructionConfigWatcherEvent>,
+	predicate: (event: UserInstructionConfigWatcherEvent) => boolean,
+	timeoutMs = WAIT_TIMEOUT_MS,
+): Promise<UserInstructionConfigWatcherEvent> {
+	const startedAt = Date.now();
+	while (Date.now() - startedAt < timeoutMs) {
+		const match = events.find(predicate);
+		if (match) {
+			return match;
+		}
+		await new Promise((resolve) => setTimeout(resolve, WAIT_INTERVAL_MS));
+	}
+	throw new Error("Timed out waiting for watcher event.");
+}
+
+describe("user instruction config loader", () => {
+	const tempRoots: string[] = [];
+
+	afterEach(async () => {
+		await Promise.all(
+			tempRoots.map((dir) => rm(dir, { recursive: true, force: true })),
+		);
+		tempRoots.length = 0;
+	});
+
+	it("resolves legacy-compatible default search paths", () => {
+		const workspacePath = "/repo/demo";
+		expect(resolveSkillsConfigSearchPaths(workspacePath)).toEqual(
+			expect.arrayContaining([
+				join(workspacePath, ".clinerules", "skills"),
+				join(workspacePath, ".cline", "skills"),
+				join(workspacePath, ".claude", "skills"),
+				join(workspacePath, ".agents", "skills"),
+			]),
+		);
+		expect(resolveRulesConfigSearchPaths(workspacePath)).toEqual(
+			expect.arrayContaining([join(workspacePath, ".clinerules")]),
+		);
+		expect(resolveWorkflowsConfigSearchPaths(workspacePath)).toEqual(
+			expect.arrayContaining([join(workspacePath, ".clinerules", "workflows")]),
+		);
+	});
+
+	it("parses markdown frontmatter for skill, rule, and workflow configs", () => {
+		const skill = parseSkillConfigFromMarkdown(
+			`---
+name: debugging
+description: Use structured debugging
+disabled: true
+---
+Follow the debugging checklist.`,
+			"fallback",
+		);
+		expect(skill.name).toBe("debugging");
+		expect(skill.description).toBe("Use structured debugging");
+		expect(skill.disabled).toBe(true);
+		expect(skill.instructions).toBe("Follow the debugging checklist.");
+
+		const rule = parseRuleConfigFromMarkdown(
+			`---
+name: rule-a
+disabled: true
+---
+Always run tests before merge.`,
+			"rule-a",
+		);
+		expect(rule.name).toBe("rule-a");
+		expect(rule.disabled).toBe(true);
+
+		const workflow = parseWorkflowConfigFromMarkdown(
+			`---
+name: release
+disabled: true
+---
+Document rollout and rollback steps.`,
+			"release",
+		);
+		expect(workflow.name).toBe("release");
+		expect(workflow.disabled).toBe(true);
+	});
+
+	it("emits typed events for skills, rules, and workflows in one watcher", async () => {
+		const tempRoot = await mkdtemp(
+			join(tmpdir(), "core-user-instructions-loader-"),
+		);
+		tempRoots.push(tempRoot);
+		const skillsDir = join(tempRoot, "skills");
+		const rulesDir = join(tempRoot, "rules");
+		const workflowsDir = join(tempRoot, "workflows");
+		await mkdir(join(skillsDir, "incident-response"), { recursive: true });
+		await mkdir(rulesDir, { recursive: true });
+		await mkdir(workflowsDir, { recursive: true });
+
+		await writeFile(
+			join(skillsDir, "incident-response", "SKILL.md"),
+			`---
+name: incident-response
+description: Handle incidents fast
+---
+Escalation runbook`,
+		);
+		await writeFile(
+			join(rulesDir, "default.md"),
+			"Keep changes minimal and tested.",
+		);
+		await writeFile(
+			join(workflowsDir, "release.md"),
+			"Ship with release checklist.",
+		);
+
+		const watcher = createUserInstructionConfigWatcher({
+			skills: { directories: [skillsDir] },
+			rules: { directories: [rulesDir] },
+			workflows: { directories: [workflowsDir] },
+		});
+
+		const events: Array<UserInstructionConfigWatcherEvent> = [];
+		const unsubscribe = watcher.subscribe((event) => events.push(event));
+
+		try {
+			await watcher.start();
+			await waitForEvent(
+				events,
+				(event) => event.kind === "upsert" && event.record.type === "skill",
+			);
+			await waitForEvent(
+				events,
+				(event) => event.kind === "upsert" && event.record.type === "rule",
+			);
+			await waitForEvent(
+				events,
+				(event) => event.kind === "upsert" && event.record.type === "workflow",
+			);
+		} finally {
+			unsubscribe();
+			watcher.stop();
+		}
+	});
+});

package/src/agents/user-instruction-config-loader.ts

@@ -0,0 +1,438 @@
+import { readdir, stat } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+import {
+	RULES_CONFIG_DIRECTORY_NAME,
+	resolveDocumentsRulesDirectoryPath,
+	resolveDocumentsWorkflowsDirectoryPath,
+	resolveRulesConfigSearchPaths as resolveRulesConfigSearchPathsFromShared,
+	resolveSkillsConfigSearchPaths as resolveSkillsConfigSearchPathsFromShared,
+	resolveWorkflowsConfigSearchPaths as resolveWorkflowsConfigSearchPathsFromShared,
+	SKILLS_CONFIG_DIRECTORY_NAME,
+	WORKFLOWS_CONFIG_DIRECTORY_NAME,
+} from "@clinebot/shared/storage";
+import YAML from "yaml";
+import {
+	type UnifiedConfigDefinition,
+	type UnifiedConfigFileCandidate,
+	UnifiedConfigFileWatcher,
+	type UnifiedConfigWatcherEvent,
+} from "./unified-config-file-watcher";
+
+const SKILL_FILE_NAME = "SKILL.md";
+
+const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".txt"]);
+
+export {
+	RULES_CONFIG_DIRECTORY_NAME,
+	resolveDocumentsRulesDirectoryPath,
+	resolveDocumentsWorkflowsDirectoryPath,
+	SKILLS_CONFIG_DIRECTORY_NAME,
+	WORKFLOWS_CONFIG_DIRECTORY_NAME,
+};
+
+export interface ParseMarkdownFrontmatterResult {
+	data: Record<string, unknown>;
+	body: string;
+	hadFrontmatter: boolean;
+	parseError?: string;
+}
+
+export interface SkillConfig {
+	name: string;
+	description?: string;
+	disabled?: boolean;
+	instructions: string;
+	frontmatter: Record<string, unknown>;
+}
+
+export interface RuleConfig {
+	name: string;
+	disabled?: boolean;
+	instructions: string;
+	frontmatter: Record<string, unknown>;
+}
+
+export interface WorkflowConfig {
+	name: string;
+	disabled?: boolean;
+	instructions: string;
+	frontmatter: Record<string, unknown>;
+}
+
+export type UserInstructionConfigType = "skill" | "rule" | "workflow";
+
+export type UserInstructionConfig = SkillConfig | RuleConfig | WorkflowConfig;
+
+export type UserInstructionConfigWatcher = UnifiedConfigFileWatcher<
+	UserInstructionConfigType,
+	UserInstructionConfig
+>;
+
+export type UserInstructionConfigWatcherEvent = UnifiedConfigWatcherEvent<
+	UserInstructionConfigType,
+	UserInstructionConfig
+>;
+
+export interface CreateInstructionWatcherOptions {
+	debounceMs?: number;
+	emitParseErrors?: boolean;
+}
+
+export interface CreateSkillsConfigDefinitionOptions {
+	directories?: ReadonlyArray<string>;
+	workspacePath?: string;
+}
+
+export interface CreateRulesConfigDefinitionOptions {
+	directories?: ReadonlyArray<string>;
+	workspacePath?: string;
+}
+
+export interface CreateWorkflowsConfigDefinitionOptions {
+	directories?: ReadonlyArray<string>;
+	workspacePath?: string;
+}
+
+function normalizeName(name: string): string {
+	return name.trim().toLowerCase();
+}
+
+function isMarkdownFile(fileName: string): boolean {
+	return MARKDOWN_EXTENSIONS.has(extname(fileName).toLowerCase());
+}
+
+function parseMarkdownFrontmatter(
+	content: string,
+): ParseMarkdownFrontmatterResult {
+	const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+	const match = content.match(frontmatterRegex);
+	if (!match) {
+		return { data: {}, body: content, 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: content,
+			hadFrontmatter: true,
+			parseError: message,
+		};
+	}
+}
+
+function parseStringField(
+	value: unknown,
+	fieldName: string,
+	isRequired: boolean,
+): string | undefined {
+	if (value === undefined || value === null) {
+		if (isRequired) {
+			throw new Error(`Missing required frontmatter field '${fieldName}'.`);
+		}
+		return undefined;
+	}
+	if (typeof value !== "string") {
+		throw new Error(`Frontmatter field '${fieldName}' must be a string.`);
+	}
+	const normalized = value.trim();
+	if (!normalized && isRequired) {
+		throw new Error(`Frontmatter field '${fieldName}' cannot be empty.`);
+	}
+	return normalized || undefined;
+}
+
+function parseBooleanField(
+	value: unknown,
+	fieldName: string,
+): boolean | undefined {
+	if (value === undefined || value === null) {
+		return undefined;
+	}
+	if (typeof value !== "boolean") {
+		throw new Error(`Frontmatter field '${fieldName}' must be a boolean.`);
+	}
+	return value;
+}
+
+export function parseSkillConfigFromMarkdown(
+	content: string,
+	fallbackName: string,
+): SkillConfig {
+	const { data, body, parseError } = parseMarkdownFrontmatter(content);
+	if (parseError) {
+		throw new Error(`Failed to parse YAML frontmatter: ${parseError}`);
+	}
+	const instructions = body.trim();
+	if (!instructions) {
+		throw new Error("Missing instructions body in skill file.");
+	}
+	const parsedName = parseStringField(data.name, "name", false);
+	const name = parsedName ?? fallbackName.trim();
+	if (!name) {
+		throw new Error("Missing skill name.");
+	}
+
+	return {
+		name,
+		description: parseStringField(data.description, "description", false),
+		disabled:
+			parseBooleanField(data.disabled, "disabled") ??
+			(parseBooleanField(data.enabled, "enabled") === false ? true : undefined),
+		instructions,
+		frontmatter: data,
+	};
+}
+
+export function parseRuleConfigFromMarkdown(
+	content: string,
+	fallbackName: string,
+): RuleConfig {
+	const { data, body, parseError } = parseMarkdownFrontmatter(content);
+	if (parseError) {
+		throw new Error(`Failed to parse YAML frontmatter: ${parseError}`);
+	}
+	const instructions = body.trim();
+	if (!instructions) {
+		throw new Error("Missing instructions body in rule file.");
+	}
+	const name =
+		parseStringField(data.name, "name", false) ?? fallbackName.trim();
+	if (!name) {
+		throw new Error("Missing rule name.");
+	}
+	return {
+		name,
+		disabled:
+			parseBooleanField(data.disabled, "disabled") ??
+			(parseBooleanField(data.enabled, "enabled") === false ? true : undefined),
+		instructions,
+		frontmatter: data,
+	};
+}
+
+export function parseWorkflowConfigFromMarkdown(
+	content: string,
+	fallbackName: string,
+): WorkflowConfig {
+	const { data, body, parseError } = parseMarkdownFrontmatter(content);
+	if (parseError) {
+		throw new Error(`Failed to parse YAML frontmatter: ${parseError}`);
+	}
+	const instructions = body.trim();
+	if (!instructions) {
+		throw new Error("Missing instructions body in workflow file.");
+	}
+	const name =
+		parseStringField(data.name, "name", false) ?? fallbackName.trim();
+	if (!name) {
+		throw new Error("Missing workflow name.");
+	}
+	return {
+		name,
+		disabled:
+			parseBooleanField(data.disabled, "disabled") ??
+			(parseBooleanField(data.enabled, "enabled") === false ? true : undefined),
+		instructions,
+		frontmatter: data,
+	};
+}
+
+export function resolveSkillsConfigSearchPaths(
+	workspacePath?: string,
+): string[] {
+	return resolveSkillsConfigSearchPathsFromShared(workspacePath);
+}
+
+export function resolveRulesConfigSearchPaths(
+	workspacePath?: string,
+): string[] {
+	return resolveRulesConfigSearchPathsFromShared(workspacePath);
+}
+
+export function resolveWorkflowsConfigSearchPaths(
+	workspacePath?: string,
+): string[] {
+	return resolveWorkflowsConfigSearchPathsFromShared(workspacePath);
+}
+
+async function discoverSkillFiles(
+	directoryPath: string,
+): Promise<ReadonlyArray<UnifiedConfigFileCandidate>> {
+	try {
+		const entries = await readdir(directoryPath, { withFileTypes: true });
+		const candidates: UnifiedConfigFileCandidate[] = [];
+		for (const entry of entries) {
+			if (entry.isFile() && entry.name === SKILL_FILE_NAME) {
+				candidates.push({
+					directoryPath,
+					fileName: entry.name,
+					filePath: join(directoryPath, entry.name),
+				});
+				continue;
+			}
+			if (entry.isDirectory()) {
+				candidates.push({
+					directoryPath: join(directoryPath, entry.name),
+					fileName: SKILL_FILE_NAME,
+					filePath: join(directoryPath, entry.name, SKILL_FILE_NAME),
+				});
+			}
+		}
+		return candidates;
+	} catch (error) {
+		const nodeError = error as NodeJS.ErrnoException;
+		if (nodeError.code === "ENOENT") {
+			return [];
+		}
+		throw error;
+	}
+}
+
+async function discoverRulesLikeFiles(
+	directoryPath: string,
+): Promise<ReadonlyArray<UnifiedConfigFileCandidate>> {
+	try {
+		const entryStat = await stat(directoryPath);
+		if (entryStat.isFile()) {
+			return [
+				{
+					directoryPath: dirname(directoryPath),
+					fileName: basename(directoryPath),
+					filePath: directoryPath,
+				},
+			];
+		}
+	} catch (error) {
+		const nodeError = error as NodeJS.ErrnoException;
+		if (nodeError.code !== "ENOENT") {
+			throw error;
+		}
+	}
+
+	try {
+		const entries = await readdir(directoryPath, { withFileTypes: true });
+		return entries
+			.filter((entry) => entry.isFile() && isMarkdownFile(entry.name))
+			.map((entry) => ({
+				directoryPath,
+				fileName: entry.name,
+				filePath: join(directoryPath, entry.name),
+			}));
+	} catch (error) {
+		const nodeError = error as NodeJS.ErrnoException;
+		if (nodeError.code === "ENOENT") {
+			return [];
+		}
+		throw error;
+	}
+}
+
+export function createSkillsConfigDefinition(
+	options?: CreateSkillsConfigDefinitionOptions,
+): UnifiedConfigDefinition<"skill", SkillConfig> {
+	const directories =
+		options?.directories ??
+		resolveSkillsConfigSearchPaths(options?.workspacePath);
+
+	return {
+		type: "skill",
+		directories,
+		discoverFiles: discoverSkillFiles,
+		includeFile: (fileName) => fileName === SKILL_FILE_NAME,
+		parseFile: (context) =>
+			parseSkillConfigFromMarkdown(
+				context.content,
+				basename(context.directoryPath),
+			),
+		resolveId: (skill) => normalizeName(skill.name),
+	};
+}
+
+export function createRulesConfigDefinition(
+	options?: CreateRulesConfigDefinitionOptions,
+): UnifiedConfigDefinition<"rule", RuleConfig> {
+	const directories =
+		options?.directories ??
+		resolveRulesConfigSearchPaths(options?.workspacePath);
+
+	return {
+		type: "rule",
+		directories,
+		discoverFiles: discoverRulesLikeFiles,
+		includeFile: (fileName, filePath) =>
+			fileName === ".clinerules" ||
+			isMarkdownFile(fileName) ||
+			isMarkdownFile(filePath),
+		parseFile: (context) =>
+			parseRuleConfigFromMarkdown(
+				context.content,
+				basename(context.filePath, extname(context.filePath)),
+			),
+		resolveId: (rule) => normalizeName(rule.name),
+	};
+}
+
+export function createWorkflowsConfigDefinition(
+	options?: CreateWorkflowsConfigDefinitionOptions,
+): UnifiedConfigDefinition<"workflow", WorkflowConfig> {
+	const directories =
+		options?.directories ??
+		resolveWorkflowsConfigSearchPaths(options?.workspacePath);
+
+	return {
+		type: "workflow",
+		directories,
+		discoverFiles: discoverRulesLikeFiles,
+		includeFile: (fileName) => isMarkdownFile(fileName),
+		parseFile: (context) =>
+			parseWorkflowConfigFromMarkdown(
+				context.content,
+				basename(context.filePath, extname(context.filePath)),
+			),
+		resolveId: (workflow) => normalizeName(workflow.name),
+	};
+}
+
+export interface CreateUserInstructionConfigWatcherOptions
+	extends CreateInstructionWatcherOptions {
+	skills?: CreateSkillsConfigDefinitionOptions;
+	rules?: CreateRulesConfigDefinitionOptions;
+	workflows?: CreateWorkflowsConfigDefinitionOptions;
+}
+
+export function createUserInstructionConfigWatcher(
+	options?: CreateUserInstructionConfigWatcherOptions,
+): UserInstructionConfigWatcher {
+	const definitions: ReadonlyArray<
+		UnifiedConfigDefinition<UserInstructionConfigType, UserInstructionConfig>
+	> = [
+		createSkillsConfigDefinition(options?.skills) as UnifiedConfigDefinition<
+			UserInstructionConfigType,
+			UserInstructionConfig
+		>,
+		createRulesConfigDefinition(options?.rules) as UnifiedConfigDefinition<
+			UserInstructionConfigType,
+			UserInstructionConfig
+		>,
+		createWorkflowsConfigDefinition(
+			options?.workflows,
+		) as UnifiedConfigDefinition<
+			UserInstructionConfigType,
+			UserInstructionConfig
+		>,
+	];
+
+	return new UnifiedConfigFileWatcher(definitions, {
+		debounceMs: options?.debounceMs,
+		emitParseErrors: options?.emitParseErrors,
+	});
+}

package/src/auth/client.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it, vi } from "vitest";
+import { createOAuthClientCallbacks } from "./client";
+
+describe("auth/client createOAuthClientCallbacks", () => {
+	it("emits instructions and URL and forwards prompts", async () => {
+		const onOutput = vi.fn();
+		const onPrompt = vi.fn().mockResolvedValue("value");
+		const callbacks = createOAuthClientCallbacks({ onOutput, onPrompt });
+
+		callbacks.onAuth({
+			url: "https://example.com/auth",
+			instructions: "Open your browser",
+		});
+		const answer = await callbacks.onPrompt({ message: "Enter code" });
+
+		expect(answer).toBe("value");
+		expect(onPrompt).toHaveBeenCalledWith({ message: "Enter code" });
+		expect(onOutput).toHaveBeenNthCalledWith(1, "Open your browser");
+		expect(onOutput).toHaveBeenNthCalledWith(2, "https://example.com/auth");
+	});
+
+	it("tries opening URL and reports opener errors", async () => {
+		const openUrl = vi.fn().mockRejectedValue(new Error("failed"));
+		const onOpenUrlError = vi.fn();
+		const callbacks = createOAuthClientCallbacks({
+			onPrompt: vi.fn().mockResolvedValue(""),
+			openUrl,
+			onOpenUrlError,
+		});
+
+		callbacks.onAuth({ url: "https://example.com/auth" });
+		await Promise.resolve();
+
+		expect(openUrl).toHaveBeenCalledWith("https://example.com/auth");
+		expect(onOpenUrlError).toHaveBeenCalledTimes(1);
+		expect(onOpenUrlError.mock.calls[0]?.[0]).toMatchObject({
+			url: "https://example.com/auth",
+		});
+	});
+});

package/src/auth/client.ts

@@ -0,0 +1,25 @@
+import type { OAuthLoginCallbacks, OAuthPrompt } from "./types";
+
+export interface OAuthClientCallbacksOptions {
+	onPrompt: (prompt: OAuthPrompt) => Promise<string>;
+	onOutput?: (message: string) => void;
+	openUrl?: (url: string) => void | Promise<void>;
+	onOpenUrlError?: (context: { url: string; error: unknown }) => void;
+}
+
+export function createOAuthClientCallbacks(
+	options: OAuthClientCallbacksOptions,
+): OAuthLoginCallbacks {
+	return {
+		onAuth: ({ url, instructions }) => {
+			options.onOutput?.(instructions ?? "Complete sign-in in your browser.");
+			if (options.openUrl) {
+				void Promise.resolve(options.openUrl(url)).catch((error) => {
+					options.onOpenUrlError?.({ url, error });
+				});
+			}
+			options.onOutput?.(url);
+		},
+		onPrompt: options.onPrompt,
+	};
+}