@vibesdotdev/cli 0.0.1

package/src/schemas/types.d.ts

@@ -0,0 +1,195 @@
+import type { RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/descriptor';
+export type CLISurfaceTarget = 'cli' | 'web' | 'worker' | 'bridge';
+export interface PatternTarget {
+    kind: string;
+    id: string;
+    variant?: string;
+}
+export interface CLILogBufferBehavior {
+    enabled?: boolean;
+    sinks?: string[];
+    fallbackToStdout?: boolean;
+}
+export interface CLIGroupAssetDescriptor extends RuntimeDescriptor {
+    kind: 'cli/group';
+    name: string;
+    description: string;
+    parent?: string;
+    aliases?: string[];
+    surfaces?: CLISurfaceTarget[];
+    internal?: boolean;
+    order?: number;
+    logBuffer?: CLILogBufferBehavior;
+}
+export interface CLICommandArgument {
+    name: string;
+    description: string;
+    required?: boolean;
+    variadic?: boolean;
+    default?: unknown;
+}
+export interface CLICommandOption {
+    flags: string;
+    description: string;
+    default?: unknown;
+    choices?: string[];
+}
+export interface CLICommandExample {
+    command: string;
+    description: string;
+}
+export interface CLICommandAssetDescriptor extends RuntimeDescriptor {
+    kind: 'cli/command';
+    name: string;
+    description: string;
+    group: string;
+    arguments?: CLICommandArgument[];
+    options?: CLICommandOption[];
+    aliases?: string[];
+    surfaces?: CLISurfaceTarget[];
+    internal?: boolean;
+    examples?: CLICommandExample[];
+    order?: number;
+    tuiAppId?: string;
+    logBuffer?: CLILogBufferBehavior;
+}
+export interface CRUDPatternConfig {
+    list?: {
+        enabled?: boolean;
+        defaultFormat?: 'table' | 'json' | 'yaml';
+        columns?: string[];
+        sortBy?: string;
+        paginate?: boolean;
+    };
+    get?: {
+        enabled?: boolean;
+        idParam?: string;
+    };
+    create?: {
+        enabled?: boolean;
+        interactive?: boolean;
+        promptFields?: string[];
+    };
+    update?: {
+        enabled?: boolean;
+        editableFields?: string[];
+    };
+    delete?: {
+        enabled?: boolean;
+        confirm?: boolean;
+        bulk?: boolean;
+    };
+}
+export interface ToolWrapperPatternConfig {
+    arguments?: Array<{
+        name: string;
+        toolParam: string;
+        description?: string;
+        required?: boolean;
+        variadic?: boolean;
+    }>;
+    options?: Array<{
+        flags: string;
+        toolParam: string;
+        description?: string;
+        default?: unknown;
+        choices?: string[];
+    }>;
+    output?: {
+        format?: 'raw' | 'json' | 'yaml' | 'table';
+        extractField?: string;
+    };
+}
+export interface LogViewerPatternConfig {
+    source: 'worker' | 'file' | 'stream';
+    defaultLines?: number;
+    follow?: boolean;
+    defaultLevels?: string[];
+    filters?: Array<{
+        name: string;
+        flag: string;
+        description: string;
+    }>;
+}
+export interface ProcessManagerPatternConfig {
+    processId: string;
+    commands?: {
+        start?: boolean;
+        stop?: boolean;
+        restart?: boolean;
+        status?: boolean;
+        logs?: boolean;
+    };
+    healthCheck?: {
+        url?: string;
+        interval?: number;
+    };
+}
+export interface ConfigNamespacePatternConfig {
+    namespace: string;
+    schema?: string;
+    defaults?: Record<string, unknown>;
+    commands?: {
+        get?: boolean;
+        set?: boolean;
+        reset?: boolean;
+        edit?: boolean;
+    };
+}
+export interface CLICRUDGroupDescriptor extends RuntimeDescriptor {
+    kind: 'cli/group';
+    name: string;
+    description: string;
+    parent?: string;
+    pattern: 'crud';
+    target: PatternTarget;
+    crud: CRUDPatternConfig;
+    surfaces?: CLISurfaceTarget[];
+    internal?: boolean;
+}
+export interface CLIToolWrapperCommandDescriptor extends RuntimeDescriptor {
+    kind: 'cli/command';
+    name: string;
+    description?: string;
+    group: string;
+    pattern: 'tool-wrapper';
+    target: PatternTarget;
+    toolWrapper: ToolWrapperPatternConfig;
+    surfaces?: CLISurfaceTarget[];
+    internal?: boolean;
+    order?: number;
+}
+export interface CLILogViewerGroupDescriptor extends RuntimeDescriptor {
+    kind: 'cli/group';
+    name: string;
+    description: string;
+    parent?: string;
+    pattern: 'log-viewer';
+    target: PatternTarget;
+    logViewer: LogViewerPatternConfig;
+    surfaces?: CLISurfaceTarget[];
+    internal?: boolean;
+}
+export interface CLIProcessManagerGroupDescriptor extends RuntimeDescriptor {
+    kind: 'cli/group';
+    name: string;
+    description: string;
+    parent?: string;
+    pattern: 'process-manager';
+    target: PatternTarget;
+    processManager: ProcessManagerPatternConfig;
+    surfaces?: CLISurfaceTarget[];
+    internal?: boolean;
+}
+export interface CLIConfigNamespaceGroupDescriptor extends RuntimeDescriptor {
+    kind: 'cli/group';
+    name: string;
+    description: string;
+    parent?: string;
+    pattern: 'config-namespace';
+    target?: PatternTarget;
+    configNamespace: ConfigNamespacePatternConfig;
+    surfaces?: CLISurfaceTarget[];
+    internal?: boolean;
+}
+export type CLIPatternDescriptor = CLICRUDGroupDescriptor | CLIToolWrapperCommandDescriptor | CLILogViewerGroupDescriptor | CLIProcessManagerGroupDescriptor | CLIConfigNamespaceGroupDescriptor;

package/src/schemas/types.ts

@@ -0,0 +1,225 @@
+import type { RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/descriptor';
+
+export type CLISurfaceTarget = 'cli' | 'web' | 'worker' | 'bridge';
+
+export interface PatternTarget {
+	kind: string;
+	id: string;
+	variant?: string;
+}
+
+export interface CLILogBufferBehavior {
+	enabled?: boolean;
+	sinks?: string[];
+	fallbackToStdout?: boolean;
+}
+
+export interface CLIGroupAssetDescriptor extends RuntimeDescriptor {
+	kind: 'cli/group';
+	name: string;
+	description: string;
+	parent?: string;
+	aliases?: string[];
+	surfaces?: CLISurfaceTarget[];
+	internal?: boolean;
+	order?: number;
+	logBuffer?: CLILogBufferBehavior;
+}
+
+export interface CLICommandArgument {
+	name: string;
+	description: string;
+	required?: boolean;
+	variadic?: boolean;
+	default?: unknown;
+}
+
+export interface CLICommandOption {
+	flags: string;
+	description: string;
+	default?: unknown;
+	choices?: string[];
+	/**
+	 * Coerce parsed option value. Commander returns user-supplied option values
+	 * as strings by default; declaring `type: 'number'` makes the surface call
+	 * `.argParser(Number)` so impls receive a real number.
+	 */
+	type?: 'string' | 'number' | 'boolean';
+}
+
+export interface CLICommandExample {
+	command: string;
+	description: string;
+}
+
+export interface CLICommandAssetDescriptor extends RuntimeDescriptor {
+	kind: 'cli/command';
+	name: string;
+	description: string;
+	group: string;
+	arguments?: CLICommandArgument[];
+	options?: CLICommandOption[];
+	aliases?: string[];
+	surfaces?: CLISurfaceTarget[];
+	internal?: boolean;
+	examples?: CLICommandExample[];
+	order?: number;
+	tuiAppId?: string;
+	logBuffer?: CLILogBufferBehavior;
+}
+
+export interface CRUDPatternConfig {
+	list?: {
+		enabled?: boolean;
+		defaultFormat?: 'table' | 'json' | 'yaml';
+		columns?: string[];
+		sortBy?: string;
+		paginate?: boolean;
+	};
+	get?: {
+		enabled?: boolean;
+		idParam?: string;
+	};
+	create?: {
+		enabled?: boolean;
+		interactive?: boolean;
+		promptFields?: string[];
+	};
+	update?: {
+		enabled?: boolean;
+		editableFields?: string[];
+	};
+	delete?: {
+		enabled?: boolean;
+		confirm?: boolean;
+		bulk?: boolean;
+	};
+}
+
+export interface ToolWrapperPatternConfig {
+	arguments?: Array<{
+		name: string;
+		toolParam: string;
+		description?: string;
+		required?: boolean;
+		variadic?: boolean;
+	}>;
+	options?: Array<{
+		flags: string;
+		toolParam: string;
+		description?: string;
+		default?: unknown;
+		choices?: string[];
+	}>;
+	output?: {
+		format?: 'raw' | 'json' | 'yaml' | 'table';
+		extractField?: string;
+	};
+}
+
+export interface LogViewerPatternConfig {
+	source: 'worker' | 'file' | 'stream';
+	defaultLines?: number;
+	follow?: boolean;
+	defaultLevels?: string[];
+	filters?: Array<{
+		name: string;
+		flag: string;
+		description: string;
+	}>;
+}
+
+export interface ProcessManagerPatternConfig {
+	processId: string;
+	commands?: {
+		start?: boolean;
+		stop?: boolean;
+		restart?: boolean;
+		status?: boolean;
+		logs?: boolean;
+	};
+	healthCheck?: {
+		url?: string;
+		interval?: number;
+	};
+}
+
+export interface ConfigNamespacePatternConfig {
+	namespace: string;
+	schema?: string;
+	defaults?: Record<string, unknown>;
+	commands?: {
+		get?: boolean;
+		set?: boolean;
+		reset?: boolean;
+		edit?: boolean;
+	};
+}
+
+export interface CLICRUDGroupDescriptor extends RuntimeDescriptor {
+	kind: 'cli/group';
+	name: string;
+	description: string;
+	parent?: string;
+	pattern: 'crud';
+	target: PatternTarget;
+	crud: CRUDPatternConfig;
+	surfaces?: CLISurfaceTarget[];
+	internal?: boolean;
+}
+
+export interface CLIToolWrapperCommandDescriptor extends RuntimeDescriptor {
+	kind: 'cli/command';
+	name: string;
+	description?: string;
+	group: string;
+	pattern: 'tool-wrapper';
+	target: PatternTarget;
+	toolWrapper: ToolWrapperPatternConfig;
+	surfaces?: CLISurfaceTarget[];
+	internal?: boolean;
+	order?: number;
+}
+
+export interface CLILogViewerGroupDescriptor extends RuntimeDescriptor {
+	kind: 'cli/group';
+	name: string;
+	description: string;
+	parent?: string;
+	pattern: 'log-viewer';
+	target: PatternTarget;
+	logViewer: LogViewerPatternConfig;
+	surfaces?: CLISurfaceTarget[];
+	internal?: boolean;
+}
+
+export interface CLIProcessManagerGroupDescriptor extends RuntimeDescriptor {
+	kind: 'cli/group';
+	name: string;
+	description: string;
+	parent?: string;
+	pattern: 'process-manager';
+	target: PatternTarget;
+	processManager: ProcessManagerPatternConfig;
+	surfaces?: CLISurfaceTarget[];
+	internal?: boolean;
+}
+
+export interface CLIConfigNamespaceGroupDescriptor extends RuntimeDescriptor {
+	kind: 'cli/group';
+	name: string;
+	description: string;
+	parent?: string;
+	pattern: 'config-namespace';
+	target?: PatternTarget;
+	configNamespace: ConfigNamespacePatternConfig;
+	surfaces?: CLISurfaceTarget[];
+	internal?: boolean;
+}
+
+export type CLIPatternDescriptor =
+	| CLICRUDGroupDescriptor
+	| CLIToolWrapperCommandDescriptor
+	| CLILogViewerGroupDescriptor
+	| CLIProcessManagerGroupDescriptor
+	| CLIConfigNamespaceGroupDescriptor;

package/src/support/ui-toolkit.ts

@@ -0,0 +1,224 @@
+import YAML from 'yaml';
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+function isInteractive(): boolean {
+	return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+function writeOut(message: string): void {
+	process.stdout.write(`${message}\n`);
+}
+
+function writeErr(message: string): void {
+	process.stderr.write(`${message}\n`);
+}
+
+export class VibesUIToolkit {
+	private format: 'json' | 'yaml' | 'table' | 'markdown' = 'table';
+
+	constructor(_options: { mode?: 'rich' | 'plain'; compact?: boolean; autoExit?: boolean } = {}) {}
+
+	static createSync(
+		options: { mode?: 'rich' | 'plain'; compact?: boolean; autoExit?: boolean } = {}
+	): VibesUIToolkit {
+		return new VibesUIToolkit(options);
+	}
+
+	setFormat(format: 'json' | 'yaml' | 'table' | 'markdown'): void {
+		this.format = format;
+	}
+
+	info(message: string): void {
+		writeOut(message);
+	}
+
+	success(message: string): void {
+		writeOut(message);
+	}
+
+	warn(message: string): void {
+		writeErr(message);
+	}
+
+	warning(message: string): void {
+		this.warn(message);
+	}
+
+	error(message: string): void {
+		writeErr(message);
+	}
+
+	log(message: string): void {
+		writeOut(message);
+	}
+
+	async prompt(message: string, options: { default?: string } = {}): Promise<string | null> {
+		if (!isInteractive()) {
+			return options.default ?? null;
+		}
+		const rl = createInterface({ input, output });
+		try {
+			const suffix = options.default ? ` [${options.default}]` : '';
+			const answer = await rl.question(`${message}${suffix}: `);
+			const trimmed = answer.trim();
+			if (trimmed.length > 0) {
+				return trimmed;
+			}
+			return options.default ?? null;
+		} finally {
+			rl.close();
+		}
+	}
+
+	async confirm(
+		message: string | { message: string; defaultValue?: boolean },
+		defaultValue = false
+	): Promise<boolean> {
+		const promptText = typeof message === 'string' ? message : message.message;
+		const initial =
+			typeof message === 'string' ? defaultValue : (message.defaultValue ?? defaultValue);
+		const response = await this.prompt(`${promptText} [y/N]`, { default: initial ? 'y' : 'n' });
+		return response?.toLowerCase().startsWith('y') ?? initial;
+	}
+
+	async select<T>(
+		message: string,
+		options: Array<{ label: string; value: T }>,
+		defaultValue?: T
+	): Promise<T | null> {
+		if (options.length === 0) {
+			return null;
+		}
+		if (!isInteractive()) {
+			return defaultValue ?? options[0]?.value ?? null;
+		}
+		this.info(message);
+		options.forEach((option, index) => this.info(`${index + 1}. ${option.label}`));
+		const response = await this.prompt('Select option number', { default: '1' });
+		const index = Math.max(1, Number(response || '1')) - 1;
+		return options[index]?.value ?? defaultValue ?? null;
+	}
+
+	async multiselect<T>(
+		message: string,
+		options: Array<{ label: string; value: T }>,
+		required = false
+	): Promise<T[]> {
+		if (options.length === 0) {
+			return [];
+		}
+		if (!isInteractive()) {
+			return required ? [options[0].value] : [];
+		}
+		this.info(message);
+		options.forEach((option, index) => this.info(`${index + 1}. ${option.label}`));
+		const response = await this.prompt('Select comma-separated option numbers');
+		if (!response) {
+			return required ? [options[0].value] : [];
+		}
+		const values = response
+			.split(',')
+			.map((part) => Number(part.trim()) - 1)
+			.filter((index) => Number.isInteger(index) && index >= 0 && index < options.length)
+			.map((index) => options[index].value);
+		return values.length > 0 || !required ? values : [options[0].value];
+	}
+
+	table(data: unknown[], options?: { columns?: string[] } | string | string[]): void {
+		if (this.format === 'json') return this.json(data);
+		if (this.format === 'yaml') return this.yaml(data);
+		const normalized = Array.isArray(options)
+			? { columns: options }
+			: typeof options === 'string'
+				? { title: options }
+				: options;
+		if (normalized && 'title' in normalized && normalized.title) writeOut(normalized.title);
+		if (
+			Array.isArray(data) &&
+			normalized &&
+			'columns' in normalized &&
+			normalized.columns?.length
+		) {
+			const rows = data.map((row) =>
+				!row || typeof row !== 'object'
+					? row
+					: Object.fromEntries(
+							normalized.columns!.map((column) => [
+								column,
+								(row as Record<string, unknown>)[column]
+							])
+						)
+			);
+			console.table(rows);
+			return;
+		}
+		console.table(data);
+	}
+
+	json(data: unknown): void {
+		writeOut(JSON.stringify(data, null, 2));
+	}
+
+	yaml(data: unknown): void {
+		writeOut(YAML.stringify(data));
+	}
+
+	keyValue(data: Record<string, unknown>): void {
+		this.table(Object.entries(data).map(([key, value]) => ({ key, value })));
+	}
+
+	/**
+	 * Render a value in a caller-selected format. Convenience over `json`/`yaml`/
+	 * `table` for command impls that defer format to an `--output` flag.
+	 */
+	render(
+		data: unknown,
+		options: { format?: 'json' | 'yaml' | 'table' | 'markdown' | 'text' } = {}
+	): void {
+		const format = options.format ?? this.format;
+		switch (format) {
+			case 'json':
+				this.json(data);
+				return;
+			case 'yaml':
+				this.yaml(data);
+				return;
+			case 'table':
+				this.table(Array.isArray(data) ? data : [data]);
+				return;
+			case 'markdown':
+			case 'text':
+			default:
+				writeOut(typeof data === 'string' ? data : JSON.stringify(data, null, 2));
+				return;
+		}
+	}
+
+	progress(message?: string): {
+		update: (nextMessage?: string) => void;
+		complete: (nextMessage?: string) => void;
+		fail: (nextMessage?: string) => void;
+	} {
+		if (message) writeOut(message);
+		return {
+			update: (nextMessage?: string) => nextMessage && writeOut(nextMessage),
+			complete: (nextMessage?: string) => nextMessage && writeOut(nextMessage),
+			fail: (nextMessage?: string) => nextMessage && writeErr(nextMessage)
+		};
+	}
+
+	async withCommand<T>(
+		_command: { name?: string; description?: string },
+		handler: (toolkit: VibesUIToolkit) => Promise<T> | T
+	): Promise<T> {
+		return await handler(this);
+	}
+
+	async withInteractiveCommand<T>(
+		command: { name?: string; description?: string },
+		handler: (toolkit: VibesUIToolkit) => Promise<T> | T
+	): Promise<T> {
+		return this.withCommand(command, handler);
+	}
+}