@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/core/config.ts

@@ -0,0 +1,1285 @@
+/**
+ * Bootspring Configuration
+ * Handles loading and validating bootspring.config.js
+ *
+ * @package bootspring
+ * @module core/config
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { z } from 'zod';
+
+// =============================================================================
+// Zod Schemas for Configuration Validation
+// =============================================================================
+
+// -----------------------------------------------------------------------------
+// Plugin Schemas
+// -----------------------------------------------------------------------------
+
+/**
+ * Base plugin schema - all plugins share these common fields
+ */
+export const BasePluginSchema = z.object({
+  enabled: z.boolean().optional().default(false),
+  provider: z.string().optional(),
+  features: z.array(z.string()).optional().default([])
+}).passthrough();
+
+/**
+ * Auth plugin schema with specific provider options
+ */
+export const AuthPluginSchema = z.object({
+  enabled: z.boolean().optional().default(false),
+  provider: z.enum(['clerk', 'nextauth', 'auth0', 'supabase', 'jwt', 'custom']).optional(),
+  features: z.array(z.enum([
+    'social_login', 'email_password', 'magic_link', 'sso', 'mfa', 'rbac', 'passwordless'
+  ])).optional().default([])
+}).passthrough();
+
+/**
+ * Payments plugin schema
+ */
+export const PaymentsPluginSchema = z.object({
+  enabled: z.boolean().optional().default(false),
+  provider: z.enum(['stripe', 'paddle', 'lemonsqueezy', 'paypal', 'custom']).optional(),
+  features: z.array(z.enum([
+    'checkout', 'subscriptions', 'invoices', 'usage_billing', 'trials', 'coupons'
+  ])).optional().default([])
+}).passthrough();
+
+/**
+ * Database plugin schema
+ */
+export const DatabasePluginSchema = z.object({
+  enabled: z.boolean().optional().default(true),
+  provider: z.enum(['prisma', 'drizzle', 'typeorm', 'kysely', 'custom']).optional(),
+  features: z.array(z.enum([
+    'migrations', 'transactions', 'seeding', 'multi_tenant', 'full_text_search', 'soft_delete'
+  ])).optional().default([])
+}).passthrough();
+
+/**
+ * Testing plugin schema
+ */
+export const TestingPluginSchema = z.object({
+  enabled: z.boolean().optional().default(true),
+  provider: z.enum(['vitest', 'jest', 'playwright', 'cypress', 'custom']).optional(),
+  features: z.array(z.enum([
+    'unit', 'integration', 'e2e', 'coverage', 'snapshot', 'mocking'
+  ])).optional().default([])
+}).passthrough();
+
+/**
+ * Security plugin schema
+ */
+export const SecurityPluginSchema = z.object({
+  enabled: z.boolean().optional().default(true),
+  provider: z.string().optional(),
+  features: z.array(z.enum([
+    'input_validation', 'rate_limiting', 'csrf', 'xss', 'sql_injection',
+    'audit', 'rbac', 'encryption', 'secrets_management'
+  ])).optional().default([])
+}).passthrough();
+
+/**
+ * AI plugin schema
+ */
+export const AIPluginSchema = z.object({
+  enabled: z.boolean().optional().default(false),
+  provider: z.enum(['anthropic', 'openai', 'google', 'cohere', 'custom']).optional(),
+  features: z.array(z.enum([
+    'streaming', 'tool_use', 'embeddings', 'rag', 'agents', 'vision'
+  ])).optional().default([])
+}).passthrough();
+
+/**
+ * Email plugin schema
+ */
+export const EmailPluginSchema = z.object({
+  enabled: z.boolean().optional().default(false),
+  provider: z.enum(['resend', 'sendgrid', 'postmark', 'ses', 'mailgun', 'custom']).optional(),
+  features: z.array(z.enum([
+    'transactional', 'marketing', 'templates', 'tracking'
+  ])).optional().default([])
+}).passthrough();
+
+/**
+ * Analytics plugin schema
+ */
+export const AnalyticsPluginSchema = z.object({
+  enabled: z.boolean().optional().default(false),
+  provider: z.enum(['posthog', 'amplitude', 'mixpanel', 'google_analytics', 'custom']).optional(),
+  features: z.array(z.enum([
+    'page_views', 'events', 'user_tracking', 'funnels', 'experiments'
+  ])).optional().default([])
+}).passthrough();
+
+/**
+ * Monitoring plugin schema
+ */
+export const MonitoringPluginSchema = z.object({
+  enabled: z.boolean().optional().default(false),
+  provider: z.enum(['sentry', 'datadog', 'newrelic', 'logrocket', 'custom']).optional(),
+  features: z.array(z.enum([
+    'error_tracking', 'performance', 'logs', 'alerts', 'apm'
+  ])).optional().default([])
+}).passthrough();
+
+/**
+ * Combined plugins schema with specific plugin types
+ */
+export const PluginsSchema = z.object({
+  auth: AuthPluginSchema.optional(),
+  payments: PaymentsPluginSchema.optional(),
+  database: DatabasePluginSchema.optional(),
+  testing: TestingPluginSchema.optional(),
+  security: SecurityPluginSchema.optional(),
+  ai: AIPluginSchema.optional(),
+  email: EmailPluginSchema.optional(),
+  analytics: AnalyticsPluginSchema.optional(),
+  monitoring: MonitoringPluginSchema.optional()
+}).catchall(BasePluginSchema);
+
+// Backward compatible alias
+export const PluginSchema = BasePluginSchema;
+
+// -----------------------------------------------------------------------------
+// Agent Configuration Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Individual agent configuration
+ */
+export const AgentConfigSchema = z.object({
+  enabled: z.boolean().optional().default(true),
+  expertise: z.array(z.string()).optional(),
+  customInstructions: z.string().optional(),
+  priority: z.enum(['high', 'medium', 'low']).optional().default('medium')
+}).passthrough();
+
+/**
+ * Agents section configuration
+ */
+export const AgentsConfigSchema = z.object({
+  enabled: z.record(z.string(), z.boolean()).optional(),
+  custom: z.record(z.string(), AgentConfigSchema).optional(),
+  defaults: z.array(z.string()).optional(),
+  settings: z.object({
+    maxConcurrent: z.number().int().min(1).max(10).optional().default(3),
+    timeout: z.number().int().min(1000).max(300000).optional().default(60000),
+    verbose: z.boolean().optional().default(false)
+  }).optional()
+}).passthrough();
+
+// -----------------------------------------------------------------------------
+// Skills Configuration Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Individual skill configuration
+ */
+export const SkillConfigSchema = z.object({
+  enabled: z.boolean().optional().default(true),
+  tier: z.enum(['free', 'pro', 'premium']).optional().default('free'),
+  category: z.string().optional(),
+  maxChars: z.number().int().min(100).optional()
+}).passthrough();
+
+/**
+ * Skills section configuration
+ */
+export const SkillsConfigSchema = z.object({
+  categories: z.record(z.string(), z.boolean()).optional(),
+  custom: z.record(z.string(), SkillConfigSchema).optional(),
+  external: z.object({
+    enabled: z.boolean().optional().default(false),
+    manifestUrl: z.string().url().optional(),
+    cacheDir: z.string().optional(),
+    requireSignature: z.boolean().optional().default(false)
+  }).optional(),
+  settings: z.object({
+    defaultMaxChars: z.number().int().min(100).optional().default(50000),
+    summaryByDefault: z.boolean().optional().default(false),
+    includeExternal: z.boolean().optional().default(false)
+  }).optional()
+}).passthrough();
+
+// -----------------------------------------------------------------------------
+// Workflows Configuration Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Workflow phase schema
+ */
+export const WorkflowPhaseSchema = z.object({
+  name: z.string().min(1, 'Phase name is required'),
+  agents: z.array(z.string()).min(1, 'At least one agent is required'),
+  duration: z.string().optional(),
+  parallel: z.boolean().optional().default(false),
+  description: z.string().optional()
+}).passthrough();
+
+/**
+ * Individual workflow configuration
+ */
+export const WorkflowConfigSchema = z.object({
+  name: z.string().min(1, 'Workflow name is required'),
+  description: z.string().optional(),
+  tier: z.enum(['free', 'pro']).optional().default('free'),
+  pack: z.string().optional(),
+  outcomes: z.array(z.string()).optional(),
+  completionSignals: z.array(z.string()).optional(),
+  phases: z.array(WorkflowPhaseSchema).min(1, 'At least one phase is required')
+}).passthrough();
+
+/**
+ * Workflows section configuration
+ */
+export const WorkflowsConfigSchema = z.object({
+  enabled: z.record(z.string(), z.boolean()).optional(),
+  custom: z.record(z.string(), WorkflowConfigSchema).optional(),
+  default: z.string().optional(),
+  settings: z.object({
+    autoAdvance: z.boolean().optional().default(true),
+    pauseBetweenPhases: z.boolean().optional().default(false),
+    trackSignals: z.boolean().optional().default(true),
+    emitTelemetry: z.boolean().optional().default(true)
+  }).optional()
+}).passthrough();
+
+// -----------------------------------------------------------------------------
+// Quality Configuration Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Quality check configuration
+ */
+export const QualityCheckSchema = z.union([
+  z.boolean(),
+  z.object({
+    enabled: z.boolean().optional().default(true),
+    checks: z.array(z.enum([
+      'lint', 'typecheck', 'test', 'build', 'security', 'coverage', 'format'
+    ])).optional()
+  })
+]);
+
+/**
+ * Quality section configuration
+ */
+export const QualityConfigSchema = z.object({
+  preCommit: QualityCheckSchema.optional().default(true),
+  prePush: QualityCheckSchema.optional().default(false),
+  preDeploy: QualityCheckSchema.optional(),
+  strictMode: z.boolean().optional().default(false),
+  coverage: z.object({
+    statements: z.number().min(0).max(100).optional(),
+    branches: z.number().min(0).max(100).optional(),
+    functions: z.number().min(0).max(100).optional(),
+    lines: z.number().min(0).max(100).optional()
+  }).optional()
+}).passthrough();
+
+// -----------------------------------------------------------------------------
+// Context Configuration Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Context generation configuration
+ */
+export const ContextConfigSchema = z.object({
+  includeEnvVars: z.boolean().optional().default(true),
+  includeTechStack: z.boolean().optional().default(true),
+  includePlugins: z.boolean().optional().default(true),
+  includeGitInfo: z.boolean().optional().default(true),
+  includeTodos: z.boolean().optional().default(true),
+  includeLearnings: z.boolean().optional().default(true),
+  customSections: z.array(z.object({
+    title: z.string(),
+    content: z.string()
+  })).optional().default([]),
+  maxSize: z.number().int().min(1000).optional()
+}).passthrough();
+
+// -----------------------------------------------------------------------------
+// Paths Configuration Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Paths configuration
+ */
+export const PathsConfigSchema = z.object({
+  context: z.string().optional().default('CLAUDE.md'),
+  config: z.string().optional().default('bootspring.config.js'),
+  todo: z.string().optional().default('todo.md'),
+  roadmap: z.string().optional().default('ROADMAP.md'),
+  changelog: z.string().optional().default('CHANGELOG.md'),
+  state: z.string().optional().default('.bootspring')
+}).passthrough();
+
+// -----------------------------------------------------------------------------
+// Dashboard Configuration Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Dashboard configuration
+ */
+export const DashboardConfigSchema = z.object({
+  port: z.number().int().min(1024).max(65535).optional().default(3456),
+  autoOpen: z.boolean().optional().default(false),
+  host: z.string().optional().default('localhost'),
+  theme: z.enum(['light', 'dark', 'system']).optional().default('system')
+}).passthrough();
+
+// -----------------------------------------------------------------------------
+// Project Configuration Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Project information schema
+ */
+export const ProjectConfigSchema = z.object({
+  name: z.string().min(1, 'Project name is required'),
+  description: z.string().optional().default(''),
+  version: z.string().regex(/^\d+\.\d+\.\d+/, 'Version must be semver format').optional().default('1.0.0'),
+  author: z.string().optional(),
+  license: z.string().optional(),
+  repository: z.string().url().optional()
+}).passthrough();
+
+// -----------------------------------------------------------------------------
+// Stack Configuration Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Technology stack configuration
+ */
+export const StackConfigSchema = z.object({
+  framework: z.enum([
+    'nextjs', 'remix', 'nuxt', 'sveltekit', 'astro', 'express', 'fastify', 'hono', 'custom'
+  ]).optional(),
+  language: z.enum(['typescript', 'javascript']).optional(),
+  database: z.enum(['postgresql', 'mysql', 'mongodb', 'sqlite', 'supabase', 'planetscale', 'none']).optional(),
+  hosting: z.enum([
+    'vercel', 'railway', 'render', 'fly', 'aws', 'gcp', 'azure', 'cloudflare', 'self-hosted', 'custom'
+  ]).optional()
+}).passthrough();
+
+// -----------------------------------------------------------------------------
+// Main Configuration Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Complete Bootspring configuration schema
+ */
+export const ConfigSchema = z.object({
+  project: ProjectConfigSchema.optional(),
+  stack: StackConfigSchema.optional(),
+  plugins: PluginsSchema.optional(),
+  agents: AgentsConfigSchema.optional(),
+  skills: SkillsConfigSchema.optional(),
+  workflows: WorkflowsConfigSchema.optional(),
+  dashboard: DashboardConfigSchema.optional(),
+  quality: QualityConfigSchema.optional(),
+  context: ContextConfigSchema.optional(),
+  paths: PathsConfigSchema.optional(),
+  mcp: z.object({
+    enabled: z.boolean().optional().default(false),
+    servers: z.record(z.string(), z.object({
+      command: z.string(),
+      args: z.array(z.string()).optional(),
+      env: z.record(z.string(), z.string()).optional()
+    })).optional()
+  }).optional()
+}).passthrough();
+
+// =============================================================================
+// TypeScript Types (using z.input for input types, z.infer for output types)
+// =============================================================================
+
+// Input types (what users provide - allows partial/missing defaults)
+export type BasePluginInput = z.input<typeof BasePluginSchema>;
+export type AuthPluginInput = z.input<typeof AuthPluginSchema>;
+export type PaymentsPluginInput = z.input<typeof PaymentsPluginSchema>;
+export type DatabasePluginInput = z.input<typeof DatabasePluginSchema>;
+export type TestingPluginInput = z.input<typeof TestingPluginSchema>;
+export type SecurityPluginInput = z.input<typeof SecurityPluginSchema>;
+export type AIPluginInput = z.input<typeof AIPluginSchema>;
+export type EmailPluginInput = z.input<typeof EmailPluginSchema>;
+export type AnalyticsPluginInput = z.input<typeof AnalyticsPluginSchema>;
+export type MonitoringPluginInput = z.input<typeof MonitoringPluginSchema>;
+export type PluginsInput = z.input<typeof PluginsSchema>;
+export type ConfigInput = z.input<typeof ConfigSchema>;
+
+// Output types (after parsing with defaults applied)
+export type BasePlugin = z.infer<typeof BasePluginSchema>;
+export type AuthPlugin = z.infer<typeof AuthPluginSchema>;
+export type PaymentsPlugin = z.infer<typeof PaymentsPluginSchema>;
+export type DatabasePlugin = z.infer<typeof DatabasePluginSchema>;
+export type TestingPlugin = z.infer<typeof TestingPluginSchema>;
+export type SecurityPlugin = z.infer<typeof SecurityPluginSchema>;
+export type AIPlugin = z.infer<typeof AIPluginSchema>;
+export type EmailPlugin = z.infer<typeof EmailPluginSchema>;
+export type AnalyticsPlugin = z.infer<typeof AnalyticsPluginSchema>;
+export type MonitoringPlugin = z.infer<typeof MonitoringPluginSchema>;
+export type Plugins = z.infer<typeof PluginsSchema>;
+
+export type AgentConfig = z.infer<typeof AgentConfigSchema>;
+export type AgentsConfig = z.infer<typeof AgentsConfigSchema>;
+
+export type SkillConfig = z.infer<typeof SkillConfigSchema>;
+export type SkillsConfig = z.infer<typeof SkillsConfigSchema>;
+
+export type ConfigWorkflowPhase = z.infer<typeof WorkflowPhaseSchema>;
+export type WorkflowConfig = z.infer<typeof WorkflowConfigSchema>;
+export type WorkflowsConfig = z.infer<typeof WorkflowsConfigSchema>;
+
+export type QualityCheck = z.infer<typeof QualityCheckSchema>;
+export type QualityConfig = z.infer<typeof QualityConfigSchema>;
+
+export type ContextConfig = z.infer<typeof ContextConfigSchema>;
+export type PathsConfig = z.infer<typeof PathsConfigSchema>;
+export type DashboardConfig = z.infer<typeof DashboardConfigSchema>;
+export type ConfigProjectConfig = z.infer<typeof ProjectConfigSchema>;
+export type ConfigStackConfig = z.infer<typeof StackConfigSchema>;
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+/**
+ * Loaded configuration with internal metadata
+ */
+export interface LoadedConfig extends ConfigInput {
+  _projectRoot?: string | undefined;
+  _configPath?: string | null | undefined;
+  _bootspringDir?: string | undefined;
+  _validation?: ValidationResult | { skipped: boolean } | undefined;
+}
+
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings?: string[] | undefined;
+  data?: Config | null | undefined;
+  validatedAt?: string | undefined;
+}
+
+/**
+ * Section validation result
+ */
+export interface SectionValidationResult {
+  valid: boolean;
+  errors: string[];
+  data: unknown;
+}
+
+/**
+ * Preset definition
+ */
+export interface PresetDefinition {
+  name: string;
+  description: string;
+  tags: string[];
+  extends: string | null;
+  config: Partial<ConfigInput>;
+}
+
+/**
+ * Preset info for listing
+ */
+export interface PresetInfo {
+  key: string;
+  name: string;
+  description: string;
+  tags?: string[] | undefined;
+  extends?: string | null | undefined;
+}
+
+/**
+ * List presets options
+ */
+export interface ListPresetsOptions {
+  tag?: string | undefined;
+  verbose?: boolean | undefined;
+}
+
+/**
+ * Validate options
+ */
+export interface ValidateOptions {
+  strict?: boolean | undefined;
+  sections?: string[] | undefined;
+}
+
+/**
+ * Load with validation options
+ */
+export interface LoadWithValidationOptions {
+  validate?: boolean | undefined;
+  strict?: boolean | undefined;
+  silent?: boolean | undefined;
+}
+
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+
+/**
+ * Format Zod validation errors into user-friendly messages
+ */
+export function formatValidationErrors(zodError: z.ZodError): string[] {
+  return zodError.issues.map(issue => {
+    const path = issue.path.join('.');
+    const prefix = path ? `${path}: ` : '';
+
+    switch (issue.code) {
+      case 'invalid_type':
+        return `${prefix}Expected ${issue.expected}, received ${issue.received}`;
+      case 'invalid_enum_value':
+        return `${prefix}Invalid value "${issue.received}". Expected one of: ${issue.options.join(', ')}`;
+      case 'too_small':
+        if (issue.type === 'string') {
+          return `${prefix}String must contain at least ${issue.minimum} character(s)`;
+        }
+        if (issue.type === 'array') {
+          return `${prefix}Array must contain at least ${issue.minimum} element(s)`;
+        }
+        return `${prefix}Value must be greater than or equal to ${issue.minimum}`;
+      case 'too_big':
+        return `${prefix}Value must be less than or equal to ${issue.maximum}`;
+      case 'invalid_string':
+        if (issue.validation === 'url') {
+          return `${prefix}Invalid URL format`;
+        }
+        if (issue.validation === 'regex') {
+          return `${prefix}Invalid format`;
+        }
+        return `${prefix}${issue.message}`;
+      default:
+        return `${prefix}${issue.message}`;
+    }
+  });
+}
+
+/**
+ * Section schema mapping
+ */
+const sectionSchemas: Record<string, z.ZodTypeAny> = {
+  project: ProjectConfigSchema,
+  stack: StackConfigSchema,
+  plugins: PluginsSchema,
+  agents: AgentsConfigSchema,
+  skills: SkillsConfigSchema,
+  workflows: WorkflowsConfigSchema,
+  dashboard: DashboardConfigSchema,
+  quality: QualityConfigSchema,
+  context: ContextConfigSchema,
+  paths: PathsConfigSchema
+};
+
+/**
+ * Validate a specific config section
+ */
+export function validateSection(section: string, data: unknown): SectionValidationResult {
+  const schema = sectionSchemas[section];
+  if (!schema) {
+    return {
+      valid: false,
+      errors: [`Unknown configuration section: ${section}`],
+      data: null
+    };
+  }
+
+  const result = schema.safeParse(data);
+
+  if (result.success) {
+    return {
+      valid: true,
+      errors: [],
+      data: result.data
+    };
+  }
+
+  return {
+    valid: false,
+    errors: formatValidationErrors(result.error),
+    data: null
+  };
+}
+
+// =============================================================================
+// Default Configuration
+// =============================================================================
+
+export const DEFAULT_CONFIG: ConfigInput = {
+  project: {
+    name: 'My Project',
+    description: '',
+    version: '1.0.0'
+  },
+  stack: {
+    framework: 'nextjs',
+    language: 'typescript',
+    database: 'postgresql',
+    hosting: 'vercel'
+  },
+  plugins: {
+    auth: { enabled: false, provider: 'clerk' },
+    payments: { enabled: false, provider: 'stripe' },
+    database: { enabled: true, provider: 'prisma' },
+    testing: { enabled: true, provider: 'vitest' },
+    security: { enabled: true },
+    ai: { enabled: false }
+  },
+  dashboard: {
+    port: 3456,
+    autoOpen: false
+  },
+  quality: {
+    preCommit: true,
+    prePush: false,
+    strictMode: false
+  },
+  paths: {
+    context: 'CLAUDE.md',
+    config: 'bootspring.config.js',
+    todo: 'todo.md'
+  }
+};
+
+// Config file names to search for
+export const CONFIG_FILES = [
+  'bootspring.config.js',
+  'bootspring.config.mjs',
+  'bootspring.config.json',
+  '.bootspringrc',
+  '.bootspringrc.js',
+  '.bootspringrc.json'
+];
+
+// =============================================================================
+// Configuration Presets
+// =============================================================================
+
+export const CONFIG_PRESETS: Record<string, PresetDefinition> = {
+  'saas-starter': {
+    name: 'SaaS Starter',
+    description: 'Full SaaS setup with auth, payments, and database',
+    tags: ['fullstack', 'production', 'monetization'],
+    extends: null,
+    config: {
+      stack: {
+        framework: 'nextjs',
+        language: 'typescript',
+        database: 'postgresql',
+        hosting: 'vercel'
+      },
+      plugins: {
+        auth: { enabled: true, provider: 'clerk', features: ['email_password', 'social_login'] },
+        payments: { enabled: true, provider: 'stripe', features: ['checkout', 'subscriptions'] },
+        database: { enabled: true, provider: 'prisma', features: ['migrations', 'seeding'] },
+        testing: { enabled: true, provider: 'vitest', features: ['unit', 'integration'] },
+        security: { enabled: true, features: ['input_validation', 'rate_limiting'] },
+        email: { enabled: true, provider: 'resend', features: ['transactional'] },
+        analytics: { enabled: true, provider: 'posthog', features: ['events', 'user_tracking'] },
+        ai: { enabled: false }
+      },
+      quality: {
+        preCommit: true,
+        prePush: false,
+        strictMode: false
+      }
+    }
+  },
+
+  'api-only': {
+    name: 'API Only',
+    description: 'Headless API configuration without frontend',
+    tags: ['backend', 'headless', 'microservice'],
+    extends: null,
+    config: {
+      stack: {
+        framework: 'express',
+        language: 'typescript',
+        database: 'postgresql',
+        hosting: 'railway'
+      },
+      plugins: {
+        auth: { enabled: true, provider: 'jwt', features: ['email_password'] },
+        payments: { enabled: false },
+        database: { enabled: true, provider: 'prisma', features: ['migrations', 'transactions'] },
+        testing: { enabled: true, provider: 'vitest', features: ['unit', 'integration'] },
+        security: { enabled: true, features: ['input_validation', 'rate_limiting', 'csrf'] },
+        monitoring: { enabled: true, provider: 'sentry', features: ['error_tracking', 'performance'] },
+        ai: { enabled: false }
+      },
+      quality: {
+        preCommit: true,
+        prePush: true,
+        strictMode: true
+      }
+    }
+  },
+
+  'static-site': {
+    name: 'Static Site',
+    description: 'Simple static site setup with optional CMS',
+    tags: ['static', 'content', 'marketing'],
+    extends: null,
+    config: {
+      stack: {
+        framework: 'astro',
+        language: 'typescript',
+        database: 'none',
+        hosting: 'vercel'
+      },
+      plugins: {
+        auth: { enabled: false },
+        payments: { enabled: false },
+        database: { enabled: false },
+        testing: { enabled: true, provider: 'vitest', features: ['unit'] },
+        security: { enabled: true, features: ['xss'] },
+        analytics: { enabled: true, provider: 'google_analytics', features: ['page_views'] },
+        ai: { enabled: false }
+      },
+      quality: {
+        preCommit: true,
+        prePush: false,
+        strictMode: false
+      }
+    }
+  },
+
+  'enterprise': {
+    name: 'Enterprise',
+    description: 'Enterprise-grade configuration with all security and quality features',
+    tags: ['enterprise', 'security', 'compliance'],
+    extends: 'saas-starter',
+    config: {
+      stack: {
+        framework: 'nextjs',
+        language: 'typescript',
+        database: 'postgresql',
+        hosting: 'aws'
+      },
+      plugins: {
+        auth: { enabled: true, provider: 'clerk', features: ['sso', 'mfa', 'rbac'] },
+        payments: { enabled: true, provider: 'stripe', features: ['checkout', 'subscriptions', 'invoices'] },
+        database: { enabled: true, provider: 'prisma', features: ['migrations', 'transactions', 'multi_tenant', 'soft_delete'] },
+        testing: { enabled: true, provider: 'vitest', features: ['unit', 'integration', 'e2e', 'coverage'] },
+        security: { enabled: true, features: ['input_validation', 'rate_limiting', 'csrf', 'audit', 'rbac', 'encryption'] },
+        monitoring: { enabled: true, provider: 'datadog', features: ['error_tracking', 'performance', 'logs', 'apm'] },
+        email: { enabled: true, provider: 'ses', features: ['transactional', 'tracking'] },
+        ai: { enabled: false }
+      },
+      quality: {
+        preCommit: true,
+        prePush: true,
+        preDeploy: { enabled: true, checks: ['lint', 'typecheck', 'test', 'build', 'security'] },
+        strictMode: true,
+        coverage: {
+          statements: 80,
+          branches: 75,
+          functions: 80,
+          lines: 80
+        }
+      }
+    }
+  },
+
+  'minimal': {
+    name: 'Minimal',
+    description: 'Bare minimum setup for quick prototyping',
+    tags: ['prototype', 'minimal', 'quick'],
+    extends: null,
+    config: {
+      stack: {
+        framework: 'nextjs',
+        language: 'typescript',
+        database: 'none',
+        hosting: 'vercel'
+      },
+      plugins: {
+        auth: { enabled: false },
+        payments: { enabled: false },
+        database: { enabled: false },
+        testing: { enabled: false },
+        security: { enabled: true },
+        ai: { enabled: false }
+      },
+      quality: {
+        preCommit: false,
+        prePush: false,
+        strictMode: false
+      }
+    }
+  },
+
+  'ai-app': {
+    name: 'AI Application',
+    description: 'AI-powered application with Claude integration',
+    tags: ['ai', 'llm', 'anthropic'],
+    extends: null,
+    config: {
+      stack: {
+        framework: 'nextjs',
+        language: 'typescript',
+        database: 'postgresql',
+        hosting: 'vercel'
+      },
+      plugins: {
+        auth: { enabled: true, provider: 'clerk', features: ['email_password'] },
+        payments: { enabled: false },
+        database: { enabled: true, provider: 'prisma', features: ['migrations'] },
+        testing: { enabled: true, provider: 'vitest', features: ['unit', 'mocking'] },
+        security: { enabled: true, features: ['input_validation', 'rate_limiting'] },
+        ai: { enabled: true, provider: 'anthropic', features: ['streaming', 'tool_use'] }
+      },
+      quality: {
+        preCommit: true,
+        prePush: false,
+        strictMode: false
+      }
+    }
+  }
+};
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Deep merge two objects
+ */
+export function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T {
+  const result = { ...target } as T;
+
+  for (const key of Object.keys(source) as (keyof T)[]) {
+    const sourceValue = source[key];
+    const targetValue = target[key];
+
+    if (Array.isArray(sourceValue)) {
+      (result as Record<string, unknown>)[key as string] = [...sourceValue];
+    } else if (
+      sourceValue !== null &&
+      typeof sourceValue === 'object' &&
+      !Array.isArray(sourceValue) &&
+      targetValue !== null &&
+      typeof targetValue === 'object' &&
+      !Array.isArray(targetValue)
+    ) {
+      (result as Record<string, unknown>)[key as string] = deepMerge(
+        targetValue as Record<string, unknown>,
+        sourceValue as Record<string, unknown>
+      );
+    } else if (sourceValue !== undefined) {
+      (result as Record<string, unknown>)[key as string] = sourceValue;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Find the project root directory
+ */
+export function findProjectRoot(): string {
+  let dir = process.cwd();
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    if (
+      fs.existsSync(path.join(dir, 'package.json')) ||
+      fs.existsSync(path.join(dir, 'bootspring.config.js')) ||
+      fs.existsSync(path.join(dir, '.git'))
+    ) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+
+  return process.cwd();
+}
+
+/**
+ * Find config file in project
+ */
+export function findConfigFile(projectRoot: string): string | null {
+  for (const filename of CONFIG_FILES) {
+    const filepath = path.join(projectRoot, filename);
+    if (fs.existsSync(filepath)) {
+      return filepath;
+    }
+  }
+  return null;
+}
+
+// =============================================================================
+// Preset Functions
+// =============================================================================
+
+/**
+ * Get a preset configuration
+ */
+export function getPreset(presetName: string): PresetDefinition | null {
+  return CONFIG_PRESETS[presetName] ?? null;
+}
+
+/**
+ * Resolve preset inheritance chain
+ */
+export function resolvePresetChain(presetName: string, seen: Set<string> = new Set()): ConfigInput {
+  const preset = CONFIG_PRESETS[presetName];
+  if (!preset) {
+    throw new Error(`Unknown preset: ${presetName}. Available: ${Object.keys(CONFIG_PRESETS).join(', ')}`);
+  }
+
+  if (seen.has(presetName)) {
+    throw new Error(`Circular preset inheritance detected: ${presetName}`);
+  }
+  seen.add(presetName);
+
+  let config: ConfigInput = { ...DEFAULT_CONFIG };
+
+  if (preset.extends) {
+    const parentConfig = resolvePresetChain(preset.extends, seen);
+    config = deepMerge(config, parentConfig);
+  }
+
+  config = deepMerge(config, preset.config as ConfigInput);
+
+  return config;
+}
+
+/**
+ * Apply a preset to configuration
+ */
+export function applyPreset(presetNames: string | string[], overrides: Partial<ConfigInput> = {}): ConfigInput {
+  const presets = Array.isArray(presetNames) ? presetNames : [presetNames];
+
+  if (presets.length === 0) {
+    throw new Error('At least one preset name is required');
+  }
+
+  let config: ConfigInput = { ...DEFAULT_CONFIG };
+
+  for (const presetName of presets) {
+    const trimmedName = presetName.trim();
+    const presetConfig = resolvePresetChain(trimmedName);
+    config = deepMerge(config, presetConfig);
+  }
+
+  config = deepMerge(config, overrides as ConfigInput);
+
+  return config;
+}
+
+/**
+ * Combine multiple presets
+ */
+export function combinePresets(presetNames: string[], overrides: Partial<ConfigInput> = {}): ConfigInput {
+  if (!Array.isArray(presetNames) || presetNames.length === 0) {
+    throw new Error('combinePresets requires a non-empty array of preset names');
+  }
+  return applyPreset(presetNames, overrides);
+}
+
+/**
+ * Parse preset string
+ */
+export function parsePresetString(presetString: string): string[] {
+  if (!presetString || typeof presetString !== 'string') {
+    return [];
+  }
+  return presetString.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/**
+ * Validate preset names
+ */
+export function validatePresets(presetNames: string | string[]): { valid: boolean; errors: string[]; validPresets: string[] } {
+  const presets = Array.isArray(presetNames) ? presetNames : [presetNames];
+  const errors: string[] = [];
+  const validPresets: string[] = [];
+  const availablePresets = Object.keys(CONFIG_PRESETS);
+
+  for (const preset of presets) {
+    if (CONFIG_PRESETS[preset]) {
+      validPresets.push(preset);
+    } else {
+      errors.push(`Unknown preset: "${preset}". Available: ${availablePresets.join(', ')}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors, validPresets };
+}
+
+/**
+ * Get presets by tag
+ */
+export function getPresetsByTag(tag: string): string[] {
+  return Object.entries(CONFIG_PRESETS)
+    .filter(([, preset]) => preset.tags && preset.tags.includes(tag))
+    .map(([key]) => key);
+}
+
+/**
+ * Create custom preset
+ */
+export function createCustomPreset(baseName: string, newName: string, customConfig: Partial<ConfigInput> = {}): PresetDefinition {
+  const basePreset = CONFIG_PRESETS[baseName];
+  if (!basePreset) {
+    throw new Error(`Unknown base preset: ${baseName}`);
+  }
+
+  return {
+    name: newName,
+    description: `Custom preset based on ${basePreset.name}`,
+    tags: [...(basePreset.tags || []), 'custom'],
+    extends: baseName,
+    config: customConfig
+  };
+}
+
+/**
+ * List available presets
+ */
+export function listPresets(options: ListPresetsOptions = {}): PresetInfo[] {
+  let entries = Object.entries(CONFIG_PRESETS);
+
+  if (options.tag) {
+    entries = entries.filter(([, preset]) =>
+      preset.tags && preset.tags.includes(options.tag!)
+    );
+  }
+
+  return entries.map(([key, preset]) => {
+    const info: PresetInfo = {
+      key,
+      name: preset.name,
+      description: preset.description
+    };
+
+    if (options.verbose) {
+      info.tags = preset.tags || [];
+      info.extends = preset.extends;
+    }
+
+    return info;
+  });
+}
+
+// =============================================================================
+// Core Functions
+// =============================================================================
+
+/**
+ * Load configuration from file
+ */
+export function load(projectRoot: string | null = null): LoadedConfig {
+  const root = projectRoot ?? findProjectRoot();
+  const configPath = findConfigFile(root);
+
+  let userConfig: Partial<Config> = {};
+
+  if (configPath) {
+    try {
+      if (configPath.endsWith('.json') || configPath.endsWith('.bootspringrc')) {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        userConfig = JSON.parse(content) as Partial<Config>;
+      } else {
+        delete require.cache[require.resolve(configPath)];
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        userConfig = require(configPath) as Partial<Config>;
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`Warning: Could not load config from ${configPath}: ${message}`);
+    }
+  }
+
+  const config: LoadedConfig = deepMerge(DEFAULT_CONFIG, userConfig);
+
+  config._projectRoot = root;
+  config._configPath = configPath;
+  config._bootspringDir = path.join(root, '.bootspring');
+
+  return config;
+}
+
+/**
+ * Save configuration to file
+ */
+export function save(config: LoadedConfig, filepath: string | null = null): boolean {
+  const root = config._projectRoot ?? findProjectRoot();
+  const targetPath = filepath ?? path.join(root, 'bootspring.config.js');
+
+  const cleanConfig = { ...config };
+  delete cleanConfig._projectRoot;
+  delete cleanConfig._configPath;
+  delete cleanConfig._bootspringDir;
+  delete cleanConfig._validation;
+
+  const content = `/**
+ * Bootspring Configuration
+ * https://bootspring.com/docs/configuration
+ */
+
+module.exports = ${JSON.stringify(cleanConfig, null, 2)};
+`;
+
+  try {
+    fs.writeFileSync(targetPath, content, 'utf-8');
+    return true;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error saving config: ${message}`);
+    return false;
+  }
+}
+
+/**
+ * Validate configuration
+ */
+export function validate(config: LoadedConfig, options: ValidateOptions = {}): ValidationResult {
+  const configToValidate = { ...config };
+  delete configToValidate._projectRoot;
+  delete configToValidate._configPath;
+  delete configToValidate._bootspringDir;
+  delete configToValidate._validation;
+
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (options.sections && options.sections.length > 0) {
+    let allValid = true;
+    const validatedData: Record<string, unknown> = {};
+
+    for (const section of options.sections) {
+      const sectionValue = (configToValidate as Record<string, unknown>)[section];
+      if (sectionValue !== undefined) {
+        const result = validateSection(section, sectionValue);
+        if (!result.valid) {
+          allValid = false;
+          errors.push(...result.errors);
+        } else {
+          validatedData[section] = result.data;
+        }
+      }
+    }
+
+    return {
+      valid: allValid,
+      errors,
+      warnings,
+      data: allValid ? validatedData as unknown as Config : null
+    };
+  }
+
+  const result = ConfigSchema.safeParse(configToValidate);
+
+  if (result.success) {
+    return {
+      valid: true,
+      errors: [],
+      warnings,
+      data: result.data
+    };
+  }
+
+  return {
+    valid: false,
+    errors: formatValidationErrors(result.error),
+    warnings,
+    data: null
+  };
+}
+
+/**
+ * Load and optionally validate configuration
+ */
+export function loadWithValidation(projectRoot: string | null = null, options: LoadWithValidationOptions = {}): LoadedConfig {
+  const { validate: shouldValidate = true, strict = false, silent = false } = options;
+
+  const config = load(projectRoot);
+
+  if (!shouldValidate) {
+    config._validation = { skipped: true };
+    return config;
+  }
+
+  const validation = validate(config);
+
+  config._validation = {
+    valid: validation.valid,
+    errors: validation.errors,
+    warnings: validation.warnings ?? [],
+    validatedAt: new Date().toISOString()
+  };
+
+  if (!validation.valid) {
+    if (strict) {
+      const errorMessage = `Configuration validation failed:\n${validation.errors.map(e => `  - ${e}`).join('\n')}`;
+      throw new Error(errorMessage);
+    }
+
+    if (!silent) {
+      console.warn('\x1b[33mWarning: Configuration has validation issues:\x1b[0m');
+      validation.errors.forEach(error => {
+        console.warn(`  \x1b[33m- ${error}\x1b[0m`);
+      });
+      console.warn('\x1b[33mThe configuration will still be used, but some features may not work correctly.\x1b[0m');
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Get validation hint for error path
+ */
+export function getValidationHint(errorPath: string): string | null {
+  const hints: Record<string, string> = {
+    'stack.framework': 'Valid frameworks: nextjs, remix, nuxt, sveltekit, astro, express, fastify, hono, custom',
+    'stack.language': 'Valid languages: typescript, javascript',
+    'stack.database': 'Valid databases: postgresql, mysql, mongodb, sqlite, supabase, planetscale, none',
+    'stack.hosting': 'Valid hosting options: vercel, railway, render, fly, aws, gcp, azure, cloudflare, self-hosted, custom',
+    'plugins.auth.provider': 'Valid auth providers: clerk, nextauth, auth0, supabase, jwt, custom',
+    'plugins.payments.provider': 'Valid payment providers: stripe, paddle, lemonsqueezy, paypal, custom',
+    'plugins.database.provider': 'Valid database ORMs: prisma, drizzle, typeorm, kysely, custom',
+    'plugins.testing.provider': 'Valid test frameworks: vitest, jest, playwright, cypress, custom',
+    'plugins.ai.providers': 'Valid AI providers: anthropic, openai, google, cohere, huggingface, custom',
+    'dashboard.port': 'Port must be between 1024 and 65535',
+    'project.version': 'Version must follow semver format (e.g., 1.0.0)'
+  };
+
+  return hints[errorPath] ?? null;
+}
+
+/**
+ * Parse and validate configuration with defaults
+ */
+export function parseConfig(config: LoadedConfig): Config {
+  const configToParse = { ...config };
+  delete configToParse._projectRoot;
+  delete configToParse._configPath;
+  delete configToParse._bootspringDir;
+  delete configToParse._validation;
+
+  const result = ConfigSchema.safeParse(configToParse);
+  if (result.success) {
+    return result.data;
+  }
+  return configToParse as Config;
+}
+
+/**
+ * Get default configuration
+ */
+export function getDefaults(): ConfigInput {
+  return { ...DEFAULT_CONFIG };
+}