@vibesdotdev/cli 0.0.1

package/src/surface/register-commands.ts

@@ -0,0 +1,266 @@
+import type { Command } from 'commander';
+import { Option } from 'commander';
+import type { VibesRuntime } from '@vibesdotdev/runtime/api/runtime';
+import type {
+	CLICommandAssetDescriptor,
+	CLIGroupAssetDescriptor,
+	CLILogBufferBehavior
+} from '../schemas/descriptors';
+import type { PatternResolver } from '../patterns';
+import { isPatternDescriptor, type CLIPatternDescriptor } from '../patterns/schemas';
+import type {
+	CLISurfaceOptions,
+	CommandContext,
+	CommandExecutionStartInfo
+} from '../schemas/surface';
+import {
+	allowedRootFallbackGroups,
+	findScopeMissingGroups,
+	findUnexpectedMissingGroups
+} from './command-group-policy';
+import { attachTuiAction } from './attach-tui-action';
+import { getLogger } from '../logging';
+import { getCLIDiscovery } from './discovery-cache';
+
+const logger = getLogger('surface').child('register-commands');
+
+export async function registerCommands(params: {
+	runtime: VibesRuntime;
+	program: Command;
+	groups: Map<string, Command>;
+	groupDescriptors: Map<string, CLIGroupAssetDescriptor>;
+	options: CLISurfaceOptions;
+	patternResolver: PatternResolver | null;
+	buildContext: () => Promise<CommandContext>;
+}): Promise<void> {
+	const { runtime, options } = params;
+	const { verbose } = options;
+	const discovery = getCLIDiscovery(runtime, options);
+	const commands = discovery.commands;
+
+	if (verbose) logger.debug(`Discovered ${commands.length} commands`);
+
+	const sorted = discovery.sortedCommands;
+	const rootFallbackGroups = allowedRootFallbackGroups(options);
+	const registeredGroupIds = new Set(params.groups.keys());
+	const declaredGroupIds = new Set(discovery.allGroups.map((descriptor) => descriptor.id));
+	const scopeMissingGroups = findScopeMissingGroups(
+		sorted,
+		registeredGroupIds,
+		declaredGroupIds,
+		rootFallbackGroups
+	);
+	const missingGroups = findUnexpectedMissingGroups(sorted, declaredGroupIds, rootFallbackGroups);
+	if (missingGroups.size > 0) {
+		const message = [
+			'[CLI] Command descriptors reference unknown groups:',
+			...Array.from(missingGroups.entries()).map(
+				([groupId, commandIds]) => `  - ${groupId}: ${commandIds.join(', ')}`
+			)
+		].join('\n');
+		if (options.strictCommandGroups ?? true) throw new Error(message);
+		if (verbose) logger.warn(message);
+	}
+
+	const skippedByScope = new Set(scopeMissingGroups.keys());
+	if (verbose && skippedByScope.size > 0) {
+		const message = [
+			'[CLI] Skipping commands because their groups are not registered in this scope:',
+			...Array.from(scopeMissingGroups.entries()).map(
+				([groupId, commandIds]) => `  - ${groupId}: ${commandIds.join(', ')}`
+			)
+		].join('\n');
+		logger.warn(message);
+	}
+
+	const scopedCommands = sorted.filter((command) => !skippedByScope.has(command.group));
+	for (const command of scopedCommands) await registerCommand(params, command, rootFallbackGroups);
+}
+
+async function registerCommand(
+	params: {
+		runtime: VibesRuntime;
+		program: Command;
+		groups: Map<string, Command>;
+		groupDescriptors: Map<string, CLIGroupAssetDescriptor>;
+		options: CLISurfaceOptions;
+		patternResolver: PatternResolver | null;
+		buildContext: () => Promise<CommandContext>;
+	},
+	descriptor: CLICommandAssetDescriptor,
+	rootFallbackGroups: Set<string>
+): Promise<void> {
+	const { runtime, options } = params;
+	const { verbose } = options;
+	const groupParent = params.groups.get(descriptor.group);
+	const parent =
+		groupParent ??
+		(rootFallbackGroups.has(descriptor.group) || !(options.strictCommandGroups ?? true)
+			? params.program
+			: null);
+	if (!parent) {
+		throw new Error(
+			`[CLI] Missing group '${descriptor.group}' for command '${descriptor.id}'. Add a cli/group descriptor or explicitly allow root fallback.`
+		);
+	}
+	if (!groupParent && verbose) {
+		const message = `[CLI] Command '${descriptor.id}' registered at root via fallback group '${descriptor.group}'.`;
+		if (rootFallbackGroups.has(descriptor.group)) {
+			logger.debug(message);
+		} else {
+			logger.warn(message);
+		}
+	}
+
+	if (params.patternResolver && isPatternDescriptor(descriptor)) {
+		const ctx = await params.buildContext();
+		await params.patternResolver.resolve(descriptor as CLIPatternDescriptor, parent, ctx);
+		if (verbose) {
+			logger.debug(
+				`Pattern '${(descriptor as { pattern?: string }).pattern}' applied to: ${descriptor.id}`
+			);
+		}
+		return;
+	}
+
+	const cmd = parent.command(descriptor.name).description(descriptor.description);
+	if (descriptor.arguments) {
+		for (const arg of descriptor.arguments) {
+			const variadic = arg.variadic ? '...' : '';
+			const spec = arg.required ? `<${arg.name}${variadic}>` : `[${arg.name}${variadic}]`;
+			cmd.argument(spec, arg.description, arg.default as string);
+		}
+	}
+
+	if (descriptor.options) {
+		for (const opt of descriptor.options) {
+			const option = new Option(opt.flags, opt.description);
+			if (opt.choices) option.choices(opt.choices);
+			if (opt.type === 'number') {
+				option.argParser((value) => {
+					const n = Number(value);
+					if (Number.isNaN(n)) {
+						throw new Error(`Expected a number for ${opt.flags}, got: ${value}`);
+					}
+					return n;
+				});
+			}
+			if (opt.default !== undefined) option.default(coerceDefault(opt.default, opt.type));
+			cmd.addOption(option);
+		}
+	}
+	if (descriptor.aliases) for (const alias of descriptor.aliases) cmd.alias(alias);
+
+	const groupDescriptor = params.groupDescriptors.get(descriptor.group);
+	const logBuffer = resolveLogBufferBehavior(descriptor, groupDescriptor);
+
+	if (descriptor.tuiAppId) {
+		await attachTuiAction(cmd, runtime, descriptor, {
+			beforeExecute: async ({ args, options: commandOptions }) => {
+				await emitCommandExecutionStart(params.options, {
+					command: descriptor,
+					group: groupDescriptor,
+					args,
+					options: commandOptions,
+					logBuffer
+				});
+			}
+		});
+		if (verbose) logger.debug(`Command (tui/app: ${descriptor.tuiAppId}): ${descriptor.id}`);
+		return;
+	}
+
+	cmd.action(async (...args: unknown[]) => {
+		args.pop();
+		const cmdOptions = args.pop() as Record<string, unknown>;
+		const positionalArgs: Record<string, unknown> = {};
+		if (descriptor.arguments) {
+			descriptor.arguments.forEach((arg: (typeof descriptor.arguments)[number], i: number) => {
+				if (i < args.length) positionalArgs[arg.name] = args[i];
+			});
+		}
+		await emitCommandExecutionStart(params.options, {
+			command: descriptor,
+			group: groupDescriptor,
+			args: positionalArgs,
+			options: cmdOptions,
+			logBuffer
+		});
+		const impl = await resolveCommandImpl(runtime, descriptor, verbose);
+		if (!impl) {
+			throw new Error(
+				`[CLI] Command '${descriptor.id}' is registered but has no resolvable implementation in this runtime scope.`
+			);
+		}
+		await impl.execute(positionalArgs, cmdOptions);
+	});
+
+	if (verbose) logger.debug(`Command: ${descriptor.id}`);
+}
+
+async function resolveCommandImpl(
+	runtime: VibesRuntime,
+	descriptor: CLICommandAssetDescriptor,
+	verbose?: boolean
+): Promise<{
+	execute: (args: Record<string, unknown>, opts: Record<string, unknown>) => Promise<void>;
+} | null> {
+	try {
+		const impl = (await runtime.query('cli/command').withId(descriptor.id).resolve()) as {
+			execute?: (args: Record<string, unknown>, opts: Record<string, unknown>) => Promise<void>;
+		};
+		if (!impl || typeof impl.execute !== 'function') {
+			if (verbose) logger.warn(`Invalid implementation for: ${descriptor.id}`);
+			return null;
+		}
+		return { execute: impl.execute.bind(impl) };
+	} catch {
+		if (verbose) logger.warn(`No implementation for: ${descriptor.id}`);
+		return null;
+	}
+}
+
+function resolveLogBufferBehavior(
+	command: CLICommandAssetDescriptor,
+	group?: CLIGroupAssetDescriptor
+): CLILogBufferBehavior | null {
+	const groupBehavior = group?.logBuffer;
+	const commandBehavior = command.logBuffer;
+
+	if (!groupBehavior && !commandBehavior) {
+		if (command.tuiAppId) {
+			return {
+				enabled: true,
+				sinks: ['stdout'],
+				fallbackToStdout: true
+			};
+		}
+		return null;
+	}
+
+	const merged: CLILogBufferBehavior = {
+		enabled: commandBehavior?.enabled ?? groupBehavior?.enabled ?? true,
+		sinks: commandBehavior?.sinks ?? groupBehavior?.sinks,
+		fallbackToStdout: commandBehavior?.fallbackToStdout ?? groupBehavior?.fallbackToStdout ?? true
+	};
+
+	if (!merged.enabled) return null;
+	if (command.tuiAppId && (!merged.sinks || merged.sinks.length === 0)) {
+		merged.sinks = ['stdout'];
+	}
+	return merged;
+}
+
+function coerceDefault(value: unknown, type: 'string' | 'number' | 'boolean' | undefined): unknown {
+	if (type !== 'number' || typeof value !== 'string') return value;
+	const n = Number(value);
+	return Number.isNaN(n) ? value : n;
+}
+
+async function emitCommandExecutionStart(
+	options: CLISurfaceOptions,
+	info: CommandExecutionStartInfo
+): Promise<void> {
+	if (!options.onCommandExecutionStart) return;
+	await options.onCommandExecutionStart(info);
+}

package/src/surface/register-groups.ts

@@ -0,0 +1,84 @@
+import type { Command } from 'commander';
+import type { VibesRuntime } from '@vibesdotdev/runtime/api/runtime';
+import type { PatternResolver } from '../patterns';
+import { isPatternDescriptor, type CLIPatternDescriptor } from '../patterns/schemas';
+import type { CLIGroupAssetDescriptor } from '../schemas/descriptors';
+import type { CLISurfaceOptions, CommandContext } from '../schemas/surface';
+import { getLogger } from '../logging';
+import { getCLIDiscovery } from './discovery-cache';
+
+const logger = getLogger('surface').child('register-groups');
+
+export async function registerGroups(params: {
+	runtime: VibesRuntime;
+	program: Command;
+	groups: Map<string, Command>;
+	groupDescriptors: Map<string, CLIGroupAssetDescriptor>;
+	options: CLISurfaceOptions;
+	patternResolver: PatternResolver | null;
+	buildContext: () => Promise<CommandContext>;
+}): Promise<void> {
+	const { runtime, options } = params;
+	const { verbose } = options;
+	const discovery = getCLIDiscovery(runtime, options);
+	const groups = discovery.groups;
+
+	if (verbose) {
+		logger.debug(`Discovered ${groups.length} groups`);
+	}
+
+	for (const group of discovery.sortedGroups) {
+		await registerGroup(params, group);
+	}
+}
+
+async function registerGroup(
+	params: {
+		program: Command;
+		groups: Map<string, Command>;
+		groupDescriptors: Map<string, CLIGroupAssetDescriptor>;
+		options: CLISurfaceOptions;
+		patternResolver: PatternResolver | null;
+		buildContext: () => Promise<CommandContext>;
+	},
+	descriptor: CLIGroupAssetDescriptor
+): Promise<void> {
+	const { verbose } = params.options;
+	let parent = params.program;
+	if (descriptor.parent) {
+		const parentGroup = params.groups.get(descriptor.parent);
+		if (!parentGroup) {
+			const message = `[CLI] Group '${descriptor.id}' references missing parent '${descriptor.parent}'.`;
+			if (params.options.strictGroupParents === true) throw new Error(message);
+			if (verbose) logger.warn(message);
+		} else {
+			parent = parentGroup;
+		}
+	}
+
+	const groupCmd = parent.command(descriptor.name).description(descriptor.description);
+
+	if (descriptor.aliases) {
+		for (const alias of descriptor.aliases) {
+			groupCmd.alias(alias);
+		}
+	}
+
+	params.groups.set(descriptor.id, groupCmd);
+	params.groupDescriptors.set(descriptor.id, descriptor);
+
+	if (verbose) {
+		logger.debug(`Group: ${descriptor.id}`);
+	}
+
+	if (params.patternResolver && isPatternDescriptor(descriptor)) {
+		const ctx = await params.buildContext();
+		await params.patternResolver.resolve(descriptor as CLIPatternDescriptor, groupCmd, ctx);
+
+		if (verbose) {
+			logger.debug(
+				`Pattern '${(descriptor as { pattern?: string }).pattern}' applied to: ${descriptor.id}`
+			);
+		}
+	}
+}

package/src/surface.ts

@@ -0,0 +1,9 @@
+/**
+ * CLI Surface
+ *
+ * The Commander.js integration for the universal runtime.
+ * Discovers cli/group and cli/command descriptors and builds a command tree.
+ */
+
+export { CLISurface } from './surface/CLISurface';
+export type { CLISurfaceOptions, CommandContext } from './schemas/surface';

package/src/types.ts

@@ -0,0 +1,3 @@
+export type { CLIContext } from './providers.ts';
+export type { RuntimeContext } from './core/runtime/context.ts';
+export type { UIContext as UIToolkit } from './providers.ts';

package/src/ui/schemas/types.ts

@@ -0,0 +1 @@
+export type { UIContext as UIToolkit } from '../../providers.ts';

package/src/ui/toolkit/VibesUIToolkit.ts

@@ -0,0 +1 @@
+export { VibesUIToolkit } from '../../support/ui-toolkit.ts';

package/src/ui.context.descriptor.ts

@@ -0,0 +1,13 @@
+/**
+ * CLI UI Context Descriptor
+ *
+ * Provides UI toolkit for terminal output (CLI surface only).
+ */
+
+import { createContextDescriptor } from '@vibesdotdev/runtime/factory/context';
+
+export default createContextDescriptor({
+	id: 'cli/ui',
+	description: 'UI toolkit for terminal output and user interaction.',
+	hardware: ['consumer']
+});

package/src/utils/open.ts

@@ -0,0 +1,36 @@
+import { spawn } from 'bun';
+
+const ALLOWED_SCHEMES = new Set(['http:', 'https:']);
+
+function validateUrl(url: string): void {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new Error(`Invalid URL: ${url}`);
+	}
+	if (!ALLOWED_SCHEMES.has(parsed.protocol)) {
+		throw new Error(
+			`URL scheme not allowed: ${parsed.protocol}. Only http:// and https:// are permitted.`
+		);
+	}
+}
+
+export async function open(url: string): Promise<void> {
+	validateUrl(url);
+
+	const platform = process.platform;
+	const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open';
+
+	const proc = spawn({
+		cmd: [command, url],
+		stdout: 'ignore',
+		stderr: 'pipe'
+	});
+
+	const exitCode = await proc.exited;
+	if (exitCode !== 0) {
+		const stderr = await new Response(proc.stderr).text();
+		throw new Error(`Failed to open browser: ${stderr.trim() || `exit code ${exitCode}`}`);
+	}
+}

package/src/version.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI version string for `vibes --version`.
+ *
+ * In compiled binaries, `__VIBES_VERSION__` is substituted at build time.
+ * In source mode, falls back to 'dev'.
+ */
+declare const __VIBES_VERSION__: string | undefined;
+
+export const VIBES_VERSION: string =
+	typeof __VIBES_VERSION__ === 'string' ? __VIBES_VERSION__ : 'dev';