@vibesdotdev/cli 0.0.2 → 1.0.0-rc.2

package/src/providers.ts

@@ -1,282 +0,0 @@
-/**
- * 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

@@ -1,119 +0,0 @@
-/**
- * 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

@@ -1,136 +0,0 @@
-/**
- * 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

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