@vibesdotdev/cli 0.0.1

package/src/bin.ts

@@ -0,0 +1,84 @@
+/**
+ * CLI Binary Path Resolution
+ *
+ * Provides utilities for resolving the path to the vibes CLI binary.
+ * Used by PM and workers to spawn the CLI correctly.
+ */
+
+import { dirname, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const MONOREPO_ENTRY_SEGMENTS = ['apps', 'cli-bin', 'src', 'bin', 'vibes.ts'] as const;
+
+function findMonorepoCliEntry(startDir: string, searched: Set<string>): string | undefined {
+	let current = resolve(startDir);
+
+	while (true) {
+		const candidate = resolve(current, ...MONOREPO_ENTRY_SEGMENTS);
+		searched.add(candidate);
+		if (existsSync(candidate)) return candidate;
+
+		const parent = dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+
+	return undefined;
+}
+
+/**
+ * Resolve the vibes CLI entry point path.
+ * Searches in order: apps/cli-bin, single-app layout, flat layout.
+ *
+ * @throws Error if no CLI entry point is found
+ */
+export function resolveCliEntry(): string {
+	const searched = new Set<string>();
+	const monorepoStarts = [process.cwd(), MODULE_DIR];
+
+	for (const start of monorepoStarts) {
+		const monorepoEntry = findMonorepoCliEntry(start, searched);
+		if (monorepoEntry) return monorepoEntry;
+	}
+
+	const fallbackEntries = [
+		resolve(process.cwd(), 'src', 'bin', 'vibes.ts'),
+		resolve(process.cwd(), 'bin', 'vibes.ts'),
+		resolve(MODULE_DIR, 'src', 'bin', 'vibes.ts'),
+		resolve(MODULE_DIR, 'bin', 'vibes.ts'),
+		resolve(MODULE_DIR, '..', 'src', 'bin', 'vibes.ts'),
+		resolve(MODULE_DIR, '..', 'bin', 'vibes.ts')
+	];
+
+	for (const candidate of fallbackEntries) {
+		searched.add(candidate);
+		if (existsSync(candidate)) return candidate;
+	}
+
+	throw new Error(`Failed to resolve CLI entry point. Searched:\n${[...searched].join('\n')}`);
+}
+
+/**
+ * Resolve the bun command to invoke the CLI.
+ * Returns the appropriate args to run the CLI.
+ *
+ * @param target - Worker target (consumer or cloud)
+ * @param options.hot - Enable hot reload (default: false)
+ * @returns Object with command and args array
+ */
+export function resolveCliInvocation(
+	target: 'consumer' | 'cloud',
+	options: { hot?: boolean } = {}
+): { command: string; args: string[] } {
+	const cliEntry = resolveCliEntry();
+	const hot = options.hot ?? false;
+
+	return {
+		command: 'bun',
+		args: hot
+			? ['run', '--hot', '--bun', cliEntry, 'workers', 'serve', target]
+			: ['run', '--bun', cliEntry, 'workers', 'serve', target]
+	};
+}

package/src/bootstrap.ts

@@ -0,0 +1,19 @@
+/**
+ * CLI Bootstrap (compatibility re-export)
+ *
+ * @deprecated Prefer importing from '@vibesdotdev/runtime-surface-cli' for new code.
+ *
+ * This file is now a thin re-export shim for backward compatibility during the
+ * surface package migration. All real bootstrap logic (runtime initialization,
+ * umbrella plugin loading, etc.) lives in the dedicated surface package.
+ *
+ * Canonical usage:
+ *   import { createVibesCliApp } from '@vibesdotdev/runtime-surface-cli';
+ */
+
+export {
+  createVibesCliApp,
+  type VibesCliAppOptions,
+  type VibesCliApp,
+  type CliPluginLoader,
+} from '@vibesdotdev/runtime-surface-cli';

package/src/cli.plugin.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CLI Plugin
+ *
+ * Registers CLI kinds with the universal runtime:
+ * - cli/group: Command groups for organizing commands
+ * - cli/command: Executable CLI commands
+ *
+ * This plugin does NOT create a separate runtime - it extends the universal
+ * runtime with CLI-specific asset kinds that CLISurface uses to build
+ * the Commander.js command tree.
+ */
+/**
+ * CLI Plugin
+ *
+ * Registers cli/group and cli/command kinds with the universal runtime.
+ * CLISurface queries these kinds to build the Commander.js command tree.
+ */
+declare const _default: import("@vibesdotdev/runtime").RuntimePlugin;
+export default _default;

package/src/cli.plugin.ts

@@ -0,0 +1,202 @@
+/**
+ * CLI Plugin
+ *
+ * Registers CLI kinds with the universal runtime:
+ * - cli/group: Command groups for organizing commands
+ * - cli/command: Executable CLI commands
+ *
+ * This plugin does NOT create a separate runtime - it extends the universal
+ * runtime with CLI-specific asset kinds that CLISurface uses to build
+ * the Commander.js command tree.
+ */
+
+import {
+	createRuntimePlugin,
+	loader,
+	type KindContext,
+	type RuntimeKindDescriptorRecord
+} from '@vibesdotdev/runtime';
+import type { RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/descriptor';
+import type { RuntimeScope } from '@vibesdotdev/runtime/schemas/scope';
+import {
+	CLIGroupDescriptorSchema,
+	CLICommandDescriptorSchema,
+	type CLIGroupAssetDescriptor,
+	type CLICommandAssetDescriptor
+} from './schemas/descriptors';
+
+// CLI command descriptors
+import completionDescriptor from './commands/completion/completion.descriptor';
+import { runtimeCodegenCommandDescriptor } from './commands/runtime/codegen.command.descriptor';
+import { runtimeCodegenCommandImpl } from './commands/runtime/codegen.command.impl';
+import uiContextDescriptor from './ui.context.descriptor';
+import cliStartupLogger from './logging/cli-startup.logger.descriptor';
+import runtimeGroup from './commands/runtime/runtime-group.descriptor';
+
+// Profile descriptors
+import profileGroupDescriptor from './commands/profile/profile-group.descriptor';
+import profileListDescriptor from './commands/profile/profile.list.descriptor';
+import profileCreateDescriptor from './commands/profile/profile.create.descriptor';
+import profileUseDescriptor from './commands/profile/profile.use.descriptor';
+import profileDeleteDescriptor from './commands/profile/profile.delete.descriptor';
+import profileInfoDescriptor from './commands/profile/profile.info.descriptor';
+
+// Docs
+import cliCommandsDescriptor from './docs/cli.commands.docs.descriptor.ts';
+import cliGroupsDescriptor from './docs/cli.groups.docs.descriptor.ts';
+import cliOutputDescriptor from './docs/cli.output.docs.descriptor.ts';
+
+/**
+ * CLI Group kind - metadata only, no implementation needed
+ */
+function isCLIGroupAssetDescriptor(
+	descriptor: RuntimeDescriptor
+): descriptor is CLIGroupAssetDescriptor {
+	return descriptor.kind === 'cli/group' && typeof descriptor.id === 'string';
+}
+
+class DefaultCLIGroupImplementation {
+	constructor(public readonly descriptor: CLIGroupAssetDescriptor) {}
+}
+
+const cliGroupKind = {
+	id: 'cli/group',
+	descriptorSchema: CLIGroupDescriptorSchema,
+	defaultImplementation: class {
+		readonly descriptor: CLIGroupAssetDescriptor;
+
+		constructor(descriptor: RuntimeDescriptor) {
+			if (!isCLIGroupAssetDescriptor(descriptor)) {
+				throw new Error(`Invalid cli/group descriptor '${descriptor.id ?? 'unknown'}'`);
+			}
+			this.descriptor = descriptor;
+		}
+	},
+
+	// Resolution: prefer explicit scope matches
+	resolve: (candidates: RuntimeDescriptor[], scope: RuntimeScope) => {
+		const descriptors = candidates.filter(isCLIGroupAssetDescriptor);
+		if (descriptors.length === 0) return undefined;
+		if (descriptors.length === 1) return descriptors[0];
+
+		// Filter by surface
+		let matches = descriptors.filter((d) => {
+			if (!d.surfaces || d.surfaces.length === 0) return true;
+			return d.surfaces.includes(scope.surface as (typeof d.surfaces)[number]);
+		});
+
+		if (matches.length === 0) return undefined;
+
+		// Filter by hardware
+		matches = matches.filter((d) => {
+			if (!d.hardware || d.hardware.length === 0) return true;
+			return d.hardware.includes(scope.hardware);
+		});
+
+		// Sort by order, return first
+		matches.sort((a, b) => (a.order ?? 999) - (b.order ?? 999));
+		return matches[0];
+	},
+
+	contexts: []
+} satisfies RuntimeKindDescriptorRecord<DefaultCLIGroupImplementation>;
+
+/**
+ * CLI Command kind - requires implementation with execute()
+ */
+function isCLICommandAssetDescriptor(
+	descriptor: RuntimeDescriptor
+): descriptor is CLICommandAssetDescriptor {
+	return (
+		descriptor.kind === 'cli/command' && typeof descriptor.id === 'string' && 'group' in descriptor
+	);
+}
+
+class DefaultCLICommandImplementation {
+	readonly descriptor: CLICommandAssetDescriptor;
+
+	constructor(descriptor: RuntimeDescriptor) {
+		if (!isCLICommandAssetDescriptor(descriptor)) {
+			throw new Error(`Invalid cli/command descriptor '${descriptor.id ?? 'unknown'}'`);
+		}
+		this.descriptor = descriptor;
+	}
+
+	async execute(_args: Record<string, unknown>, _opts: Record<string, unknown>): Promise<void> {
+		throw new Error(`No implementation for command: ${this.descriptor.id}`);
+	}
+}
+
+const cliCommandKind = {
+	id: 'cli/command',
+	descriptorSchema: CLICommandDescriptorSchema,
+	defaultImplementation: DefaultCLICommandImplementation,
+
+	// Resolution: prefer explicit scope matches
+	resolve: (candidates: RuntimeDescriptor[], scope: RuntimeScope) => {
+		const descriptors = candidates.filter(isCLICommandAssetDescriptor);
+		if (descriptors.length === 0) return undefined;
+		if (descriptors.length === 1) return descriptors[0];
+
+		// Filter by surface
+		let matches = descriptors.filter((d) => {
+			if (!d.surfaces || d.surfaces.length === 0) return true;
+			return d.surfaces.includes(scope.surface as (typeof d.surfaces)[number]);
+		});
+
+		if (matches.length === 0) return undefined;
+
+		// Filter by hardware
+		matches = matches.filter((d) => {
+			if (!d.hardware || d.hardware.length === 0) return true;
+			return d.hardware.includes(scope.hardware);
+		});
+
+		// Sort by order, return first
+		matches.sort((a, b) => (a.order ?? 999) - (b.order ?? 999));
+		return matches[0];
+	},
+
+	// Commands receive runtime context
+	contexts: ['runtime']
+} satisfies RuntimeKindDescriptorRecord<DefaultCLICommandImplementation>;
+
+/**
+ * CLI Plugin
+ *
+ * Registers cli/group and cli/command kinds with the universal runtime.
+ * CLISurface queries these kinds to build the Commander.js command tree.
+ */
+export default createRuntimePlugin({
+	id: 'cli',
+	name: 'CLI Surface',
+	description: 'CLI command system using Commander.js',
+	dependencies: ['context'],
+	kinds: [cliGroupKind, cliCommandKind],
+
+	descriptors: [
+		completionDescriptor,
+		runtimeCodegenCommandDescriptor,
+		uiContextDescriptor,
+		cliStartupLogger,
+		runtimeGroup,
+		profileGroupDescriptor,
+		profileListDescriptor,
+		profileCreateDescriptor,
+		profileUseDescriptor,
+		profileDeleteDescriptor,
+		profileInfoDescriptor,
+		cliCommandsDescriptor,
+		cliGroupsDescriptor,
+		cliOutputDescriptor
+	],
+
+	loaders: [
+		loader('completion', () => import('./commands/completion/completion.impl.ts')),
+		loader('profile.list', () => import('./commands/profile/profile.list.impl.ts')),
+		loader('profile.create', () => import('./commands/profile/profile.create.impl.ts')),
+		loader('profile.use', () => import('./commands/profile/profile.use.impl.ts')),
+		loader('profile.delete', () => import('./commands/profile/profile.delete.impl.ts')),
+		loader('profile.info', () => import('./commands/profile/profile.info.impl.ts'))
+	]
+});

package/src/commands/completion/bash.ts

@@ -0,0 +1,68 @@
+/**
+ * Bash Completion Generator
+ *
+ * Generates a bash completion function from the command tree.
+ */
+
+import type { CommandNode } from './tree';
+
+function generateCaseBlock(path: string, node: CommandNode, indent: string): string[] {
+	const lines: string[] = [];
+	if (node.children.length === 0) return lines;
+
+	const childNames = node.children.flatMap((c) => [c.name, ...c.aliases]).join(' ');
+	lines.push(`${indent}${path})`);
+	lines.push(`${indent}    COMPREPLY=( $(compgen -W "${childNames}" -- "\${cur}") )`);
+	lines.push(`${indent}    return 0`);
+	lines.push(`${indent}    ;;`);
+
+	for (const child of node.children) {
+		if (child.children.length > 0) {
+			lines.push(...generateCaseBlock(`${path} ${child.name}`, child, indent));
+			for (const alias of child.aliases) {
+				lines.push(...generateCaseBlock(`${path} ${alias}`, child, indent));
+			}
+		}
+	}
+
+	return lines;
+}
+
+export function generateBashCompletion(tree: CommandNode): string {
+	const cases = generateCaseBlock('vibes', tree, '        ');
+
+	return `# vibes bash completion — generated by vibes completion bash
+# Add to ~/.bashrc: eval "$(vibes completion bash)"
+
+_vibes_completions() {
+    local cur prev words cword
+    _init_completion || return
+
+    local cmd="\${words[*]:0:cword}"
+
+    case "\${cmd}" in
+${cases.join('\n')}
+    esac
+
+    # Option completion
+    if [[ "\${cur}" == -* ]]; then
+        local opts=""
+        case "\${cmd}" in
+${tree.children
+	.flatMap((g) =>
+		g.children.map((c) => {
+			const opts = c.options.map((o) => (o.short ? `-${o.short} --${o.long}` : `--${o.long}`)).join(' ');
+			return opts ? `            vibes ${g.name} ${c.name}) opts="${opts}" ;;` : '';
+		})
+	)
+	.filter(Boolean)
+	.join('\n')}
+        esac
+        COMPREPLY=( $(compgen -W "\${opts}" -- "\${cur}") )
+        return 0
+    fi
+}
+
+complete -F _vibes_completions vibes
+`;
+}

package/src/commands/completion/completion.descriptor.ts

@@ -0,0 +1,48 @@
+/**
+ * Shell Completion Generator Command Descriptor
+ *
+ * Generates shell completions and autosuggestions from runtime descriptors.
+ * Supports bash, zsh (with inline autosuggestion widget), fish, and fig specs.
+ */
+
+import type { CLICommandAssetDescriptor } from '../../schemas/descriptors';
+
+const descriptor: CLICommandAssetDescriptor = {
+	kind: 'cli/command',
+	id: 'completion',
+	name: 'completion',
+	description: 'Generate shell completions and autosuggestions',
+	group: 'shell-integration',
+
+	arguments: [
+		{
+			name: 'shell',
+			description: 'Target shell: bash, zsh, fish, or fig',
+			required: true
+		}
+	],
+
+	options: [
+		{
+			flags: '--json',
+			description: 'Output command tree as JSON (for tooling)'
+		},
+		{
+			flags: '--install',
+			description: 'Install to standard shell completion directory'
+		}
+	],
+
+	examples: [
+		{ command: 'vibes completion zsh', description: 'Output zsh completions with autosuggestions' },
+		{ command: 'eval "$(vibes completion zsh)"', description: 'Enable in current shell' },
+		{ command: 'vibes completion fig', description: 'Generate Fig/Amazon Q completion spec' },
+		{ command: 'vibes completion --json', description: 'Output raw command tree as JSON' }
+	],
+
+	surfaces: ['cli'],
+	hardware: ['consumer'],
+	enabled: true
+};
+
+export default descriptor;

package/src/commands/completion/completion.impl.ts

@@ -0,0 +1,188 @@
+/**
+ * Shell Completion Generator Implementation
+ *
+ * Builds the CLI command tree from runtime descriptors and generates
+ * shell-specific completion scripts. The zsh output includes an inline
+ * autosuggestion widget with history-based ranking.
+ */
+
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+import { existsSync, readFileSync, appendFileSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+import { buildCommandTree } from './tree';
+import { generateBashCompletion } from './bash';
+import { generateZshCompletion } from './zsh';
+import { generateFishCompletion } from './fish';
+import { generateFigSpec } from './fig';
+
+interface CompletionOptions {
+	json?: boolean;
+	install?: boolean;
+}
+
+const SHELLS = ['bash', 'zsh', 'fish', 'fig'] as const;
+type Shell = (typeof SHELLS)[number];
+
+const GREEN = '\x1b[32m';
+const GRAY = '\x1b[90m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+function getInstallPath(shell: Shell): string {
+	const home = homedir();
+	switch (shell) {
+		case 'bash':
+			return join(home, '.bash_completion.d', 'vibes');
+		case 'zsh':
+			return join(home, '.zsh', 'completions', '_vibes');
+		case 'fish':
+			return join(home, '.config', 'fish', 'completions', 'vibes.fish');
+		case 'fig':
+			return join(home, '.fig', 'autocomplete', 'vibes.ts');
+	}
+}
+
+function getProfilePath(shell: Shell): string | null {
+	const home = homedir();
+	switch (shell) {
+		case 'bash': {
+			const bashrc = join(home, '.bashrc');
+			const profile = join(home, '.bash_profile');
+			return existsSync(bashrc) ? bashrc : profile;
+		}
+		case 'zsh':
+			return join(home, '.zshrc');
+		case 'fish':
+			return null;
+		case 'fig':
+			return null;
+	}
+}
+
+function getProfileLine(shell: Shell, installPath: string): string | null {
+	switch (shell) {
+		case 'bash':
+			return `[[ -f "${installPath}" ]] && source "${installPath}"`;
+		case 'zsh':
+			return `[[ -f "${installPath}" ]] && source "${installPath}"`;
+		case 'fish':
+		case 'fig':
+			return null;
+	}
+}
+
+function profileAlreadyConfigured(profilePath: string, shell: Shell): boolean {
+	if (!existsSync(profilePath)) return false;
+	const content = readFileSync(profilePath, 'utf-8');
+	return content.includes('vibes completion') || content.includes('_vibes');
+}
+
+function generateScript(shell: Shell, tree: ReturnType<typeof buildCommandTree>): string {
+	switch (shell) {
+		case 'bash':
+			return generateBashCompletion(tree);
+		case 'zsh':
+			return generateZshCompletion(tree);
+		case 'fish':
+			return generateFishCompletion(tree);
+		case 'fig':
+			return generateFigSpec(tree);
+	}
+}
+
+function log(msg: string): void {
+	process.stderr.write(msg + '\n');
+}
+
+export default {
+	async execute(args: Record<string, unknown>, opts: Record<string, unknown>): Promise<void> {
+		const options = opts as CompletionOptions;
+		const runtime = getVibesRuntime();
+		const tree = buildCommandTree(runtime);
+
+		if (options.json) {
+			process.stdout.write(`${JSON.stringify(tree, null, 2)}\n`);
+			return;
+		}
+
+		const shell = args.shell as string;
+		if (!SHELLS.includes(shell as Shell)) {
+			log(`${RED}✗${RESET} Unknown shell: ${BOLD}${shell}${RESET}`);
+			log(`  Supported: ${SHELLS.join(', ')}`);
+			process.exit(1);
+		}
+
+		const script = generateScript(shell as Shell, tree);
+
+		if (!options.install) {
+			process.stdout.write(script);
+			return;
+		}
+
+		const installPath = getInstallPath(shell as Shell);
+		const cmdCount = countCommands(tree);
+
+		log('');
+		log(`${BOLD}vibes completion${RESET} ${GRAY}${shell}${RESET}`);
+		log(`${'─'.repeat(50)}`);
+
+		// Write completion script
+		const dir = dirname(installPath);
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+		await Bun.write(installPath, script);
+		log(`  ${GREEN}✓${RESET} Wrote completion script ${GRAY}(${cmdCount} commands)${RESET}`);
+		log(`    ${GRAY}${installPath}${RESET}`);
+
+		// Append to profile if needed
+		const profilePath = getProfilePath(shell as Shell);
+		const profileLine = getProfileLine(shell as Shell, installPath);
+
+		if (profilePath && profileLine) {
+			if (profileAlreadyConfigured(profilePath, shell as Shell)) {
+				log(`  ${GREEN}✓${RESET} Shell profile already configured`);
+				log(`    ${GRAY}${profilePath}${RESET}`);
+			} else {
+				const marker = '\n# vibes shell completion\n';
+				appendFileSync(profilePath, marker + profileLine + '\n');
+				log(`  ${GREEN}✓${RESET} Appended to shell profile`);
+				log(`    ${GRAY}${profilePath}${RESET}`);
+			}
+		} else if (shell === 'fish') {
+			log(`  ${GREEN}✓${RESET} Fish loads completions automatically`);
+		} else if (shell === 'fig') {
+			log(`  ${GREEN}✓${RESET} Amazon Q / Inshellisense will load spec automatically`);
+		}
+
+		// Features summary
+		log('');
+		log(`  ${BOLD}Features:${RESET}`);
+		log(`    ${GREEN}✓${RESET} Tab completion for all vibes commands`);
+		if (shell === 'zsh') {
+			log(`    ${GREEN}✓${RESET} zsh-autosuggestions integration ${GRAY}(inline ghost-text)${RESET}`);
+			log(`    ${GREEN}✓${RESET} Custom vibes strategy ${GRAY}(suggests from 296 known commands)${RESET}`);
+		}
+		if (shell === 'fig') {
+			log(`    ${GREEN}✓${RESET} Rich dropdown UI in supported terminals`);
+			log(`    ${GREEN}✓${RESET} Dynamic argument generators`);
+		}
+
+		log('');
+		log(`  ${YELLOW}⏭${RESET}  Restart your shell or run: ${BOLD}source ${profilePath ?? installPath}${RESET}`);
+		log('');
+	}
+};
+
+function countCommands(tree: ReturnType<typeof buildCommandTree>): number {
+	let count = 0;
+	for (const child of tree.children) {
+		if (child.children.length > 0) {
+			count += countCommands(child);
+		} else {
+			count++;
+		}
+	}
+	return count;
+}