@vibesdotdev/config 0.0.1

package/src/config.plugin.ts

@@ -0,0 +1,214 @@
+/**
+ * Config Plugin
+ *
+ * Registers config/manifest kind with the runtime.
+ * This is the entry point for the config module's runtime integration.
+ *
+ * The config/manifest kind extends storage/manifest with:
+ * - Form field metadata for UI rendering
+ * - Navigation configuration for settings placement
+ * - Context constraints for conditional availability
+ * - Configuration tiers (system, user, internal)
+ */
+
+import { createRuntimePlugin, loader } from '@vibesdotdev/runtime';
+import { createRuntimeImplementation } from '@vibesdotdev/runtime/factory/implementation';
+import {
+	ConfigManifestDescriptorSchema,
+	type ConfigManifestDescriptor
+} from './schemas/config-manifest-descriptor';
+import { ConfigManifest } from './manifest/config-manifest';
+import type { HardwareContext } from './manifest/types';
+import {
+	ConfigCollectionDescriptorSchema,
+	type ConfigCollectionDescriptor
+} from './schemas/collection';
+import { ConfigCollection } from './collection/collection';
+import { SettingsSectionDescriptorSchema } from './settings/settings-section.schema';
+import configLoaderDescriptor, {
+	type ConfigLoaderInterface,
+	type LoadResult,
+	type SaveResult
+} from './services/loader/loader.descriptor';
+
+// Config loader kind definition
+const configLoaderKind = {
+	id: 'config/loader',
+	descriptorSchema: configLoaderDescriptor.schemas.input,
+
+	/**
+	 * Default implementation selection:
+	 * - consumer + { storage: 'local' } → LocalConfigLoader
+	 * - consumer + { storage: 'local-first' } → LocalFirstConfigLoader (sync)
+	 * - cloud + { storage: 'cloud' } → CloudConfigLoader
+	 */
+	resolve: (_candidates: unknown[], scope: { hardware: string; qualifiers?: Record<string, unknown> }) => {
+		// Implementation selection is handled by runtime based on scope constraints
+		// Each implementation declares its scope, runtime picks the best match
+		return undefined; // Let runtime use implementation registration
+	}
+};
+
+// Type-safe kind definition
+const configManifestKind = {
+	id: 'config/manifest',
+	descriptorSchema: ConfigManifestDescriptorSchema,
+
+	/**
+	 * Default implementation: ConfigManifest
+	 *
+	 * ConfigManifest extends StorageManifest with:
+	 * - Form field metadata
+	 * - Context-aware defaults
+	 * - Visibility rules
+	 * - Navigation configuration
+	 */
+	defaultImplementation: ConfigManifest as new (
+		descriptor: ConfigManifestDescriptor
+	) => ConfigManifest<unknown>,
+
+	/**
+	 * Resolution strategy: Match by tier and context constraints.
+	 *
+	 * Config manifests are typically looked up by ID, but when
+	 * querying by tier or navigation, we filter by context.
+	 */
+	resolve: (candidates: ConfigManifestDescriptor[], scope: { hardware: string }) => {
+		// Filter to candidates matching hardware (type-safe cast to HardwareContext)
+		const hardwareContext = scope.hardware as HardwareContext;
+		const matching = candidates.filter((d: ConfigManifestDescriptor) => {
+			// Check hardware constraint
+			if (d.context?.hardware && !d.context.hardware.includes(hardwareContext)) {
+				return false;
+			}
+			// Check enabled
+			if (d.enabled === false) {
+				return false;
+			}
+			return true;
+		});
+
+		if (matching.length === 0) return undefined;
+
+		// Return first match (typically looked up by ID anyway)
+		return matching[0];
+	}
+};
+
+/**
+ * Config plugin - registers config/manifest kind with the runtime.
+ *
+ * Kinds registered:
+ * - `config/manifest` - User-editable configuration with form metadata
+ *
+ * Dependencies:
+ * - Requires storage plugin for adapter resolution
+ *
+ * @example
+ * ```ts
+ * import { getVibesRuntime } from '@vibesdotdev/runtime';
+ * import { storagePlugin } from '@vibesdotdev/storage';
+ * import configPlugin from 'config.plugin';
+ *
+ * const runtime = getVibesRuntime();
+ *
+ * // Register storage first (config depends on it)
+ * await runtime.registerPlugin(storagePlugin);
+ * await runtime.registerPlugin(configPlugin);
+ *
+ * // Now you can query config manifests
+ * const aiConfig = await runtime.query('config/manifest')
+ *   .filter(d => d.id === 'ai')
+ *   .resolve();
+ *
+ * const config = await aiConfig.loadWithDefaults(ctx);
+ * ```
+ */
+// Config collection kind definition
+const configCollectionKind = {
+	id: 'config/collection',
+	descriptorSchema: ConfigCollectionDescriptorSchema,
+
+	/**
+	 * Default implementation: ConfigCollection
+	 *
+	 * ConfigCollection groups related config manifests and provides
+	 * unified load/subscribe/dispose lifecycle.
+	 */
+	defaultImplementation: ConfigCollection as new (
+		descriptor: ConfigCollectionDescriptor,
+		...args: unknown[]
+	) => ConfigCollection
+};
+
+/**
+ * Settings section kind — pure-data contribution.
+ *
+ * Each owning module registers a `settings/section` descriptor naming its
+ * `config/manifest` IDs. Surfaces assemble the global Settings UI by
+ * concatenating every registered section, sorted by `order`. Config itself
+ * does not enumerate which sections exist.
+ *
+ * See `./settings/assemble.ts` for `assembleSettingsSections(runtime)`.
+ */
+const settingsSectionKind = {
+	id: 'settings/section',
+	descriptorSchema: SettingsSectionDescriptorSchema
+	// No defaultImplementation — descriptors are the contribution.
+	// No resolve override — runtime returns all registered candidates.
+};
+
+import type { AnyRuntimeKindDescriptor } from '@vibesdotdev/runtime';
+
+// CLI command descriptors
+import settingsDescriptor from './cli/settings.descriptor';
+import configContextDescriptor from './config.context.descriptor';
+
+// Docs
+import manifestsDescriptor from './docs/manifests.docs.descriptor';
+import environmentDescriptor from './docs/environment.docs.descriptor';
+import validationDescriptor from './docs/validation.docs.descriptor';
+
+export default createRuntimePlugin({
+	id: 'config',
+	name: 'Config Module',
+	description:
+		'User-editable configuration with form metadata, navigation, and context-aware defaults',
+
+	// Config depends on storage for adapter resolution. TUI integrations are
+	// activated after discovery so they do not depend on bootstrap order.
+	dependencies: ['storage'],
+
+	kinds: [
+		configLoaderKind,
+		configManifestKind,
+		configCollectionKind,
+		settingsSectionKind
+	] as readonly AnyRuntimeKindDescriptor[],
+
+	descriptors: [configLoaderDescriptor, settingsDescriptor, configContextDescriptor, manifestsDescriptor, environmentDescriptor, validationDescriptor],
+
+	loaders: [
+		// Config loader implementations - selected by runtime based on scope
+		loader(
+			'config.loader.local',
+			{ kind: 'config/loader', scope: 'consumer' },
+			() => import('./services/loader/loader.impl.consumer.js')
+		),
+		loader(
+			'config.loader.local-first',
+			{ kind: 'config/loader', scope: 'consumer' },
+			() => import('./services/loader/loader.impl.consumer.local-first.js')
+		),
+		loader(
+			'config.loader.cloud',
+			{ kind: 'config/loader', scope: 'cloud' },
+			() => import('./services/loader/loader.impl.cloud.js')
+		)
+	],
+
+	onRegister: async (_runtime) => {
+		// TUI apps (config settings, registry) are registered by
+		// @vibesdotdev/plugins-tui so they do not leak JSX into non-TUI consumers.
+	}
+});

package/src/crud/base-types.ts

@@ -0,0 +1,10 @@
+/**
+ * Leaf-level CRUD base types.
+ *
+ * Extracted from `./types.ts` so other type modules (extensions, routing)
+ * can reference `BaseRecord`, `CRUDViewMode`, and `FormStep` without
+ * cycling through the full crud/types module that itself imports those
+ * sibling type modules.
+ */
+
+export type { CRUDViewMode, BaseRecord, FormStep } from './schemas/base-types.schema.ts';

package/src/crud/index.ts

@@ -0,0 +1,15 @@
+export type { BaseRecord, CRUDViewMode, FormStep } from './base-types.ts';
+export type {
+	ListColumn,
+	ListViewConfig,
+	ListAction,
+	FormViewConfig,
+	DetailViewConfig,
+	DetailSection,
+	DeleteConfig,
+	DetectionConfig,
+	CRUDConfig,
+	RecordManifest,
+	CRUDPageProps
+} from './types.ts';
+export { isRecordManifest, hasNestedRoutings } from './types.ts';

package/src/crud/schemas/base-types.schema.ts

@@ -0,0 +1,20 @@
+export type CRUDViewMode = 'list' | 'create' | 'edit' | 'view' | 'delete';
+
+export interface BaseRecord {
+	id: string;
+}
+
+export interface FormStep {
+	id: string;
+	title: string;
+	description?: string;
+	icon?: string;
+	fields: string[];
+	validate?: 'fields' | 'custom' | 'none';
+	optional?: boolean;
+	visibleWhen?: {
+		field: string;
+		operator: 'equals' | 'notEquals' | 'in' | 'notIn' | 'exists' | 'isEmpty';
+		value?: unknown;
+	};
+}

package/src/crud/schemas/shared.schema.ts

@@ -0,0 +1,14 @@
+export interface BaseRecord {
+	id: string;
+	createdAt?: Date | string;
+	updatedAt?: Date | string;
+}
+
+export type CRUDViewMode = 'list' | 'create' | 'edit' | 'detail' | 'delete';
+
+export interface FormStep {
+	id: string;
+	title: string;
+	fields: string[];
+	optional?: boolean;
+}

package/src/crud/shared.ts

@@ -0,0 +1,8 @@
+/**
+ * CRUD Shared Types
+ *
+ * Base types that are shared across config modules to avoid circular dependencies.
+ * These are minimal type definitions that don't import from other config modules.
+ */
+
+export type { BaseRecord, CRUDViewMode, FormStep } from './schemas/shared.schema.ts';

package/src/crud/types.ts

@@ -0,0 +1,299 @@
+/**
+ * CRUD Metadata Types for Config Manifests
+ *
+ * Extends the manifest system with metadata for rendering
+ * list views, create/edit forms, and delete confirmations.
+ */
+
+import type { ReactNode } from 'react';
+import type { ConfigManifest, ConfigFieldMeta } from '../manifest/types.ts';
+import type { ExtensionSurface } from '../extensions/types.ts';
+import type { ManifestRouting, NestedRouting } from '../routing/types.ts';
+
+import type { BaseRecord, CRUDViewMode, FormStep } from './base-types.ts';
+export type { BaseRecord, CRUDViewMode, FormStep } from './base-types.ts';
+
+// =============================================================================
+// List View Configuration
+
+/**
+ * Column definition for list/table views
+ */
+export interface ListColumn<T = unknown> {
+	/** Field key to display (dot notation for nested) */
+	key: string;
+	/** Column header label */
+	label: string;
+	/** Column width (characters or 'auto') */
+	width?: number | 'auto';
+	/** Text alignment */
+	align?: 'left' | 'center' | 'right';
+	/** Whether column is sortable */
+	sortable?: boolean;
+	/** Custom render function */
+	render?: (value: unknown, record: T) => ReactNode;
+	/** Format preset (applies default render) */
+	format?: 'text' | 'number' | 'date' | 'boolean' | 'status' | 'badge';
+}
+
+/**
+ * List view configuration
+ */
+export interface ListViewConfig<T = unknown> {
+	/** Columns to display */
+	columns: ListColumn<T>[];
+	/** Field to use as display name in UI */
+	displayField: string;
+	/** Field to use as unique identifier */
+	idField?: string; // defaults to 'id'
+	/** Default sort field */
+	defaultSort?: string;
+	/** Default sort direction */
+	defaultSortDirection?: 'asc' | 'desc';
+	/** Empty state message */
+	emptyMessage?: string;
+	/** Whether to show search/filter */
+	searchable?: boolean;
+	/** Fields to search in */
+	searchFields?: string[];
+	/** Row actions (edit, delete, custom) */
+	actions?: ListAction[];
+	/** Bulk actions */
+	bulkActions?: ListAction[];
+}
+
+/**
+ * Action available in list view
+ */
+export interface ListAction {
+	id: string;
+	label: string;
+	icon?: string;
+	variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
+	/** When action should be disabled */
+	disabledWhen?: (record: unknown) => boolean;
+	/** When action should be hidden */
+	hiddenWhen?: (record: unknown) => boolean;
+}
+
+// Form View Configuration
+
+/**
+ * Form view configuration (create/edit)
+ */
+export interface FormViewConfig {
+	/** Title for create mode */
+	createTitle?: string;
+	/** Title for edit mode */
+	editTitle?: string;
+	/** Fields to show in create mode (defaults to all) */
+	createFields?: string[];
+	/** Fields to show in edit mode (defaults to all) */
+	editFields?: string[];
+	/** Fields that are read-only in edit mode */
+	readOnlyInEdit?: string[];
+	/** Whether to show cancel button */
+	showCancel?: boolean;
+	/** Submit button label for create */
+	createSubmitLabel?: string;
+	/** Submit button label for edit */
+	editSubmitLabel?: string;
+	/** Layout mode */
+	layout?: 'vertical' | 'horizontal' | 'grid';
+	/**
+	 * Optional wizard steps for multi-step forms.
+	 * If provided, form renders as a stepped wizard.
+	 * If omitted, form renders all fields in a single view.
+	 */
+	steps?: FormStep[];
+}
+
+// Detail View Configuration
+
+/**
+ * Detail/view configuration (read-only view of single record)
+ */
+export interface DetailViewConfig {
+	/** Title template (can include {field} placeholders) */
+	titleTemplate?: string;
+	/** Fields to display */
+	fields?: string[];
+	/** Whether to group fields */
+	grouped?: boolean;
+	/** Custom sections */
+	sections?: DetailSection[];
+}
+
+/**
+ * Section in detail view
+ */
+export interface DetailSection {
+	id: string;
+	title: string;
+	icon?: string;
+	fields: string[];
+	collapsed?: boolean;
+}
+
+// Delete Confirmation Configuration
+
+/**
+ * Delete confirmation configuration
+ */
+export interface DeleteConfig {
+	/** Confirmation message template */
+	confirmMessage?: string;
+	/** Whether to require typing name to confirm */
+	requireNameConfirmation?: boolean;
+	/** Warning message about consequences */
+	warningMessage?: string;
+	/** Related records that will be affected */
+	cascadeWarning?: string;
+}
+
+// Auto-Detection Configuration
+
+/**
+ * Auto-detection configuration for CRUD resources
+ * Enables scanning for local/cloud providers, agents, etc.
+ */
+export interface DetectionConfig<TDetected = unknown, TRecord = unknown> {
+	/** Whether detection is enabled */
+	enabled: boolean;
+	/** Function that performs detection */
+	detector: () => Promise<TDetected[]>;
+	/** Label for detection button */
+	label?: string;
+	/** Description of what will be detected */
+	description?: string;
+	/** Function to match detected item with existing record */
+	matcher: (detected: TDetected, existing: TRecord) => boolean;
+}
+
+// Combined CRUD Configuration
+
+/**
+ * Complete CRUD configuration for a record-type manifest
+ */
+export interface CRUDConfig<T = unknown, TDetected = unknown> {
+	/** List view configuration */
+	list: ListViewConfig<T>;
+	/** Form view configuration */
+	form?: FormViewConfig;
+	/** Detail view configuration */
+	detail?: DetailViewConfig;
+	/** Delete confirmation configuration */
+	delete?: DeleteConfig;
+	/** Auto-detection configuration */
+	detection?: DetectionConfig<TDetected, T>;
+	/** Whether records can be created */
+	canCreate?: boolean;
+	/** Whether records can be edited */
+	canEdit?: boolean;
+	/** Whether records can be deleted */
+	canDelete?: boolean;
+	/** Whether records can be duplicated */
+	canDuplicate?: boolean;
+}
+
+// Record Manifest (Manifest + CRUD Config)
+
+/**
+ * A manifest for record-type configurations (providers, agents, etc.)
+ * Extends ConfigManifest with CRUD metadata for automatic UI generation.
+ */
+export interface RecordManifest<T = unknown, TDetected = unknown> extends ConfigManifest {
+	/** CRUD configuration for list/form/detail views */
+	crud: CRUDConfig<T, TDetected>;
+	/** Schema for individual records (vs the full config) */
+	recordSchema?: ConfigManifest['schema'];
+	/**
+	 * Discriminated routing configuration (single discriminator).
+	 * When present, a discriminator field value determines which variant
+	 * fields, schema, and overrides are active.
+	 */
+	routing?: ManifestRouting;
+	/**
+	 * Nested routing configurations (multiple discriminators).
+	 * Used when a manifest contains multiple independent discriminated unions,
+	 * each at a different path. For example, agent role configurations where
+	 * each role (orchestration, development, etc.) has its own type discriminator.
+	 *
+	 * @example
+	 * ```typescript
+	 * nestedRoutings: [
+	 *   { path: 'agents.orchestration', discriminator: 'type', label: 'Orchestration Agent', variants: agentVariants },
+	 *   { path: 'agents.development', discriminator: 'type', label: 'Development Agent', variants: agentVariants },
+	 * ]
+	 * ```
+	 */
+	nestedRoutings?: NestedRouting[];
+}
+
+/**
+ * Type guard to check if manifest has CRUD config
+ */
+export function isRecordManifest(manifest: ConfigManifest): manifest is RecordManifest {
+	return 'crud' in manifest && manifest.crud !== undefined;
+}
+
+/**
+ * Type guard to check if manifest has nested routings
+ */
+export function hasNestedRoutings(
+	manifest: ConfigManifest
+): manifest is RecordManifest & { nestedRoutings: NestedRouting[] } {
+	return (
+		isRecordManifest(manifest) &&
+		'nestedRoutings' in manifest &&
+		Array.isArray(manifest.nestedRoutings) &&
+		manifest.nestedRoutings.length > 0
+	);
+}
+
+// CRUD Page Props
+
+/**
+ * Props for the generic CRUD page component
+ */
+export interface CRUDPageProps<T extends BaseRecord = BaseRecord> {
+	/** The record manifest */
+	manifest: RecordManifest<T>;
+	/** Surface for loading extensions (enables extension loading when set) */
+	surface?: ExtensionSurface;
+	/** Whether component is embedded (removes padding and FocusZone) */
+	embedded?: boolean;
+	/** Initial view mode */
+	initialMode?: CRUDViewMode;
+	/** Selected record ID (for edit/view/delete modes) */
+	selectedId?: string;
+	/** Called when navigating between modes */
+	onModeChange?: (mode: CRUDViewMode, recordId?: string) => void;
+	/** Called after successful create */
+	onCreated?: (record: T) => void;
+	/** Called after successful update */
+	onUpdated?: (record: T) => void;
+	/** Called after successful delete */
+	onDeleted?: (recordId: string) => void;
+	/** Custom list row renderer */
+	renderListRow?: (record: T, defaultRender: () => ReactNode) => ReactNode;
+	/** Custom form field renderer */
+	renderFormField?: (
+		field: ConfigFieldMeta,
+		value: unknown,
+		onChange: (value: unknown) => void,
+		defaultRender: () => ReactNode
+	) => ReactNode;
+	/** Custom detail field renderer */
+	renderDetailField?: (
+		field: ConfigFieldMeta,
+		value: unknown,
+		defaultRender: () => ReactNode
+	) => ReactNode;
+	/** Custom empty state */
+	renderEmpty?: () => ReactNode;
+	/** Custom header */
+	renderHeader?: (mode: CRUDViewMode, record?: T) => ReactNode;
+	/** Custom footer */
+	renderFooter?: (mode: CRUDViewMode, record?: T) => ReactNode;
+}