@vibesdotdev/cli 0.0.1

package/src/docs/cli.output.docs.descriptor.ts

@@ -0,0 +1,445 @@
+import type { DocsTopicDescriptor } from './types.ts';
+
+const cli_outputMarkdown = `---
+title: CLI Output
+summary: Output formatting, UI toolkit integration, tables, and colors
+tags: [cli, output, formatting, ui, tables, colors]
+parent: cli
+order: 3
+---
+
+# CLI Output
+
+The vibes CLI provides consistent output formatting through the \`VibesUIToolkit\`. Commands use the toolkit to render tables, JSON, YAML, and formatted text with proper colorization and structure.
+
+## Overview
+
+Output formatting is handled by \`VibesUIToolkit\`, a unified interface for CLI output that supports multiple formats and interactive prompts.
+
+\`\`\`ts
+import { VibesUIToolkit } from '@vibesdotdev/cli/support/ui-toolkit';
+
+const ui = VibesUIToolkit.createSync({ mode: 'plain' });
+ui.info('Starting process...');
+ui.table(data);
+ui.success('Done!');
+\`\`\`
+
+## VibesUIToolkit API
+
+### Creation
+
+\`\`\`ts
+// Synchronous creation (most common)
+const ui = VibesUIToolkit.createSync({
+  mode: 'plain',    // or 'rich' for TUI apps
+  compact: false,   // reduce whitespace
+  autoExit: true    // exit after command completes
+});
+\`\`\`
+
+### Output methods
+
+| Method | Description | Output |
+|--------|-------------|--------|
+| \`ui.info(message)\` | Informational message | stdout |
+| \`ui.success(message)\` | Success message | stdout |
+| \`ui.warn(message)\` | Warning message | stderr |
+| \`ui.error(message)\` | Error message | stderr |
+| \`ui.log(message)\` | Raw log output | stdout |
+
+### Format-aware rendering
+
+The toolkit supports multiple output formats:
+
+\`\`\`ts
+ui.setFormat('json');   // or 'yaml', 'table', 'markdown'
+ui.render(data);        // outputs in selected format
+\`\`\`
+
+**Format examples:**
+
+\`\`\`ts
+const data = [
+  { id: 'tools.list', description: 'List tools' },
+  { id: 'tools.info', description: 'Show tool info' }
+];
+
+// JSON output
+ui.setFormat('json');
+ui.render(data);
+// [{ "id": "tools.list", "description": "List tools" }, ...]
+
+// YAML output
+ui.setFormat('yaml');
+ui.render(data);
+// - id: tools.list
+//   description: List tools
+
+// Table output
+ui.setFormat('table');
+ui.render(data);
+// ┌─────────────┬──────────────────┐
+// │    id       │   description    │
+// ├─────────────┼──────────────────┤
+// │ tools.list  │  List tools      │
+// │ tools.info  │  Show tool info  │
+// └─────────────┴──────────────────┘
+\`\`\`
+
+## Table rendering
+
+Tables are the primary output format for list commands:
+
+\`\`\`ts
+// Basic table
+ui.table(data);
+
+// With column selection
+ui.table(data, { columns: ['id', 'name'] });
+
+// With title
+ui.table(data, { title: 'Registered Tools' });
+
+// Column names only (shorthand)
+ui.table(data, ['id', 'name', 'status']);
+\`\`\`
+
+### Table options
+
+\`\`\`ts
+interface TableOptions {
+  columns?: string[];   // subset of fields to display
+  title?: string;       // table header
+}
+
+// Usage
+ui.table(rows, {
+  columns: ['id', 'description', 'enabled'],
+  title: 'Available Commands'
+});
+\`\`\`
+
+### Example: Command list
+
+\`\`\`ts
+const commands = [
+  { id: 'profile.list', group: 'profile', description: 'List profiles' },
+  { id: 'profile.create', group: 'profile', description: 'Create profile' },
+  { id: 'completion', group: 'shell-integration', description: 'Generate completions' }
+];
+
+ui.table(commands, {
+  columns: ['id', 'group', 'description'],
+  title: 'Registered Commands'
+});
+\`\`\`
+
+**Output:**
+
+\`\`\`
+Registered Commands
+┌─────────────────┬───────────────────┬────────────────────┐
+│       id        │      group        │    description     │
+├─────────────────┼───────────────────┼────────────────────┤
+│  profile.list   │     profile       │   List profiles    │
+│ profile.create  │     profile       │   Create profile   │
+│   completion    │ shell-integration │ Generate completions│
+└─────────────────┴───────────────────┴────────────────────┘
+\`\`\`
+
+## JSON/YAML output
+
+Many commands support \`--json\` or \`--yaml\` flags for machine-readable output:
+
+\`\`\`ts
+// Command implementation pattern
+async function listProfiles(options: { json?: boolean; yaml?: boolean }) {
+  const profiles = await getProfiles();
+  
+  if (options.json) {
+    ui.setFormat('json');
+    ui.render(profiles);
+  } else if (options.yaml) {
+    ui.setFormat('yaml');
+    ui.render(profiles);
+  } else {
+    ui.table(profiles, { columns: ['name', 'active', 'created'] });
+  }
+}
+\`\`\`
+
+**Usage:**
+
+\`\`\`bash
+# Default table output
+$ vibes profile list
+
+# JSON for scripting
+$ vibes profile list --json | jq '.[] | select(.active == true)'
+
+# YAML for config generation
+$ vibes profile list --yaml > profiles.yaml
+\`\`\`
+
+## Interactive prompts
+
+The toolkit provides interactive prompts for user input:
+
+\`\`\`ts
+// Text input
+const name = await ui.prompt('Profile name:', { default: 'default' });
+
+// Confirmation
+const confirmed = await ui.confirm('Delete this profile?', { defaultValue: false });
+
+// Single selection
+const choice = await ui.select('Select profile:', [
+  { label: 'Development', value: 'dev' },
+  { label: 'Production', value: 'prod' }
+]);
+
+// Multiple selection
+const profiles = await ui.multiselect('Select profiles to delete:', [
+  { label: 'Old Dev', value: 'old-dev' },
+  { label: 'Test', value: 'test' }
+], { required: false });
+\`\`\`
+
+### Non-interactive fallback
+
+Prompts gracefully degrade in non-TTY environments:
+
+\`\`\`ts
+// Returns default in CI/pipes
+const name = await ui.prompt('Name:', { default: 'default' });
+// → 'default' if not interactive
+
+// Returns empty array in CI
+const choices = await ui.multiselect('Choose:', options);
+// → [] if not interactive and not required
+\`\`\`
+
+## Progress indicators
+
+Simple progress tracking for long operations:
+
+\`\`\`ts
+const progress = ui.progress('Building...');
+progress.update('Compiling modules...');
+progress.complete('Build complete!');
+
+// Or with failure
+try {
+  await build();
+  progress.complete('Success!');
+} catch (error) {
+  progress.fail('Build failed');
+  throw error;
+}
+\`\`\`
+
+## Color and formatting
+
+The toolkit respects environment variables and options:
+
+\`\`\`bash
+# Environment variable
+VIBES_NO_COLOR=1 vibes profile list
+
+# Command flag
+vibes profile list --no-color
+\`\`\`
+
+### Color methods
+
+\`\`\`ts
+// Built-in colorization (when enabled)
+ui.info('ℹ️  Information');    // blue
+ui.success('✅ Success');       // green
+ui.warn('⚠️  Warning');         // yellow
+ui.error('❌ Error');           // red
+\`\`\`
+
+## Integration with commands
+
+Commands receive a UI toolkit through the context:
+
+\`\`\`ts
+// packages/cli/src/commands/profile/profile.list.impl.ts
+import { VibesUIToolkit } from '../../support/ui-toolkit';
+
+export async function execute(
+  args: Record<string, unknown>,
+  opts: { json?: boolean; yaml?: boolean },
+  context: CommandContext
+): Promise<void> {
+  const ui = VibesUIToolkit.createSync({ mode: 'plain' });
+  
+  if (opts.json) ui.setFormat('json');
+  if (opts.yaml) ui.setFormat('yaml');
+  
+  const profiles = await listProfiles();
+  
+  if (opts.json || opts.yaml) {
+    ui.render(profiles);
+  } else {
+    ui.table(profiles, {
+      columns: ['name', 'active', 'created'],
+      title: 'Configuration Profiles'
+    });
+  }
+}
+\`\`\`
+
+## Log buffer integration
+
+Commands can buffer output during execution:
+
+\`\`\`ts
+// Descriptor with log buffer config
+const command: CLICommandAssetDescriptor = {
+  kind: 'cli/command',
+  id: 'dev.build',
+  name: 'build',
+  description: 'Build the project',
+  group: 'dev',
+  logBuffer: {
+    enabled: true,
+    sinks: ['file', 'memory'],
+    fallbackToStdout: true
+  }
+};
+\`\`\`
+
+Buffered output is held until command completion, then flushed:
+
+\`\`\`bash
+# Output appears all at once when command finishes
+$ vibes dev build
+[build output buffered...]
+✅ Build complete!
+\`\`\`
+
+## WRONG patterns
+
+### ❌ Direct console.log
+
+\`\`\`ts
+// BAD — bypasses formatting, breaks --json
+console.log('Profile:', profile.name);
+
+// GOOD — uses toolkit
+ui.info(\`Profile: \${profile.name}\`);
+\`\`\`
+
+### ❌ Mixed output streams
+
+\`\`\`ts
+// BAD — data on stdout, errors mixed in
+console.log(data);
+console.error('Warning: deprecated');
+
+// GOOD — separate concerns
+ui.render(data);      // data to stdout
+ui.warn('Warning');   // warnings to stderr
+\`\`\`
+
+### ❌ Manual JSON formatting
+
+\`\`\`ts
+// BAD — inconsistent formatting
+process.stdout.write(JSON.stringify(data));
+
+// GOOD — toolkit handles formatting
+ui.setFormat('json');
+ui.render(data);
+\`\`\`
+
+### ❌ Ignoring format flags
+
+\`\`\`ts
+// BAD — always outputs table
+ui.table(profiles);
+
+// GOOD — respects --json/--yaml
+if (opts.json) {
+  ui.setFormat('json');
+  ui.render(profiles);
+} else {
+  ui.table(profiles);
+}
+\`\`\`
+
+### ❌ Hardcoded colors
+
+\`\`\`ts
+// BAD — ignores VIBES_NO_COLOR
+process.stdout.write('\\x1b[32mSuccess\\x1b[0m');
+
+// GOOD — use toolkit methods
+ui.success('Success');
+\`\`\`
+
+## Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| \`VIBES_NO_COLOR\` | Disable ANSI colors | \`false\` |
+| \`VIBES_OUTPUT_FORMAT\` | Default output format | \`table\` |
+| \`VIBES_INTERACTIVE\` | Force interactive mode | auto-detect |
+| \`CI\` | CI mode (non-interactive) | auto-detect |
+
+## Related
+
+:::card{title="See also"}
+- [\`cli.commands\`](cli.commands) — Command structure and execution
+- [\`cli.groups\`](cli.groups) — Command group organization
+- [\`tools.list\`](tools.list) — Example command using output formatting
+:::
+`;
+
+const descriptor: DocsTopicDescriptor = {
+	kind: 'docs/topic',
+	id: 'cli.output',
+	title: 'CLI Output',
+	summary: 'Output formatting, UI toolkit integration, tables, and colors',
+	body: {
+		type: 'markdown',
+		sourceType: 'raw',
+		source: cli_outputMarkdown
+	},
+	parent: 'cli',
+	order: 3,
+	tags: ['cli', 'output', 'formatting', 'ui', 'tables', 'colors'],
+	surfaces: ['cli', 'web', 'in-app'],
+	hardware: ['consumer'],
+	enabled: true,
+	man: {
+		name: 'cli.output — CLI output formatting and UI toolkit',
+		section: 1,
+		synopsis: 'vibes man cli.output',
+		options: [
+			{ flag: '--json', description: 'Output as JSON' },
+			{ flag: '--yaml', description: 'Output as YAML' },
+			{ flag: '--no-color', description: 'Disable ANSI colors' }
+		],
+		examples: [
+			{
+				description: 'View output formatting documentation',
+				command: 'vibes man cli.output'
+			},
+			{
+				description: 'List commands with JSON output',
+				command: 'vibes tools list --json'
+			},
+			{
+				description: 'Profile list with YAML output',
+				command: 'vibes profile list --yaml'
+			}
+		],
+		seeAlso: ['cli.commands', 'cli.groups', 'tools.list']
+	}
+};
+
+export default descriptor;

package/src/docs/types.ts

@@ -0,0 +1,18 @@
+export type DocsTopicDescriptor = {
+	kind: 'docs/topic';
+	id: string;
+	title: string;
+	summary?: string;
+	body: {
+		type: 'markdown';
+		sourceType: 'raw';
+		source: string;
+	};
+	parent?: string;
+	order?: number;
+	enabled?: boolean;
+	man?: unknown;
+	tags?: string[];
+	surfaces?: string[];
+	hardware?: string[];
+};

package/src/errors.ts

@@ -0,0 +1,123 @@
+/**
+ * CLI Errors
+ *
+ * Error types for CLI commands.
+ */
+
+/**
+ * Base CLI error
+ */
+export class CLIError extends Error {
+	constructor(
+		message: string,
+		public code: string = 'CLI_ERROR',
+		public exitCode: number = 1
+	) {
+		super(message);
+		this.name = 'CLIError';
+	}
+}
+
+/**
+ * Command not found error
+ */
+export class CommandNotFoundError extends CLIError {
+	constructor(command: string) {
+		super(`Command not found: ${command}`, 'COMMAND_NOT_FOUND', 127);
+		this.name = 'CommandNotFoundError';
+	}
+}
+
+/**
+ * Invalid argument error
+ */
+export class InvalidArgumentError extends CLIError {
+	constructor(argument: string, reason?: string) {
+		const msg = reason
+			? `Invalid argument '${argument}': ${reason}`
+			: `Invalid argument: ${argument}`;
+		super(msg, 'INVALID_ARGUMENT', 1);
+		this.name = 'InvalidArgumentError';
+	}
+}
+
+/**
+ * Missing required argument error
+ */
+export class MissingArgumentError extends CLIError {
+	constructor(argument: string) {
+		super(`Missing required argument: ${argument}`, 'MISSING_ARGUMENT', 1);
+		this.name = 'MissingArgumentError';
+	}
+}
+
+/**
+ * Authentication required error
+ */
+export class AuthRequiredError extends CLIError {
+	constructor(message = 'Authentication required. Run: vibes auth login') {
+		super(message, 'AUTH_REQUIRED', 1);
+		this.name = 'AuthRequiredError';
+	}
+}
+
+/**
+ * Permission denied error
+ */
+export class PermissionDeniedError extends CLIError {
+	constructor(resource?: string) {
+		const msg = resource ? `Permission denied: ${resource}` : 'Permission denied';
+		super(msg, 'PERMISSION_DENIED', 1);
+		this.name = 'PermissionDeniedError';
+	}
+}
+
+/**
+ * Resource not found error
+ */
+export class NotFoundError extends CLIError {
+	constructor(resource: string) {
+		super(`Not found: ${resource}`, 'NOT_FOUND', 1);
+		this.name = 'NotFoundError';
+	}
+}
+
+/**
+ * Configuration error
+ */
+export class ConfigError extends CLIError {
+	constructor(message: string) {
+		super(message, 'CONFIG_ERROR', 1);
+		this.name = 'ConfigError';
+	}
+}
+
+/**
+ * Network error
+ */
+export class NetworkError extends CLIError {
+	constructor(message: string) {
+		super(message, 'NETWORK_ERROR', 1);
+		this.name = 'NetworkError';
+	}
+}
+
+/**
+ * Timeout error
+ */
+export class TimeoutError extends CLIError {
+	constructor(operation: string, timeout: number) {
+		super(`Operation '${operation}' timed out after ${timeout}ms`, 'TIMEOUT', 1);
+		this.name = 'TimeoutError';
+	}
+}
+
+/**
+ * User cancelled error
+ */
+export class UserCancelledError extends CLIError {
+	constructor() {
+		super('Operation cancelled by user', 'USER_CANCELLED', 0);
+		this.name = 'UserCancelledError';
+	}
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+/**
+ * CLI Module
+ *
+ * The CLI surface for the universal runtime.
+ * Integrates Commander.js with runtime-discovered commands.
+ *
+ * Usage:
+ * ```typescript
+ * import { createVibesCliApp } from '@vibesdotdev/cli/bootstrap';
+ *
+ * const app = await createVibesCliApp();
+ * await app.cli.run(process.argv);
+ * ```
+ */
+
+// Bootstrap
+export {
+	createVibesCliApp,
+	type VibesCliAppOptions,
+	type VibesCliApp,
+	type CliPluginLoader
+} from './bootstrap';
+
+// Surface
+export { CLISurface, type CLISurfaceOptions, type CommandContext } from './surface';
+
+// Plugin (registers cli/group and cli/command kinds)
+export { default as cliPlugin } from './cli.plugin';
+
+// Context providers
+export {
+	registerCLIProviders,
+	requestCLIExit,
+	detectOutputFormat,
+	shouldKeepAlive,
+	resetKeepAlive,
+	CLIExitSignal,
+	type CLIProviderOptions,
+	type UIContext,
+	type LoggerContext,
+	type AppContext,
+	type CLIContext
+} from './providers';
+
+// Patterns
+export {
+	PatternResolver,
+	createPatternResolver,
+	isPatternDescriptor,
+	getPatternType,
+	type PatternImplementation,
+	type CLIPatternDescriptor,
+	type CLICRUDGroupDescriptor,
+	type CLIToolWrapperCommandDescriptor,
+	type CLILogViewerGroupDescriptor,
+	type CLIProcessManagerGroupDescriptor,
+	type CLIConfigNamespaceGroupDescriptor
+} from './patterns';
+
+// Errors
+export {
+	CLIError,
+	CommandNotFoundError,
+	InvalidArgumentError,
+	MissingArgumentError,
+	AuthRequiredError,
+	PermissionDeniedError,
+	NotFoundError,
+	ConfigError,
+	NetworkError,
+	TimeoutError,
+	UserCancelledError
+} from './errors';
+
+// Binary path resolution
+export { resolveCliEntry, resolveCliInvocation } from './bin';

package/src/logging/cli-startup.logger.descriptor.ts

@@ -0,0 +1,16 @@
+/**
+ * CLI Startup Logger Descriptor
+ */
+
+import type { LoggerDescriptor } from '@vibesdotdev/logging';
+
+const descriptor: LoggerDescriptor = {
+	kind: 'logging/logger',
+	id: 'cli-startup',
+	namespace: 'cli:startup',
+	runtime: 'cli',
+	sinks: ['stdout'],
+	level: 'warn'
+};
+
+export default descriptor;

package/src/logging.ts

@@ -0,0 +1,35 @@
+import {
+	getLogger as getRuntimeLogger,
+	updateNamespaceSettings,
+	parseNamespaceSettingsFromEnv
+} from '@vibesdotdev/logging';
+
+const envSettings = parseNamespaceSettingsFromEnv(
+	(typeof process !== 'undefined' && process.env) || {}
+);
+
+updateNamespaceSettings(envSettings);
+
+let globalLogger: ReturnType<typeof getRuntimeLogger> | null = null;
+
+function ensureLogger(): ReturnType<typeof getRuntimeLogger> {
+	if (!globalLogger) {
+		globalLogger = getRuntimeLogger('cli');
+	}
+
+	return globalLogger;
+}
+
+export function setLogger(logger: ReturnType<typeof getRuntimeLogger>): void {
+	globalLogger = logger;
+}
+
+export function getLogger(
+	child?: Parameters<ReturnType<typeof getRuntimeLogger>['child']>[0]
+): ReturnType<typeof getRuntimeLogger> {
+	const baseLogger = ensureLogger();
+	if (!child) {
+		return baseLogger;
+	}
+	return baseLogger.child(child);
+}