@vibesdotdev/cli 0.0.1

package/src/providers.ts

@@ -0,0 +1,282 @@
+/**
+ * CLI Context Providers
+ *
+ * Registers CLI-specific context providers with the universal runtime.
+ * These contexts are available to CLI commands and patterns.
+ */
+
+import type { VibesRuntime } from '@vibesdotdev/runtime/api/runtime';
+import { VibesUIToolkit } from './support/ui-toolkit';
+import { getLogger } from './logging';
+
+const providerLogger = getLogger('providers');
+
+/**
+ * UI Context - output formatting and display
+ */
+export interface UIContext {
+	info(message: string): void;
+	success(message: string): void;
+	warn(message: string): void;
+	error(message: string): void;
+	log(message: string): void;
+	table(data: unknown[], options?: { columns?: string[] } | string | string[]): void;
+	json(data: unknown): void;
+	yaml(data: unknown): void;
+	keyValue(data: Record<string, unknown>): void;
+	progress(message?: string): {
+		update: (nextMessage?: string) => void;
+		complete: (nextMessage?: string) => void;
+		fail: (nextMessage?: string) => void;
+	};
+	setFormat(format: 'json' | 'yaml' | 'table' | 'markdown'): void;
+	/**
+	 * Render a value in a caller-selected format. Higher-level convenience over
+	 * `json` / `yaml` / `table` used by command implementations that defer their
+	 * output format to an `--output` flag.
+	 */
+	render(
+		data: unknown,
+		options?: { format?: 'json' | 'yaml' | 'table' | 'markdown' | 'text' }
+	): void | Promise<void>;
+}
+
+/**
+ * Logger Context - structured logging
+ */
+export interface LoggerContext {
+	info(message: string, meta?: unknown): void;
+	warn(message: string, meta?: unknown): void;
+	error(message: string, meta?: unknown): void;
+	debug(message: string, meta?: unknown): void;
+}
+
+/**
+ * App Context - lifecycle control
+ */
+export interface AppContext {
+	keepAlive(): void;
+	shouldKeepAlive(): boolean;
+	exit(code?: number): void;
+}
+
+export interface ConfigContext {
+	get(key: string): Promise<unknown>;
+	set(key: string, value: unknown): Promise<void>;
+	getNamespace(namespace: string): Promise<Record<string, unknown>>;
+	delete(key: string): Promise<void>;
+}
+
+/**
+ * Signal used to abort command execution without forcing process termination.
+ * CLISurface catches this and lets the process unwind naturally.
+ */
+export class CLIExitSignal extends Error {
+	constructor(public readonly code: number) {
+		super(`CLI requested exit with code ${code}`);
+		this.name = 'CLIExitSignal';
+	}
+}
+
+export function requestCLIExit(code = 0): never {
+	process.exitCode = code;
+	throw new CLIExitSignal(code);
+}
+
+/**
+ * CLI Invocation Context - how the CLI was invoked
+ */
+export interface CLIContext {
+	command: string[];
+	bin: string;
+	script?: string;
+	cwd: string;
+	args: string[];
+}
+
+/**
+ * Options for CLI provider registration
+ */
+export interface CLIProviderOptions {
+	verbose?: boolean;
+	format?: 'json' | 'yaml' | 'table' | 'markdown';
+}
+
+// Shared state for keepAlive across the process
+let keepAliveFlag = false;
+
+function makeContextLoader(id: string, factory: () => unknown) {
+	return async () => ({
+		meta: { id, kind: 'context', priority: 0 },
+		impl: { provide: factory }
+	});
+}
+
+/**
+ * Register CLI context providers with the runtime
+ *
+ * Call this before initializing CLISurface.
+ */
+export function registerCLIProviders(
+	runtime: VibesRuntime,
+	options: CLIProviderOptions = {}
+): void {
+	const format = options.format ?? detectOutputFormat();
+
+	// Debug: Check if context kind exists
+	if (!runtime.hasKind('context')) {
+		throw new Error('Context kind not registered - cannot register CLI providers');
+	}
+
+	const ctx = runtime.assets('context');
+
+	// UI Context
+	ctx.registerLoader(
+		'cli/ui',
+		makeContextLoader('cli/ui', () => {
+			const ui = new VibesUIToolkit({
+				mode: 'rich',
+				compact: false,
+				autoExit: false
+			});
+
+			ui.setFormat(format);
+
+			return ui as UIContext;
+		}),
+		{
+			constraint: { surfaces: ['cli'] },
+			priority: 0
+		}
+	);
+
+	// Logger Context
+	ctx.registerLoader(
+		'cli/logger',
+		makeContextLoader('cli/logger', () => ({
+			info: (msg: string, meta?: unknown) => {
+				if (options.verbose) providerLogger.info(msg, { meta });
+			},
+			warn: (msg: string, meta?: unknown) => providerLogger.warn(msg, { meta }),
+			error: (msg: string, meta?: unknown) => providerLogger.error(msg, { meta }),
+			debug: (msg: string, meta?: unknown) => {
+				if (options.verbose) providerLogger.debug(msg, { meta });
+			}
+		})),
+		{
+			constraint: { surfaces: ['cli'] },
+			priority: 0
+		}
+	);
+
+	// App Context
+	ctx.registerLoader(
+		'cli/app',
+		makeContextLoader('cli/app', () => ({
+			keepAlive: () => {
+				keepAliveFlag = true;
+			},
+			shouldKeepAlive: () => keepAliveFlag,
+			exit: (code = 0) => requestCLIExit(code)
+		})),
+		{
+			constraint: { surfaces: ['cli'] },
+			priority: 0
+		}
+	);
+
+	// CLI Invocation Context
+	ctx.registerLoader(
+		'cli/invocation',
+		makeContextLoader('cli/invocation', () => detectCLIInvocation()),
+		{
+			constraint: { surfaces: ['cli'] },
+			priority: 0
+		}
+	);
+
+	// Output Format Context
+	ctx.registerLoader(
+		'cli/output-format',
+		makeContextLoader('cli/output-format', () => format),
+		{
+			constraint: { surfaces: ['cli'] },
+			priority: 0
+		}
+	);
+}
+
+/**
+ * Detect output format from CLI arguments
+ */
+export function detectOutputFormat(): 'json' | 'yaml' | 'table' | 'markdown' {
+	const inline = process.argv.find((arg) => arg.startsWith('--format='));
+	if (inline) {
+		const fmt = inline.slice('--format='.length).toLowerCase();
+		if (fmt === 'json' || fmt === 'yaml' || fmt === 'table' || fmt === 'markdown') {
+			return fmt;
+		}
+	}
+
+	const idx = process.argv.findIndex((arg) => arg === '--format');
+	if (idx >= 0 && idx + 1 < process.argv.length) {
+		const fmt = String(process.argv[idx + 1]).toLowerCase();
+		if (fmt === 'json' || fmt === 'yaml' || fmt === 'table' || fmt === 'markdown') {
+			return fmt as 'json' | 'yaml' | 'table' | 'markdown';
+		}
+	}
+
+	return 'table';
+}
+
+/**
+ * Detect how the CLI was invoked
+ */
+function detectCLIInvocation(): CLIContext {
+	const argv = process.argv;
+	const cwd = process.cwd();
+	const interpreter = argv[0] ?? '';
+	const isInterpreted = interpreter.includes('bun') || interpreter.includes('node');
+
+	let command: string[] = [];
+	let bin = interpreter;
+	let script: string | undefined;
+	let args: string[] = [];
+
+	if (isInterpreted) {
+		let scriptIndex = 1;
+		while (scriptIndex < argv.length && argv[scriptIndex].startsWith('-')) {
+			scriptIndex++;
+		}
+
+		if (scriptIndex < argv.length) {
+			script = argv[scriptIndex];
+			command = [interpreter, ...argv.slice(1, scriptIndex + 1)];
+			args = argv.slice(scriptIndex + 1);
+		} else {
+			command = [interpreter];
+			args = argv.slice(1);
+		}
+		bin = command.join(' ');
+	} else {
+		command = [interpreter];
+		args = argv.slice(1);
+		bin = interpreter;
+	}
+
+	return { command, bin, script, cwd, args };
+}
+
+/**
+ * Check if process should keep alive (for long-running commands)
+ */
+export function shouldKeepAlive(): boolean {
+	return keepAliveFlag;
+}
+
+/**
+ * Reset keep alive flag (for testing)
+ */
+export function resetKeepAlive(): void {
+	keepAliveFlag = false;
+}

package/src/schemas/descriptors.d.ts

@@ -0,0 +1,119 @@
+/**
+ * CLI Descriptor Schemas
+ *
+ * Kind-specific descriptor schemas for cli/group and cli/command.
+ * These are owned by the CLI module and registered with the runtime via cli.plugin.ts.
+ */
+import * as z from 'zod/v4';
+/**
+ * Log buffer behavior — controls how CLI output is buffered during command execution.
+ */
+export declare const CLILogBufferBehaviorSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    sinks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fallbackToStdout: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * CLI Group descriptor config — groups organize commands into subcommand trees.
+ */
+export declare const CLIGroupDescriptorConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    parent: z.ZodOptional<z.ZodString>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    surfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        cli: "cli";
+        worker: "worker";
+        bridge: "bridge";
+        web: "web";
+    }>>>;
+    internal: z.ZodOptional<z.ZodBoolean>;
+    order: z.ZodOptional<z.ZodNumber>;
+    logBuffer: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        sinks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fallbackToStdout: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const CLIGroupDescriptorSchema: z.ZodObject<{
+    [x: string]: any;
+}, z.core.$strip>;
+/**
+ * CLI argument definition
+ */
+export declare const CLIArgumentSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+    variadic: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/**
+ * CLI option definition
+ */
+export declare const CLIOptionSchema: z.ZodObject<{
+    flags: z.ZodString;
+    description: z.ZodString;
+    default: z.ZodOptional<z.ZodUnknown>;
+    choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * CLI command example
+ */
+export declare const CLICommandExampleSchema: z.ZodObject<{
+    command: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strip>;
+/**
+ * CLI Command descriptor config — individual executable commands.
+ */
+export declare const CLICommandDescriptorConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    group: z.ZodString;
+    arguments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+        variadic: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        flags: z.ZodString;
+        description: z.ZodString;
+        default: z.ZodOptional<z.ZodUnknown>;
+        choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    surfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        cli: "cli";
+        worker: "worker";
+        bridge: "bridge";
+        web: "web";
+    }>>>;
+    internal: z.ZodOptional<z.ZodBoolean>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strip>>>;
+    order: z.ZodOptional<z.ZodNumber>;
+    tuiAppId: z.ZodOptional<z.ZodString>;
+    logBuffer: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        sinks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fallbackToStdout: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const CLICommandDescriptorSchema: z.ZodObject<{
+    [x: string]: any;
+}, z.core.$strip>;
+export type { CLICommandArgument, CLICommandAssetDescriptor, CLICommandExample, CLICommandOption, CLIGroupAssetDescriptor, CLILogBufferBehavior } from './types';
+/**
+ * Declaration merging for type-safe runtime asset resolution.
+ */
+declare module '@vibesdotdev/runtime/schemas/asset' {
+    interface RuntimeAssetSchemaRegistry {
+        'cli/group': CLIGroupAssetDescriptor;
+        'cli/command': CLICommandAssetDescriptor;
+    }
+}

package/src/schemas/descriptors.ts

@@ -0,0 +1,136 @@
+/**
+ * CLI Descriptor Schemas
+ *
+ * Kind-specific descriptor schemas for cli/group and cli/command.
+ * These are owned by the CLI module and registered with the runtime via cli.plugin.ts.
+ */
+
+import * as z from 'zod/v4';
+import { createRuntimeAssetSchema } from '@vibesdotdev/runtime/schemas/asset';
+import type {
+	CLICommandArgument,
+	CLICommandAssetDescriptor,
+	CLICommandExample,
+	CLICommandOption,
+	CLIGroupAssetDescriptor,
+	CLILogBufferBehavior
+} from './types';
+
+/**
+ * Log buffer behavior — controls how CLI output is buffered during command execution.
+ */
+export const CLILogBufferBehaviorSchema = z.object({
+	enabled: z.boolean().optional(),
+	sinks: z.array(z.string()).optional(),
+	fallbackToStdout: z.boolean().optional()
+});
+
+/**
+ * CLI Group descriptor config — groups organize commands into subcommand trees.
+ */
+export const CLIGroupDescriptorConfigSchema = z.object({
+	/** Human-readable name */
+	name: z.string().min(1),
+	/** Description of the group */
+	description: z.string().min(1),
+	/** Parent group ID (for nested groups) */
+	parent: z.string().optional(),
+	/** Command aliases */
+	aliases: z.array(z.string()).optional(),
+	/** Surfaces where this group is available */
+	surfaces: z.array(z.enum(['cli', 'web', 'worker', 'bridge'])).optional(),
+	/** Whether this group is internal-only unless the surface opts into internal commands */
+	internal: z.boolean().optional(),
+	/** Sort order within parent */
+	order: z.number().int().optional(),
+	/** Log buffer behavior for all commands in this group */
+	logBuffer: CLILogBufferBehaviorSchema.optional()
+});
+
+export const CLIGroupDescriptorSchema = createRuntimeAssetSchema(
+	'cli/group',
+	CLIGroupDescriptorConfigSchema
+);
+
+/**
+ * CLI argument definition
+ */
+export const CLIArgumentSchema = z.object({
+	name: z.string().min(1),
+	description: z.string(),
+	required: z.boolean().optional(),
+	variadic: z.boolean().optional(),
+	default: z.unknown().optional()
+});
+
+/**
+ * CLI option definition
+ */
+export const CLIOptionSchema = z.object({
+	flags: z.string().min(1),
+	description: z.string().min(1),
+	default: z.unknown().optional(),
+	choices: z.array(z.string()).optional(),
+	type: z.enum(['string', 'number', 'boolean']).optional()
+});
+
+/**
+ * CLI command example
+ */
+export const CLICommandExampleSchema = z.object({
+	command: z.string().min(1),
+	description: z.string().min(1)
+});
+
+/**
+ * CLI Command descriptor config — individual executable commands.
+ */
+export const CLICommandDescriptorConfigSchema = z.object({
+	/** Human-readable name */
+	name: z.string().min(1),
+	/** Description of the command */
+	description: z.string().min(1),
+	/** Group this command belongs to */
+	group: z.string().min(1),
+	/** Positional arguments */
+	arguments: z.array(CLIArgumentSchema).optional(),
+	/** Named options/flags */
+	options: z.array(CLIOptionSchema).optional(),
+	/** Command aliases */
+	aliases: z.array(z.string()).optional(),
+	/** Surfaces where this command is available */
+	surfaces: z.array(z.enum(['cli', 'web', 'worker', 'bridge'])).optional(),
+	/** Whether this command is internal-only unless the surface opts into internal commands */
+	internal: z.boolean().optional(),
+	/** Examples of command usage */
+	examples: z.array(CLICommandExampleSchema).optional(),
+	/** Sort order within group */
+	order: z.number().int().optional(),
+	/** TUI app ID to launch instead of execute() */
+	tuiAppId: z.string().optional(),
+	/** Log buffer behavior for this command */
+	logBuffer: CLILogBufferBehaviorSchema.optional()
+});
+
+export const CLICommandDescriptorSchema = createRuntimeAssetSchema(
+	'cli/command',
+	CLICommandDescriptorConfigSchema
+);
+export type {
+	CLICommandArgument,
+	CLICommandAssetDescriptor,
+	CLICommandExample,
+	CLICommandOption,
+	CLIGroupAssetDescriptor,
+	CLILogBufferBehavior
+} from './types';
+
+/**
+ * Declaration merging for type-safe runtime asset resolution.
+ */
+declare module '@vibesdotdev/runtime/schemas/asset' {
+	interface RuntimeAssetSchemaRegistry {
+		'cli/group': CLIGroupAssetDescriptor;
+		'cli/command': CLICommandAssetDescriptor;
+	}
+}

package/src/schemas/surface.ts

@@ -0,0 +1,52 @@
+import type { VibesRuntime } from '@vibesdotdev/runtime/api/runtime';
+import type {
+	CLICommandAssetDescriptor,
+	CLIGroupAssetDescriptor,
+	CLILogBufferBehavior
+} from './descriptors';
+import type {
+	AppContext,
+	CLIProviderOptions,
+	ConfigContext,
+	LoggerContext,
+	UIContext
+} from '../providers';
+
+export interface CommandExecutionStartInfo {
+	command: CLICommandAssetDescriptor;
+	group?: CLIGroupAssetDescriptor;
+	args: Record<string, unknown>;
+	options: Record<string, unknown>;
+	logBuffer: CLILogBufferBehavior | null;
+}
+
+/**
+ * CLI Surface options
+ */
+export interface CLISurfaceOptions extends CLIProviderOptions {
+	/** Include descriptors marked internal (default: false) */
+	includeInternal?: boolean;
+	/** Enable pattern-based command generation */
+	enablePatterns?: boolean;
+	/** Callback invoked when command execution begins */
+	onCommandExecutionStart?: (info: CommandExecutionStartInfo) => void | Promise<void>;
+	/** Callback invoked before CLISurface triggers automatic process exit */
+	onBeforeAutoExit?: () => void | Promise<void>;
+	/** Fail initialization when command descriptors reference unknown groups */
+	strictCommandGroups?: boolean;
+	/** Additional group IDs explicitly allowed to register at CLI root */
+	rootFallbackGroups?: string[];
+	/** Fail initialization when cli/group parent references are missing */
+	strictGroupParents?: boolean;
+}
+
+/**
+ * Context available to commands and patterns
+ */
+export interface CommandContext {
+	runtime: VibesRuntime;
+	ui?: UIContext;
+	logger?: LoggerContext;
+	app?: AppContext;
+	config?: ConfigContext;
+}