cerber-core 1.0.4 → 1.1.1

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

@@ -71,7 +71,14 @@ Ongoing savings:         $6,000/month per developer
 
 ## 🎯 What is Cerber Core?
 
-Cerber Core is a comprehensive toolkit for maintaining code quality and architecture in growing Node.js projects.
+**Cerber Core is a control system for Node.js architecture.**
+
+**Critical distinction:** Cerber does NOT design your system. Cerber EXECUTES your design.
+
+```
+You decide    → CERBER.md (roadmap)
+Cerber guards → enforces your decisions
+```
 
 ### 💎 The Core Value: Your Roadmap Becomes Executable Law
 
@@ -138,8 +145,165 @@ export const BACKEND_SCHEMA = {
 
 ---
 
+## 🎯 ONE SOURCE OF TRUTH
+
+**Critical principle:** Cerber does NOT design your system. Cerber enforces YOUR design.
+
+### The Rule
+
+```
+📜 CERBER.md = Your roadmap (single source of truth)
+🛡️ Guardian = Enforces CERBER.md rules
+📋 Schema files = Optional mirrors of CERBER.md (NOT source of truth)
+```
+
+**What this means:**
+
+✅ **CERBER.md defines everything** - architecture, rules, team mode  
+✅ **Cerber executes CERBER.md** - no assumptions, no magic  
+✅ **Schema files are user-owned** - Cerber helps, never decides  
+✅ **You design. Cerber guards.** - separation of concerns  
+
+❌ **Cerber does NOT guess your architecture**  
+❌ **Cerber does NOT infer folder structures**  
+❌ **Cerber does NOT auto-design systems**  
+
+### Schema Mode: Strict vs Template_Only
+
+In `CERBER.md` contract, you control schema generation:
+
+```yaml
+schema:
+  enabled: true
+  file: BACKEND_SCHEMA.ts
+  mode: strict  # or template_only
+```
+
+**For mature teams → `mode: strict`**
+- ✅ Cerber NEVER creates schema file
+- ✅ You create schema based on YOUR architecture
+- ✅ Full control, no helpers, no assumptions
+- ✅ `npx cerber init` shows: "You must create BACKEND_SCHEMA.ts"
+
+**For beginners → `mode: template_only`**
+- ✅ Cerber creates minimal template if file missing
+- ⚠️ Template says: "NOT SOURCE OF TRUTH - Edit to match CERBER.md"
+- ✅ Empty structures, commented examples only
+- ✅ Helper scaffold, NOT design decision
+
+**Default:** `template_only` (backward compatible)
+
+**Philosophy:**
+
+```
+Traditional tools:
+  → Auto-generate everything
+  → Assume folder structures
+  → "Helpful" magic that creates chaos
+
+Cerber Core:
+  → Execute CERBER.md contract
+  → Never assume architecture
+  → One decision point (CERBER.md)
+  → Works WITH AI agents, not against them
+```
+
+**Why this matters:**
+
+When your team (or AI agents) follow ONE source of truth:
+- ✅ No conflicts between "docs" and "reality"
+- ✅ No drift between "schema" and "roadmap"
+- ✅ Clear authority: CERBER.md decides, Cerber enforces
+- ✅ Architecture stays intact as team/AI scales
+
+**This is not "another tool". This is a control system.**
+
+---
+
 ## 🚀 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
+
+schema:
+  enabled: true
+  file: BACKEND_SCHEMA.ts
+  mode: template_only  # strict (mature teams) | template_only (beginners)
+  # strict = You create schema, Cerber never generates
+  # template_only = Cerber creates minimal helper if missing
+
+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
@@ -148,10 +312,12 @@ npm install cerber-core --save-dev
 
 ### Choose Your Path
 
+> ⚠️ **Note:** Examples below show common patterns. Copy and **customize to YOUR architecture**. Schema files are templates, not decisions.
+
 #### 🎨 **Frontend Developer (React/Vue/Angular)**
 
 ```bash
-# 1. Copy frontend schema example
+# 1. Copy frontend schema example (then customize!)
 cp node_modules/cerber-core/examples/frontend-schema.ts ./FRONTEND_SCHEMA.ts
 
 # 2. Copy validation script
@@ -173,10 +339,12 @@ git commit -m "test"
 - ✅ Required imports (`react`, `react-dom`)
 - ✅ Required files (`tsconfig.json`, `vite.config.ts`)
 
+**Then customize:** Edit FRONTEND_SCHEMA.ts to match YOUR folder structure, YOUR rules, YOUR tech stack.
+
 #### ⚙️ **Backend Developer (Node.js/Express/NestJS)**
 
 ```bash
-# 1. Copy backend schema example
+# 1. Copy backend schema example (then customize!)
 cp node_modules/cerber-core/examples/backend-schema.ts ./BACKEND_SCHEMA.ts
 
 # 2. Copy validation script
@@ -190,6 +358,8 @@ npx husky add .husky/pre-commit "node scripts/validate-schema.mjs"
 # 4. Add health endpoint
 ```
 
+**Then customize:** Edit BACKEND_SCHEMA.ts to match YOUR routes, YOUR layers, YOUR security rules.
+
 ```javascript
 // server.js (ESM)
 import express from 'express';
@@ -300,6 +470,27 @@ cerber-repair
 cerber-focus
 ```
 
+---
+
+## ⚠️ Important: Schema Files Are NOT Source of Truth
+
+Before diving into examples below, understand this:
+
+**📋 Schema files (BACKEND_SCHEMA.ts, FRONTEND_SCHEMA.ts):**
+- Are **examples** and **optional templates**
+- Mirror YOUR architecture decisions from CERBER.md
+- Are user-owned and user-created (in strict mode)
+- Should be customized to YOUR project structure
+
+**📜 CERBER.md:**
+- Is the ONLY source of truth
+- Defines your roadmap, rules, team mode
+- Controls if/how Cerber helps with schema generation
+
+**Cerber does NOT design your system. The examples below show patterns - YOU decide which patterns fit YOUR architecture.**
+
+---
+
 ### Guardian Setup (3 minutes)
 
 **1. Create architecture schema:**
@@ -1141,10 +1332,12 @@ Break-even: Day 1 ✅
 
 ## 💡 Examples
 
+> ⚠️ **Remember:** Examples show patterns, NOT decisions. Copy and customize to YOUR architecture defined in CERBER.md.
+
 ### Complete Examples in `/examples`
 
-- [**Frontend (React + Guardian)**](examples/frontend-schema.ts) - React/Vue architecture rules
-- [**Backend (Express + Cerber)**](examples/backend-schema.ts) - Node.js/Express patterns
+- [**Frontend (React + Guardian)**](examples/frontend-schema.ts) - React/Vue patterns (customize to your structure)
+- [**Backend (Express + Cerber)**](examples/backend-schema.ts) - Node.js/Express patterns (customize to your layers)
 - [**Health Checks**](examples/health-checks.ts) - 6 production-ready checks
 - [**SOLO Integration**](examples/solo-integration/) - Automation setup
 - [**TEAM Integration**](examples/team-integration/) - Module system setup