cerber-core 1.0.4 → 1.1.0

package/CHANGELOG.md

@@ -1,68 +1,158 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.0.0] - 2026-01-03
-
-### Added
-- **Guardian 1.0**: Pre-commit architecture validator
-  - Forbidden pattern detection with architect approval system
-  - Required file validation
-  - Required import checking
-  - package.json rules validation
-  - Recursive directory scanning
-  - Detailed error/warning reporting
-  - CLI with `--schema`, `--verbose`, `--fail-on-warning` options
-
-- **Cerber 2.1**: Runtime health monitoring
-  - Flexible health check system
-  - Multiple severity levels (critical, error, warning, info)
-  - Parallel and sequential check execution
-  - Detailed diagnostics with fix suggestions
-  - JSON output for CI/CD integration
-  - CLI with `--checks`, `--url`, `--parallel` options
-
-- **Architect Approval System**:
-  - Comment-based approval format: `// ARCHITECT_APPROVED: reason - YYYY-MM-DD - Name`
-  - Automatic parsing and tracking
-  - Integration with Guardian validation
-
-- **Examples**:
-  - Frontend schema (React/Vue patterns)
-  - Backend schema (Node.js/Express patterns)
-  - Health check templates (DB, disk, memory, env vars)
-
-- **Documentation**:
-  - Comprehensive README with real-world metrics
-  - Contributing guidelines
-  - API documentation
-  - MIT License
-
-- **Production Testing**:
-  - Extracted from Eliksir project
-  - Real metrics: 18 commits, 43 issues detected, 4.5 hours saved
-  - 95% bug detection rate pre-production
-  - 2 commits blocked by Guardian
-
-### Technical Details
-- TypeScript with ES2022 target
-- ESNext modules for modern bundlers
-- Commander.js for CLI
-- Chalk for colored output
-- Full type definitions included
-- Zero runtime dependencies (except CLI deps)
-
-## [Unreleased]
-
-### Planned
-- Web dashboard for health check visualization
-- Slack/Discord notifications
-- Custom reporter plugins
-- VS Code extension
-- Git hooks integration (Husky)
-- More built-in health checks
-- Performance monitoring
-- Metrics export (Prometheus, DataDog)
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-01-03
+
+### Added
+
+#### 🚀 Instant Setup Command
+- **`npx cerber init`** - One-command project initialization
+  - Detects or creates `CERBER.md` with architecture contract
+  - Parses machine-readable `CERBER_CONTRACT` (YAML)
+  - Generates Guardian hooks, health checks, and CI/CD workflows
+  - Supports three modes: `solo`, `dev`, `team`
+  - CLI flags: `--mode`, `--force`, `--dry-run`, `--no-husky`, `--no-workflow`, `--no-health`
+
+#### 📋 CERBER_CONTRACT Format
+- Machine-readable YAML contract embedded in `CERBER.md`
+- Defines:
+  - `mode`: solo | dev | team
+  - `guardian`: pre-commit configuration
+  - `health`: runtime health check settings
+  - `ci`: GitHub Actions and deployment gates
+- Single source of truth for tooling configuration
+
+#### 🔧 Generated Files
+- **Guardian**:
+  - `scripts/cerber-guardian.mjs` - Pre-commit validator
+  - `.husky/pre-commit` - Git hook
+  - Updates `package.json` scripts
+- **Health Checks** (optional):
+  - `src/cerber/health-checks.ts` - Template checks
+  - `src/cerber/health-route.ts` - Express route handler
+- **CI/CD**:
+  - `.github/workflows/cerber.yml` - GitHub Actions workflow
+  - Reusable `cerber-gatekeeper.yml` workflow for post-deploy health
+- **Team Mode**:
+  - `.github/CODEOWNERS` - Protect architecture files
+
+#### 🧪 Testing
+- Unit tests for contract parser
+- Manual smoke test script
+- Dry-run mode for safe testing
+
+#### 📖 Documentation
+- New `USAGE_GUIDE.md` with complete setup instructions
+- Updated README with 30-second Quick Start
+- CERBER_CONTRACT reference documentation
+
+### Changed
+- **CLI Version** - Bumped to 1.1.0
+- **README.md** - Updated Quick Start section with instant setup
+- Template structure organized into `solo/`, `dev/`, `team/` folders
+
+### Security
+- All generated files include "Generated by Cerber init" comment
+- `--force` flag required to overwrite existing files
+- CODEOWNERS template for protecting critical files
+
+---
+
+## [1.0.4] - 2026-01-02
+
+### Changed
+- Updated package description with business value messaging
+- Enhanced README with "Your Roadmap Becomes Executable Law" section
+- Added ROI calculations and cost savings data
+
+---
+
+## [1.0.3] - 2026-01-02
+
+### Changed
+- Author metadata updates
+- Documentation improvements
+
+---
+
+## [1.0.2] - 2026-01-02
+
+### Fixed
+- CI/CD workflow fixes
+- Branch protection compatibility
+
+---
+
+## [1.0.1] - 2026-01-02
+
+### Changed
+- Initial production release
+- Package metadata refinements
+
+---
+
+## [1.0.0] - 2026-01-03
+
+### Added
+- **Guardian 1.0**: Pre-commit architecture validator
+  - Forbidden pattern detection with architect approval system
+  - Required file validation
+  - Required import checking
+  - package.json rules validation
+  - Recursive directory scanning
+  - Detailed error/warning reporting
+  - CLI with `--schema`, `--verbose`, `--fail-on-warning` options
+
+- **Cerber 2.1**: Runtime health monitoring
+  - Flexible health check system
+  - Multiple severity levels (critical, error, warning, info)
+  - Parallel and sequential check execution
+  - Detailed diagnostics with fix suggestions
+  - JSON output for CI/CD integration
+  - CLI with `--checks`, `--url`, `--parallel` options
+
+- **Architect Approval System**:
+  - Comment-based approval format: `// ARCHITECT_APPROVED: reason - YYYY-MM-DD - Name`
+  - Automatic parsing and tracking
+  - Integration with Guardian validation
+
+- **Examples**:
+  - Frontend schema (React/Vue patterns)
+  - Backend schema (Node.js/Express patterns)
+  - Health check templates (DB, disk, memory, env vars)
+
+- **Documentation**:
+  - Comprehensive README with real-world metrics
+  - Contributing guidelines
+  - API documentation
+  - MIT License
+
+- **Production Testing**:
+  - Extracted from Eliksir project
+  - Real metrics: 18 commits, 43 issues detected, 4.5 hours saved
+  - 95% bug detection rate pre-production
+  - 2 commits blocked by Guardian
+
+### Technical Details
+- TypeScript with ES2022 target
+- ESNext modules for modern bundlers
+- Commander.js for CLI
+- Chalk for colored output
+- Full type definitions included
+- Zero runtime dependencies (except CLI deps)
+
+## [Unreleased]
+
+### Planned
+- Web dashboard for health check visualization
+- Slack/Discord notifications
+- Custom reporter plugins
+- VS Code extension
+- Git hooks integration (Husky)
+- More built-in health checks
+- Performance monitoring
+- Metrics export (Prometheus, DataDog)

package/README.md

@@ -140,6 +140,81 @@ export const BACKEND_SCHEMA = {
 
 ## 🚀 Quick Start
 
+### 30-Second Setup ⚡ (New in v1.1.0!)
+
+```bash
+npm install cerber-core --save-dev
+npx cerber init
+```
+
+**How it works:**
+
+**If CERBER.md is missing** → Cerber creates a template and exits.
+
+1. Fill the contract (`CERBER_CONTRACT`) with your project settings
+2. Choose mode: `solo` | `dev` | `team`
+3. Enable features: `guardian`, `health`, `ci`
+
+**Run `npx cerber init` again** to generate:
+
+- ✅ **Guardian hook + runner** - Pre-commit validation
+- ✅ **Health templates** - Production monitoring endpoints
+- ✅ **GitHub Actions workflow** - CI/CD with stable check names
+- ✅ **Team mode: CODEOWNERS** - Schema ownership enforcement
+
+**Example CERBER.md:**
+
+```yaml
+## CERBER_CONTRACT
+\`\`\`yaml
+version: 1
+mode: dev  # solo | dev | team
+
+guardian:
+  enabled: true
+  schemaFile: BACKEND_SCHEMA.ts
+
+health:
+  enabled: true
+  endpoint: /api/health
+
+ci:
+  provider: github
+  branches: [main]
+  requiredOnPR: true
+\`\`\`
+```
+
+**Error handling:**
+
+If CERBER.md exists but is invalid → you'll get a **clear error message** with:
+- Exact problem location
+- Expected format
+- Suggestion: `npx cerber init --print-template` to see valid example
+
+**Useful flags:**
+
+```bash
+npx cerber init --dry-run       # Preview without creating files
+npx cerber init --force          # Overwrite existing files
+npx cerber init --print-template # Print template to stdout
+```
+
+**What happens:**
+- ✅ Creates `CERBER.md` with your architecture contract
+- ✅ Generates Guardian pre-commit hooks
+- ✅ Sets up health check templates
+- ✅ Configures GitHub Actions workflow
+- ✅ Adapts to your mode: solo/dev/team
+
+**Next step:** Just commit! Guardian now protects your architecture.
+
+---
+
+### Manual Setup (Alternative)
+
+If you prefer manual configuration, follow the guides below.
+
 ### Installation
 
 ```bash

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