@vibesdotdev/cli 0.0.2 → 1.0.0-rc.2

package/src/surface/CLISurface.ts

@@ -1,193 +0,0 @@
-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

@@ -1,76 +0,0 @@
-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

@@ -1,49 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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

@@ -1,143 +0,0 @@
-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 });
-}