@vibesdotdev/runtime-environment-bun 0.0.0

package/src/index.ts

@@ -0,0 +1,92 @@
+/**
+ * Bun Runtime Environment Package
+ *
+ * Provides Bun-specific implementations for:
+ * - runtime/environment: BunEnvironment
+ * - runtime/loader: BunLoader
+ * - runtime/scope: Built from captured env
+ * - runtime/env: Env + secrets access
+ */
+
+import type { VibesRuntime } from '@vibesdotdev/runtime';
+import { BunEnvironment, type BunEnvironmentOptions } from './bun-environment.impl';
+import { BunLoader } from './bun-loader.impl';
+import { bunRuntimePath } from './services/runtime-path.impl';
+
+/**
+ * Register the Bun environment with the runtime.
+ * Call this at bootstrap before any plugins are loaded.
+ *
+ * @example
+ * ```ts
+ * // apps/my-app/src/hooks.server.ts
+ * import { registerBunEnvironment } from '@vibesdotdev/runtime-environment-bun';
+ * import { getVibesRuntime } from '@vibesdotdev/runtime';
+ *
+ * export async function handle({ event, resolve }) {
+ *   registerBunEnvironment(getVibesRuntime(), {
+ *     tenancy: {
+ *       ownerType: 'organization',
+ *       ownerId: event.locals.activeOrgId
+ *     }
+ *   });
+ *   // ... rest of handle
+ * }
+ * ```
+ */
+export function registerBunEnvironment(
+	runtime: VibesRuntime,
+	options: BunEnvironmentOptions = {}
+): BunEnvironment {
+	const environment = new BunEnvironment(options);
+	runtime.registerEnvironment(environment);
+
+	// Constitutional registration: the low-level path operations (owned by the host)
+	// are provided under the kind id defined by @vibesdotdev/paths.
+	// packages/paths queries this kind and stays completely agnostic to which
+	// runtime-environment-* package is active or what its classes look like.
+	//
+	// Register both the descriptor (so `query.withId('bun').resolve()` works)
+	// and the loader (so the impl is lazily produced when resolved).
+	runtime.registerDescriptor('paths/runtime-path', {
+		id: 'bun',
+		kind: 'paths/runtime-path',
+		name: 'Bun Runtime Path',
+		description: 'Bun host implementation of low-level path operations'
+	});
+	runtime.registerLoader('paths/runtime-path', 'bun', () => Promise.resolve({ impl: bunRuntimePath }));
+
+	return environment;
+}
+
+/**
+ * Get the Bun environment implementation.
+ * Throws if Bun environment wasn't registered.
+ */
+export function getBunEnvironment(runtime: VibesRuntime): BunEnvironment {
+	const env = runtime.environment;
+	if (!(env instanceof BunEnvironment)) {
+		throw new Error(
+			`Expected BunEnvironment but got ${env.constructor.name}. ` +
+				'Did you call registerBunEnvironment() at bootstrap?'
+		);
+	}
+	return env;
+}
+
+export { BunEnvironment, BunLoader };
+export { BunProcessSpawn } from './process-spawn.impl';
+export { bunRuntimePath } from './services/runtime-path.impl';
+export type { BunEnvironmentOptions };
+
+// Package import policy / dynamic plugin loading from the filesystem
+// (owned by the environment per RUNTIME-ENVIRONMENT-SURFACE-SPEC.md)
+export { loadPlugins } from './package-plugins/loader.consumer';
+export { reportMissingPlugins } from './package-plugins/installer.consumer';
+export { resolvePluginModule, getPackageName } from './package-plugins/resolve.consumer';
+
+// Fallback loader for test/dev when no surface loader is provided
+export { fallbackLoader } from './loaders/fallback-loader.impl.consumer';
+
+// Consumer asset discovery helper (filesystem scanning for .descriptor / .impl / .plugin files)
+export { discoverAssets } from './discovery/discovery.assets.consumer';

package/src/loaders/fallback-loader.impl.consumer.ts

@@ -0,0 +1,57 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import type {
+	RuntimeDiscoveryConfig,
+	RuntimeLoaderImplementation,
+	RuntimeLoaderModuleMaps
+} from '@vibesdotdev/runtime/schemas/registry';
+
+/**
+ * Test/dev fallback loader.
+ * Recursively scans basePaths for .ts/.js files and returns lazy importers.
+ */
+export const fallbackLoader: RuntimeLoaderImplementation = {
+	async loadModules({ discovery }: { discovery?: RuntimeDiscoveryConfig }) {
+		const descriptors: Record<string, () => Promise<{ default?: object }>> = {};
+		const implementations: Record<string, () => Promise<{ default?: object }>> = {};
+		const plugins: Record<string, () => Promise<{ default?: object }>> = {};
+
+		async function scanDir(dir: string) {
+			try {
+				const entries = await readdir(dir, { withFileTypes: true });
+				for (const entry of entries) {
+					const fullPath = join(dir, entry.name);
+					if (entry.isDirectory()) {
+						await scanDir(fullPath);
+						continue;
+					}
+					if (!entry.isFile()) continue;
+					const name = entry.name;
+					if (!name.endsWith('.ts') && !name.endsWith('.js')) continue;
+					const importer = async () => {
+						try {
+							return await import(fullPath);
+						} catch {
+							return {};
+						}
+					};
+					if (name.includes('.descriptor')) {
+						descriptors[fullPath] = importer;
+					} else if (name.includes('.impl')) {
+						implementations[fullPath] = importer;
+					} else if (name.includes('.plugin')) {
+						plugins[fullPath] = importer;
+					}
+				}
+			} catch {
+				// Skip unreadable directories
+			}
+		}
+
+		for (const basePath of discovery?.basePaths ?? []) {
+			await scanDir(basePath);
+		}
+
+		return { descriptors, implementations, plugins } as RuntimeLoaderModuleMaps;
+	}
+};

package/src/package-plugins/candidates.consumer.ts

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { basename, extname, join, sep } from 'path';
+import type { ExportTarget } from '@vibesdotdev/runtime/schemas/package-plugins';
+
+const EXPORT_CONDITION_PRIORITY = [
+	'bun',
+	'import',
+	'module',
+	'default',
+	'compiled',
+	'node',
+	'require'
+];
+
+function readPackageJson(packageRoot: string): { exports?: Record<string, unknown> | string } {
+	return JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')) as {
+		exports?: Record<string, unknown> | string;
+	};
+}
+
+export function getPackageName(specifier: string): string {
+	if (specifier.startsWith('@')) {
+		const parts = specifier.split('/');
+		return `${parts[0]}/${parts[1]}`;
+	}
+	return specifier.split('/')[0]!;
+}
+
+export function isBarePackageSpecifier(specifier: string): boolean {
+	return specifier === getPackageName(specifier);
+}
+
+export function packageRootFor(baseDir: string, packageName: string): string | null {
+	const root = join(baseDir, 'node_modules', ...packageName.split('/'));
+	return existsSync(join(root, 'package.json')) ? root : null;
+}
+
+export function exportPluginSpecifiers(packageName: string, packageRoot: string): string[] {
+	const pkg = readPackageJson(packageRoot) as { exports?: Record<string, unknown> };
+	if (!pkg.exports || typeof pkg.exports !== 'object' || Array.isArray(pkg.exports)) return [];
+
+	const exactName = `./${packageName.split('/').pop()!}.plugin`;
+	const keys = Object.keys(pkg.exports).filter((key) => key === './plugin' || key.endsWith('.plugin'));
+	keys.sort((left, right) => {
+		if (left === './plugin') return -1;
+		if (right === './plugin') return 1;
+		if (left === exactName) return -1;
+		if (right === exactName) return 1;
+		return left.localeCompare(right);
+	});
+
+	return keys.map((key) => `${packageName}/${key.slice(2)}`);
+}
+
+function resolveExportTarget(packageRoot: string, target: ExportTarget): string | null {
+	if (!target) return null;
+	if (typeof target === 'string') return join(packageRoot, target);
+	if (Array.isArray(target)) {
+		for (const option of target) {
+			const resolved = resolveExportTarget(packageRoot, option);
+			if (resolved && existsSync(resolved)) return resolved;
+			if (resolved) return resolved;
+		}
+		return null;
+	}
+
+	const record = target as Record<string, unknown>;
+	for (const key of EXPORT_CONDITION_PRIORITY) {
+		if (!(key in record)) continue;
+		const resolved = resolveExportTarget(packageRoot, record[key] as ExportTarget);
+		if (resolved && existsSync(resolved)) return resolved;
+		if (resolved) return resolved;
+	}
+
+	for (const value of Object.values(record)) {
+		const resolved = resolveExportTarget(packageRoot, value as ExportTarget);
+		if (resolved && existsSync(resolved)) return resolved;
+		if (resolved) return resolved;
+	}
+
+	return null;
+}
+
+export function resolvePackageExportPath(packageRoot: string, subpath: string): string | null {
+	const pkg = readPackageJson(packageRoot);
+	if (!pkg.exports) return null;
+
+	if (typeof pkg.exports === 'string') {
+		return subpath === '.' ? join(packageRoot, pkg.exports) : null;
+	}
+
+	const exportsMap = pkg.exports as Record<string, unknown>;
+	const exportValue = subpath === '.' ? (exportsMap['.'] ?? exportsMap) : exportsMap[subpath];
+	return resolveExportTarget(packageRoot, exportValue as ExportTarget);
+}
+
+export function resolvePackageSpecifierPath(baseDir: string, specifier: string): string | null {
+	const packageName = getPackageName(specifier);
+	const packageRoot = packageRootFor(baseDir, packageName);
+	if (!packageRoot) return null;
+
+	const subpath = specifier === packageName ? '.' : `./${specifier.slice(packageName.length + 1)}`;
+	return resolvePackageExportPath(packageRoot, subpath);
+}
+
+function collectPluginFiles(dir: string, files: string[] = [], depth = 0): string[] {
+	if (depth > 6) return files;
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name === 'node_modules' || entry.name === '.git') continue;
+		const fullPath = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			collectPluginFiles(fullPath, files, depth + 1);
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		if (!entry.name.includes('.plugin.')) continue;
+		const extension = extname(entry.name);
+		if (!['.ts', '.js', '.mjs', '.cjs'].includes(extension)) continue;
+		files.push(fullPath);
+	}
+	return files;
+}
+
+export function pluginFileCandidates(packageRoot: string, packageName: string): string[] {
+	const expectedBasename = `${packageName.split('/').pop()!}.plugin`;
+	return collectPluginFiles(packageRoot).sort((left, right) => {
+		const leftName = basename(left).replace(extname(left), '');
+		const rightName = basename(right).replace(extname(right), '');
+		const leftScore = Number(leftName !== expectedBasename) * 100 + left.split(sep).length;
+		const rightScore = Number(rightName !== expectedBasename) * 100 + right.split(sep).length;
+		return leftScore - rightScore || left.localeCompare(right);
+	});
+}

package/src/package-plugins/import-module.consumer.ts

@@ -0,0 +1,27 @@
+/**
+ * Standard dynamic import for plugin modules.
+ *
+ * Resolves a path on disk to a `file://` URL and imports it. No bundle-shim
+ * fallback: a self-contained binary already has its own first-party plugins
+ * bundled, and project-local third-party plugins resolve normally through
+ * Bun's standard module resolution.
+ */
+
+import { pathToFileURL } from 'url';
+
+export function isNotFoundError(message: string): boolean {
+	return (
+		message.includes('Cannot find') ||
+		message.includes('Could not resolve') ||
+		message.includes('Failed to resolve')
+	);
+}
+
+export async function importPluginModule(path: string): Promise<{
+	loadedPath: string;
+	module: Record<string, unknown>;
+}> {
+	const url = path.startsWith('file://') ? path : pathToFileURL(path).href;
+	const module = (await import(url)) as Record<string, unknown>;
+	return { loadedPath: path, module };
+}

package/src/package-plugins/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Package Plugin Loading
+ *
+ * Re-exports consumer-specific plugin loading utilities.
+ */
+
+export { loadPlugins } from './loader.consumer';
+export { reportMissingPlugins } from './installer.consumer';

package/src/package-plugins/installer.consumer.ts

@@ -0,0 +1,38 @@
+/**
+ * Plugin install advisor.
+ *
+ * When `loadPlugins` returns `missing: [...]` (specifiers that didn't resolve
+ * from the project), this surface emits a clear, actionable instruction
+ * telling the user exactly how to install them and from which directory.
+ *
+ * Auto-installing was removed: it was the source of opaque failures and
+ * surprising network calls. The CLI now refuses to mutate the project's
+ * dependencies on the user's behalf — they run `bun add` themselves.
+ */
+
+import type { PackagePluginRequest, PluginLoadOptions } from '@vibesdotdev/runtime/schemas/package-plugins';
+import { getPackageName } from './resolve.consumer';
+import { reportError } from './reporting';
+
+export function reportMissingPlugins(
+	requests: PackagePluginRequest[],
+	options?: PluginLoadOptions
+): void {
+	if (requests.length === 0) return;
+
+	const byProject = new Map<string, Set<string>>();
+	for (const request of requests) {
+		const packages = byProject.get(request.projectDir) ?? new Set<string>();
+		packages.add(getPackageName(request.id));
+		byProject.set(request.projectDir, packages);
+	}
+
+	for (const [projectDir, packages] of byProject) {
+		const pkgList = [...packages].sort().join(' ');
+		reportError(
+			options,
+			`[vibes] ${packages.size} plugin(s) configured but not installed in ${projectDir}.\n` +
+				`        Run: cd ${projectDir} && bun add ${pkgList}`
+		);
+	}
+}

package/src/package-plugins/loader.consumer.ts

@@ -0,0 +1,80 @@
+/**
+ * Plugin loader.
+ *
+ * Resolves each `PackagePluginRequest` via Bun's standard module resolution
+ * from `request.projectDir` and registers any returned `RuntimePlugin` with
+ * the runtime. Plugins that don't resolve are reported as missing; the caller
+ * surfaces install instructions to the user.
+ */
+
+import type { VibesRuntime } from '@vibesdotdev/runtime';
+import type {
+	LoadPluginsResult,
+	PackagePluginRequest,
+	PluginLoadOptions,
+	PluginLoadResult
+} from '@vibesdotdev/runtime/schemas/package-plugins';
+import { reportInfo, reportWarn } from './reporting';
+import { resolvePluginModule } from './resolve.consumer';
+
+function validatePluginRequest(request: PackagePluginRequest): void {
+	if (typeof request.id !== 'string') {
+		throw new Error(
+			`[vibes] Plugin request id must be a string, got ${typeof request.id}. ` +
+				`Check your vibes.config.ts plugins array — all entries must be strings. ` +
+				`Received: ${JSON.stringify(request)}`
+		);
+	}
+}
+
+export async function loadPlugins(
+	runtime: VibesRuntime,
+	requests: PackagePluginRequest[],
+	options?: PluginLoadOptions
+): Promise<LoadPluginsResult> {
+	const loaded: PluginLoadResult[] = [];
+	const missing: PackagePluginRequest[] = [];
+	const verbose = options?.verbose ?? false;
+
+	for (const request of requests) {
+		validatePluginRequest(request);
+		const resolved = await resolvePluginModule(request);
+		if ('plugins' in resolved) {
+			for (const entry of resolved.plugins) {
+				try {
+					await runtime.registerPlugin(entry.plugin);
+					loaded.push({
+						id: `${request.id} → ${entry.plugin.id}`,
+						success: true,
+						resolvedPath: entry.resolvedPath
+					});
+					if (verbose) {
+						reportInfo(options, `[vibes] Loaded plugin: ${entry.plugin.id} (${entry.specifier})`);
+					}
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					loaded.push({
+						id: `${request.id} → ${entry.plugin.id}`,
+						success: false,
+						error: message
+					});
+					reportWarn(
+						options,
+						`[vibes] Failed to register ${entry.plugin.id} from ${entry.specifier}: ${message}`
+					);
+				}
+			}
+			continue;
+		}
+
+		if (resolved.missing) {
+			missing.push(request);
+			continue;
+		}
+
+		loaded.push({ id: request.id, success: false, error: resolved.error });
+		reportWarn(options, `[vibes] Failed to load ${request.id}: ${resolved.error}`);
+	}
+
+	return { loaded, missing };
+}

package/src/package-plugins/reporting.ts

@@ -0,0 +1,13 @@
+import type { PluginLoadOptions } from '@vibesdotdev/runtime/schemas/package-plugins';
+
+export function reportInfo(options: PluginLoadOptions | undefined, message: string): void {
+	options?.report?.info?.(message);
+}
+
+export function reportWarn(options: PluginLoadOptions | undefined, message: string): void {
+	options?.report?.warn?.(message);
+}
+
+export function reportError(options: PluginLoadOptions | undefined, message: string): void {
+	options?.report?.error?.(message);
+}