cerber-core 1.0.0

package/solo/README.md

@@ -0,0 +1,258 @@
+# 🛡️ Cerber SOLO
+
+> **Automation tools for solo developers**
+
+Extends Cerber Core (Guardian 1.0 + Cerber 2.1) with intelligent automation specifically designed for solo developers.
+
+**Author:** Stefan Pitek  
+**Version:** 2.0
+
+---
+
+## 🎯 What is Cerber SOLO?
+
+Cerber SOLO adds an automation layer on top of Guardian and Cerber, providing:
+
+- **Auto-repair** - Fixes package.json, .env.example, CHANGELOG automatically
+- **Performance budget** - Enforces bundle size limits
+- **Dependency health** - Weekly security & deprecation checks
+- **Documentation sync** - Validates code vs docs
+- **Feature flags** - Toggle features without redeploy
+- **Daily dashboard** - Morning health overview
+- **Smart rollback** - Surgical file rollback
+
+---
+
+## ⚡ Quick Start
+
+### Add Scripts to package.json
+
+```json
+{
+  "scripts": {
+    "cerber:morning": "node solo/scripts/cerber-daily-check.js",
+    "cerber:repair": "node solo/scripts/cerber-auto-repair.js",
+    "cerber:deps": "node solo/scripts/cerber-deps-health.js",
+    "cerber:perf": "node solo/scripts/cerber-performance-budget.js",
+    "cerber:docs": "node solo/scripts/cerber-docs-sync.js",
+    "cerber:flags": "node solo/scripts/cerber-flags-check.js",
+    "cerber:snapshot": "node solo/scripts/cerber-snapshot.js",
+    "cerber:pre-push": "npm run cerber:deps && npm run cerber:docs && npm run cerber:perf"
+  }
+}
+```
+
+### Daily Workflow
+
+```bash
+# Morning
+npm run cerber:morning      # Start day (2 min)
+
+# Development
+npm run cerber:repair       # Auto-fix issues
+git commit                  # Guardian validates
+
+# Before Push
+npm run cerber:pre-push     # Full check (3 min)
+
+# End of Day
+npm run cerber:snapshot     # Capture progress
+```
+
+---
+
+## 📚 Tools Overview
+
+### 🔧 Auto-Repair
+
+```bash
+npm run cerber:repair
+```
+
+**Automatically fixes:**
+- Format and sort package.json
+- Sync .env.example with code
+- Generate CHANGELOG from git log
+- Remove console.logs (with approval)
+
+### 🏥 Dependency Health
+
+```bash
+npm run cerber:deps
+```
+
+**Checks:**
+- Security vulnerabilities
+- Outdated packages
+- Deprecated packages
+- Lock file sync
+
+**Output:** Health score (0-100) and actionable report
+
+### 📊 Performance Budget
+
+```bash
+npm run cerber:perf
+```
+
+**Enforces:**
+- Total bundle size limit (500 KB)
+- Largest chunk limit (250 KB)
+- Image size constraints
+
+**Configuration:** `solo/config/performance-budget.json`
+
+### 📚 Documentation Sync
+
+```bash
+npm run cerber:docs
+```
+
+**Validates:**
+- API endpoints in code vs README
+- ENV vars in code vs .env.example
+- Detects stale documentation
+
+### 🚩 Feature Flags
+
+```bash
+npm run cerber:flags
+```
+
+**Checks:**
+- Active flags
+- Expired flags
+- Per-environment status
+
+**TypeScript API:** `solo/lib/feature-flags.ts`
+
+### ⏪ Smart Rollback
+
+```bash
+node solo/scripts/cerber-rollback.js <hash> --file=path.ts
+```
+
+**Features:**
+- Rollback specific file from commit
+- Safety checks
+- Diff preview
+- Dry-run mode
+
+### ☀️ Daily Check
+
+```bash
+npm run cerber:morning
+```
+
+**Shows:**
+- Backend health
+- Guardian status
+- Git status
+- Yesterday's snapshot
+- Today's priorities
+
+### 📸 Snapshot
+
+```bash
+npm run cerber:snapshot
+```
+
+**Captures:**
+- Git statistics
+- File counts
+- LOC metrics
+- Saves to `.cerber/snapshots/` (30-day retention)
+
+---
+
+## 🎨 Feature Flags
+
+### Usage
+
+```typescript
+import { isFeatureEnabled } from './solo/lib/feature-flags';
+
+if (isFeatureEnabled('new-feature')) {
+  // Show new feature
+}
+```
+
+### Configuration
+
+```typescript
+export const FLAGS = {
+  "new-ui": {
+    enabled: true,
+    description: "New UI redesign",
+    owner: "team",
+    environments: ["development", "staging"],
+    expiresAt: "2026-06-01"
+  }
+};
+```
+
+---
+
+## 🔧 Configuration
+
+### Main Config
+
+**File:** `solo/config/solo-contract.json`
+
+```json
+{
+  "version": "2.0-solo",
+  "autoRepair": {
+    "enabled": true,
+    "safe": ["format-package-json", "sync-env", "changelog"]
+  },
+  "performanceBudget": {
+    "bundleSize": { "max": 500, "warning": 400 }
+  },
+  "snapshots": {
+    "retentionDays": 30
+  }
+}
+```
+
+---
+
+## 📖 Full Documentation
+
+**[Read complete documentation →](../docs/SOLO.md)**
+
+- Installation
+- Daily workflow
+- Command reference
+- Integration with Guardian
+- Troubleshooting
+- Best practices
+
+---
+
+## 🤝 Integration with Guardian
+
+Cerber SOLO works **alongside** your existing Guardian setup:
+
+```
+Morning:     npm run cerber:morning    # SOLO dashboard
+Development: git commit                # Guardian validates
+Before Push: npm run cerber:pre-push   # SOLO checks
+Deploy:      curl /api/health          # Cerber 2.1 validates
+```
+
+---
+
+## 💡 Example Project
+
+See [`examples/solo-integration/`](../examples/solo-integration/) for complete integration example.
+
+---
+
+## 📄 License
+
+MIT © 2026 Stefan Pitek
+
+---
+
+**Built with ❤️ for solo developers**

package/solo/config/performance-budget.json

@@ -0,0 +1,53 @@
+{
+  "version": "1.0",
+  "description": "Performance budget configuration for Cerber SOLO",
+  
+  "bundleSize": {
+    "max": 500,
+    "warning": 400,
+    "unit": "KB",
+    "description": "Total bundle size limit"
+  },
+  
+  "largestChunk": {
+    "max": 250,
+    "warning": 200,
+    "unit": "KB",
+    "description": "Maximum size for a single chunk"
+  },
+  
+  "images": {
+    "max": 200,
+    "unit": "KB",
+    "description": "Maximum image file size"
+  },
+  
+  "thresholds": {
+    "critical": {
+      "description": "Build fails if exceeded",
+      "bundleSize": 500,
+      "chunkSize": 250
+    },
+    "warning": {
+      "description": "Warning issued but build continues",
+      "bundleSize": 400,
+      "chunkSize": 200
+    }
+  },
+  
+  "excludePaths": [
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    ".next"
+  ],
+  
+  "recommendations": [
+    "Enable code splitting",
+    "Use dynamic imports",
+    "Compress images",
+    "Remove unused dependencies",
+    "Analyze bundle with webpack-bundle-analyzer"
+  ]
+}

package/solo/config/solo-contract.json

@@ -0,0 +1,71 @@
+{
+  "version": "2.0-solo",
+  "extends": "cerber-core",
+  "description": "Cerber SOLO configuration for solo developers",
+  
+  "autoRepair": {
+    "enabled": true,
+    "safe": [
+      "format-package-json",
+      "sync-env",
+      "changelog"
+    ],
+    "description": "Automatically repair common issues"
+  },
+  
+  "performanceBudget": {
+    "bundleSize": {
+      "max": 500,
+      "warning": 400,
+      "unit": "KB"
+    },
+    "largestChunk": {
+      "max": 250,
+      "warning": 200,
+      "unit": "KB"
+    },
+    "images": {
+      "max": 200,
+      "unit": "KB"
+    }
+  },
+  
+  "snapshots": {
+    "enabled": true,
+    "retentionDays": 30,
+    "directory": ".cerber/snapshots"
+  },
+  
+  "dailyChecks": {
+    "enabled": true,
+    "healthEndpoints": [
+      "http://localhost:3000/api/health",
+      "http://localhost:4000/api/health",
+      "http://localhost:5000/api/health"
+    ]
+  },
+  
+  "dependencies": {
+    "checkVulnerabilities": true,
+    "checkOutdated": true,
+    "checkDeprecated": true,
+    "healthScoreThreshold": 60
+  },
+  
+  "documentation": {
+    "syncEnabled": true,
+    "checkEndpoints": true,
+    "checkEnvVars": true,
+    "checkTodos": true
+  },
+  
+  "featureFlags": {
+    "enabled": true,
+    "checkExpired": true
+  },
+  
+  "rollback": {
+    "safetyChecks": true,
+    "requireCleanWorkingDirectory": true
+  }
+}

package/solo/lib/feature-flags.ts

@@ -0,0 +1,177 @@
+/**
+ * Cerber SOLO - Feature Flags System
+ * 
+ * Extends Cerber Core with automation for solo developers
+ * 
+ * @author Stefan Pitek
+ * @copyright 2026 Stefan Pitek
+ * @license MIT
+ */
+
+export type FeatureFlag = string;
+
+export interface FlagConfig {
+  enabled: boolean;
+  description: string;
+  owner: string;
+  expiresAt?: string;
+  environments?: ("development" | "staging" | "production")[];
+}
+
+export interface FeatureFlagsConfig {
+  [key: string]: FlagConfig;
+}
+
+/**
+ * Default feature flags configuration
+ */
+const defaultFlags: FeatureFlagsConfig = {
+  "example-feature": {
+    enabled: false,
+    description: "Example feature flag",
+    owner: "team",
+    environments: ["development"]
+  }
+};
+
+/**
+ * Load feature flags from environment or use defaults
+ */
+let featureFlags: FeatureFlagsConfig = defaultFlags;
+
+/**
+ * Initialize feature flags with custom configuration
+ * @param config - Custom feature flags configuration
+ */
+export function initializeFeatureFlags(config: FeatureFlagsConfig): void {
+  featureFlags = { ...defaultFlags, ...config };
+}
+
+/**
+ * Check if a feature flag is enabled
+ * @param flag - Feature flag name
+ * @returns true if the flag is enabled, false otherwise
+ */
+export function isFeatureEnabled(flag: FeatureFlag): boolean {
+  const config = featureFlags[flag];
+  
+  if (!config) {
+    console.warn(`Feature flag "${flag}" not found, defaulting to false`);
+    return false;
+  }
+  
+  // Check if flag is enabled
+  if (!config.enabled) {
+    return false;
+  }
+  
+  // Check environment restrictions
+  if (config.environments && config.environments.length > 0) {
+    const currentEnv = process.env.NODE_ENV || "development";
+    if (!config.environments.includes(currentEnv as any)) {
+      return false;
+    }
+  }
+  
+  // Check expiry date
+  if (config.expiresAt) {
+    const expiryDate = new Date(config.expiresAt);
+    const now = new Date();
+    
+    if (now > expiryDate) {
+      console.warn(`Feature flag "${flag}" has expired on ${config.expiresAt}`);
+      return false;
+    }
+  }
+  
+  return true;
+}
+
+/**
+ * React hook for feature flags
+ * @param flag - Feature flag name
+ * @returns true if the flag is enabled, false otherwise
+ */
+export function useFeatureFlag(flag: FeatureFlag): boolean {
+  return isFeatureEnabled(flag);
+}
+
+/**
+ * Higher-order component for conditional rendering based on feature flags
+ * @param flag - Feature flag name
+ * @param Component - Component to render if flag is enabled
+ * @param Fallback - Optional fallback component if flag is disabled
+ * @returns Component or Fallback based on flag status
+ */
+export function withFeatureFlag(
+  flag: FeatureFlag,
+  Component: any,
+  Fallback?: any
+): any {
+  return function FeatureFlagWrapper(props: any) {
+    const isEnabled = isFeatureEnabled(flag);
+    
+    if (isEnabled) {
+      return Component(props);
+    }
+    
+    if (Fallback) {
+      return Fallback(props);
+    }
+    
+    return null;
+  };
+}
+
+/**
+ * Get all feature flags
+ * @returns All feature flags configuration
+ */
+export function getAllFlags(): FeatureFlagsConfig {
+  return { ...featureFlags };
+}
+
+/**
+ * Get enabled feature flags
+ * @returns List of enabled feature flag names
+ */
+export function getEnabledFlags(): string[] {
+  return Object.keys(featureFlags).filter(flag => isFeatureEnabled(flag));
+}
+
+/**
+ * Get feature flag configuration
+ * @param flag - Feature flag name
+ * @returns Feature flag configuration or undefined
+ */
+export function getFlagConfig(flag: FeatureFlag): FlagConfig | undefined {
+  return featureFlags[flag];
+}
+
+/**
+ * Check if a feature flag exists
+ * @param flag - Feature flag name
+ * @returns true if the flag exists, false otherwise
+ */
+export function flagExists(flag: FeatureFlag): boolean {
+  return flag in featureFlags;
+}
+
+/**
+ * Get expired feature flags
+ * @returns List of expired feature flag names
+ */
+export function getExpiredFlags(): string[] {
+  const now = new Date();
+  
+  return Object.keys(featureFlags).filter(flag => {
+    const config = featureFlags[flag];
+    if (!config.expiresAt) return false;
+    
+    const expiryDate = new Date(config.expiresAt);
+    return now > expiryDate;
+  });
+}
+
+// Export types
+export type { FeatureFlag, FlagConfig, FeatureFlagsConfig };