@vibesdotdev/config 0.0.1

package/src/routing/types.ts

@@ -0,0 +1,470 @@
+/**
+ * Discriminated Routing Types
+ *
+ * Types for discriminated field routing - where a discriminator field value
+ * dynamically loads variant-specific fields, schemas, and component overrides.
+ */
+
+import type { ZodTypeAny } from 'zod/v4';
+import type { ConfigFieldMeta, ConfigFieldGroup } from '../manifest/types.ts';
+import type { FormStep } from '../crud/shared.ts';
+import type { LazyComponentOverride, ExtensionSurface } from '../extensions/types.ts';
+
+// Manifest Variant
+
+/**
+ * Surface-specific component overrides for a variant
+ */
+export interface VariantSurfaceOverrides {
+	/** TUI (React/OpenTUI) component overrides */
+	tui?: Record<string, LazyComponentOverride>;
+	/** Web (SvelteKit) component overrides */
+	web?: Record<string, LazyComponentOverride>;
+	/** CLI component overrides */
+	cli?: Record<string, LazyComponentOverride>;
+}
+
+/**
+ * A manifest variant that extends/overrides a base manifest
+ * based on a discriminator field value.
+ *
+ * @template TConfig - The configuration type for this variant
+ */
+export interface ManifestVariant<
+	TConfig extends Record<string, unknown> = Record<string, unknown>
+> {
+	/** Unique variant identifier (matches discriminator value) */
+	id: string;
+
+	/**
+	 * Schema extension (merged with base schema)
+	 * Variant-specific validation that extends the base schema
+	 */
+	schema?: ZodTypeAny;
+
+	/**
+	 * Field extensions - merged with base manifest fields
+	 * Variant fields are added/override base fields
+	 */
+	fields: Record<string, ConfigFieldMeta>;
+
+	/**
+	 * Field groups - merged with base manifest groups
+	 */
+	groups?: ConfigFieldGroup[];
+
+	/**
+	 * Default values for variant-specific fields
+	 * Merged with base defaults (variant wins on conflict)
+	 */
+	defaults?: Partial<TConfig>;
+
+	/**
+	 * Optional: Override step field placement
+	 * If not provided, fields auto-inject by matching group ID
+	 * If provided, completely replaces base form steps
+	 */
+	stepOverrides?: FormStep[];
+
+	/**
+	 * Surface-specific component overrides
+	 * Keyed by surface type, then by field key
+	 */
+	overrides?: VariantSurfaceOverrides;
+}
+
+// Routing Configuration
+
+/**
+ * Variant loader function type
+ * Used for lazy loading variants on demand
+ */
+export type VariantLoader = () => Promise<Map<string, ManifestVariant>>;
+
+/**
+ * Routing configuration for a manifest
+ * Enables discriminated field routing based on a field value
+ */
+export interface ManifestRouting {
+	/**
+	 * Field key that determines which variant to load
+	 * e.g., 'providerType', 'agentType'
+	 */
+	discriminator: string;
+
+	/**
+	 * Display priority for discriminator field (lower = first)
+	 * Controls where discriminator appears in forms
+	 * @default 0 (appears first)
+	 */
+	priority?: number;
+
+	/**
+	 * Variants map or lazy loader function
+	 * - Map: Eagerly loaded variants keyed by discriminator value
+	 * - Function: Lazy loader that returns variants on demand
+	 */
+	variants: Map<string, ManifestVariant> | VariantLoader;
+
+	/**
+	 * Optional fallback variant when discriminator value doesn't match
+	 */
+	fallback?: ManifestVariant;
+}
+
+// Nested Routing Configuration
+
+/**
+ * Nested routing configuration for sub-objects with their own discriminators.
+ * Used when a manifest contains multiple discriminated unions (e.g., agent roles).
+ *
+ * @example
+ * ```typescript
+ * // For autoloop config with multiple agent roles:
+ * nestedRoutings: [
+ *   { path: 'agents.orchestration', discriminator: 'type', variants: agentVariants },
+ *   { path: 'agents.development', discriminator: 'type', variants: agentVariants },
+ *   { path: 'agents.planning', discriminator: 'type', variants: agentVariants },
+ * ]
+ * ```
+ */
+export interface NestedRouting {
+	/**
+	 * Dot-notation path to the nested object containing the discriminator.
+	 * e.g., 'agents.orchestration', 'providers.primary'
+	 */
+	path: string;
+
+	/**
+	 * Field key within the nested object that determines variant.
+	 * e.g., 'type' (full path becomes 'agents.orchestration.type')
+	 */
+	discriminator: string;
+
+	/**
+	 * Display label for this nested routing section
+	 */
+	label: string;
+
+	/**
+	 * Optional description for the section
+	 */
+	description?: string;
+
+	/**
+	 * Optional icon for the section
+	 */
+	icon?: string;
+
+	/**
+	 * Field path for enable/disable toggle (relative to path).
+	 * When set, the section shows an enable/disable toggle.
+	 * e.g., 'enabled' (full path becomes 'agents.orchestration.enabled')
+	 */
+	enableField?: string;
+
+	/**
+	 * Whether this nested routing is required (no enable toggle).
+	 * @default false
+	 */
+	required?: boolean;
+
+	/**
+	 * Display priority (lower = first in list)
+	 * @default 100
+	 */
+	priority?: number;
+
+	/**
+	 * Variants map or lazy loader function.
+	 * Can reference shared variants across multiple nested routings.
+	 */
+	variants: Map<string, ManifestVariant> | VariantLoader;
+
+	/**
+	 * Optional fallback variant when discriminator value doesn't match
+	 */
+	fallback?: ManifestVariant;
+
+	/**
+	 * Fields to show in collapsed summary view.
+	 * Paths are relative to the nested object.
+	 * e.g., ['model', 'provider'] shows agents.orchestration.model
+	 */
+	summaryFields?: string[];
+
+	/**
+	 * Whether the section starts expanded
+	 * @default false
+	 */
+	defaultExpanded?: boolean;
+}
+
+/**
+ * Active nested variant state for tracking multiple discriminators
+ */
+export interface ActiveNestedVariant {
+	/** The routing path this variant is active for */
+	path: string;
+	/** The discriminator value */
+	discriminatorValue: string;
+	/** The resolved variant */
+	variant: ManifestVariant;
+	/** Whether this section is enabled (if enableField is set) */
+	enabled: boolean;
+}
+
+/**
+ * Result of resolving a nested variant
+ */
+export interface ResolvedNestedVariant<
+	TConfig extends Record<string, unknown> = Record<string, unknown>
+> {
+	/** The routing path */
+	path: string;
+	/** The resolved variant (or undefined if not found) */
+	variant?: ManifestVariant<TConfig>;
+	/** Whether the variant was found */
+	found: boolean;
+	/** The discriminator value used for lookup */
+	discriminatorValue: string;
+	/** Whether fallback was used */
+	usedFallback: boolean;
+	/** Whether this nested routing is enabled */
+	enabled: boolean;
+}
+
+// Provider Module (Domain-Specific Extension)
+
+/**
+ * Authentication type for provider connections
+ */
+export type ProviderAuthType = 'none' | 'bearer' | 'api_key' | 'basic' | 'oauth';
+
+/**
+ * Provider category for organization
+ */
+export type ProviderCategory = 'local' | 'cloud' | 'custom';
+
+/**
+ * Hardware constraint for provider execution
+ * - 'consumer': Runs on user's machine (CLI, local server)
+ * - 'cloud': Runs on platform servers
+ */
+export type HardwareConstraint = 'consumer' | 'cloud';
+
+/**
+ * Provider client interface - minimal contract for lazy-loaded clients
+ */
+export interface ProviderClient {
+	/** Provider identifier */
+	readonly providerId: string;
+	/** Test connection to the provider */
+	testConnection?(): Promise<{ success: boolean; error?: string }>;
+}
+
+/**
+ * Provider client factory type
+ */
+export type ProviderClientFactory = () => Promise<ProviderClient>;
+
+/**
+ * Provider metadata
+ */
+export interface ProviderMeta {
+	/** Display label */
+	label: string;
+	/** Icon (emoji) */
+	icon: string;
+	/** Short description */
+	description: string;
+	/** Provider category */
+	category: ProviderCategory;
+	/**
+	 * Hardware constraints - where this provider can run
+	 * Defaults to ['consumer', 'cloud'] if not specified
+	 */
+	hardware?: HardwareConstraint[];
+	/** Supported capabilities */
+	capabilities?: string[];
+	/** Documentation URL */
+	docsUrl?: string;
+}
+
+/**
+ * Provider adapter configuration
+ */
+export interface ProviderAdapter {
+	/** Lazy-load client factory (optional - only needed if connection testing is implemented) */
+	client?: ProviderClientFactory;
+	/** Authentication type */
+	authType: ProviderAuthType;
+	/** Whether connection test is available */
+	supportsConnectionTest?: boolean;
+}
+
+/**
+ * Complete provider module definition
+ *
+ * A provider module is a complete provider definition that includes:
+ * - Identity and metadata
+ * - Adapter/client implementation
+ * - Operating defaults
+ * - Config manifest variant
+ *
+ * @template TConfig - The configuration type for this provider
+ */
+export interface ProviderModule<TConfig extends Record<string, unknown> = Record<string, unknown>> {
+	/** Unique provider identifier (e.g., 'local-llm', 'cloud-llm') */
+	id: string;
+
+	/** Provider type for discrimination (usually same as id) */
+	type: string;
+
+	/** Provider metadata */
+	meta: ProviderMeta;
+
+	/** Adapter configuration */
+	adapter: ProviderAdapter;
+
+	/** Operating defaults for this provider */
+	defaults: TConfig;
+
+	/** Config manifest variant */
+	config: ManifestVariant<TConfig>;
+}
+
+// Variant Resolution Types
+
+/**
+ * Result of variant resolution
+ */
+export interface ResolvedVariant<
+	TConfig extends Record<string, unknown> = Record<string, unknown>
+> {
+	/** The resolved variant (or undefined if not found) */
+	variant?: ManifestVariant<TConfig>;
+	/** Whether the variant was found */
+	found: boolean;
+	/** The discriminator value used for lookup */
+	discriminatorValue: string;
+	/** Whether fallback was used */
+	usedFallback: boolean;
+}
+
+/**
+ * Options for getting surface overrides from a variant
+ */
+export interface GetVariantOverridesOptions {
+	/** The variant to get overrides from */
+	variant: ManifestVariant;
+	/** Target surface */
+	surface: ExtensionSurface;
+	/** Whether to include base manifest overrides */
+	includeBase?: boolean;
+}
+
+// Type Guards
+
+/**
+ * Type guard to check if routing has lazy variants
+ */
+export function hasLazyVariants(
+	routing: ManifestRouting
+): routing is ManifestRouting & { variants: VariantLoader } {
+	return typeof routing.variants === 'function';
+}
+
+/**
+ * Type guard to check if routing has eager variants
+ */
+export function hasEagerVariants(
+	routing: ManifestRouting
+): routing is ManifestRouting & { variants: Map<string, ManifestVariant> } {
+	return routing.variants instanceof Map;
+}
+
+/**
+ * Type guard to check if an object is a ManifestVariant
+ */
+export function isManifestVariant(obj: unknown): obj is ManifestVariant {
+	return (
+		typeof obj === 'object' &&
+		obj !== null &&
+		'id' in obj &&
+		'fields' in obj &&
+		typeof (obj as ManifestVariant).id === 'string' &&
+		typeof (obj as ManifestVariant).fields === 'object'
+	);
+}
+
+/**
+ * Type guard to check if an object is a ProviderModule
+ */
+export function isProviderModule(obj: unknown): obj is ProviderModule {
+	return (
+		typeof obj === 'object' &&
+		obj !== null &&
+		'id' in obj &&
+		'type' in obj &&
+		'meta' in obj &&
+		'adapter' in obj &&
+		'defaults' in obj &&
+		'config' in obj &&
+		isManifestVariant((obj as ProviderModule).config)
+	);
+}
+
+/**
+ * Type guard to check if nested routing has lazy variants
+ */
+export function hasNestedLazyVariants(
+	routing: NestedRouting
+): routing is NestedRouting & { variants: VariantLoader } {
+	return typeof routing.variants === 'function';
+}
+
+/**
+ * Type guard to check if nested routing has eager variants
+ */
+export function hasNestedEagerVariants(
+	routing: NestedRouting
+): routing is NestedRouting & { variants: Map<string, ManifestVariant> } {
+	return routing.variants instanceof Map;
+}
+
+/**
+ * Type guard to check if an object is a NestedRouting
+ */
+export function isNestedRouting(obj: unknown): obj is NestedRouting {
+	return (
+		typeof obj === 'object' &&
+		obj !== null &&
+		'path' in obj &&
+		'discriminator' in obj &&
+		'label' in obj &&
+		'variants' in obj &&
+		typeof (obj as NestedRouting).path === 'string' &&
+		typeof (obj as NestedRouting).discriminator === 'string' &&
+		typeof (obj as NestedRouting).label === 'string'
+	);
+}
+
+/**
+ * Get the full discriminator path for a nested routing
+ * @param routing - The nested routing
+ * @returns Full dot-notation path (e.g., 'agents.orchestration.type')
+ */
+export function getNestedDiscriminatorPath(routing: NestedRouting): string {
+	return `${routing.path}.${routing.discriminator}`;
+}
+
+/**
+ * Get the full enable field path for a nested routing
+ * @param routing - The nested routing
+ * @returns Full dot-notation path or undefined if no enable field
+ */
+export function getNestedEnablePath(routing: NestedRouting): string | undefined {
+	if (!routing.enableField) return undefined;
+	return `${routing.path}.${routing.enableField}`;
+}