cerber-core 1.0.4 → 1.1.1

package/USAGE_GUIDE.md

@@ -0,0 +1,254 @@
+# How to Use Cerber in Your Project
+
+## Quick Start (Recommended)
+
+1. **Install Cerber Core**
+   ```bash
+   npm install cerber-core --save-dev
+   ```
+
+2. **Run init command**
+   ```bash
+   npx cerber init
+   ```
+
+3. **Follow the prompts**
+   - If no `CERBER.md` exists, one will be created for you
+   - Customize the contract (mode, endpoints, branches)
+   - Run `npx cerber init` again to generate files
+
+4. **Review generated files**
+   - `CERBER.md` - Your architecture contract
+   - `scripts/cerber-guardian.mjs` - Pre-commit validator
+   - `.husky/pre-commit` - Git hook
+   - `src/cerber/health-checks.ts` - Health check templates
+   - `.github/workflows/cerber.yml` - CI/CD workflow
+
+5. **Customize for your project**
+   - Create `BACKEND_SCHEMA.ts` with your architecture rules
+   - Edit `src/cerber/health-checks.ts` to add your checks
+   - Update `.github/CODEOWNERS` if in team mode
+
+6. **Commit and push**
+   ```bash
+   git add .
+   git commit -m "feat: add Cerber protection"
+   git push
+   ```
+
+---
+
+## Configuration Modes
+
+### Solo Mode
+**Best for:** Individual developers, prototypes, small projects
+
+**Features:**
+- Guardian pre-commit validation
+- Basic health checks (optional)
+- Simple CI workflow
+
+**Setup:**
+```yaml
+# In CERBER.md CERBER_CONTRACT
+mode: solo
+```
+
+### Dev Mode (Default)
+**Best for:** Small teams (2-5 developers), standard projects
+
+**Features:**
+- Guardian with required imports
+- Health check endpoints
+- GitHub Actions CI/CD
+- Optional post-deploy health gates
+
+**Setup:**
+```yaml
+# In CERBER.md CERBER_CONTRACT
+mode: dev
+```
+
+### Team Mode
+**Best for:** Larger teams, strict architecture enforcement
+
+**Features:**
+- Everything from Dev mode
+- CODEOWNERS protection
+- Required PR reviews for architecture files
+- Post-deploy health validation (enabled by default)
+
+**Setup:**
+```yaml
+# In CERBER.md CERBER_CONTRACT
+mode: team
+```
+
+---
+
+## CERBER_CONTRACT Reference
+
+```yaml
+version: 1
+mode: dev  # solo | dev | team
+
+guardian:
+  enabled: true                    # Enable pre-commit validation
+  schemaFile: BACKEND_SCHEMA.ts    # Path to your schema
+  hook: husky                      # husky | manual
+  approvalsTag: ARCHITECT_APPROVED # Tag for exceptions
+
+health:
+  enabled: true                    # Generate health check templates
+  endpoint: /api/health            # Your health endpoint path
+  failOn:
+    critical: true                 # Block deploy on critical issues
+    error: true                    # Block deploy on errors
+    warning: false                 # Allow warnings
+
+ci:
+  provider: github                 # github | gitlab | manual
+  branches: [main]                 # Protected branches
+  requiredOnPR: true               # Run Guardian on PRs
+  postDeploy:
+    enabled: false                 # Post-deploy health gate
+    waitSeconds: 90                # Wait time before check
+    healthUrlVar: CERBER_HEALTH_URL          # GitHub Variable name
+    authHeaderSecret: CERBER_HEALTH_AUTH_HEADER  # GitHub Secret name (optional)
+```
+
+---
+
+## CLI Flags
+
+### Basic Usage
+```bash
+npx cerber init                    # Interactive setup
+npx cerber init --mode dev         # Override mode
+npx cerber init --dry-run          # Preview without creating files
+npx cerber init --force            # Overwrite existing files
+```
+
+### Advanced Flags
+```bash
+--mode <mode>           # Override contract mode (solo|dev|team)
+--force                 # Overwrite existing files
+--dry-run               # Show what would be generated
+--no-husky              # Skip Husky hook generation
+--no-workflow           # Skip GitHub Actions workflow
+--no-health             # Skip health check templates
+--write-contract        # Update CERBER.md with CLI options
+```
+
+### Examples
+```bash
+# Preview dev mode setup
+npx cerber init --mode dev --dry-run
+
+# Generate only Guardian files (no health checks)
+npx cerber init --no-health --no-workflow
+
+# Force regenerate all files in team mode
+npx cerber init --mode team --force
+```
+
+---
+
+## GitHub Actions Setup
+
+### Required Variables
+
+If you enable post-deploy health checks, set up GitHub Variables:
+
+1. Go to: **Settings** > **Secrets and variables** > **Actions** > **Variables**
+2. Add new repository variable:
+   - **Name:** `CERBER_HEALTH_URL`
+   - **Value:** `https://your-api.com/api/health`
+
+### Optional Secrets
+
+For authenticated health endpoints:
+
+1. Go to: **Settings** > **Secrets and variables** > **Actions** > **Secrets**
+2. Add new repository secret:
+   - **Name:** `CERBER_HEALTH_AUTH_HEADER`
+   - **Value:** `Bearer your-token-here`
+
+---
+
+## Team Mode Setup
+
+### CODEOWNERS Configuration
+
+1. Edit `.github/CODEOWNERS`:
+   ```
+   /CERBER.md @your-username
+   /BACKEND_SCHEMA.ts @your-username
+   /.github/workflows/cerber.yml @your-username
+   ```
+
+2. Replace `@your-username` with:
+   - Your GitHub username (individual)
+   - Team name like `@org/architects` (organization)
+
+### Branch Protection
+
+1. Go to: **Settings** > **Branches** > **Branch protection rules**
+2. Add rule for `main`:
+   - ✅ Require pull request reviews before merging
+   - ✅ Require review from Code Owners
+   - ✅ Require status checks to pass
+     - Add: `cerber-guardian`
+     - Add: `post-deploy-health` (if enabled)
+
+---
+
+## Troubleshooting
+
+### "CERBER.md not found"
+Run `npx cerber init` - it will create a template for you.
+
+### "Schema file not found"
+Create `BACKEND_SCHEMA.ts` at your project root with Guardian rules. See [Guardian Configuration](https://github.com/Agaslez/cerber-core#guardian-configuration).
+
+### Guardian hook not running
+```bash
+npx husky install
+chmod +x .husky/pre-commit
+```
+
+### Post-deploy health check fails
+- Verify `CERBER_HEALTH_URL` is set in GitHub Variables
+- Check health endpoint returns proper JSON format
+- Review `failOn` settings in `CERBER_CONTRACT`
+
+### Files already exist error
+Use `--force` flag to overwrite:
+```bash
+npx cerber init --force
+```
+
+---
+
+## Migration from Manual Setup
+
+If you have existing Guardian/Cerber setup:
+
+1. Create `CERBER.md` with contract matching your current config
+2. Run `npx cerber init --dry-run` to preview changes
+3. Backup existing files
+4. Run `npx cerber init --force` to migrate
+5. Review and test generated files
+
+---
+
+## Next Steps
+
+- 📖 Read [Guardian Configuration Guide](https://github.com/Agaslez/cerber-core#guardian-configuration)
+- 🔍 Explore [Cerber Health Examples](https://github.com/Agaslez/cerber-core#cerber-examples)
+- 💬 Ask questions in [GitHub Discussions](https://github.com/Agaslez/cerber-core/discussions)
+- ⭐ Star the repo if Cerber saved you time!
+
+---
+
+**Need help?** Open an issue or discussion: https://github.com/Agaslez/cerber-core

package/bin/cerber

@@ -1,105 +1,121 @@
 #!/usr/bin/env node
-
-/**
- * Cerber Core - Unified CLI
- * 
- * Main entry point for all Cerber commands
- * 
- * @author Stefan Pitek
- * @license MIT
- */
-
-import chalk from 'chalk';
-import { program } from 'commander';
-
-program
-  .name('cerber')
-  .description('Cerber Core - Code quality & health monitoring')
-  .version('1.0.0');
-
-program
-  .command('guardian')
-  .description('Run Guardian pre-commit validation')
-  .option('-s, --schema <file>', 'Schema file path')
-  .option('-v, --verbose', 'Verbose output')
-  .option('--fail-on-warning', 'Exit with error on warnings')
-  .action(async (options) => {
-    const { Guardian } = await import('../dist/guardian/index.js');
-    const schema = options.schema ? await import(options.schema) : null;
-    
-    const guardian = new Guardian(schema?.default || {});
-    const result = await guardian.validate();
-    
-    if (!result.success) {
-      console.error(chalk.red('❌ Guardian validation failed'));
-      process.exit(1);
-    }
-    
-    console.log(chalk.green('✅ Guardian validation passed'));
-  });
-
-program
-  .command('health')
-  .description('Run Cerber health checks')
-  .option('-c, --checks <file>', 'Health checks file path')
-  .option('-u, --url <url>', 'Fetch health from URL')
-  .option('-p, --parallel', 'Run checks in parallel')
-  .action(async (options) => {
-    const { Cerber } = await import('../dist/cerber/index.js');
-    
-    if (options.url) {
-      const response = await fetch(options.url);
-      const result = await response.json();
-      console.log(JSON.stringify(result, null, 2));
-      process.exit(result.status === 'healthy' ? 0 : 1);
-    }
-    
-    const checksModule = options.checks ? await import(options.checks) : null;
-    const checks = checksModule ? Object.values(checksModule).filter(v => typeof v === 'function') : [];
-    
-    const cerber = new Cerber(checks);
-    const result = await cerber.runChecks({ parallel: options.parallel });
-    
-    process.exit(result.status === 'healthy' ? 0 : 1);
-  });
-
-program
-  .command('morning')
-  .description('Run morning dashboard (SOLO)')
-  .action(async () => {
-    const { execSync } = await import('child_process');
-    execSync('node solo/scripts/cerber-daily-check.js', { stdio: 'inherit' });
-  });
-
-program
-  .command('repair')
-  .description('Auto-repair common issues (SOLO)')
-  .option('--dry-run', 'Show what would be fixed without making changes')
-  .option('--approve', 'Require approval for each fix')
-  .action(async (options) => {
-    const { execSync } = await import('child_process');
-    const args = [
-      options.dryRun && '--dry-run',
-      options.approve && '--approve'
-    ].filter(Boolean).join(' ');
-    
-    execSync(`node solo/scripts/cerber-auto-repair.js ${args}`, { stdio: 'inherit' });
-  });
-
-program
-  .command('focus <module>')
-  .description('Generate focus context for module (TEAM)')
-  .action(async (module) => {
-    const { execSync } = await import('child_process');
-    execSync(`bash team/scripts/cerber-focus.sh ${module}`, { stdio: 'inherit' });
-  });
-
-program
-  .command('dashboard')
-  .description('Show system dashboard (SOLO)')
-  .action(async () => {
-    const { execSync } = await import('child_process');
-    execSync('node solo/scripts/cerber-dashboard.js', { stdio: 'inherit' });
-  });
-
-program.parse();
+
+/**
+ * Cerber Core - Unified CLI
+ * 
+ * Main entry point for all Cerber commands
+ * 
+ * @author Stefan Pitek
+ * @license MIT
+ */
+
+import chalk from 'chalk';
+import { program } from 'commander';
+
+program
+  .name('cerber')
+  .description('Cerber Core - Code quality & health monitoring')
+  .version('1.1.0');
+
+program
+  .command('init')
+  .description('Initialize Cerber in your project')
+  .option('--mode <mode>', 'Override mode: solo | dev | team')
+  .option('--force', 'Overwrite existing files')
+  .option('--dry-run', 'Show what would be generated without creating files')
+  .option('--print-template', 'Print CERBER.md template contract to stdout')
+  .option('--no-husky', 'Skip Husky hook generation')
+  .option('--no-workflow', 'Skip GitHub Actions workflow generation')
+  .option('--no-health', 'Skip health check template generation')
+  .option('--write-contract', 'Update CERBER.md contract with CLI options')
+  .action(async (options) => {
+    const { initCommand } = await import('../dist/cli/init.js');
+    await initCommand(options);
+  });
+
+program
+  .command('guardian')
+  .description('Run Guardian pre-commit validation')
+  .option('-s, --schema <file>', 'Schema file path')
+  .option('-v, --verbose', 'Verbose output')
+  .option('--fail-on-warning', 'Exit with error on warnings')
+  .action(async (options) => {
+    const { Guardian } = await import('../dist/guardian/index.js');
+    const schema = options.schema ? await import(options.schema) : null;
+    
+    const guardian = new Guardian(schema?.default || {});
+    const result = await guardian.validate();
+    
+    if (!result.success) {
+      console.error(chalk.red('❌ Guardian validation failed'));
+      process.exit(1);
+    }
+    
+    console.log(chalk.green('✅ Guardian validation passed'));
+  });
+
+program
+  .command('health')
+  .description('Run Cerber health checks')
+  .option('-c, --checks <file>', 'Health checks file path')
+  .option('-u, --url <url>', 'Fetch health from URL')
+  .option('-p, --parallel', 'Run checks in parallel')
+  .action(async (options) => {
+    const { Cerber } = await import('../dist/cerber/index.js');
+    
+    if (options.url) {
+      const response = await fetch(options.url);
+      const result = await response.json();
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.status === 'healthy' ? 0 : 1);
+    }
+    
+    const checksModule = options.checks ? await import(options.checks) : null;
+    const checks = checksModule ? Object.values(checksModule).filter(v => typeof v === 'function') : [];
+    
+    const cerber = new Cerber(checks);
+    const result = await cerber.runChecks({ parallel: options.parallel });
+    
+    process.exit(result.status === 'healthy' ? 0 : 1);
+  });
+
+program
+  .command('morning')
+  .description('Run morning dashboard (SOLO)')
+  .action(async () => {
+    const { execSync } = await import('child_process');
+    execSync('node solo/scripts/cerber-daily-check.js', { stdio: 'inherit' });
+  });
+
+program
+  .command('repair')
+  .description('Auto-repair common issues (SOLO)')
+  .option('--dry-run', 'Show what would be fixed without making changes')
+  .option('--approve', 'Require approval for each fix')
+  .action(async (options) => {
+    const { execSync } = await import('child_process');
+    const args = [
+      options.dryRun && '--dry-run',
+      options.approve && '--approve'
+    ].filter(Boolean).join(' ');
+    
+    execSync(`node solo/scripts/cerber-auto-repair.js ${args}`, { stdio: 'inherit' });
+  });
+
+program
+  .command('focus <module>')
+  .description('Generate focus context for module (TEAM)')
+  .action(async (module) => {
+    const { execSync } = await import('child_process');
+    execSync(`bash team/scripts/cerber-focus.sh ${module}`, { stdio: 'inherit' });
+  });
+
+program
+  .command('dashboard')
+  .description('Show system dashboard (SOLO)')
+  .action(async () => {
+    const { execSync } = await import('child_process');
+    execSync('node solo/scripts/cerber-dashboard.js', { stdio: 'inherit' });
+  });
+
+program.parse();

package/dev/templates/BACKEND_SCHEMA.ts.tpl

@@ -0,0 +1,48 @@
+/**
+ * ⚠️  CERBER TEMPLATE (NOT SOURCE OF TRUTH)
+ * 
+ * This file is a starting point. Edit it to match YOUR architecture.
+ * The source of truth is CERBER.md.
+ * 
+ * Generated by: npx cerber init
+ * Project: {{PROJECT_NAME}}
+ * 
+ * See: https://github.com/Agaslez/cerber-core#guardian-configuration
+ */
+
+export const BACKEND_SCHEMA = {
+  version: "1.0.0",
+  
+  // Your architecture rules (customize)
+  rules: [],
+  
+  // Patterns that should never appear in your code
+  forbiddenPatterns: [
+    // Uncomment and customize based on your tech stack:
+    // {
+    //   pattern: /password\s*=\s*['"][^'"]+['"]/i,
+    //   name: "Hardcoded passwords",
+    //   severity: "error"
+    // },
+    // {
+    //   pattern: /api[_-]?key\s*=\s*['"][^'"]+['"]/i,
+    //   name: "Hardcoded API keys",
+    //   severity: "error"
+    // }
+  ]
+};
+
+export default BACKEND_SCHEMA;
+
+/**
+ * 💡 Next Steps:
+ * 
+ * 1. Define your project structure in CERBER.md (single source of truth)
+ * 2. Add forbiddenPatterns for your tech stack
+ * 3. Add requiredImports rules for your architecture layers
+ * 4. Test with: npx cerber-guardian
+ * 
+ * Full examples:
+ * - node_modules/cerber-core/examples/backend-schema.ts
+ * - node_modules/cerber-core/examples/frontend-schema.ts
+ */

package/dev/templates/cerber-guardian.mjs.tpl

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Generated by Cerber init - DO NOT EDIT MANUALLY
+// To regenerate: npx cerber init --force
+
+import { execSync } from 'child_process';
+import fs from 'fs';
+
+const SCHEMA_FILE = '{{SCHEMA_FILE}}';
+const APPROVALS_TAG = '{{APPROVALS_TAG}}';
+
+async function main() {
+  console.log('🛡️  Cerber Guardian: Validating staged files...');
+
+  if (!fs.existsSync(SCHEMA_FILE)) {
+    console.error(`❌ Schema file not found: ${SCHEMA_FILE}`);
+    console.error('Guardian MVP: schema missing. Add your rules to proceed.');
+    process.exit(1);
+  }
+
+  let stagedFiles;
+  try {
+    stagedFiles = execSync('git diff --cached --name-only', { encoding: 'utf-8' })
+      .trim()
+      .split('\n')
+      .filter(Boolean);
+  } catch (err) {
+    console.error('❌ Failed to get staged files');
+    process.exit(1);
+  }
+
+  if (stagedFiles.length === 0) {
+    console.log('✅ No files staged for commit');
+    return;
+  }
+
+  console.log(`Checking ${stagedFiles.length} file(s)...`);
+  console.log('Guardian MVP: schema detected. Add validation rules to enforce imports/forbidden patterns.');
+  console.log('✅ All checks passed');
+}
+
+main().catch(err => {
+  console.error('❌ Guardian check failed:', err?.message || err);
+  process.exit(1);
+});

package/dev/templates/cerber.yml.tpl

@@ -0,0 +1,53 @@
+# Generated by Cerber init
+name: Cerber CI
+
+on:
+  push:
+    branches: {{CI_BRANCHES}}
+  pull_request:
+    branches: {{CI_BRANCHES}}
+  workflow_dispatch:
+
+jobs:
+  cerber-ci:
+    name: Cerber CI
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build (if script exists)
+        run: |
+          if npm run | grep -q "build"; then
+            npm run build
+          else
+            echo "No build script defined; skipping"
+          fi
+
+      - name: Test (if script exists)
+        run: |
+          if npm run | grep -q "test"; then
+            npm test
+          else
+            echo "No test script defined; skipping"
+          fi
+
+      - name: Run Guardian
+        run: |
+          if npm run | grep -q "cerber:guardian"; then
+            npm run cerber:guardian
+          else
+            node scripts/cerber-guardian.mjs
+          fi
+
+{{POST_DEPLOY_BLOCK}}

package/dev/templates/health-checks.ts.tpl

@@ -0,0 +1,11 @@
+// Generated by Cerber init - CUSTOMIZE THIS FILE
+// To regenerate template: npx cerber init --force
+
+import { CerberCheck, makeIssue } from 'cerber-core';
+
+export const checks: Record<string, CerberCheck> = {
+  database: async () => {
+    // TODO: Implement your database health check
+    return [];
+  },
+};