@clinebot/core 0.0.0

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.js";
+
+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.js";
+
+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,
+	};
+}

package/src/auth/cline.test.ts

@@ -0,0 +1,130 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ClineOAuthCredentials } from "./cline.js";
+import { getValidClineCredentials } from "./cline.js";
+
+const PROVIDER_OPTIONS = {
+	apiBaseUrl: "https://auth.example.com",
+};
+
+function createCredentials(
+	overrides: Partial<ClineOAuthCredentials> = {},
+): ClineOAuthCredentials {
+	return {
+		access: "access-old",
+		refresh: "refresh-old",
+		expires: 0,
+		accountId: "acct-1",
+		email: "user@example.com",
+		metadata: { provider: "google" },
+		...overrides,
+	};
+}
+
+describe("auth/cline getValidClineCredentials", () => {
+	afterEach(() => {
+		vi.unstubAllGlobals();
+		vi.restoreAllMocks();
+	});
+
+	it("returns existing credentials when not expired", async () => {
+		const nowSpy = vi.spyOn(Date, "now").mockReturnValue(10_000);
+		const current = createCredentials({ expires: 400_000 });
+		const fetchMock = vi.fn();
+		vi.stubGlobal("fetch", fetchMock);
+
+		const result = await getValidClineCredentials(current, PROVIDER_OPTIONS);
+		expect(result).toBe(current);
+		expect(fetchMock).not.toHaveBeenCalled();
+		nowSpy.mockRestore();
+	});
+
+	it("refreshes expired credentials", async () => {
+		const nowSpy = vi.spyOn(Date, "now").mockReturnValue(100_000);
+		const current = createCredentials({ expires: 101_000 });
+		const fetchMock = vi.fn(
+			async () =>
+				new Response(
+					JSON.stringify({
+						success: true,
+						data: {
+							accessToken: "access-new",
+							refreshToken: "refresh-new",
+							tokenType: "Bearer",
+							expiresAt: "2030-01-01T00:00:00.000Z",
+							userInfo: {
+								subject: "sub-1",
+								email: "new@example.com",
+								name: "New User",
+								clineUserId: "acct-2",
+								accounts: [],
+							},
+						},
+					}),
+					{ status: 200, headers: { "Content-Type": "application/json" } },
+				),
+		);
+		vi.stubGlobal("fetch", fetchMock);
+
+		const result = await getValidClineCredentials(current, PROVIDER_OPTIONS);
+		expect(result).toMatchObject({
+			access: "access-new",
+			refresh: "refresh-new",
+			accountId: "acct-2",
+			email: "new@example.com",
+		});
+		nowSpy.mockRestore();
+	});
+
+	it("returns null when refresh fails with invalid_grant", async () => {
+		const nowSpy = vi.spyOn(Date, "now").mockReturnValue(100_000);
+		const current = createCredentials({ expires: 101_000 });
+		vi.stubGlobal(
+			"fetch",
+			vi.fn(
+				async () =>
+					new Response(
+						JSON.stringify({
+							error: "invalid_grant",
+							error_description: "refresh expired",
+						}),
+						{
+							status: 401,
+							headers: { "Content-Type": "application/json" },
+						},
+					),
+			),
+		);
+
+		const result = await getValidClineCredentials(current, PROVIDER_OPTIONS);
+		expect(result).toBeNull();
+		nowSpy.mockRestore();
+	});
+
+	it("keeps current credentials on transient refresh error while token remains valid", async () => {
+		const nowSpy = vi.spyOn(Date, "now").mockReturnValue(100_000);
+		const current = createCredentials({ expires: 150_000 });
+		vi.stubGlobal(
+			"fetch",
+			vi.fn(
+				async () =>
+					new Response(
+						JSON.stringify({
+							error: "server_error",
+							error_description: "temporary issue",
+						}),
+						{
+							status: 500,
+							headers: { "Content-Type": "application/json" },
+						},
+					),
+			),
+		);
+
+		const result = await getValidClineCredentials(current, PROVIDER_OPTIONS, {
+			refreshBufferMs: 60_000,
+			retryableTokenGraceMs: 30_000,
+		});
+		expect(result).toBe(current);
+		nowSpy.mockRestore();
+	});
+});