@girardmedia/bootspring 1.2.0 → 2.0.3

package/core/config.js

@@ -8,6 +8,502 @@
 
 const fs = require('fs');
 const path = require('path');
+const { z } = require('zod');
+
+// =============================================================================
+// Zod Schemas for Configuration Validation
+// =============================================================================
+
+// -----------------------------------------------------------------------------
+// Plugin Schemas
+// -----------------------------------------------------------------------------
+
+/**
+ * Base plugin schema - all plugins share these common fields
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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); // Allow additional plugins with base schema
+
+// Backward compatible alias
+const PluginSchema = BasePluginSchema;
+
+// -----------------------------------------------------------------------------
+// Agent Configuration Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Individual agent configuration
+ */
+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
+ */
+const AgentsConfigSchema = z.object({
+  // Enable/disable specific agents
+  enabled: z.record(z.string(), z.boolean()).optional(),
+  // Custom agent configurations
+  custom: z.record(z.string(), AgentConfigSchema).optional(),
+  // Default agents to suggest based on project type
+  defaults: z.array(z.string()).optional(),
+  // Agent invocation settings
+  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
+ */
+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
+ */
+const SkillsConfigSchema = z.object({
+  // Enable/disable skill categories
+  categories: z.record(z.string(), z.boolean()).optional(),
+  // Custom skill configurations
+  custom: z.record(z.string(), SkillConfigSchema).optional(),
+  // External skills settings
+  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(),
+  // Skill invocation settings
+  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
+ */
+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
+ */
+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
+ */
+const WorkflowsConfigSchema = z.object({
+  // Enable/disable specific workflows
+  enabled: z.record(z.string(), z.boolean()).optional(),
+  // Custom workflow definitions
+  custom: z.record(z.string(), WorkflowConfigSchema).optional(),
+  // Default workflow for the project
+  default: z.string().optional(),
+  // Workflow settings
+  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
+ */
+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 (extended)
+ */
+const QualityConfigSchema = z.object({
+  preCommit: QualityCheckSchema.optional().default(true),
+  prePush: QualityCheckSchema.optional().default(false),
+  preDeploy: QualityCheckSchema.optional(),
+  strictMode: z.boolean().optional().default(false),
+  // Coverage thresholds
+  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
+ */
+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([]),
+  // Maximum context file size
+  maxSize: z.number().int().min(1000).optional()
+}).passthrough();
+
+// -----------------------------------------------------------------------------
+// Paths Configuration Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Paths configuration
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+const ConfigSchema = z.object({
+  // Core project settings
+  project: ProjectConfigSchema.optional(),
+  stack: StackConfigSchema.optional(),
+
+  // Feature configurations
+  plugins: PluginsSchema.optional(),
+  agents: AgentsConfigSchema.optional(),
+  skills: SkillsConfigSchema.optional(),
+  workflows: WorkflowsConfigSchema.optional(),
+
+  // Tool configurations
+  dashboard: DashboardConfigSchema.optional(),
+  quality: QualityConfigSchema.optional(),
+  context: ContextConfigSchema.optional(),
+  paths: PathsConfigSchema.optional(),
+
+  // MCP configuration
+  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();
+
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+
+/**
+ * Format Zod validation errors into user-friendly messages
+ * @param {z.ZodError} zodError - Zod error object
+ * @returns {string[]} Array of formatted error messages
+ */
+function formatValidationErrors(zodError) {
+  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}`;
+    }
+  });
+}
+
+/**
+ * Validate a specific config section
+ * @param {string} section - Section name (e.g., 'plugins', 'agents')
+ * @param {object} data - Section data to validate
+ * @returns {object} Validation result { valid, errors, data }
+ */
+function validateSection(section, data) {
+  const sectionSchemas = {
+    project: ProjectConfigSchema,
+    stack: StackConfigSchema,
+    plugins: PluginsSchema,
+    agents: AgentsConfigSchema,
+    skills: SkillsConfigSchema,
+    workflows: WorkflowsConfigSchema,
+    dashboard: DashboardConfigSchema,
+    quality: QualityConfigSchema,
+    context: ContextConfigSchema,
+    paths: PathsConfigSchema
+  };
+
+  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
 const DEFAULT_CONFIG = {
@@ -30,7 +526,7 @@ const DEFAULT_CONFIG = {
     database: { enabled: true, provider: 'prisma' },
     testing: { enabled: true, provider: 'vitest' },
     security: { enabled: true },
-    ai: { enabled: false, provider: 'anthropic' }
+    ai: { enabled: false, providers: [] }
   },
 
   dashboard: {
@@ -61,6 +557,397 @@ const CONFIG_FILES = [
   '.bootspringrc.json'
 ];
 
+/**
+ * Predefined configuration presets
+ * Use with --preset flag or applyPreset() function
+ *
+ * Available presets:
+ * - saas-starter: Full SaaS setup (auth, payments, database)
+ * - api-only: Headless API configuration
+ * - static-site: Simple static site setup
+ * - enterprise: Enterprise-grade configuration
+ * - minimal: Bare minimum for prototyping
+ * - ai-app: AI-powered application
+ *
+ * Usage: bootspring init --preset saas-starter
+ * Combine: bootspring init --preset saas-starter,ai-app
+ */
+const CONFIG_PRESETS = {
+  '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, providers: ['anthropic'], features: ['streaming', 'tool_use'] }
+      },
+      quality: {
+        preCommit: true,
+        prePush: false,
+        strictMode: false
+      }
+    }
+  }
+};
+
+/**
+ * Get a preset configuration
+ * @param {string} presetName - Preset name
+ * @returns {object|null} Preset config or null if not found
+ */
+function getPreset(presetName) {
+  return CONFIG_PRESETS[presetName] || null;
+}
+
+/**
+ * Resolve preset inheritance chain
+ * @param {string} presetName - Preset name to resolve
+ * @param {Set} seen - Set of already seen presets (for circular detection)
+ * @returns {object} Resolved configuration including all parent presets
+ */
+function resolvePresetChain(presetName, seen = new Set()) {
+  const preset = CONFIG_PRESETS[presetName];
+  if (!preset) {
+    throw new Error(`Unknown preset: ${presetName}. Available: ${Object.keys(CONFIG_PRESETS).join(', ')}`);
+  }
+
+  // Detect circular inheritance
+  if (seen.has(presetName)) {
+    throw new Error(`Circular preset inheritance detected: ${presetName}`);
+  }
+  seen.add(presetName);
+
+  // Start with defaults
+  let config = { ...DEFAULT_CONFIG };
+
+  // If this preset extends another, resolve the parent first
+  if (preset.extends) {
+    const parentConfig = resolvePresetChain(preset.extends, seen);
+    config = deepMerge(config, parentConfig);
+  }
+
+  // Apply this preset's config on top
+  config = deepMerge(config, preset.config);
+
+  return config;
+}
+
+/**
+ * Apply a preset to the current configuration
+ * Supports single preset string or array of presets
+ * @param {string|string[]} presetNames - Preset name(s)
+ * @param {object} overrides - Additional overrides to apply
+ * @returns {object} Merged configuration
+ */
+function applyPreset(presetNames, overrides = {}) {
+  // Normalize to array
+  const presets = Array.isArray(presetNames) ? presetNames : [presetNames];
+
+  if (presets.length === 0) {
+    throw new Error('At least one preset name is required');
+  }
+
+  // Start with defaults
+  let config = { ...DEFAULT_CONFIG };
+
+  // Apply each preset in order (later presets override earlier ones)
+  for (const presetName of presets) {
+    const trimmedName = presetName.trim();
+    const presetConfig = resolvePresetChain(trimmedName);
+    config = deepMerge(config, presetConfig);
+  }
+
+  // Apply any overrides
+  config = deepMerge(config, overrides);
+
+  return config;
+}
+
+/**
+ * Combine multiple presets into a single configuration
+ * This is an alias for applyPreset with array input
+ * @param {string[]} presetNames - Array of preset names to combine
+ * @param {object} overrides - Additional overrides to apply
+ * @returns {object} Combined configuration
+ */
+function combinePresets(presetNames, overrides = {}) {
+  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 (supports comma-separated presets)
+ * @param {string} presetString - Preset string (e.g., "saas-starter" or "saas-starter,ai-app")
+ * @returns {string[]} Array of preset names
+ */
+function parsePresetString(presetString) {
+  if (!presetString || typeof presetString !== 'string') {
+    return [];
+  }
+  return presetString.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/**
+ * Validate preset name(s)
+ * @param {string|string[]} presetNames - Preset name(s) to validate
+ * @returns {object} Validation result { valid, errors, validPresets }
+ */
+function validatePresets(presetNames) {
+  const presets = Array.isArray(presetNames) ? presetNames : [presetNames];
+  const errors = [];
+  const validPresets = [];
+  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 preset by tag
+ * @param {string} tag - Tag to search for
+ * @returns {Array} Array of preset keys that have this tag
+ */
+function getPresetsByTag(tag) {
+  return Object.entries(CONFIG_PRESETS)
+    .filter(([_key, preset]) => preset.tags && preset.tags.includes(tag))
+    .map(([key]) => key);
+}
+
+/**
+ * Create a custom preset from an existing preset
+ * @param {string} baseName - Base preset name to extend
+ * @param {string} newName - Name for the new preset
+ * @param {object} customConfig - Custom configuration to apply
+ * @returns {object} The new preset definition
+ */
+function createCustomPreset(baseName, newName, customConfig = {}) {
+  const basePreset = CONFIG_PRESETS[baseName];
+  if (!basePreset) {
+    throw new Error(`Unknown base preset: ${baseName}`);
+  }
+
+  const customPreset = {
+    name: newName,
+    description: `Custom preset based on ${basePreset.name}`,
+    tags: [...(basePreset.tags || []), 'custom'],
+    extends: baseName,
+    config: customConfig
+  };
+
+  return customPreset;
+}
+
+/**
+ * List available presets
+ * @param {object} options - List options
+ * @param {string} options.tag - Filter by tag
+ * @param {boolean} options.verbose - Include full descriptions and tags
+ * @returns {Array} Array of preset info objects
+ */
+function listPresets(options = {}) {
+  let entries = Object.entries(CONFIG_PRESETS);
+
+  // Filter by tag if specified
+  if (options.tag) {
+    entries = entries.filter(([_key, preset]) =>
+      preset.tags && preset.tags.includes(options.tag)
+    );
+  }
+
+  return entries.map(([key, preset]) => {
+    const info = {
+      key,
+      name: preset.name,
+      description: preset.description
+    };
+
+    if (options.verbose) {
+      info.tags = preset.tags || [];
+      info.extends = preset.extends || null;
+    }
+
+    return info;
+  });
+}
+
 /**
  * Find the project root directory
  * @returns {string|null} Project root path or null
@@ -101,6 +988,7 @@ function findConfigFile(projectRoot) {
 
 /**
  * Deep merge two objects
+ * Arrays are replaced (not merged) to maintain preset integrity
  * @param {object} target - Target object
  * @param {object} source - Source object
  * @returns {object} Merged object
@@ -109,10 +997,27 @@ function deepMerge(target, source) {
   const result = { ...target };
 
   for (const key of Object.keys(source)) {
-    if (source[key] instanceof Object && key in target && target[key] instanceof Object) {
-      result[key] = deepMerge(target[key], source[key]);
-    } else {
-      result[key] = source[key];
+    const sourceValue = source[key];
+    const targetValue = target[key];
+
+    // Arrays are replaced entirely (not merged element by element)
+    if (Array.isArray(sourceValue)) {
+      result[key] = [...sourceValue];
+    }
+    // Objects are deep merged (but not arrays, null, or other non-plain objects)
+    else if (
+      sourceValue !== null &&
+      typeof sourceValue === 'object' &&
+      !Array.isArray(sourceValue) &&
+      targetValue !== null &&
+      typeof targetValue === 'object' &&
+      !Array.isArray(targetValue)
+    ) {
+      result[key] = deepMerge(targetValue, sourceValue);
+    }
+    // Primitives and other values are replaced
+    else {
+      result[key] = sourceValue;
     }
   }
 
@@ -190,39 +1095,162 @@ module.exports = ${JSON.stringify(cleanConfig, null, 2)};
 }
 
 /**
- * Validate configuration
+ * Validate configuration using Zod schema
  * @param {object} config - Configuration object
- * @returns {object} Validation result { valid, errors }
+ * @param {object} options - Validation options
+ * @param {boolean} options.strict - If true, fail on unknown fields
+ * @param {string[]} options.sections - Only validate specific sections
+ * @returns {object} Validation result { valid, errors, warnings, data }
  */
-function validate(config) {
+function validate(config, options = {}) {
+  // Remove internal properties before validation
+  const configToValidate = { ...config };
+  delete configToValidate._projectRoot;
+  delete configToValidate._configPath;
+  delete configToValidate._bootspringDir;
+
   const errors = [];
+  const warnings = [];
 
-  // Required fields
-  if (!config.project?.name) {
-    errors.push('project.name is required');
+  // If specific sections requested, validate only those
+  if (options.sections && options.sections.length > 0) {
+    let allValid = true;
+    const validatedData = {};
+
+    for (const section of options.sections) {
+      if (configToValidate[section] !== undefined) {
+        const result = validateSection(section, configToValidate[section]);
+        if (!result.valid) {
+          allValid = false;
+          errors.push(...result.errors);
+        } else {
+          validatedData[section] = result.data;
+        }
+      }
+    }
+
+    return {
+      valid: allValid,
+      errors,
+      warnings,
+      data: allValid ? validatedData : null
+    };
   }
 
-  // Valid framework
-  const validFrameworks = ['nextjs', 'remix', 'nuxt', 'sveltekit', 'express', 'fastify'];
-  if (config.stack?.framework && !validFrameworks.includes(config.stack.framework)) {
-    errors.push(`Invalid framework: ${config.stack.framework}. Valid: ${validFrameworks.join(', ')}`);
+  // Full config validation
+  const result = ConfigSchema.safeParse(configToValidate);
+
+  if (result.success) {
+    return {
+      valid: true,
+      errors: [],
+      warnings,
+      data: result.data
+    };
   }
 
-  // Valid language
-  const validLanguages = ['typescript', 'javascript'];
-  if (config.stack?.language && !validLanguages.includes(config.stack.language)) {
-    errors.push(`Invalid language: ${config.stack.language}. Valid: ${validLanguages.join(', ')}`);
+  return {
+    valid: false,
+    errors: formatValidationErrors(result.error),
+    warnings,
+    data: null
+  };
+}
+
+/**
+ * Load and optionally validate configuration
+ * Validation is graceful by default - invalid configs still load with warnings
+ * @param {string} [projectRoot] - Optional project root path
+ * @param {object} [options] - Load options
+ * @param {boolean} [options.validate] - Whether to validate (default: true)
+ * @param {boolean} [options.strict] - If true, throw on validation errors (default: false)
+ * @param {boolean} [options.silent] - If true, suppress validation warnings (default: false)
+ * @returns {object} Configuration object with _validation property
+ */
+function loadWithValidation(projectRoot = null, options = {}) {
+  const { validate: shouldValidate = true, strict = false, silent = false } = options;
+
+  // Load the config normally
+  const config = load(projectRoot);
+
+  // Skip validation if not requested
+  if (!shouldValidate) {
+    config._validation = { skipped: true };
+    return config;
   }
 
-  // Port range
-  if (config.dashboard?.port && (config.dashboard.port < 1024 || config.dashboard.port > 65535)) {
-    errors.push('dashboard.port must be between 1024 and 65535');
+  // Validate the loaded config
+  const validation = validate(config);
+
+  // Attach validation results
+  config._validation = {
+    valid: validation.valid,
+    errors: validation.errors,
+    warnings: validation.warnings || [],
+    validatedAt: new Date().toISOString()
+  };
+
+  // Handle validation results
+  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 {
-    valid: errors.length === 0,
-    errors
+  return config;
+}
+
+/**
+ * Get a helpful error message for a validation error
+ * @param {string} errorPath - Dot-notation path to the error
+ * @param {string} errorMessage - The error message
+ * @returns {string} A helpful message with suggestions
+ */
+function getValidationHint(errorPath, errorMessage) {
+  const hints = {
+    '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
+ * @param {object} config - Raw configuration object
+ * @returns {object} Parsed configuration with defaults applied
+ */
+function parseConfig(config) {
+  // Remove internal properties before parsing
+  const configToParse = { ...config };
+  delete configToParse._projectRoot;
+  delete configToParse._configPath;
+  delete configToParse._bootspringDir;
+
+  const result = ConfigSchema.safeParse(configToParse);
+  if (result.success) {
+    return result.data;
+  }
+  // Return original config if parsing fails (for backwards compatibility)
+  return configToParse;
 }
 
 /**
@@ -234,12 +1262,67 @@ function getDefaults() {
 }
 
 module.exports = {
+  // Core functions
   load,
+  loadWithValidation,
   save,
   validate,
+  validateSection,
+  parseConfig,
   getDefaults,
   findProjectRoot,
   findConfigFile,
+
+  // Preset functions
+  getPreset,
+  applyPreset,
+  combinePresets,
+  listPresets,
+  parsePresetString,
+  validatePresets,
+  getPresetsByTag,
+  createCustomPreset,
+  resolvePresetChain,
+
+  // Validation helpers
+  formatValidationErrors,
+  getValidationHint,
+
+  // Constants
   DEFAULT_CONFIG,
-  CONFIG_FILES
+  CONFIG_FILES,
+  CONFIG_PRESETS,
+
+  // Schemas - Main
+  ConfigSchema,
+
+  // Schemas - Plugins
+  PluginSchema,
+  PluginsSchema,
+  AuthPluginSchema,
+  PaymentsPluginSchema,
+  DatabasePluginSchema,
+  TestingPluginSchema,
+  SecurityPluginSchema,
+  AIPluginSchema,
+  EmailPluginSchema,
+  AnalyticsPluginSchema,
+  MonitoringPluginSchema,
+
+  // Schemas - Features
+  AgentsConfigSchema,
+  AgentConfigSchema,
+  SkillsConfigSchema,
+  SkillConfigSchema,
+  WorkflowsConfigSchema,
+  WorkflowConfigSchema,
+  WorkflowPhaseSchema,
+
+  // Schemas - Settings
+  ProjectConfigSchema,
+  StackConfigSchema,
+  QualityConfigSchema,
+  DashboardConfigSchema,
+  ContextConfigSchema,
+  PathsConfigSchema
 };