@vibesdotdev/cli 0.0.1

package/src/core/namespace/index.ts

@@ -0,0 +1,298 @@
+/**
+ * CLI Namespace Registry (compatibility layer)
+ *
+ * Provides a lightweight namespace registry used by legacy config services.
+ * New CLI surfaces are descriptor-driven; this module exists to keep older
+ * imports functional while commands are migrated.
+ */
+
+import { join } from 'path';
+import { homedir } from 'os';
+import { mkdir } from 'node:fs/promises';
+import {
+	getNestedValue,
+	setNestedValue
+} from '@vibesdotdev/config/form/core';
+import type {
+	ConfigScope,
+	ConfigValue,
+	NamespaceDefinition,
+	NamespaceListEntry,
+	NamespaceConfigAccessor
+} from './schemas';
+
+// Config loader — file-based JSON storage
+//
+// Reads/writes scoped config files:
+//   global:  ~/.vibes/config.json
+//   local:   ./.vibes/config.json
+//   project: ./vibes.config.json
+//
+// When loading with merge=true, configs are deep-merged in specificity order
+// (global < local < project) so more-specific scopes override less-specific.
+
+interface LegacyLoadOptions {
+	scopes?: string[];
+	merge?: boolean;
+}
+
+interface LegacySaveOptions {
+	scope: ConfigScope;
+	format?: string;
+	pretty?: boolean;
+	encrypt?: boolean;
+	merge?: boolean;
+}
+
+function getConfigPath(scope: ConfigScope): string {
+	switch (scope) {
+		case 'global':
+			return join(homedir(), '.vibes', 'config.json');
+		case 'local':
+			return join(process.cwd(), '.vibes', 'config.json');
+		case 'project':
+			return join(process.cwd(), 'vibes.config.json');
+	}
+}
+
+async function readJsonFile(path: string): Promise<Record<string, ConfigValue>> {
+	try {
+		const file = Bun.file(path);
+		if (!(await file.exists())) return {};
+		const text = await file.text();
+		const parsed = JSON.parse(text);
+		if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+			return parsed as Record<string, ConfigValue>;
+		}
+		return {};
+	} catch {
+		return {};
+	}
+}
+
+function deepMergeConfigs(
+	target: Record<string, ConfigValue>,
+	source: Record<string, ConfigValue>
+): Record<string, ConfigValue> {
+	const result = { ...target };
+	for (const [key, value] of Object.entries(source)) {
+		const existing = result[key];
+		if (
+			value && typeof value === 'object' && !Array.isArray(value) &&
+			existing && typeof existing === 'object' && !Array.isArray(existing)
+		) {
+			result[key] = deepMergeConfigs(
+				existing as Record<string, ConfigValue>,
+				value as Record<string, ConfigValue>
+			);
+		} else {
+			result[key] = value;
+		}
+	}
+	return result;
+}
+
+async function loadConfig(options: LegacyLoadOptions): Promise<{ config: Record<string, ConfigValue> }> {
+	const scopes = (options.scopes ?? ['global', 'project', 'local']) as ConfigScope[];
+	const merge = options.merge ?? true;
+
+	// Specificity order: global < local < project
+	const scopeOrder: ConfigScope[] = ['global', 'local', 'project'];
+	const orderedScopes = scopeOrder.filter((s) => scopes.includes(s));
+
+	let merged: Record<string, ConfigValue> = {};
+
+	for (const scope of orderedScopes) {
+		const data = await readJsonFile(getConfigPath(scope));
+		if (Object.keys(data).length === 0) continue;
+
+		if (merge) {
+			merged = deepMergeConfigs(merged, data);
+		} else {
+			// Return first found
+			return { config: data };
+		}
+	}
+
+	return { config: merged };
+}
+
+async function saveConfig(config: Record<string, ConfigValue>, options: LegacySaveOptions): Promise<void> {
+	const filePath = getConfigPath(options.scope);
+	const dir = filePath.substring(0, filePath.lastIndexOf('/'));
+
+	await mkdir(dir, { recursive: true });
+
+	let dataToWrite: Record<string, ConfigValue>;
+
+	if (options.merge !== false) {
+		// Merge with existing content at this scope
+		const existing = await readJsonFile(filePath);
+		dataToWrite = deepMergeConfigs(existing, config);
+	} else {
+		dataToWrite = config;
+	}
+
+	const pretty = options.pretty !== false;
+	const content = JSON.stringify(dataToWrite, null, pretty ? 2 : 0);
+	await Bun.write(filePath, content);
+}
+
+
+function asObject(
+	value: ConfigValue | Record<string, ConfigValue> | undefined
+): Record<string, ConfigValue> {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) {
+		return {};
+	}
+	return value as Record<string, ConfigValue>;
+}
+
+function deleteNestedValue(root: Record<string, ConfigValue>, path: string): void {
+	const parts = path.split('.').filter(Boolean);
+	if (parts.length === 0) return;
+
+	let current = root;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const key = parts[i];
+		const next = current[key];
+		if (!next || typeof next !== 'object' || Array.isArray(next)) {
+			return;
+		}
+		current = next as Record<string, ConfigValue>;
+	}
+
+	delete current[parts[parts.length - 1]];
+}
+
+function flattenConfig(source: Record<string, ConfigValue>, prefix = ''): NamespaceListEntry[] {
+	const entries: NamespaceListEntry[] = [];
+	for (const [key, value] of Object.entries(source)) {
+		const fullKey = prefix ? `${prefix}.${key}` : key;
+		if (value && typeof value === 'object' && !Array.isArray(value)) {
+			entries.push(...flattenConfig(value as Record<string, ConfigValue>, fullKey));
+			continue;
+		}
+		entries.push({ key: fullKey, value });
+	}
+	return entries;
+}
+
+async function loadRootConfig(scope?: ConfigScope): Promise<Record<string, ConfigValue>> {
+	const scopes = scope ? [scope] : ['global', 'project', 'local'];
+	const loaded = await loadConfig({ scopes, merge: true });
+	return asObject(loaded.config);
+}
+
+function createAccessor<TConfig extends Record<string, ConfigValue>>(
+	definition: NamespaceDefinition
+): NamespaceConfigAccessor<TConfig> {
+	const namespaceId = definition.id;
+	const defaults = definition.configDefaults ?? {};
+
+	return {
+		async get(key: string): Promise<ConfigValue | undefined> {
+			const config = await loadRootConfig();
+			const namespaceConfig = asObject(
+				getNestedValue(config as Record<string, unknown>, namespaceId) as ConfigValue | undefined
+			);
+			const value = getNestedValue(namespaceConfig as Record<string, unknown>, key);
+			if (value !== undefined) return value as ConfigValue;
+			return getNestedValue(defaults as Record<string, unknown>, key) as ConfigValue | undefined;
+		},
+
+		async set(key: string, value: ConfigValue, scope: ConfigScope = 'global'): Promise<void> {
+			const config = await loadRootConfig(scope);
+			const namespaceConfig = asObject(
+				getNestedValue(config as Record<string, unknown>, namespaceId) as ConfigValue | undefined
+			);
+			setNestedValue(namespaceConfig as Record<string, unknown>, key, value);
+			setNestedValue(config as Record<string, unknown>, namespaceId, namespaceConfig);
+			await saveConfig(config, {
+				scope,
+				format: 'json',
+				pretty: true,
+				encrypt: true,
+				merge: false
+			});
+		},
+
+		async delete(key: string, scope: ConfigScope = 'global'): Promise<void> {
+			const config = await loadRootConfig(scope);
+			const namespaceConfig = asObject(
+				getNestedValue(config as Record<string, unknown>, namespaceId) as ConfigValue | undefined
+			);
+			deleteNestedValue(namespaceConfig, key);
+			setNestedValue(config as Record<string, unknown>, namespaceId, namespaceConfig);
+			await saveConfig(config, {
+				scope,
+				format: 'json',
+				pretty: true,
+				encrypt: true,
+				merge: false
+			});
+		},
+
+		async list(): Promise<NamespaceListEntry[]> {
+			const config = await loadRootConfig();
+			const namespaceConfig = asObject(
+				getNestedValue(config as Record<string, unknown>, namespaceId) as ConfigValue | undefined
+			);
+			return flattenConfig(namespaceConfig);
+		},
+
+		async getConfig(): Promise<TConfig> {
+			const config = await loadRootConfig();
+			const namespaceConfig = asObject(
+				getNestedValue(config as Record<string, unknown>, namespaceId) as ConfigValue | undefined
+			);
+			return { ...defaults, ...namespaceConfig } as TConfig;
+		},
+
+		async setConfig(config: Partial<TConfig>, scope: ConfigScope = 'global'): Promise<void> {
+			const rootConfig = await loadRootConfig(scope);
+			const current = asObject(getNestedValue(rootConfig as Record<string, unknown>, namespaceId) as ConfigValue | undefined);
+			const merged = { ...defaults, ...current, ...config } as Record<string, ConfigValue>;
+			setNestedValue(rootConfig as Record<string, unknown>, namespaceId, merged);
+			await saveConfig(rootConfig, {
+				scope,
+				format: 'json',
+				pretty: true,
+				encrypt: true,
+				merge: false
+			});
+		}
+	};
+}
+
+class NamespaceRegistry {
+	private definitions = new Map<string, NamespaceDefinition>();
+
+	register(definition: NamespaceDefinition): void {
+		this.definitions.set(definition.id, definition);
+	}
+
+	has(id: string): boolean {
+		return this.definitions.has(id);
+	}
+
+	getIds(): string[] {
+		return [...this.definitions.keys()];
+	}
+
+	getConfig<TConfig extends Record<string, ConfigValue>>(
+		id: string
+	): NamespaceConfigAccessor<TConfig> {
+		const definition = this.definitions.get(id) ?? { id };
+		if (!this.definitions.has(id)) {
+			this.definitions.set(id, definition);
+		}
+		return createAccessor<TConfig>(definition);
+	}
+}
+
+const registry = new NamespaceRegistry();
+
+export function getNamespaceRegistry(): NamespaceRegistry {
+	return registry;
+}

package/src/core/namespace/schemas/index.ts

@@ -0,0 +1,25 @@
+export type ConfigScope = 'global' | 'project' | 'local';
+
+type PrimitiveValue = string | number | boolean | null;
+export type ConfigValue = PrimitiveValue | ConfigValue[] | { [key: string]: ConfigValue };
+
+export interface NamespaceDefinition {
+	id: string;
+	name?: string;
+	description?: string;
+	configDefaults?: Record<string, ConfigValue>;
+}
+
+export interface NamespaceListEntry {
+	key: string;
+	value: ConfigValue;
+}
+
+export interface NamespaceConfigAccessor<TConfig extends Record<string, ConfigValue>> {
+	get(key: string, scope?: ConfigScope): Promise<ConfigValue | undefined>;
+	set(key: string, value: ConfigValue, scope?: ConfigScope): Promise<void>;
+	delete(key: string, scope?: ConfigScope): Promise<void>;
+	list(scope?: ConfigScope): Promise<NamespaceListEntry[]>;
+	getConfig(scope?: ConfigScope): Promise<TConfig>;
+	setConfig(config: Partial<TConfig>, scope?: ConfigScope): Promise<void>;
+}

package/src/core/plugins/types.ts

@@ -0,0 +1,87 @@
+/**
+ * CLI Plugin Types
+ * Compatibility shim for plugins that need CLI runtime context
+ */
+
+import type { UIContext } from '../../providers.ts';
+
+/**
+ * Command layout interface for structured output
+ */
+export interface CommandLayout {
+	appendError(message: string): void;
+	appendOutput(message: string): void;
+	appendInfo(message: string): void;
+	appendSuccess(message: string): void;
+	appendWarning(message: string): void;
+	appendJSON(data: unknown): void;
+	appendTable(data: unknown[], columns?: string[]): void;
+	showProgress(message?: string): void;
+	hideProgress(): void;
+	complete(): Promise<void>;
+}
+
+/**
+ * UI Toolkit interface providing rich output capabilities for CLI commands
+ */
+export interface UIToolkit {
+	// Basic output
+	info(message: string): void;
+	warn(message: string): void;
+	warning(message: string): void;
+	error(message: string): void;
+	success(message: string): void;
+	log(message: string): void;
+	table(data: unknown[], options?: string | { columns?: string[]; title?: string }): void;
+	json(data: unknown): void;
+	yaml(data: unknown): void;
+	markdown(data: unknown): void;
+	setFormat(format: 'json' | 'yaml' | 'table' | 'markdown'): void;
+
+	// Rich command execution
+	withCommand(
+		options: {
+			plugin: string;
+			command: string;
+			args?: Record<string, unknown>;
+			flags?: Record<string, unknown>;
+		},
+		fn: (toolkit: UIToolkit) => Promise<void>
+	): Promise<void>;
+
+	createCommand(options: {
+		plugin: string;
+		command: string;
+		args?: Record<string, unknown>;
+	}): Promise<CommandLayout>;
+
+	render(data: unknown, options?: { format?: string }): Promise<void>;
+	prompt(questions: unknown[]): Promise<Record<string, unknown>>;
+	confirm(message: string, options?: Record<string, unknown>): Promise<boolean>;
+	createInteractiveCommand(options: Record<string, unknown>): Promise<CommandLayout>;
+	appendInfo?(message: string): void;
+	appendSuccess?(message: string): void;
+	appendTable?(data: unknown[], columns?: string[]): void;
+	[key: string]: unknown;
+}
+
+/**
+ * CLI Runtime Context with plugin-specific extensions
+ */
+export interface CLIRuntimeContext {
+	ui?: UIContext | UIToolkit;
+	logger?: {
+		info(msg: string, ...args: unknown[]): void;
+		warn(msg: string, ...args: unknown[]): void;
+		error(msg: string, ...args: unknown[]): void;
+		debug(msg: string, ...args: unknown[]): void;
+	};
+	config?: unknown;
+	pm?: unknown;
+	runtime?: unknown;
+	cli?: {
+		cwd?: string;
+		[key: string]: unknown;
+	};
+	[key: string]: unknown;
+}

package/src/core/runtime/context.ts

@@ -0,0 +1,50 @@
+/**
+ * CLI Runtime Context
+ *
+ * The context object passed to CLI command handlers.
+ * Provides UI output, logging, and lifecycle control.
+ */
+
+import type { UIContext, AppContext, LoggerContext } from '../../providers.ts';
+type PMContext = unknown;
+
+export interface RuntimeContext {
+	ui: UIContext;
+	app?: AppContext;
+	logger?: LoggerContext;
+	// Extended context properties (set by plugins and consumers)
+	config?: unknown;
+	pm?: PMContext;
+	runtime?: unknown;
+	cli?: {
+		cwd?: string;
+		[key: string]: unknown;
+	};
+	[key: string]: unknown;
+}
+
+let _context: RuntimeContext | null = null;
+
+export function getContext(): RuntimeContext {
+	if (!_context) {
+		// Return a minimal context when not set
+		return {
+			ui: {
+				info: (msg: string): void => {
+					process.stdout.write(`${msg}\n`);
+				},
+				warn: (msg: string): void => {
+					process.stderr.write(`${msg}\n`);
+				},
+				error: (msg: string): void => {
+					process.stderr.write(`${msg}\n`);
+				}
+			} as UIContext
+		};
+	}
+	return _context;
+}
+
+export function setContext(ctx: RuntimeContext): void {
+	_context = ctx;
+}

package/src/core/runtime/hooks.ts

@@ -0,0 +1,12 @@
+/**
+ * CLI Runtime Hooks
+ * Compatibility shim for plugins that need lifecycle hooks
+ */
+import type { RuntimeContext } from './context.ts';
+
+export interface Hook {
+  id: string;
+  name: string;
+  dependencies?: string[];
+  init(context: RuntimeContext): Promise<void> | void;
+}

package/src/core/runtime/shared/context.ts

@@ -0,0 +1,65 @@
+/**
+ * CLI Runtime Context Loader
+ *
+ * Convenience accessor for the standard CLI runtime context bundle —
+ * the live `cli/ui` + `cli/logger` (with a fallback) + optional
+ * `pm/client` resolved from the active `VibesRuntime`. Command
+ * implementations should call this once at the top of `execute()` to
+ * obtain the surfaces they need rather than calling
+ * `runtime.context()` for each one.
+ *
+ * Canonical home per RUNTIME-FIRST-MODULES.md (`packages/cli` owns
+ * "the helpers that make runtime-discovered commands usable in shells").
+ * Feature packages (bridge, expert, etc.) import from
+ * `@vibesdotdev/cli/core/runtime/shared/context` rather than
+ * maintaining per-package copies.
+ */
+
+import type { LoggerContext, UIContext } from '../../../providers.ts';
+type IProcessManager = unknown;
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+import { getLogger } from '@vibesdotdev/logging';
+
+function fallbackLogger(): LoggerContext {
+	const logger = getLogger('cli:runtime-context');
+	return {
+		info: (message: string, meta?: unknown) =>
+			logger.info(message, meta as Record<string, unknown>),
+		warn: (message: string, meta?: unknown) =>
+			logger.warn(message, meta as Record<string, unknown>),
+		error: (message: string, meta?: unknown) =>
+			logger.error(message, meta as Record<string, unknown>),
+		debug: (message: string, meta?: unknown) =>
+			logger.debug(message, meta as Record<string, unknown>)
+	};
+}
+
+async function optionalContext<T>(id: string): Promise<T | undefined> {
+	const runtime = getVibesRuntime();
+	try {
+		return await runtime.context<T>(id);
+	} catch {
+		return undefined;
+	}
+}
+
+export interface CliRuntimeContext {
+	ui: UIContext;
+	logger: LoggerContext;
+	pm?: IProcessManager;
+}
+
+/**
+ * Resolve the standard CLI runtime context bundle.
+ *
+ * Throws if `cli/ui` is unavailable (every CLI command needs it).
+ * Falls back to a logging-namespace-scoped logger if `cli/logger`
+ * isn't registered. Returns `pm` only when `pm/client` is registered.
+ */
+export async function loadCliRuntimeContext(): Promise<CliRuntimeContext> {
+	const runtime = getVibesRuntime();
+	const ui = await runtime.context<UIContext>('cli/ui');
+	const logger = (await optionalContext<LoggerContext>('cli/logger')) ?? fallbackLogger();
+	const pm = await optionalContext<IProcessManager>('pm/client');
+	return { ui, logger, pm };
+}

package/src/core/runtime/shared/options.ts

@@ -0,0 +1,60 @@
+/**
+ * CLI Option Parsers
+ *
+ * Pure helpers for normalizing the `Record<string, unknown>` shape that
+ * Commander.js / our descriptor-driven CLI surface delivers to command
+ * handlers. Every parser returns `undefined` for empty/invalid input so
+ * callers can apply their own defaulting.
+ *
+ * Canonical home for option parsing per RUNTIME-FIRST-MODULES.md
+ * (`packages/cli` owns "the helpers that make runtime-discovered
+ * commands usable in shells"). Feature packages (bridge, expert, etc.)
+ * import from `@vibesdotdev/cli/core/runtime/shared/options` rather
+ * than maintaining per-package copies.
+ */
+
+export function readString(value: unknown): string | undefined {
+	if (typeof value !== 'string') return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function readBoolean(value: unknown): boolean | undefined {
+	if (typeof value === 'boolean') return value;
+	if (typeof value === 'string') {
+		if (value === 'true') return true;
+		if (value === 'false') return false;
+	}
+	return undefined;
+}
+
+export function readNumber(value: unknown): number | undefined {
+	if (typeof value === 'number' && Number.isFinite(value)) return value;
+	if (typeof value === 'string' && value.trim().length > 0) {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : undefined;
+	}
+	return undefined;
+}
+
+export function readStringArray(value: unknown): string[] | undefined {
+	if (Array.isArray(value)) {
+		const items = value
+			.map((entry) => readString(entry))
+			.filter((entry): entry is string => typeof entry === 'string');
+		return items.length > 0 ? items : undefined;
+	}
+
+	const single = readString(value);
+	return single ? [single] : undefined;
+}
+
+export function splitCsv(value: unknown): string[] | undefined {
+	const raw = readString(value);
+	if (!raw) return undefined;
+	const items = raw
+		.split(',')
+		.map((entry) => entry.trim())
+		.filter((entry) => entry.length > 0);
+	return items.length > 0 ? items : undefined;
+}

package/src/core/schemas/manifest.ts

@@ -0,0 +1,26 @@
+/**
+ * CLI Core Schema Manifest
+ * Compatibility shim for command manifests
+ */
+
+export interface CommandDoc {
+  path: string;
+  title: string;
+}
+
+export interface CommandEntry {
+  name: string;
+  description: string;
+  schema?: unknown;
+  access?: {
+    auth?: 'required' | 'optional' | 'none';
+  };
+  docs?: CommandDoc[];
+}
+
+export interface CommandManifest {
+  namespace: string;
+  description: string;
+  commands: CommandEntry[];
+  docs?: CommandDoc[];
+}

package/src/core/schemas/types.ts

@@ -0,0 +1,6 @@
+/**
+ * CLI Core Schema Types
+ * Compatibility shim
+ */
+export type { CLIContext } from '../../providers.ts';
+export type { RuntimeContext } from '../runtime/context.ts';

package/src/core/ui/interface.ts

@@ -0,0 +1,12 @@
+/**
+ * CLI UI Interface
+ * Compatibility shim for UI handles
+ */
+
+export interface IUIHandles {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  success(message: string): void;
+  log(message: string): void;
+}