@vibesdotdev/config 0.0.1

package/src/manifest/types.ts

@@ -0,0 +1,726 @@
+/**
+ * Configuration Manifest Types
+ *
+ * Core type definitions for the universal configuration system.
+ * Manifests define configuration schemas with UI hints, context rules,
+ * and storage configuration.
+ */
+
+import type { z } from 'zod/v4';
+
+// Configuration Tiers
+
+/**
+ * Configuration tiers determine storage location, visibility, and access patterns
+ *
+ * - system: Platform-level settings (database-backed, admin-only)
+ * - user: User-facing configuration (JSON for CLI/TUI, database for web)
+ * - internal: Developer/tooling configuration (env vars, constants)
+ */
+export type ConfigTier = 'system' | 'user' | 'internal';
+
+/**
+ * Storage adapter types
+ *
+ * - auto: Automatically resolve based on tier and surface
+ * - json: JSON file storage (CLI/TUI)
+ * - localdb: LocalDB SQLite storage (unified with CLI config system)
+ * - cloud: Cloud settings API (Web/Bridge)
+ * - database: Database storage (system settings)
+ * - encrypted: Encrypted JSON storage
+ * - memory: In-memory storage (testing)
+ * - env: Environment variables (internal config)
+ */
+export type StorageAdapterType =
+	| 'auto'
+	| 'json'
+	| 'localdb'
+	| 'cloud'
+	| 'database'
+	| 'env'
+	| 'encrypted'
+	| 'memory';
+
+/**
+ * Storage scope for file-based adapters
+ */
+export type StorageScope = 'global' | 'project' | 'auto';
+
+/**
+ * UI surfaces that can render configuration forms
+ */
+export type ConfigSurface = 'tui' | 'cli' | 'web' | 'bridge';
+
+/**
+ * Hardware context for context-aware defaults
+ */
+export type HardwareContext = 'cloud' | 'consumer' | 'gpu' | 'cpu-only';
+
+/**
+ * Environment context
+ */
+export type EnvironmentContext = 'development' | 'staging' | 'production';
+
+// Navigation Types
+
+/**
+ * Predefined pages in the application
+ * Can be extended with string for custom pages
+ */
+export type NavigationPage =
+	| 'settings' // Global settings
+	| 'settings/account' // Account sub-page
+	| 'settings/storage' // Storage settings sub-page
+	| 'ai' // AI configuration page (/ai)
+	| 'knowledge' // Knowledge base page
+	| 'session' // Session management
+	| string // Custom pages
+	| null; // Hidden from navigation
+
+/**
+ * Predefined sections within pages
+ */
+export type NavigationSection =
+	| 'general'
+	| 'account'
+	| 'preferences'
+	| 'appearance'
+	| 'privacy'
+	| 'advanced'
+	| 'admin'
+	| string; // Custom sections
+
+/**
+ * Navigation configuration for a manifest
+ */
+export interface ManifestNavigation {
+	/**
+	 * Page/route where this manifest appears
+	 * - null = Don't show in any navigation (accessed programmatically only)
+	 * - 'settings' = Global settings page
+	 * - 'ai' = AI configuration page (/ai)
+	 */
+	page: NavigationPage;
+
+	/**
+	 * Section within the page for grouping multiple manifests
+	 * Sections become tabs or collapsible groups in the UI
+	 */
+	section?: NavigationSection;
+
+	/**
+	 * Display order within the section (lower = first)
+	 * @default 100
+	 */
+	order?: number;
+
+	/**
+	 * Whether to include in global settings page
+	 * Set false for domain-specific configs (AI, Knowledge, etc.)
+	 * @default true (unless page is domain-specific)
+	 */
+	showInGlobalSettings?: boolean;
+
+	/**
+	 * Parent manifest ID for hierarchical organization
+	 * Child manifests appear nested under parent
+	 */
+	parent?: string;
+
+	/**
+	 * Custom navigation label (defaults to manifest.name)
+	 */
+	label?: string;
+
+	/**
+	 * Icon for navigation (overrides manifest.icon for nav only)
+	 */
+	icon?: string;
+
+	/**
+	 * Tags for custom filtering beyond page/section
+	 */
+	tags?: string[];
+
+	/**
+	 * Additional route parameters or query strings
+	 */
+	params?: Record<string, string>;
+}
+
+// Configuration Context
+
+/**
+ * Runtime context available for conditional logic in manifests
+ */
+export interface ConfigContext {
+	/** Current hardware target */
+	hardware: HardwareContext;
+	/** Current environment */
+	environment: EnvironmentContext;
+	/** Current UI surface */
+	surface: ConfigSurface;
+	/** Whether user is authenticated */
+	isAuthenticated: boolean;
+	/** User's role (if authenticated) */
+	userRole?: string;
+	/** Feature flags that are enabled */
+	enabledFeatures: Set<string>;
+	/** Get a config value from another field or manifest */
+	get: <T = unknown>(path: string) => T | undefined;
+	/** Custom context values */
+	custom: Record<string, unknown>;
+}
+
+// Configuration Rules (Conditional Logic)
+
+/**
+ * Rule for conditional visibility, disabled state, or requirements
+ */
+export type ConfigRule =
+	| ConfigFieldRule
+	| ConfigContextRule
+	| ConfigAndRule
+	| ConfigOrRule
+	| ConfigNotRule
+	| ConfigFunctionRule;
+
+/** Rule based on another field's value */
+export interface ConfigFieldRule {
+	field: string;
+	operator: 'equals' | 'notEquals' | 'in' | 'notIn' | 'exists' | 'isEmpty';
+	value?: unknown;
+}
+
+/** Rule based on context */
+export interface ConfigContextRule {
+	context: keyof Omit<ConfigContext, 'get' | 'custom'> | `custom.${string}`;
+	operator: 'equals' | 'notEquals' | 'in' | 'notIn' | 'exists';
+	value?: unknown;
+}
+
+/** Combine rules with AND */
+export interface ConfigAndRule {
+	and: ConfigRule[];
+}
+
+/** Combine rules with OR */
+export interface ConfigOrRule {
+	or: ConfigRule[];
+}
+
+/** Negate a rule */
+export interface ConfigNotRule {
+	not: ConfigRule;
+}
+
+/** Custom function rule (for complex logic) */
+export interface ConfigFunctionRule {
+	fn: (ctx: ConfigContext, allValues: Record<string, unknown>) => boolean;
+}
+
+// Field UI Configuration
+
+/**
+ * UI component types for rendering fields
+ */
+export type FieldComponent =
+	| 'input'
+	| 'textarea'
+	| 'number'
+	| 'select'
+	| 'multi-select'
+	| 'radio-group'
+	| 'checkbox'
+	| 'switch'
+	| 'slider'
+	| 'color'
+	| 'date'
+	| 'datetime'
+	| 'file'
+	| 'password'
+	| 'secret'
+	| 'json'
+	| 'code'
+	| 'reference'
+	| 'multi-reference'
+	| 'custom';
+
+/**
+ * Field width in form layout
+ */
+export type FieldWidth = 'full' | 'half' | 'third' | 'quarter';
+
+/**
+ * UI configuration for a field
+ */
+export interface FieldUI {
+	/** Display label */
+	label: string;
+	/** Short description (shown near field) */
+	description?: string;
+	/** Longer help text (shown on hover/focus) */
+	helpText?: string;
+	/** Placeholder text for inputs */
+	placeholder?: string;
+	/** Icon (emoji or icon name) */
+	icon?: string;
+	/** Component to render */
+	component?: FieldComponent;
+	/** Custom component reference (when component is 'custom') */
+	customComponent?: string;
+	/** Display order within group */
+	order?: number;
+	/** Group this field belongs to */
+	group?: string;
+	/** Field width in form layout */
+	width?: FieldWidth;
+	/** Whether to hide the label */
+	hideLabel?: boolean;
+	/** Additional CSS classes */
+	className?: string;
+}
+
+/**
+ * Option for enum/select fields
+ */
+export interface FieldOption<T = string> {
+	/** Option value */
+	value: T;
+	/** Display label */
+	label: string;
+	/** Optional description */
+	description?: string;
+	/** Optional icon */
+	icon?: string;
+	/** When this option should be disabled */
+	disabledWhen?: ConfigRule;
+	/** When this option should be hidden */
+	hiddenWhen?: ConfigRule;
+}
+
+// Field Metadata
+
+/**
+ * Access control for system-tier fields
+ */
+export interface FieldAccess {
+	/** Whether this setting is visible to non-admin users */
+	isPublic?: boolean;
+	/** Whether this setting can be modified (vs read-only) */
+	isEditable?: boolean;
+	/** Required role to view/edit */
+	requiredRole?: string;
+	/** Surfaces where this field is available */
+	surfaces?: ConfigSurface[];
+}
+
+/**
+ * Conditional rules for field behavior
+ */
+export interface FieldRules {
+	/** When this field should be visible */
+	visibleWhen?: ConfigRule;
+	/** When this field should be disabled */
+	disabledWhen?: ConfigRule;
+	/** When this field is required (beyond schema) */
+	requiredWhen?: ConfigRule;
+	/** When to show a warning */
+	warnWhen?: ConfigRule;
+	/** Warning message */
+	warnMessage?: string;
+}
+
+/**
+ * Context-aware default values
+ */
+export interface FieldDefaults<T = unknown> {
+	/** Base default value (from schema or override) */
+	base: T;
+	/** Override defaults by hardware context */
+	byHardware?: Partial<Record<HardwareContext, T>>;
+	/** Override defaults by environment */
+	byEnvironment?: Partial<Record<EnvironmentContext, T>>;
+	/** Override defaults by surface */
+	bySurface?: Partial<Record<ConfigSurface, T>>;
+	/** Custom default resolver */
+	resolver?: (ctx: ConfigContext) => T;
+}
+
+/**
+ * Reference field configuration for entity lookups
+ */
+export interface ReferenceConfig {
+	/**
+	 * Entity type to reference (e.g., 'model', 'provider', 'tool', 'prompt')
+	 */
+	entity: string;
+	/**
+	 * Field to use as the value (default: 'id')
+	 */
+	valueField?: string;
+	/**
+	 * Field to use as the display label (default: 'name')
+	 */
+	labelField?: string;
+	/**
+	 * Optional description field for richer display
+	 */
+	descriptionField?: string;
+	/**
+	 * API endpoint to fetch options (if not using default entity resolution)
+	 */
+	endpoint?: string;
+	/**
+	 * Static filter to apply when fetching options
+	 */
+	filter?: Record<string, unknown>;
+	/**
+	 * Dynamic filter based on other field values
+	 * Key = filter param, Value = field path to get value from
+	 */
+	dynamicFilter?: Record<string, string>;
+	/**
+	 * Whether to allow creating new entities inline
+	 */
+	allowCreate?: boolean;
+	/**
+	 * For multi-reference: whether ordering matters (enables drag/drop)
+	 */
+	orderable?: boolean;
+	/**
+	 * Maximum number of selections (for multi-reference)
+	 */
+	maxItems?: number;
+	/**
+	 * Minimum number of selections (for multi-reference)
+	 */
+	minItems?: number;
+	/**
+	 * Custom component name for specialized rendering
+	 * e.g., 'ModelAndProviderSelect', 'ToolSelector'
+	 */
+	customRenderer?: string;
+	/**
+	 * Additional props to pass to the custom renderer
+	 */
+	customRendererProps?: Record<string, unknown>;
+}
+
+/**
+ * Complete field metadata
+ */
+export interface ConfigFieldMeta<T = unknown> {
+	/** UI configuration */
+	ui: FieldUI;
+	/** Conditional behavior rules */
+	rules?: FieldRules;
+	/** Context-aware defaults */
+	defaults?: FieldDefaults<T>;
+	/** Options for enum/select fields */
+	options?: FieldOption<T extends string ? T : string>[];
+	/** Reference configuration for entity lookup fields */
+	reference?: ReferenceConfig;
+	/** Access control (for system tier) */
+	access?: FieldAccess;
+	/** Dependencies on other fields (for validation/updates) */
+	dependsOn?: string[];
+	/** Tags for categorization/filtering */
+	tags?: string[];
+}
+
+// Field Groups
+
+/**
+ * Group of related fields for UI organization
+ */
+export interface ConfigFieldGroup {
+	/** Group identifier */
+	id: string;
+	/** Display label */
+	label: string;
+	/** Optional description */
+	description?: string;
+	/** Optional icon */
+	icon?: string;
+	/** Display order */
+	order?: number;
+	/** Whether group is collapsible */
+	collapsible?: boolean;
+	/** Whether group starts collapsed */
+	defaultCollapsed?: boolean;
+	/** When this group should be visible */
+	visibleWhen?: ConfigRule;
+}
+
+// Storage Configuration
+
+/**
+ * Storage source with priority for config loading
+ * Configs are loaded from all sources and merged by priority (higher = wins)
+ */
+export interface StorageSource {
+	/** Source type */
+	type: 'cwd-file' | 'user-file' | 'cwd-db' | 'user-db' | 'cloud';
+	/** Priority for merging (higher wins conflicts) */
+	priority: number;
+	/** Whether this source is read-only */
+	readonly?: boolean;
+	/** Adapter to use for this source */
+	adapter?: StorageAdapterType;
+}
+
+/**
+ * Storage configuration for a manifest
+ */
+export interface ManifestStorage {
+	/** Storage adapter to use (default: 'auto') */
+	adapter?: StorageAdapterType;
+	/** Scope for file-based adapters */
+	scope?: StorageScope;
+	/** Namespace/table/key prefix */
+	namespace: string;
+	/** Whether to encrypt sensitive fields */
+	encryptSensitive?: boolean;
+	/** Fields that should be encrypted */
+	sensitiveFields?: string[];
+	/** Migration version for schema changes */
+	version?: number;
+	/**
+	 * Multi-source configuration (optional)
+	 * When specified, config is loaded from all sources and merged by priority
+	 * Default priority: cwd-file(1) < user-file(2) < cwd-db(3) < user-db(4) < cloud(5)
+	 */
+	sources?: StorageSource[];
+	/**
+	 * Where new values are saved by default
+	 * @default 'user-file' for user tier, 'cwd-db' for system tier
+	 */
+	defaultSaveTarget?: StorageSource['type'];
+}
+
+// Component Overrides
+
+/**
+ * Lazy-loaded component override
+ * Uses dynamic import for code-splitting
+ */
+export type ComponentLoader<T = any> = () => Promise<{ default: T }>;
+
+/**
+ * CRUD component overrides per surface
+ */
+export interface CRUDComponentOverrides {
+	/** Custom list/table view component */
+	list?: ComponentLoader;
+	/** Custom create form component */
+	create?: ComponentLoader;
+	/** Custom edit form component */
+	edit?: ComponentLoader;
+	/** Custom detail/read view component */
+	detail?: ComponentLoader;
+	/** Custom delete confirmation component */
+	delete?: ComponentLoader;
+}
+
+/**
+ * Component overrides for different surfaces
+ */
+export interface ManifestComponents {
+	/** TUI (terminal) component overrides */
+	tui?: {
+		/** Main page component for this manifest */
+		page?: ComponentLoader;
+		/** CRUD component overrides */
+		crud?: CRUDComponentOverrides;
+	};
+	/** Web (Svelte) component overrides */
+	web?: {
+		/** Main page component for this manifest */
+		page?: ComponentLoader;
+		/** CRUD component overrides */
+		crud?: CRUDComponentOverrides;
+	};
+	/** CLI (non-interactive) component overrides */
+	cli?: {
+		/** Main page component for this manifest */
+		page?: ComponentLoader;
+	};
+}
+
+// Context Constraints
+
+/**
+ * Constraints on when a manifest applies
+ */
+export interface ManifestContext {
+	/** Hardware contexts where this manifest applies */
+	hardware?: HardwareContext[];
+	/** Environments where this manifest applies */
+	environment?: EnvironmentContext[];
+	/** Surfaces where this manifest applies */
+	surfaces?: ConfigSurface[];
+	/** Feature flags required for this manifest */
+	requiredFeatures?: string[];
+}
+
+// Config File Location
+
+/**
+ * Configuration for loading config from TypeScript/JavaScript files.
+ * Allows manifests to specify optional config file patterns like 'vibes.example.ts'.
+ */
+export interface ConfigFileLocation {
+	/**
+	 * File pattern to look for in project root.
+	 * Examples: 'vibes.example.ts', 'vibes.config.ts'
+	 */
+	pattern: string;
+
+	/**
+	 * Named export to look for in the file.
+	 * - 'default' = use default export
+	 * - string = use named export (e.g., 'exampleConfig')
+	 * - undefined = try default, then try export matching manifest id
+	 */
+	exportName?: string;
+
+	/**
+	 * For record-type manifests, a 'configs' export can contain multiple named configs.
+	 * This specifies the property name within that export.
+	 * Example: vibes.autoloop.ts exports { configs: { simple: {...}, full: {...} } }
+	 */
+	configsExport?: string;
+
+	/**
+	 * Priority relative to other sources (higher wins in merge).
+	 * @default 3 (above localdb at 2, below CLI overrides at 4)
+	 */
+	priority?: number;
+
+	/**
+	 * Whether this file is required (error if missing) or optional.
+	 * @default false
+	 */
+	required?: boolean;
+
+	/**
+	 * Additional file patterns to search (e.g., for legacy names).
+	 * Searched in order, first match wins.
+	 */
+	fallbackPatterns?: string[];
+}
+
+// Configuration Manifest
+
+/**
+ * Complete configuration manifest
+ *
+ * Defines a configuration namespace with its schema, field metadata,
+ * storage configuration, and context constraints.
+ *
+ * @template T - Zod schema type for the configuration
+ */
+export interface ConfigManifest<T extends z.ZodTypeAny = z.ZodTypeAny> {
+	// Identity
+
+	/** Unique identifier (e.g., 'ai', 'storage', 'system.settings') */
+	id: string;
+	/** Display name */
+	name: string;
+	/** Description */
+	description?: string;
+	/** Icon (emoji or icon name) */
+	icon?: string;
+	/** Schema version for migrations */
+	version?: number;
+
+	// Classification
+
+	/** Configuration tier */
+	tier: ConfigTier;
+	/** Category within the tier (for organization) */
+	category?: string;
+
+	// Schema
+
+	/** Zod schema (source of truth for validation) */
+	schema: T;
+
+	// Field Metadata
+
+	/** Field metadata keyed by field path */
+	fields: Record<string, ConfigFieldMeta>;
+
+	/** Field groups for UI organization */
+	groups?: ConfigFieldGroup[];
+
+	// Storage
+
+	/** Storage configuration */
+	storage: ManifestStorage;
+
+	// Config Files
+
+	/**
+	 * Optional config file location(s) for loading config from project files.
+	 * Config loaded from files is merged with storage-based config.
+	 * Multiple locations are searched in order; all matching files are merged.
+	 */
+	configFiles?: ConfigFileLocation | ConfigFileLocation[];
+
+	// Context
+
+	/** Context constraints for when this manifest applies */
+	context?: ManifestContext;
+
+	/**
+	 * Navigation and UI placement configuration
+	 * Determines where this manifest appears in the UI hierarchy
+	 * If omitted, manifest won't appear in any navigation
+	 */
+	navigation?: ManifestNavigation;
+
+	// Component Overrides
+
+	/**
+	 * Component overrides for different surfaces
+	 * Allows customizing how this manifest renders in TUI, Web, CLI
+	 * Uses lazy loading for code-splitting
+	 */
+	components?: ManifestComponents;
+
+	// Lifecycle
+
+	/** Called after config is loaded */
+	onLoad?: (config: z.infer<T>, ctx: ConfigContext) => z.infer<T> | Promise<z.infer<T>>;
+	/** Called before config is saved */
+	onSave?: (config: z.infer<T>, ctx: ConfigContext) => z.infer<T> | Promise<z.infer<T>>;
+	/** Called when a field changes */
+	onFieldChange?: (
+		field: string,
+		value: unknown,
+		allValues: Record<string, unknown>,
+		ctx: ConfigContext
+	) => Record<string, unknown> | void;
+}
+
+// Type Utilities
+
+/**
+ * Extract the config type from a manifest
+ */
+export type InferConfigType<M extends ConfigManifest> =
+	M extends ConfigManifest<infer T> ? z.infer<T> : never;
+
+/**
+ * Extract field paths from a Zod schema
+ */
+export type FieldPaths<T> =
+	T extends z.ZodObject<infer Shape>
+		? {
+				[K in keyof Shape]: Shape[K] extends z.ZodObject<any>
+					? `${K & string}` | `${K & string}.${FieldPaths<Shape[K]>}`
+					: K & string;
+			}[keyof Shape]
+		: never;