@clinebot/core 0.0.27 → 0.0.29

package/src/{agents → extensions/plugin}/plugin-config-loader.test.ts

@@ -24,17 +24,17 @@ describe("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(root, "a.js"), "export default {}", "utf8");
 			await writeFile(join(nested, "b.ts"), "export default {}", "utf8");
 			await writeFile(
-				join(root, ".a.mjs.cline-plugin.mjs"),
+				join(root, ".a.js.cline-plugin.js"),
 				"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")]);
+			expect(discovered).toEqual([join(root, "a.js"), join(nested, "b.ts")]);
 		} finally {
 			await rm(root, { recursive: true, force: true });
 		}
@@ -47,13 +47,13 @@ describe("plugin-config-loader", () => {
 			setHomeDir(root);
 			const pluginsDir = join(root, "plugins");
 			await mkdir(pluginsDir, { recursive: true });
-			const filePath = join(root, "direct.mjs");
-			const dirPluginPath = join(pluginsDir, "dir-plugin.mjs");
+			const filePath = join(root, "direct.js");
+			const dirPluginPath = join(pluginsDir, "dir-plugin.js");
 			await writeFile(filePath, "export default {}", "utf8");
 			await writeFile(dirPluginPath, "export default {}", "utf8");
 
 			const resolved = resolveAgentPluginPaths({
-				pluginPaths: ["./direct.mjs", "./plugins"],
+				pluginPaths: ["./direct.js", "./plugins"],
 				workspacePath: join(root, "workspace"),
 				cwd: root,
 			});
@@ -71,14 +71,19 @@ describe("plugin-config-loader", () => {
 			const srcDir = join(pluginDir, "src");
 			await mkdir(srcDir, { recursive: true });
 			const declaredEntry = join(srcDir, "index.ts");
-			const ignoredEntry = join(pluginDir, "ignored.mjs");
+			const ignoredEntry = join(pluginDir, "ignored.js");
 			await writeFile(
 				join(pluginDir, "package.json"),
 				JSON.stringify({
 					name: "plugin-package",
 					private: true,
 					cline: {
-						plugins: ["./src/index.ts"],
+						plugins: [
+							{
+								paths: ["./src/index.ts"],
+								capabilities: ["tools"],
+							},
+						],
 					},
 				}),
 				"utf8",
@@ -109,15 +114,15 @@ describe("plugin-config-loader", () => {
 		try {
 			process.env.HOME = home;
 			setHomeDir(home);
-			const workspacePlugins = join(workspace, ".clinerules", "plugins");
+			const workspacePlugins = join(workspace, ".cline", "plugins");
 			const userPlugins = join(home, ".cline", "plugins");
-			const documentsPlugins = join(home, "Documents", "Plugins");
+			const documentsPlugins = join(home, "Documents", "Cline", "Plugins");
 			await mkdir(workspacePlugins, { recursive: true });
 			await mkdir(userPlugins, { recursive: true });
 			await mkdir(documentsPlugins, { recursive: true });
-			const workspacePlugin = join(workspacePlugins, "workspace.mjs");
-			const userPlugin = join(userPlugins, "user.mjs");
-			const documentsPlugin = join(documentsPlugins, "documents.mjs");
+			const workspacePlugin = join(workspacePlugins, "workspace.js");
+			const userPlugin = join(userPlugins, "user.js");
+			const documentsPlugin = join(documentsPlugins, "documents.js");
 			await writeFile(workspacePlugin, "export default {}", "utf8");
 			await writeFile(userPlugin, "export default {}", "utf8");
 			await writeFile(documentsPlugin, "export default {}", "utf8");

package/src/{agents → extensions/plugin}/plugin-config-loader.ts

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import type { AgentConfig } from "@clinebot/agents";
+import type { AgentConfig } from "@clinebot/shared";
 import {
 	discoverPluginModulePaths as discoverPluginModulePathsFromShared,
 	resolveConfiguredPluginModulePaths,

package/src/{agents → extensions/plugin}/plugin-loader.test.ts

@@ -117,10 +117,36 @@ describe("plugin-loader", () => {
 		await writeFile(
 			join(copyDir, "portable-subagents.ts"),
 			[
+				"import { safeJsonStringify } from '@clinebot/shared';",
 				"import { resolveClineDataDir } from '@clinebot/shared/storage';",
 				"import YAML from 'yaml';",
 				"export default {",
-				"  name: typeof resolveClineDataDir === 'function' ? YAML.stringify({ ok: true }) : 'invalid',",
+				"  name: typeof safeJsonStringify === 'function' ? YAML.stringify({ ok: !!resolveClineDataDir() }) : 'invalid',",
+				"  manifest: { capabilities: ['tools'] },",
+				"};",
+			].join("\n"),
+			"utf8",
+		);
+
+		const packagedCopyDir = join(copyDir, "packaged-plugin");
+		await mkdir(packagedCopyDir, { recursive: true });
+		await writeFile(
+			join(packagedCopyDir, "package.json"),
+			JSON.stringify({
+				name: "packaged-plugin",
+				type: "module",
+				cline: {
+					plugins: ["index.ts"],
+				},
+			}),
+			"utf8",
+		);
+		await writeFile(
+			join(packagedCopyDir, "index.ts"),
+			[
+				"import YAML from 'yaml';",
+				"export default {",
+				"  name: YAML.stringify({ ok: true }),",
 				"  manifest: { capabilities: ['tools'] },",
 				"};",
 			].join("\n"),
@@ -193,11 +219,22 @@ describe("plugin-loader", () => {
 		expect(plugin.name).toBe("plugin-installed-sdk");
 	});
 
-	it("requires copied plugins to provide their own non-SDK dependencies", async () => {
-		await expect(
-			loadAgentPluginFromPath(join(copyDir, "portable-subagents.ts"), {
+	it("allows standalone file plugins to use host runtime dependencies", async () => {
+		const plugin = await loadAgentPluginFromPath(
+			join(copyDir, "portable-subagents.ts"),
+			{
 				cwd: copyDir,
 				useCache: true,
+			},
+		);
+		expect(plugin.name).toMatch(/ok: true/i);
+	});
+
+	it("requires package-based plugins to provide their own non-SDK dependencies", async () => {
+		await expect(
+			loadAgentPluginFromPath(join(copyDir, "packaged-plugin", "index.ts"), {
+				cwd: join(copyDir, "packaged-plugin"),
+				useCache: true,
 			}),
 		).rejects.toThrow(/Cannot find (package|module) 'yaml'/i);
 	});

package/src/extensions/plugin/plugin-loader.ts

@@ -0,0 +1,106 @@
+import { resolve } from "node:path";
+import type { AgentConfig } from "@clinebot/shared";
+import { importPluginModule } from "./plugin-module-import";
+
+type AgentPlugin = NonNullable<AgentConfig["extensions"]>[number];
+type PluginLike = {
+	name: string;
+	manifest: {
+		capabilities: string[];
+		hookStages?: string[];
+	};
+};
+
+export interface LoadAgentPluginFromPathOptions {
+	exportName?: string;
+	cwd?: string;
+	useCache?: boolean;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function hasValidStringArray(value: unknown): value is string[] {
+	return (
+		Array.isArray(value) && value.every((entry) => typeof entry === "string")
+	);
+}
+
+function validatePluginManifest(
+	plugin: PluginLike,
+	absolutePath: string,
+): void {
+	if (!isObject(plugin.manifest)) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: missing required "manifest"`,
+		);
+	}
+	if (!hasValidStringArray(plugin.manifest.capabilities)) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: manifest.capabilities must be a string array`,
+		);
+	}
+	if (plugin.manifest.capabilities.length === 0) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: manifest.capabilities cannot be empty`,
+		);
+	}
+	if (
+		Object.hasOwn(plugin.manifest, "hookStages") &&
+		!hasValidStringArray(plugin.manifest.hookStages)
+	) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: manifest.hookStages must be a string array when provided`,
+		);
+	}
+}
+
+function validatePluginExport(
+	plugin: unknown,
+	absolutePath: string,
+): asserts plugin is PluginLike {
+	if (!isObject(plugin)) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: expected object export`,
+		);
+	}
+	if (typeof plugin.name !== "string" || plugin.name.length === 0) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: expected non-empty "name"`,
+		);
+	}
+	if (!Object.hasOwn(plugin, "manifest")) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: missing required "manifest"`,
+		);
+	}
+	validatePluginManifest(plugin as PluginLike, absolutePath);
+}
+
+export async function loadAgentPluginFromPath(
+	pluginPath: string,
+	options: LoadAgentPluginFromPathOptions = {},
+): Promise<AgentPlugin> {
+	const absolutePath = resolve(options.cwd ?? process.cwd(), pluginPath);
+	const moduleExports = await importPluginModule(absolutePath, {
+		useCache: options.useCache,
+	});
+	const exportName = options.exportName ?? "plugin";
+	const plugin = (moduleExports.default ??
+		moduleExports[exportName]) as unknown;
+
+	validatePluginExport(plugin, absolutePath);
+	return plugin as AgentPlugin;
+}
+
+export async function loadAgentPluginsFromPaths(
+	pluginPaths: string[],
+	options: LoadAgentPluginFromPathOptions = {},
+): Promise<AgentPlugin[]> {
+	const loaded: AgentPlugin[] = [];
+	for (const pluginPath of pluginPaths) {
+		loaded.push(await loadAgentPluginFromPath(pluginPath, options));
+	}
+	return loaded;
+}

package/src/extensions/plugin/plugin-module-import.ts

@@ -0,0 +1,278 @@
+import { existsSync, readFileSync } from "node:fs";
+import { builtinModules, createRequire } from "node:module";
+import { dirname, extname, isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PLUGIN_FILE_EXTENSIONS } from "@clinebot/shared";
+import createJiti from "jiti";
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const HOST_REQUIRE = createRequire(import.meta.url);
+// `plugin-module-import.ts` lives at `packages/core/src/extensions/plugin`, so
+// walking up five levels lands at the repo root.
+const WORKSPACE_ROOT = resolve(MODULE_DIR, "..", "..", "..", "..", "..");
+const WORKSPACE_ALIASES = collectWorkspaceAliases(WORKSPACE_ROOT);
+const BUILTIN_MODULES = new Set(
+	builtinModules.flatMap((id) => [id, id.replace(/^node:/, "")]),
+);
+const SUPPORTED_PLUGIN_EXTENSIONS = new Set(PLUGIN_FILE_EXTENSIONS);
+
+export interface ImportPluginModuleOptions {
+	useCache?: boolean;
+}
+
+function collectWorkspaceAliases(root: string): Record<string, string> {
+	const aliases: Record<string, string> = {};
+	const candidates: Record<string, string> = {
+		"@clinebot/agents": resolve(root, "packages/agents/src/index.ts"),
+		"@clinebot/core": resolve(root, "packages/core/src/index.ts"),
+		"@clinebot/llms": resolve(root, "packages/llms/src/index.ts"),
+		"@clinebot/rpc": resolve(root, "packages/rpc/src/index.ts"),
+		"@clinebot/scheduler": resolve(root, "packages/scheduler/src/index.ts"),
+		"@clinebot/shared": resolve(root, "packages/shared/src/index.ts"),
+		"@clinebot/shared/storage": resolve(
+			root,
+			"packages/shared/src/storage/index.ts",
+		),
+		"@clinebot/shared/db": resolve(root, "packages/shared/src/db/index.ts"),
+	};
+	for (const [key, value] of Object.entries(candidates)) {
+		if (existsSync(value)) {
+			aliases[key] = value;
+		}
+	}
+	return aliases;
+}
+
+function isBareSpecifier(specifier: string): boolean {
+	return !(
+		specifier.startsWith(".") ||
+		specifier.startsWith("/") ||
+		specifier.startsWith("file:") ||
+		specifier.startsWith("data:") ||
+		specifier.startsWith("http:") ||
+		specifier.startsWith("https:")
+	);
+}
+
+function getPackageName(specifier: string): string {
+	if (specifier.startsWith("@")) {
+		const [scope, name] = specifier.split("/", 3);
+		return name ? `${scope}/${name}` : specifier;
+	}
+	return specifier.split("/", 1)[0] ?? specifier;
+}
+
+function hasInstalledDependency(
+	pluginFilePath: string,
+	specifier: string,
+): boolean {
+	const packageName = getPackageName(specifier);
+	let current = dirname(pluginFilePath);
+	while (true) {
+		const packageDir = resolve(current, "node_modules", packageName);
+		if (
+			existsSync(packageDir) ||
+			existsSync(resolve(packageDir, "package.json"))
+		) {
+			return true;
+		}
+		const parent = resolve(current, "..");
+		if (parent === current) {
+			return false;
+		}
+		current = parent;
+	}
+}
+
+function resolvesFromHostRuntime(specifier: string): boolean {
+	try {
+		HOST_REQUIRE.resolve(specifier);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function resolveFromHostRuntime(specifier: string): string | null {
+	try {
+		return HOST_REQUIRE.resolve(specifier);
+	} catch {
+		return null;
+	}
+}
+
+function isPackageBasedPlugin(pluginFilePath: string): boolean {
+	// Walk up from the plugin file looking for a package.json with a `cline`
+	// manifest.  Stop at the first package.json we encounter — if it doesn't
+	// declare `cline` we've left the plugin boundary (e.g. hit the workspace
+	// root).  Also cap the traversal so we never wander far from the plugin
+	// search root (.cline/plugins).
+	const MAX_DEPTH = 4;
+	let current = dirname(pluginFilePath);
+	for (let depth = 0; depth < MAX_DEPTH; depth++) {
+		const packageJsonPath = resolve(current, "package.json");
+		if (existsSync(packageJsonPath)) {
+			try {
+				const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+				return pkg != null && typeof pkg === "object" && "cline" in pkg;
+			} catch {
+				return false;
+			}
+		}
+		const parent = resolve(current, "..");
+		if (parent === current) {
+			return false;
+		}
+		current = parent;
+	}
+	return false;
+}
+
+function resolveRelativeImportPath(
+	fromPath: string,
+	specifier: string,
+): string | null {
+	const resolvedBase = specifier.startsWith("file:")
+		? fileURLToPath(specifier)
+		: isAbsolute(specifier)
+			? specifier
+			: resolve(dirname(fromPath), specifier);
+	if (
+		existsSync(resolvedBase) &&
+		SUPPORTED_PLUGIN_EXTENSIONS.has(extname(resolvedBase))
+	) {
+		return resolvedBase;
+	}
+	for (const extension of SUPPORTED_PLUGIN_EXTENSIONS) {
+		const withExtension = `${resolvedBase}${extension}`;
+		if (existsSync(withExtension)) {
+			return withExtension;
+		}
+	}
+	for (const extension of SUPPORTED_PLUGIN_EXTENSIONS) {
+		const indexPath = resolve(resolvedBase, `index${extension}`);
+		if (existsSync(indexPath)) {
+			return indexPath;
+		}
+	}
+	return null;
+}
+
+function collectStaticModuleSpecifiers(source: string): string[] {
+	const specifiers = new Set<string>();
+	const patterns = [
+		/\bimport\s+(?:type\s+)?[^"'`]*?\bfrom\s*["'`]([^"'`]+)["'`]/g,
+		/\bexport\s+[^"'`]*?\bfrom\s*["'`]([^"'`]+)["'`]/g,
+		/\bimport\s*\(\s*["'`]([^"'`]+)["'`]\s*\)/g,
+		/\brequire\s*\(\s*["'`]([^"'`]+)["'`]\s*\)/g,
+	];
+	for (const pattern of patterns) {
+		for (const match of source.matchAll(pattern)) {
+			const specifier = match[1];
+			if (specifier) {
+				specifiers.add(specifier);
+			}
+		}
+	}
+	return [...specifiers];
+}
+
+function assertPluginDependenciesInstalled(
+	pluginPath: string,
+	preferHostRuntimeDependencies: boolean,
+	seen = new Set<string>(),
+): void {
+	if (seen.has(pluginPath) || !existsSync(pluginPath)) {
+		return;
+	}
+	seen.add(pluginPath);
+
+	if (!SUPPORTED_PLUGIN_EXTENSIONS.has(extname(pluginPath))) {
+		return;
+	}
+
+	const source = readFileSync(pluginPath, "utf8");
+	for (const specifier of collectStaticModuleSpecifiers(source)) {
+		if (specifier.startsWith("node:") || BUILTIN_MODULES.has(specifier)) {
+			continue;
+		}
+		if (isBareSpecifier(specifier)) {
+			if (
+				Object.hasOwn(WORKSPACE_ALIASES, specifier) ||
+				Object.hasOwn(WORKSPACE_ALIASES, getPackageName(specifier)) ||
+				hasInstalledDependency(pluginPath, specifier) ||
+				(preferHostRuntimeDependencies && resolvesFromHostRuntime(specifier))
+			) {
+				continue;
+			}
+			throw new Error(`Cannot find module '${getPackageName(specifier)}'`);
+		}
+		const resolvedPath = resolveRelativeImportPath(pluginPath, specifier);
+		if (resolvedPath) {
+			assertPluginDependenciesInstalled(
+				resolvedPath,
+				preferHostRuntimeDependencies,
+				seen,
+			);
+		}
+	}
+}
+
+function collectPluginImportAliases(
+	pluginPath: string,
+	preferHostRuntimeDependencies: boolean,
+): Record<string, string> {
+	const pluginRequire = createRequire(pluginPath);
+	const aliases: Record<string, string> = {};
+	for (const [specifier, sourcePath] of Object.entries(WORKSPACE_ALIASES)) {
+		try {
+			pluginRequire.resolve(specifier);
+			continue;
+		} catch {
+			// Use the workspace source only when the plugin package does not provide
+			// its own installed SDK dependency.
+		}
+		aliases[specifier] = sourcePath;
+	}
+	if (preferHostRuntimeDependencies) {
+		const source = readFileSync(pluginPath, "utf8");
+		for (const specifier of collectStaticModuleSpecifiers(source)) {
+			if (
+				!isBareSpecifier(specifier) ||
+				specifier.startsWith("node:") ||
+				BUILTIN_MODULES.has(specifier) ||
+				Object.hasOwn(aliases, specifier) ||
+				hasInstalledDependency(pluginPath, specifier)
+			) {
+				continue;
+			}
+			const resolved = resolveFromHostRuntime(specifier);
+			if (resolved) {
+				aliases[specifier] = resolved;
+			}
+		}
+	}
+	return aliases;
+}
+
+export async function importPluginModule(
+	pluginPath: string,
+	options: ImportPluginModuleOptions = {},
+): Promise<Record<string, unknown>> {
+	const preferHostRuntimeDependencies = !isPackageBasedPlugin(pluginPath);
+	assertPluginDependenciesInstalled(pluginPath, preferHostRuntimeDependencies);
+	const aliases = collectPluginImportAliases(
+		pluginPath,
+		preferHostRuntimeDependencies,
+	);
+	const jiti = createJiti(pluginPath, {
+		alias: aliases,
+		cache: options.useCache,
+		requireCache: options.useCache,
+		esmResolve: true,
+		interopDefault: false,
+		nativeModules: [...BUILTIN_MODULES],
+		transformModules: Object.keys(aliases),
+	});
+	return (await jiti.import(pluginPath, {})) as Record<string, unknown>;
+}