@vibesdotdev/runtime-environment-bun 0.0.0

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

@@ -0,0 +1,292 @@
+/**
+ * Plugin resolution — anchored on the project directory.
+ *
+ * For each request, we ask Bun to resolve the package's plugin entry points
+ * from `projectDir`. Bun's resolver follows the standard Node walk: it finds
+ * the package in `projectDir/node_modules`, then in parent `node_modules`,
+ * and so on. No shadow trees, no on-the-fly bundling.
+ */
+
+import { dirname, join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { pathToFileURL } from 'url';
+import type { RuntimePlugin } from '@vibesdotdev/runtime';
+import type {
+	PackagePluginRequest,
+	ResolveAttempt,
+	ResolvedPluginEntry,
+	ResolvePluginResult
+} from '@vibesdotdev/runtime/schemas/package-plugins';
+import {
+	exportPluginSpecifiers,
+	getPackageName as getPluginPackageName,
+	isBarePackageSpecifier,
+	pluginFileCandidates
+} from './candidates.consumer';
+
+function looksLikePlugin(candidate: unknown): candidate is RuntimePlugin {
+	return Boolean(
+		candidate &&
+			typeof candidate === 'object' &&
+			'id' in candidate &&
+			!('kind' in candidate) &&
+			('name' in candidate ||
+				'description' in candidate ||
+				'dependencies' in candidate ||
+				'kinds' in candidate ||
+				'onRegister' in candidate ||
+				'onActivate' in candidate ||
+				'onDispose' in candidate)
+	);
+}
+
+function resolvePlugin(mod: Record<string, unknown>): RuntimePlugin | null {
+	const def = mod.default;
+	if (looksLikePlugin(def)) return def;
+
+	for (const [key, value] of Object.entries(mod)) {
+		if (key.toLowerCase().includes('plugin') && looksLikePlugin(value)) {
+			return value;
+		}
+	}
+
+	const candidates = Object.values(mod).filter(looksLikePlugin);
+	return candidates.length === 1 ? candidates[0] : null;
+}
+
+/**
+ * Specifiers we never load in consumer scope. Cloud plugins target workerd;
+ * loading them in a consumer runtime just produces unmet-dep errors because
+ * the consumer chain does not include the cloud-only plugin graph. Skip them
+ * at the specifier level.
+ */
+function isConsumerScopedSpecifier(specifier: string): boolean {
+	return !specifier.endsWith('cloud.plugin');
+}
+
+export function getPackageName(specifier: string): string {
+	return getPluginPackageName(specifier);
+}
+
+function isNotFoundMessage(message: string): boolean {
+	return (
+		message.includes('Cannot find') ||
+		message.includes('Could not resolve') ||
+		message.includes('Failed to resolve')
+	);
+}
+
+async function importByPath(path: string): Promise<Record<string, unknown>> {
+	return (await import(pathToFileURL(path).href)) as Record<string, unknown>;
+}
+
+/**
+ * Walk up from a resolved file path to find the package root (the directory
+ * containing the matching `package.json`). This is how we discover a package's
+ * own filesystem root after `Bun.resolveSync` has already located it via the
+ * standard node_modules walk.
+ */
+function packageRootFromResolvedPath(resolvedPath: string, packageName: string): string | null {
+	let current = dirname(resolvedPath);
+	const seen = new Set<string>();
+	while (!seen.has(current)) {
+		seen.add(current);
+		const pkgJsonPath = join(current, 'package.json');
+		if (existsSync(pkgJsonPath)) {
+			try {
+				const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8')) as { name?: string };
+				if (pkg.name === packageName) return current;
+			} catch {
+				// Continue walking past unreadable package.json files.
+			}
+		}
+		const parent = dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+	return null;
+}
+
+/**
+ * Locate a package's root by walking up from `projectDir` and probing each
+ * ancestor's `node_modules/<packageName>/package.json`. Used when the package
+ * declares no `.` export (so `Bun.resolveSync(packageName, …)` throws) but we
+ * still want to find its on-disk root to probe `./plugin` exports and scan
+ * for canonical plugin files.
+ */
+function findPackageRootByWalkUp(projectDir: string, packageName: string): string | null {
+	const segments = packageName.split('/');
+	let current = projectDir;
+	const seen = new Set<string>();
+	while (!seen.has(current)) {
+		seen.add(current);
+		const candidate = join(current, 'node_modules', ...segments);
+		if (existsSync(join(candidate, 'package.json'))) return candidate;
+		const parent = dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+	return null;
+}
+
+type SpecifierAttempt =
+	| { kind: 'plugin'; entry: ResolvedPluginEntry; resolvedPath: string }
+	| { kind: 'attempt'; attempt: ResolveAttempt; resolvedPath: string | null };
+
+async function trySpecifier(
+	specifier: string,
+	projectDir: string
+): Promise<SpecifierAttempt> {
+	let resolvedPath: string | null = null;
+	try {
+		resolvedPath = Bun.resolveSync(specifier, projectDir);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return {
+			kind: 'attempt',
+			attempt: { label: specifier, message, notFound: isNotFoundMessage(message) },
+			resolvedPath: null
+		};
+	}
+
+	try {
+		const loaded = await importByPath(resolvedPath);
+		const plugin = resolvePlugin(loaded);
+		if (plugin) {
+			return {
+				kind: 'plugin',
+				entry: { plugin, specifier, resolvedPath },
+				resolvedPath
+			};
+		}
+		return {
+			kind: 'attempt',
+			attempt: {
+				label: specifier,
+				message: `Resolved ${specifier}, but it did not export a RuntimePlugin`,
+				notFound: false
+			},
+			resolvedPath
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		// Resolution succeeded but import failed (broken root export, syntax
+		// error, etc.). Surface the failure but keep `resolvedPath` so the
+		// caller can still discover the package root and probe other entries.
+		return {
+			kind: 'attempt',
+			attempt: { label: specifier, message, notFound: false },
+			resolvedPath
+		};
+	}
+}
+
+type FileAttempt =
+	| { kind: 'plugin'; entry: ResolvedPluginEntry }
+	| { kind: 'attempt'; attempt: ResolveAttempt };
+
+async function tryFile(path: string): Promise<FileAttempt> {
+	try {
+		const loaded = await importByPath(path);
+		const plugin = resolvePlugin(loaded);
+		if (plugin) {
+			return { kind: 'plugin', entry: { plugin, specifier: path, resolvedPath: path } };
+		}
+		return {
+			kind: 'attempt',
+			attempt: {
+				label: path,
+				message: `Resolved ${path}, but it did not export a RuntimePlugin`,
+				notFound: false
+			}
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { kind: 'attempt', attempt: { label: path, message, notFound: isNotFoundMessage(message) } };
+	}
+}
+
+/**
+ * Resolve all plugins exported by a package — the primary plugin (`./plugin`
+ * or the bare specifier) plus any sibling surface plugins (`./<x>.plugin`,
+ * e.g. `./cli.plugin`). Cloud-scoped specifiers are excluded in consumer
+ * resolution. Plugins are deduplicated by `plugin.id` (preserving first occurrence)
+ * to handle index-barrel re-exports.
+ */
+export async function resolvePluginModule(
+	request: PackagePluginRequest
+): Promise<ResolvePluginResult | { error: string; missing: boolean }> {
+	const { id, projectDir } = request;
+	const attempts: ResolveAttempt[] = [];
+	const packageName = getPluginPackageName(id);
+	const bareSpecifier = isBarePackageSpecifier(id);
+
+	const collected = new Map<string, ResolvedPluginEntry>();
+	const addEntry = (entry: ResolvedPluginEntry) => {
+		if (!collected.has(entry.plugin.id)) collected.set(entry.plugin.id, entry);
+	};
+
+	// Try the literal request first. Even if it doesn't expose a plugin, the
+	// resolved path tells us where the package lives so we can probe its plugin
+	// entry points and on-disk plugin files.
+	const initial = await trySpecifier(id, projectDir);
+	let initialResolvedPath: string | null = null;
+	if (initial.kind === 'plugin') {
+		addEntry(initial.entry);
+		initialResolvedPath = initial.resolvedPath;
+	} else {
+		attempts.push(initial.attempt);
+		initialResolvedPath = initial.resolvedPath;
+	}
+
+	let packageRoot: string | null = null;
+	if (bareSpecifier) {
+		if (initialResolvedPath) {
+			packageRoot = packageRootFromResolvedPath(initialResolvedPath, packageName);
+		}
+		if (!packageRoot) {
+			packageRoot = findPackageRootByWalkUp(projectDir, packageName);
+		}
+	}
+
+	if (bareSpecifier && packageRoot) {
+		for (const specifier of exportPluginSpecifiers(packageName, packageRoot)) {
+			if (specifier === id) continue;
+			if (!isConsumerScopedSpecifier(specifier)) continue;
+			const candidate = await trySpecifier(specifier, projectDir);
+			if (candidate.kind === 'plugin') {
+				addEntry(candidate.entry);
+			} else {
+				attempts.push(candidate.attempt);
+			}
+		}
+
+		// Filesystem-discovered plugin files are only used as a fallback when no
+		// explicit plugin export resolved. They are scope-agnostic but we keep
+		// them as a last resort to preserve historic discovery behavior.
+		if (collected.size === 0) {
+			for (const file of pluginFileCandidates(packageRoot, packageName)) {
+				const candidate = await tryFile(file);
+				if (candidate.kind === 'plugin') {
+					addEntry(candidate.entry);
+				} else {
+					attempts.push(candidate.attempt);
+				}
+			}
+		}
+	}
+
+	if (collected.size > 0) {
+		return {
+			plugins: Array.from(collected.values()),
+			resolvedFrom: projectDir
+		};
+	}
+
+	const lastMeaningful = [...attempts].reverse().find((attempt) => !attempt.notFound);
+	const allNotFound = attempts.length > 0 && attempts.every((attempt) => attempt.notFound);
+	return {
+		error: lastMeaningful?.message ?? `Unable to resolve plugin ${id} from ${projectDir}`,
+		missing: allNotFound
+	};
+}

package/src/process-spawn.impl.ts

@@ -0,0 +1,52 @@
+/**
+ * Bun Process Spawn Implementation
+ *
+ * Consumer-only process spawning backed by Bun.spawn().
+ * Only available when hardware === 'consumer'.
+ */
+
+import type {
+	ProcessSpawnImplementation,
+	ProcessSpawnOptions,
+	ProcessHandle
+} from '@vibesdotdev/runtime/kinds/process-spawn';
+import type { ProcessSpawnDescriptor } from '@vibesdotdev/runtime/kinds/process-spawn';
+
+export class BunProcessSpawn implements ProcessSpawnImplementation {
+	readonly id: string;
+	readonly descriptor: ProcessSpawnDescriptor;
+
+	constructor() {
+		this.id = 'process-spawn-bun';
+		this.descriptor = {
+			id: 'process-spawn-bun',
+			kind: 'process/spawn',
+			name: 'Bun Process Spawn',
+			description: 'Consumer-only process spawning via Bun.spawn()',
+			hardware: ['consumer'],
+		};
+	}
+
+	async spawn(options: ProcessSpawnOptions): Promise<ProcessHandle> {
+		const proc = Bun.spawn([options.command, ...(options.args ?? [])], {
+			cwd: options.cwd,
+			env: options.env ?? (process.env as Record<string, string>),
+			stdout: 'pipe',
+			stderr: 'pipe',
+		});
+
+		const exited = proc.exited.then((code) => ({
+			code,
+			signal: null as string | null,
+		}));
+
+		return {
+			pid: proc.pid,
+			stdout: proc.stdout as ProcessHandle['stdout'],
+			stderr: proc.stderr as ProcessHandle['stderr'],
+			stdin: null,
+			exited,
+			kill: (signal?: string) => proc.kill(signal as Parameters<typeof proc.kill>[0]),
+		};
+	}
+}

package/src/services/runtime-path.impl.ts

@@ -0,0 +1,20 @@
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve, dirname, basename, extname, isAbsolute, normalize } from 'node:path';
+
+/**
+ * Bun / Node implementation of low-level path utilities.
+ * This is the source of truth for path operations on this host.
+ *
+ * The shape matches RuntimePath from @vibesdotdev/paths (the contract lives there).
+ */
+export const bunRuntimePath = {
+	join,
+	resolve,
+	dirname,
+	basename,
+	extname,
+	isAbsolute,
+	normalize,
+	homedir,
+	tmpdir,
+};

package/src/services/self-spawn.consumer.ts

@@ -0,0 +1,91 @@
+/**
+ * Self-spawn argv resolution.
+ *
+ * Lets a hosted process (PM daemon launcher, an autoloop child, etc.)
+ * compute the command line that re-launches the *currently running*
+ * vibes binary so a fresh subprocess can run additional commands.
+ *
+ * Two host shapes are supported, and the bin entry's `import.meta.url`
+ * is the only reliable signal for distinguishing them:
+ *
+ *   - **Compiled binary** (`bun build --compile`): `import.meta.url`
+ *     starts with `file:///$bunfs/` (Bun's virtual mount for the
+ *     bundled root). `process.execPath` is the standalone binary
+ *     itself, so the spawn argv is just `[execPath]`.
+ *
+ *   - **Source mode** (`bun run vibes.ts`): `import.meta.url` is a
+ *     real `file://` path to the .ts entry. `process.execPath` is bun;
+ *     `process.argv[1]` is the entry script. Spawn argv is
+ *     `[bun, 'run', '--bun', entry]`.
+ *
+ * Bin entries call `declareSelfSpawn(import.meta.url)` once at
+ * startup. Consumers (e.g. PM client) call `readSelfSpawnArgv()`.
+ *
+ * Embedded hosts (a SvelteKit app importing PM at runtime) never call
+ * `declareSelfSpawn`. Consumers receive `null` and decide their own
+ * fallback policy (PM, for instance, falls back to scanning the
+ * workspace for a CLI source entry — useful in monorepo dev, throws
+ * with a clear message otherwise).
+ */
+
+const COMPILED_BINARY_URL_PREFIX = 'file:///$bunfs/';
+const SELF_SPAWN_ENV_VAR = 'VIBES_SELF_SPAWN_ARGV';
+
+export type SelfSpawnSource = 'compiled-binary' | 'bun-source';
+
+export interface SelfSpawnArgv {
+	argv: string[];
+	source: SelfSpawnSource;
+}
+
+/**
+ * Compute the self-spawn argv from the host's `import.meta.url`.
+ *
+ * Returns `null` when the host shape can't be determined (e.g. source
+ * mode where `process.argv[1]` is missing). Callers fall back.
+ */
+export function computeSelfSpawnArgv(binImportMetaUrl: string): SelfSpawnArgv | null {
+	if (binImportMetaUrl.startsWith(COMPILED_BINARY_URL_PREFIX)) {
+		return { argv: [process.execPath], source: 'compiled-binary' };
+	}
+	const entry = process.argv[1];
+	if (entry && entry.length > 0) {
+		return {
+			argv: [process.execPath, 'run', '--bun', entry],
+			source: 'bun-source'
+		};
+	}
+	return null;
+}
+
+/**
+ * Publish the host's self-spawn argv as a JSON env var so subprocesses
+ * and other in-process consumers can re-launch the same binary shape.
+ *
+ * Idempotent — if the env var is already set (e.g. inherited from a
+ * parent vibes process), the original launch shape is preserved.
+ */
+export function declareSelfSpawn(binImportMetaUrl: string): void {
+	if (process.env[SELF_SPAWN_ENV_VAR]) return;
+	const computed = computeSelfSpawnArgv(binImportMetaUrl);
+	if (!computed) return;
+	process.env[SELF_SPAWN_ENV_VAR] = JSON.stringify(computed.argv);
+}
+
+/**
+ * Read the published self-spawn argv. Returns `null` when no host has
+ * declared one or the value is malformed.
+ */
+export function readSelfSpawnArgv(): string[] | null {
+	const raw = process.env[SELF_SPAWN_ENV_VAR];
+	if (!raw) return null;
+	try {
+		const parsed = JSON.parse(raw) as unknown;
+		if (Array.isArray(parsed) && parsed.every((entry) => typeof entry === 'string')) {
+			return parsed as string[];
+		}
+	} catch {
+		// malformed env value — treat as not declared
+	}
+	return null;
+}

package/src/services/workspace-resolve.ts

@@ -0,0 +1,146 @@
+/**
+ * Unified Workspace Root Resolution
+ *
+ * Single source of truth for resolving the workspace root path.
+ * This consolidates the various fallback patterns used across the codebase.
+ *
+ * Priority order (highest to lowest):
+ * 1. Explicit override (e.g., MCP request header)
+ * 2. Runtime context workspacePath
+ * 3. Environment config workspacePath
+ * 4. CLI invocation cwd
+ * 5. process.cwd() fallback
+ *
+ * NOTE: This module lives in @vibesdotdev/runtime (not workspace) to avoid
+ * a circular dependency between runtime and workspace. The workspace package
+ * re-exports from here for backward compatibility.
+ */
+
+type WorkspaceSourceKey = 'override' | 'runtimeContext' | 'environment' | 'cliCwd' | 'cwd';
+
+function normalizeCandidate(path: string | undefined): string | undefined {
+	if (typeof path !== 'string') return undefined;
+	const trimmed = path.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function readStringField(
+	value: object | null | undefined,
+	key: 'workspacePath' | 'cwd'
+): string | undefined {
+	if (!value) return undefined;
+	const candidate = (value as Record<'workspacePath' | 'cwd', string | undefined>)[key];
+	return typeof candidate === 'string' ? candidate : undefined;
+}
+
+export interface WorkspaceSources {
+	override?: string;
+	runtimeContext?: string;
+	environment?: string;
+	cliCwd?: string;
+	cwd?: string;
+}
+
+export interface WorkspaceResolutionResult {
+	path: string;
+	source: WorkspaceSourceKey | 'processCwd';
+}
+
+export interface WorkspaceResolutionContext {
+	workspacePath?: string;
+	environment?: object | null;
+	cli?: object | null;
+}
+
+const RESOLUTION_ORDER: readonly WorkspaceSourceKey[] = [
+	'override',
+	'runtimeContext',
+	'environment',
+	'cliCwd',
+	'cwd'
+];
+
+/**
+ * Resolve workspace root path from multiple sources with priority fallback.
+ *
+ * @param sources - Object containing potential workspace path sources
+ * @returns The resolved workspace path (never undefined)
+ *
+ * @example
+ * ```ts
+ * const workspace = resolveWorkspaceRoot({
+ *   override: request.workspacePath,
+ *   runtimeContext: context.workspacePath,
+ *   environment: context.environment?.workspacePath,
+ *   cliCwd: context.cli?.cwd
+ * });
+ * ```
+ */
+export function resolveWorkspaceRoot(sources: WorkspaceSources = {}): string {
+	const { path } = resolveWorkspaceRootWithSource(sources);
+	return path;
+}
+
+/**
+ * Resolve workspace root path with source information for debugging.
+ *
+ * @param sources - Object containing potential workspace path sources
+ * @returns Object with resolved path and source that provided it
+ */
+export function resolveWorkspaceRootWithSource(
+	sources: WorkspaceSources = {}
+): WorkspaceResolutionResult {
+	for (const source of RESOLUTION_ORDER) {
+		const path = normalizeCandidate(sources[source]);
+		if (path) {
+			return { path, source };
+		}
+	}
+
+	const fallback = sources.cwd || process.cwd();
+	return { path: fallback, source: 'processCwd' };
+}
+
+// Context Extraction Helpers
+
+/**
+ * Extract workspace sources from a RuntimeContext-like object.
+ * Handles the various shapes of context objects in the codebase.
+ *
+ * @param context - Runtime context object with optional workspace-related fields
+ * @param override - Optional explicit override (e.g., from MCP request)
+ * @returns WorkspaceSources for use with resolveWorkspaceRoot
+ */
+export function extractWorkspaceSources(
+	context: WorkspaceResolutionContext,
+	override?: string
+): WorkspaceSources {
+	return {
+		override: normalizeCandidate(override),
+		runtimeContext: normalizeCandidate(context.workspacePath),
+		environment: normalizeCandidate(readStringField(context.environment, 'workspacePath')),
+		cliCwd: normalizeCandidate(readStringField(context.cli, 'cwd'))
+	};
+}
+
+/**
+ * Convenience function: Extract sources and resolve in one step.
+ *
+ * @param context - Runtime context object
+ * @param override - Optional explicit override
+ * @returns Resolved workspace path
+ */
+export function resolveWorkspaceFromContext(
+	context: WorkspaceResolutionContext,
+	override?: string
+): string {
+	return resolveWorkspaceRoot(extractWorkspaceSources(context, override));
+}
+
+/**
+ * Resolve the current workspace as an object with rootPath.
+ * Convenience wrapper for callers that expect `{ rootPath: string }`.
+ */
+export function resolveCurrentWorkspace(): { rootPath: string } {
+	return { rootPath: resolveWorkspaceRoot() };
+}