@vibesdotdev/cli 0.0.1

package/src/surface/CLISurface.ts

@@ -0,0 +1,193 @@
+import { Command, CommanderError } from 'commander';
+import { writeSync } from 'node:fs';
+import type { VibesRuntime } from '@vibesdotdev/runtime/api/runtime';
+import { CLIExitSignal, registerCLIProviders, resetKeepAlive, shouldKeepAlive } from '../providers';
+import { createPatternResolver, type PatternResolver } from '../patterns';
+import type { CLIGroupAssetDescriptor } from '../schemas/descriptors';
+import type { CLISurfaceOptions, CommandContext } from '../schemas/surface';
+import { buildCommandContext } from './build-context';
+import { registerGroups } from './register-groups';
+import { registerCommands } from './register-commands';
+import { getLogger } from '../logging';
+
+const logger = getLogger('surface');
+
+/**
+ * Strip frames pointing into the `bun build --compile` virtual filesystem
+ * (`/$bunfs/root/vibes.js:...`) and other bundle-only paths. These leak
+ * implementation details that aren't actionable for users.
+ */
+function stripBundlePaths(text: string): string {
+	return text
+		.split('\n')
+		.filter((line) => {
+			if (line.includes('/$bunfs/')) return false;
+			if (line.includes('B:/~BUN/')) return false;
+			return true;
+		})
+		.join('\n')
+		.trim();
+}
+
+/**
+ * Map common runtime errors to actionable, user-facing guidance.
+ * Falls back to the original message when no mapping applies.
+ *
+ * Returns `null` when no friendly mapping is known (caller falls back to
+ * the raw error message).
+ */
+function mapKnownError(rawMessage: string): string | null {
+	// "No matching implementation found for query (filtered to: foo.bar)"
+	const noMatchingImpl =
+		/No matching implementation found for query \(filtered to:\s*([^)]+)\)/i.exec(rawMessage);
+	if (noMatchingImpl) {
+		const target = noMatchingImpl[1].trim();
+		return (
+			`No provider for "${target}". The plugin owning this query did not register, ` +
+			`or its dependencies are missing. Run with -v for plugin-load details.`
+		);
+	}
+
+	// "No available adapter for record 'session.sessions'. Checked: storage.localdb"
+	const noAdapter =
+		/No available adapter for record\s*'?([^'"\s]+)'?\.?\s*Checked:\s*([^\n]+)/i.exec(rawMessage);
+	if (noAdapter) {
+		const record = noAdapter[1].trim();
+		const checked = noAdapter[2].trim();
+		return (
+			`No storage adapter is initialized for "${record}" (checked: ${checked}).\n` +
+			`Run \`vibes os init\` to set up local storage, or run with -v for details.`
+		);
+	}
+
+	if (rawMessage.includes('getRuntimePathSync() called before the runtime path service was resolved')) {
+		return (
+			'The runtime path service has not been initialized yet. ' +
+			'This is a bug — please report it. Run with -v for the full stack.'
+		);
+	}
+
+	return null;
+}
+
+function formatCliError(error: unknown, verbose: boolean): string {
+	if (verbose) {
+		const text =
+			error instanceof Error ? error.stack?.trim() || error.message.trim() : String(error);
+		return text;
+	}
+
+	const rawMessage =
+		error instanceof Error ? error.message.trim() : String(error).trim();
+	const friendly = mapKnownError(rawMessage);
+	const body = friendly ?? rawMessage;
+	const cleaned = stripBundlePaths(body);
+	return cleaned || 'CLI command failed (run with -v for details).';
+}
+
+export class CLISurface {
+	private groups = new Map<string, Command>();
+	private groupDescriptors = new Map<string, CLIGroupAssetDescriptor>();
+	private patternResolver: PatternResolver | null = null;
+	private initialized = false;
+
+	constructor(
+		private runtime: VibesRuntime,
+		private program: Command,
+		private options: CLISurfaceOptions = {}
+	) {}
+
+	async initialize(): Promise<void> {
+		if (this.initialized) throw new Error('CLISurface already initialized');
+
+		const { verbose, enablePatterns } = this.options;
+		this.program.exitOverride();
+
+		registerCLIProviders(this.runtime, this.options);
+		if (verbose) logger.debug('Registered context providers');
+
+		if (enablePatterns) {
+			this.patternResolver = await createPatternResolver(this.runtime);
+			if (verbose) {
+				logger.debug(`Pattern resolver: ${this.patternResolver.getPatternTypes().join(', ')}`);
+			}
+		}
+
+		const buildContext = async (): Promise<CommandContext> => buildCommandContext(this.runtime);
+
+		if (verbose) {
+			logger.debug(`Registering groups...`);
+			logger.debug(`Runtime assets: cli/group=${this.runtime.assets('cli/group').descriptors().length}, cli/command=${this.runtime.assets('cli/command').descriptors().length}`);
+		}
+
+		await registerGroups({
+			runtime: this.runtime,
+			program: this.program,
+			groups: this.groups,
+			groupDescriptors: this.groupDescriptors,
+			options: this.options,
+			patternResolver: this.patternResolver,
+			buildContext
+		});
+
+		if (verbose) logger.debug(`Registered ${this.groups.size} groups`);
+
+		await registerCommands({
+			runtime: this.runtime,
+			program: this.program,
+			groups: this.groups,
+			groupDescriptors: this.groupDescriptors,
+			options: this.options,
+			patternResolver: this.patternResolver,
+			buildContext
+		});
+
+		this.initialized = true;
+		if (verbose) logger.debug('Surface initialized');
+	}
+
+	async run(argv: string[] = process.argv): Promise<void> {
+		if (!this.initialized) await this.initialize();
+		// Ensure stale keepAlive state from eager module side effects never leaks into a new invocation.
+		resetKeepAlive();
+
+		let exitCode: number | undefined;
+		try {
+			if (argv.slice(2).length === 0) {
+				this.program.outputHelp();
+				exitCode = 0;
+			} else {
+				await this.program.parseAsync(argv);
+			}
+		} catch (error: any) {
+			if (error instanceof CLIExitSignal) {
+				exitCode = error.code;
+			} else if (error instanceof CommanderError || ('exitCode' in error && 'code' in error)) {
+				// `commander.help` / `commander.helpDisplayed` / `commander.version`
+				// are not failures — they're successful help/version output. Map them
+				// to exit 0 so non-TTY callers (CI, subprocesses) treat them the
+				// same way TTY users see them.
+				const helpCodes = new Set([
+					'commander.help',
+					'commander.helpDisplayed',
+					'commander.version'
+				]);
+				exitCode = helpCodes.has(error.code) ? 0 : error.exitCode;
+			} else {
+				exitCode = 1;
+				const formatted = formatCliError(error, !!this.options.verbose);
+				if (formatted) {
+					writeSync(2, `${formatted}\n`);
+				}
+			}
+		}
+
+		if (exitCode !== undefined) {
+			process.exitCode = exitCode;
+		}
+		if (!shouldKeepAlive()) {
+			if (this.options.onBeforeAutoExit) await this.options.onBeforeAutoExit();
+			process.exit(exitCode ?? process.exitCode ?? 0);
+		}
+	}
+}

package/src/surface/attach-tui-action.ts

@@ -0,0 +1,76 @@
+import type { Command } from 'commander';
+import type { VibesRuntime } from '@vibesdotdev/runtime/api/runtime';
+import type { CLICommandAssetDescriptor } from '../schemas/descriptors';
+
+interface TuiActionHooks {
+	beforeExecute?: (params: {
+		args: Record<string, unknown>;
+		options: Record<string, unknown>;
+	}) => Promise<void>;
+}
+
+export async function attachTuiAction(
+	cmd: Command,
+	runtime: VibesRuntime,
+	descriptor: CLICommandAssetDescriptor,
+	hooks: TuiActionHooks = {}
+): Promise<void> {
+	const tuiAppId = descriptor.tuiAppId!;
+
+	cmd.action(async (...actionArgs: unknown[]) => {
+		actionArgs.pop();
+		const options = actionArgs.pop() as Record<string, unknown>;
+
+		const args: Record<string, unknown> = {};
+		if (descriptor.arguments) {
+			descriptor.arguments.forEach((arg: (typeof descriptor.arguments)[number], i: number) => {
+				if (i < actionArgs.length) args[arg.name] = actionArgs[i];
+			});
+		}
+		if (hooks.beforeExecute) {
+			await hooks.beforeExecute({ args, options });
+		}
+
+		const { ensureOpenTuiReactRuntimePluginSupport } = (await import(
+			'@vibesdotdev/tui/services/runtime-plugin-support.impl.consumer' as string
+		)) as {
+			ensureOpenTuiReactRuntimePluginSupport: () => boolean;
+		};
+		ensureOpenTuiReactRuntimePluginSupport();
+
+		// Dynamic imports to avoid hard dependency on tui/react from cli
+		const { startTuiApp } = (await import('@vibesdotdev/tui/services' as string)) as {
+			startTuiApp: (opts: Record<string, unknown>) => Promise<void>;
+		};
+		const { TuiAppShell } = (await import('@vibesdotdev/tui/shell' as string)) as {
+			TuiAppShell: unknown;
+		};
+		const _reactId = 'react';
+		const React = (await import(/* @vite-ignore */ _reactId)) as {
+			createElement: (type: unknown, props: Record<string, unknown>, ...children: unknown[]) => unknown;
+		};
+
+		const appDescriptor = runtime
+			.assets('tui/app')
+			.descriptors()
+			.find((d: { id: string }) => d.id === tuiAppId) as
+			| (Record<string, unknown> & { states?: unknown })
+			| undefined;
+
+		const appImpl = (await runtime.query('tui/app').withId(tuiAppId).resolve()) as {
+			component: (props: Record<string, unknown>) => unknown;
+		};
+
+		await startTuiApp({
+			errorBoundary: false,
+			keyboardProvider: false,
+			render: (onExit: () => void) =>
+				React.createElement(TuiAppShell as unknown, {
+					runtime,
+					states: appDescriptor?.states,
+					onExit,
+					children: React.createElement(appImpl.component, { runtime, onExit, options, args })
+				})
+		});
+	});
+}

package/src/surface/build-context.ts

@@ -0,0 +1,49 @@
+import type { VibesRuntime } from '@vibesdotdev/runtime/api/runtime';
+import type { AppContext, ConfigContext, LoggerContext, UIContext } from '../providers';
+import type { CommandContext } from '../schemas/surface';
+
+export async function buildCommandContext(runtime: VibesRuntime): Promise<CommandContext> {
+	const ctx: CommandContext = { runtime };
+
+	try {
+		ctx.ui = await runtime.context<UIContext>('cli/ui');
+	} catch {
+		try {
+			ctx.ui = await runtime.context<UIContext>('ui');
+		} catch {
+			/* optional */
+		}
+	}
+
+	try {
+		ctx.logger = await runtime.context<LoggerContext>('cli/logger');
+	} catch {
+		try {
+			ctx.logger = await runtime.context<LoggerContext>('logger');
+		} catch {
+			/* optional */
+		}
+	}
+
+	try {
+		ctx.app = await runtime.context<AppContext>('cli/app');
+	} catch {
+		try {
+			ctx.app = await runtime.context<AppContext>('app');
+		} catch {
+			/* optional */
+		}
+	}
+
+	try {
+		ctx.config = await runtime.context<ConfigContext>('config/context');
+	} catch {
+		try {
+			ctx.config = await runtime.context<ConfigContext>('config');
+		} catch {
+			/* optional */
+		}
+	}
+
+	return ctx;
+}

package/src/surface/command-group-policy.ts

@@ -0,0 +1,52 @@
+import type { CLICommandAssetDescriptor } from '../schemas/descriptors';
+import type { CLISurfaceOptions } from '../schemas/surface';
+
+export const DEFAULT_ROOT_FALLBACK_GROUPS = Object.freeze([
+	'chat',
+	'shell-integration',
+	'man',
+	'marshal',
+	'settings',
+	'studio',
+	'work'
+]);
+
+export function allowedRootFallbackGroups(options: CLISurfaceOptions): Set<string> {
+	const extra = options.rootFallbackGroups ?? [];
+	return new Set([...DEFAULT_ROOT_FALLBACK_GROUPS, ...extra]);
+}
+
+export function findUnexpectedMissingGroups(
+	commands: Array<Pick<CLICommandAssetDescriptor, 'id' | 'group'>>,
+	knownGroups: Set<string>,
+	rootFallbackGroups: Set<string>
+): Map<string, string[]> {
+	const missing = new Map<string, string[]>();
+	for (const descriptor of commands) {
+		const groupId = descriptor.group;
+		if (knownGroups.has(groupId) || rootFallbackGroups.has(groupId)) continue;
+		const commandIds = missing.get(groupId) ?? [];
+		commandIds.push(descriptor.id);
+		missing.set(groupId, commandIds);
+	}
+	return missing;
+}
+
+export function findScopeMissingGroups(
+	commands: Array<Pick<CLICommandAssetDescriptor, 'id' | 'group'>>,
+	registeredGroups: Set<string>,
+	declaredGroups: Set<string>,
+	rootFallbackGroups: Set<string>
+): Map<string, string[]> {
+	const missing = new Map<string, string[]>();
+	for (const descriptor of commands) {
+		const groupId = descriptor.group;
+		if (registeredGroups.has(groupId)) continue;
+		if (rootFallbackGroups.has(groupId)) continue;
+		if (!declaredGroups.has(groupId)) continue;
+		const commandIds = missing.get(groupId) ?? [];
+		commandIds.push(descriptor.id);
+		missing.set(groupId, commandIds);
+	}
+	return missing;
+}

package/src/surface/discovery-cache.ts

@@ -0,0 +1,143 @@
+import type { VibesRuntime } from '@vibesdotdev/runtime/api/runtime';
+import type {
+	CLICommandAssetDescriptor,
+	CLIGroupAssetDescriptor
+} from '../schemas/descriptors';
+
+export interface CLIDiscoveryOptions {
+	includeInternal?: boolean;
+}
+
+export interface CLIDiscovery {
+	allGroups: CLIGroupAssetDescriptor[];
+	allCommands: CLICommandAssetDescriptor[];
+	groups: CLIGroupAssetDescriptor[];
+	commands: CLICommandAssetDescriptor[];
+	groupsById: Map<string, CLIGroupAssetDescriptor>;
+	sortedGroups: CLIGroupAssetDescriptor[];
+	sortedCommands: CLICommandAssetDescriptor[];
+}
+
+interface CachedDiscovery {
+	fingerprint: string;
+	discovery: CLIDiscovery;
+}
+
+const discoveryCache = new WeakMap<VibesRuntime, Map<string, CachedDiscovery>>();
+
+export function getCLIDiscovery(
+	runtime: VibesRuntime,
+	options: CLIDiscoveryOptions = {}
+): CLIDiscovery {
+	const includeInternal = options.includeInternal === true;
+	const allGroups = runtime.assets('cli/group').descriptors() as CLIGroupAssetDescriptor[];
+	const allCommands = runtime.assets('cli/command').descriptors() as CLICommandAssetDescriptor[];
+	const scope = runtime.scope;
+	const cacheKey = [
+		scope.surface ?? '',
+		scope.hardware ?? '',
+		scope.purpose ?? '',
+		includeInternal ? 'internal' : 'public'
+	].join(':');
+	const fingerprint = buildFingerprint(allGroups, allCommands);
+	let runtimeCache = discoveryCache.get(runtime);
+	if (!runtimeCache) {
+		runtimeCache = new Map();
+		discoveryCache.set(runtime, runtimeCache);
+	}
+
+	const cached = runtimeCache.get(cacheKey);
+	if (cached?.fingerprint === fingerprint) return cached.discovery;
+
+	const groupsById = new Map(allGroups.map((group) => [group.id, group]));
+	const groups = allGroups.filter((group) => {
+		if (group.enabled === false) return false;
+		if (group.hardware?.length && !group.hardware.includes(scope.hardware)) return false;
+		if (group.surfaces?.length && !group.surfaces.includes(scope.surface as (typeof group.surfaces)[number]))
+			return false;
+		if (!includeInternal && group.internal === true) return false;
+		return true;
+	});
+	const commands = allCommands.filter((command) => {
+		if (command.enabled === false) return false;
+		if (command.hardware?.length && !command.hardware.includes(scope.hardware)) return false;
+		if (
+			command.surfaces?.length &&
+			!command.surfaces.includes(scope.surface as (typeof command.surfaces)[number])
+		)
+			return false;
+		if (!includeInternal && command.internal === true) return false;
+		if (!includeInternal && groupsById.get(command.group)?.internal === true) return false;
+		return true;
+	});
+
+	const discovery: CLIDiscovery = {
+		allGroups,
+		allCommands,
+		groups,
+		commands,
+		groupsById,
+		sortedGroups: sortGroupsByDepth(groups),
+		sortedCommands: [...commands].sort(byOrder)
+	};
+	runtimeCache.set(cacheKey, { fingerprint, discovery });
+	return discovery;
+}
+
+export function clearCLIDiscoveryCache(runtime?: VibesRuntime): void {
+	if (runtime) {
+		discoveryCache.delete(runtime);
+		return;
+	}
+	// WeakMap cannot be cleared. This helper intentionally supports targeted
+	// invalidation for tests or runtimes that mutate descriptors after bootstrap.
+}
+
+function sortGroupsByDepth(groups: CLIGroupAssetDescriptor[]): CLIGroupAssetDescriptor[] {
+	const groupMap = new Map(groups.map((group) => [group.id, group]));
+	const depths = new Map<string, number>();
+
+	const getDepth = (group: CLIGroupAssetDescriptor): number => {
+		const existing = depths.get(group.id);
+		if (existing !== undefined) return existing;
+
+		if (!group.parent) {
+			depths.set(group.id, 0);
+			return 0;
+		}
+
+		const parent = groupMap.get(group.parent);
+		if (!parent) {
+			depths.set(group.id, 0);
+			return 0;
+		}
+
+		const depth = getDepth(parent) + 1;
+		depths.set(group.id, depth);
+		return depth;
+	};
+
+	for (const group of groups) getDepth(group);
+
+	return [...groups].sort((a, b) => {
+		const depthDiff = (depths.get(a.id) ?? 0) - (depths.get(b.id) ?? 0);
+		if (depthDiff !== 0) return depthDiff;
+		return byOrder(a, b);
+	});
+}
+
+function byOrder(
+	a: Pick<CLICommandAssetDescriptor | CLIGroupAssetDescriptor, 'order' | 'id'>,
+	b: Pick<CLICommandAssetDescriptor | CLIGroupAssetDescriptor, 'order' | 'id'>
+): number {
+	const orderDiff = (a.order ?? 999) - (b.order ?? 999);
+	if (orderDiff !== 0) return orderDiff;
+	return a.id.localeCompare(b.id);
+}
+
+function buildFingerprint(
+	groups: CLIGroupAssetDescriptor[],
+	commands: CLICommandAssetDescriptor[]
+): string {
+	return JSON.stringify({ groups, commands });
+}