cerber-core 1.0.4 → 1.1.0

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();
+#!/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.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/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 [];
+  },
+};

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

@@ -0,0 +1,50 @@
+// Generated by Cerber init - CUSTOMIZE THIS FILE
+
+import { checks } from './health-checks.js';
+
+export async function healthHandler(req: any, res: any) {
+  const startTime = Date.now();
+
+  try {
+    const results = await Promise.all(
+      Object.entries(checks).map(async ([name, check]) => ({
+        name,
+        issues: await check()
+      }))
+    );
+
+    const allIssues = results.flatMap(r => r.issues);
+    const critical = allIssues.filter(i => i.severity === 'critical').length;
+    const errors = allIssues.filter(i => i.severity === 'error').length;
+    const warnings = allIssues.filter(i => i.severity === 'warning').length;
+
+    const status = critical > 0 ? 'unhealthy' :
+                   errors > 0 ? 'degraded' : 'healthy';
+
+    const statusCode = status === 'healthy' ? 200 : 503;
+
+    res.status(statusCode).json({
+      status,
+      timestamp: new Date().toISOString(),
+      durationMs: Date.now() - startTime,
+      summary: {
+        totalChecks: results.length,
+        failedChecks: results.filter(r => r.issues.length > 0).length,
+        criticalIssues: critical,
+        errorIssues: errors,
+        warningIssues: warnings
+      },
+      components: allIssues
+    });
+  } catch (err: any) {
+    res.status(503).json({
+      status: 'error',
+      message: 'Health check failed',
+      error: err.message
+    });
+  }
+}
+
+// Usage in your server:
+// import { healthHandler } from './cerber/health-route.js';
+// app.get('{{HEALTH_ENDPOINT}}', healthHandler);

package/dev/templates/pre-commit.tpl

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Generated by Cerber init
+
+npm run cerber:guardian

package/dist/cli/contract-parser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * CERBER_CONTRACT parser
+ *
+ * Extracts and validates YAML contract from CERBER.md
+ *
+ * @author Stefan Pitek
+ * @license MIT
+ */
+import { CerberContract, ContractParseResult } from './types.js';
+export declare function parseCerberContract(projectRoot: string): Promise<ContractParseResult>;
+export declare function extractContract(content: string): ContractParseResult;
+export declare function getDefaultContract(mode?: 'solo' | 'dev' | 'team'): CerberContract;
+//# sourceMappingURL=contract-parser.d.ts.map

package/dist/cli/contract-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-parser.d.ts","sourceRoot":"","sources":["../../src/cli/contract-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAMjE,wBAAsB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAU3F;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CA8EpE;AAsHD,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,MAAM,GAAG,KAAK,GAAG,MAAc,GAAG,cAAc,CA+BxF"}

package/dist/cli/contract-parser.js

@@ -0,0 +1,241 @@
+/**
+ * CERBER_CONTRACT parser
+ *
+ * Extracts and validates YAML contract from CERBER.md
+ *
+ * @author Stefan Pitek
+ * @license MIT
+ */
+import fs from 'fs/promises';
+import path from 'path';
+const YAML_START_MARKER = '## CERBER_CONTRACT';
+const YAML_CODE_BLOCK_START = '```yaml';
+const YAML_CODE_BLOCK_END = '```';
+export async function parseCerberContract(projectRoot) {
+    const cerberPath = path.join(projectRoot, 'CERBER.md');
+    try {
+        const content = await fs.readFile(cerberPath, 'utf-8');
+        return extractContract(content);
+    }
+    catch (err) {
+        // CERBER.md doesn't exist
+        return { success: false, error: { message: 'CERBER.md not found' } };
+    }
+}
+export function extractContract(content) {
+    const lines = content.split('\n');
+    // Find CERBER_CONTRACT section
+    const contractStartIndex = lines.findIndex(line => line.trim() === YAML_START_MARKER);
+    if (contractStartIndex === -1) {
+        return {
+            success: false,
+            error: {
+                message: `Missing "${YAML_START_MARKER}" section header`,
+                context: 'Expected format:\n\n## CERBER_CONTRACT\n\`\`\`yaml\n...\n\`\`\`'
+            }
+        };
+    }
+    // Find yaml code block
+    let yamlStartIndex = -1;
+    let yamlEndIndex = -1;
+    for (let i = contractStartIndex; i < lines.length; i++) {
+        if (lines[i].trim().startsWith(YAML_CODE_BLOCK_START)) {
+            yamlStartIndex = i + 1;
+        }
+        else if (yamlStartIndex !== -1 && lines[i].trim() === YAML_CODE_BLOCK_END) {
+            yamlEndIndex = i;
+            break;
+        }
+    }
+    if (yamlStartIndex === -1) {
+        return {
+            success: false,
+            error: {
+                message: 'Missing YAML code block after CERBER_CONTRACT header',
+                line: contractStartIndex + 1,
+                context: `Expected \`\`\`yaml after line ${contractStartIndex + 1}`
+            }
+        };
+    }
+    if (yamlEndIndex === -1) {
+        return {
+            success: false,
+            error: {
+                message: 'Unclosed YAML code block',
+                line: yamlStartIndex,
+                context: 'Missing closing \`\`\` for YAML block'
+            }
+        };
+    }
+    const yamlContent = lines.slice(yamlStartIndex, yamlEndIndex).join('\n');
+    // Simple YAML parser (for our specific structure)
+    try {
+        const contract = parseSimpleYaml(yamlContent);
+        // Validate required fields
+        const validation = validateContract(contract);
+        if (!validation.valid) {
+            return {
+                success: false,
+                error: {
+                    message: 'Invalid contract structure',
+                    context: validation.errors.join('\n')
+                }
+            };
+        }
+        return { success: true, contract };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: {
+                message: 'Failed to parse YAML contract',
+                context: err.message || 'Invalid YAML structure'
+            }
+        };
+    }
+}
+function parseSimpleYaml(yamlContent) {
+    const lines = yamlContent.split('\n').filter(line => line.trim() && !line.trim().startsWith('#'));
+    const contract = {
+        version: 1,
+        mode: 'dev',
+        guardian: {},
+        health: {},
+        ci: {},
+        team: {}
+    };
+    let currentSection = null;
+    let currentSubsection = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        const indent = line.length - line.trimStart().length;
+        if (indent === 0 && trimmed.endsWith(':')) {
+            // Top-level key
+            const key = trimmed.slice(0, -1);
+            currentSection = key;
+            currentSubsection = null;
+        }
+        else if (indent === 2 && trimmed.endsWith(':')) {
+            // Second-level key
+            const key = trimmed.slice(0, -1);
+            currentSubsection = key;
+            if (currentSection && !contract[currentSection][key]) {
+                contract[currentSection][key] = {};
+            }
+        }
+        else if (trimmed.includes(':')) {
+            // Key-value pair
+            const [key, ...valueParts] = trimmed.split(':');
+            let value = valueParts.join(':').trim();
+            // Strip inline comments (# after value)
+            const commentIndex = value.indexOf('#');
+            if (commentIndex !== -1) {
+                value = value.substring(0, commentIndex).trim();
+            }
+            // Parse value type
+            if (value === 'true')
+                value = true;
+            else if (value === 'false')
+                value = false;
+            else if (!isNaN(Number(value)))
+                value = Number(value);
+            else if (value.startsWith('[') && value.endsWith(']')) {
+                value = value.slice(1, -1).split(',').map((v) => {
+                    const trimmed = v.trim();
+                    // Strip quotes from array values
+                    if ((trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+                        (trimmed.startsWith('"') && trimmed.endsWith('"'))) {
+                        return trimmed.slice(1, -1);
+                    }
+                    return trimmed;
+                });
+            }
+            if (currentSubsection && currentSection) {
+                contract[currentSection][currentSubsection][key.trim()] = value;
+            }
+            else if (currentSection) {
+                contract[currentSection][key.trim()] = value;
+            }
+            else {
+                contract[key.trim()] = value;
+            }
+        }
+    }
+    return contract;
+}
+function validateContract(contract) {
+    const errors = [];
+    // Check guardian section
+    if (!contract.guardian) {
+        errors.push('Missing "guardian" section');
+    }
+    else {
+        if (typeof contract.guardian.enabled !== 'boolean') {
+            errors.push('guardian.enabled must be true or false');
+        }
+        if (contract.guardian.enabled && !contract.guardian.schemaFile) {
+            errors.push('guardian.schemaFile is required when guardian is enabled');
+        }
+    }
+    // Check health section
+    if (!contract.health) {
+        errors.push('Missing "health" section');
+    }
+    else {
+        if (typeof contract.health.enabled !== 'boolean') {
+            errors.push('health.enabled must be true or false');
+        }
+        if (contract.health.enabled && !contract.health.endpoint) {
+            errors.push('health.endpoint is required when health is enabled');
+        }
+    }
+    // Check ci section
+    if (!contract.ci) {
+        errors.push('Missing "ci" section');
+    }
+    else {
+        if (!contract.ci.provider) {
+            errors.push('ci.provider is required (e.g., "github")');
+        }
+        if (!contract.ci.postDeploy) {
+            contract.ci.postDeploy = { enabled: false };
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+}
+export function getDefaultContract(mode = 'dev') {
+    return {
+        version: 1,
+        mode,
+        guardian: {
+            enabled: true,
+            schemaFile: 'BACKEND_SCHEMA.ts',
+            hook: 'husky',
+            approvalsTag: 'ARCHITECT_APPROVED'
+        },
+        health: {
+            enabled: mode !== 'solo',
+            endpoint: '/api/health',
+            failOn: {
+                critical: true,
+                error: true,
+                warning: false
+            }
+        },
+        ci: {
+            provider: 'github',
+            branches: ['main'],
+            requiredOnPR: true,
+            postDeploy: {
+                enabled: mode === 'team',
+                waitSeconds: 90,
+                healthUrlVar: 'CERBER_HEALTH_URL',
+                authHeaderSecret: 'CERBER_HEALTH_AUTH_HEADER'
+            }
+        }
+    };
+}
+//# sourceMappingURL=contract-parser.js.map