cerber-core 1.1.5 → 1.1.6

package/README.md

@@ -25,13 +25,35 @@ It's a contract that everything else must obey.
 
 ```bash
 npm install cerber-core --save-dev
-npx cerber-guardian --help
+npx cerber init
+# Follow prompts to generate CERBER.md contract + guardian hooks
 ```
 
 ⭐ **Like what you see?** [Star the repo](https://github.com/Agaslez/cerber-core) and share with your team!
 
 ---
 
+## 🤖 For AI Agents (Copilot, Cursor, Windsurf, Claude, etc.)
+
+**Cerber's one rule:** `CERBER.md` is the single source of truth.
+
+- If `CERBER.md` is missing → generate template and **STOP**. User must fill the contract.
+- If `CERBER.md` exists → execute contract exactly as specified.
+- **Never guess architecture.** Never invent rules. Never auto-design.
+
+**Schema modes:**
+- `schema.mode: template_only` → Generate minimal starter with "NOT SOURCE OF TRUTH" header
+- `schema.mode: strict` → Require existing schema file, never generate
+
+**Three enforcement points:**
+1. **Pre-commit** (Guardian) - Blocks violating commits
+2. **CI** (GitHub Actions) - Validates on push
+3. **Post-deploy** - Health gate checks production
+
+**Working with Cerber:** Read `CERBER.md` first. It tells you what's allowed and what's protected.
+
+---
+
 ## 📊 Real Production Metrics
 
 > From Eliksir SaaS Backend (2026-01-02 session)
@@ -228,7 +250,7 @@ In `CERBER.md` contract, you control schema generation:
 ```yaml
 schema:
   enabled: true
-  file: BACKEND_SCHEMA.ts
+  file: BACKEND_SCHEMA.mjs
   mode: strict  # or template_only
 ```
 
@@ -236,7 +258,7 @@ schema:
 - ✅ 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"
+- ✅ `npx cerber init` shows: "You must create BACKEND_SCHEMA.mjs"
 
 **For beginners → `mode: template_only`**
 - ✅ Cerber creates minimal template if file missing
@@ -307,11 +329,11 @@ mode: dev  # solo | dev | team
 
 guardian:
   enabled: true
-  schemaFile: BACKEND_SCHEMA.ts
+  schemaFile: BACKEND_SCHEMA.mjs
 
 schema:
   enabled: true
-  file: BACKEND_SCHEMA.ts
+  file: BACKEND_SCHEMA.mjs
   mode: template_only  # strict (mature teams) | template_only (beginners)
   # strict = You create schema, Cerber never generates
   # template_only = Cerber creates minimal helper if missing
@@ -370,18 +392,13 @@ npm install cerber-core --save-dev
 #### 🎨 **Frontend Developer (React/Vue/Angular)**
 
 ```bash
-# 1. Copy frontend schema example (then customize!)
-cp node_modules/cerber-core/examples/frontend-schema.ts ./FRONTEND_SCHEMA.ts
+# 1. Initialize Cerber (generates CERBER.md + templates)
+npx cerber init --mode=solo
 
-# 2. Copy validation script
-mkdir -p scripts
-cp node_modules/cerber-core/guardian/templates/validate-schema.mjs scripts/
+# 2. Customize your schema for frontend
+# Edit BACKEND_SCHEMA.mjs (rename to FRONTEND_SCHEMA.mjs if you prefer)
 
-# 3. Install pre-commit hook
-npx husky-init
-npx husky add .husky/pre-commit "node scripts/validate-schema.mjs"
-
-# 4. Test it!
+# 3. Test it!
 git commit -m "test"
 # Guardian will validate automatically (<1s)
 ```
@@ -392,26 +409,21 @@ 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.
+**Then customize:** Edit BACKEND_SCHEMA.mjs (rename to FRONTEND_SCHEMA.mjs if you prefer) to match YOUR folder structure, YOUR rules, YOUR tech stack.
 
 #### ⚙️ **Backend Developer (Node.js/Express/NestJS)**
 
 ```bash
-# 1. Copy backend schema example (then customize!)
-cp node_modules/cerber-core/examples/backend-schema.ts ./BACKEND_SCHEMA.ts
-
-# 2. Copy validation script
-mkdir -p scripts
-cp node_modules/cerber-core/guardian/templates/validate-schema.mjs scripts/
+# 1. Initialize Cerber (generates CERBER.md + guardian + health templates)
+npx cerber init --mode=dev
 
-# 3. Install pre-commit hook
-npx husky-init
-npx husky add .husky/pre-commit "node scripts/validate-schema.mjs"
+# 2. Customize BACKEND_SCHEMA.mjs
+# Edit to match YOUR routes, YOUR layers, YOUR security rules
 
-# 4. Add health endpoint
+# 3. Add health endpoint (see example below)
 ```
 
-**Then customize:** Edit BACKEND_SCHEMA.ts to match YOUR routes, YOUR layers, YOUR security rules.
+**Then customize:** Edit BACKEND_SCHEMA.mjs to match YOUR routes, YOUR layers, YOUR security rules.
 
 ```javascript
 // server.js (ESM)
@@ -529,7 +541,7 @@ cerber-focus
 
 Before diving into examples below, understand this:
 
-**📋 Schema files (BACKEND_SCHEMA.ts, FRONTEND_SCHEMA.ts):**
+**📋 Schema files (BACKEND_SCHEMA.mjs, FRONTEND_SCHEMA.mjs):**
 - Are **examples** and **optional templates**
 - Mirror YOUR architecture decisions from CERBER.md
 - Are user-owned and user-created (in strict mode)
@@ -548,8 +560,8 @@ Before diving into examples below, understand this:
 
 **1. Create architecture schema:**
 
-```typescript
-// BACKEND_SCHEMA.ts
+```javascript
+// BACKEND_SCHEMA.mjs
 export const BACKEND_SCHEMA = {
   version: '1.0.0',
   rules: [
@@ -573,7 +585,9 @@ export const BACKEND_SCHEMA = {
 **2. Add pre-commit hook:**
 
 ```bash
-npx husky add .husky/pre-commit "node scripts/validate-schema.mjs"
+# Pre-commit hook is automatically installed by npx cerber init
+# Or manually:
+npx husky add .husky/pre-commit "npm run cerber:guardian"
 ```
 
 **3. Done!** Guardian now blocks commits that violate architecture rules.
@@ -707,8 +721,8 @@ curl https://your-api.com/api/health
 
 ### Example 1: Enforce Express Router in routes
 
-```typescript
-// BACKEND_SCHEMA.ts
+```javascript
+// BACKEND_SCHEMA.mjs
 {
   name: 'Route files must import Router',
   pattern: /routes\/.*\.ts$/,
@@ -840,8 +854,8 @@ export const cloudinaryCheck = async () => {
 
 ### Guardian Configuration
 
-```typescript
-// BACKEND_SCHEMA.ts
+```javascript
+// BACKEND_SCHEMA.mjs
 export const BACKEND_SCHEMA = {
   version: '1.0.0',
   

package/package.json

@@ -1,109 +1,117 @@
-{
-  "name": "cerber-core",
-  "version": "1.1.5",
-  "description": "AI doesn't break your project. Lack of a contract does. Cerber is a contract-driven project guardian for AI-assisted development. It enforces a single source of truth (CERBER.md) across pre-commit, CI, and post-deploy health gates.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "type": "module",
-  "bin": {
-    "cerber": "./bin/cerber",
-    "cerber-guardian": "./bin/cerber-guardian",
-    "cerber-health": "./bin/cerber-health",
-    "cerber-focus": "./bin/cerber-focus",
-    "cerber-morning": "./bin/cerber-morning",
-    "cerber-repair": "./bin/cerber-repair"
-  },
-  "exports": {
-    ".": "./dist/index.js",
-    "./guardian": "./dist/guardian/index.js",
-    "./cerber": "./dist/cerber/index.js",
-    "./types": "./dist/types.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "jest",
-    "lint": "eslint src/**/*.ts",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "prepublishOnly": "npm run build",
-    "validate": "node bin/cerber-guardian",
-    "health-check": "node bin/cerber-health",
-    "morning": "node solo/scripts/cerber-daily-check.js",
-    "repair": "node solo/scripts/cerber-auto-repair.js",
-    "repair:dry": "node solo/scripts/cerber-auto-repair.js --dry-run",
-    "dashboard": "node solo/scripts/cerber-dashboard.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Agaslez/cerber-core.git"
-  },
-  "keywords": [
-    "ai",
-    "ai-agents",
-    "contract",
-    "contract-first",
-    "project-guard",
-    "single-source-of-truth",
-    "pre-commit",
-    "ci-cd",
-    "github-actions",
-    "schema-enforcement",
-    "health-check",
-    "deployment-gate",
-    "dev-workflow",
-    "automation",
-    "architecture",
-    "validation",
-    "cerber",
-    "guardian"
-  ],
-  "author": {
-    "name": "Agata Sleziak",
-    "email": "agata@example.com",
-    "url": "https://github.com/Agaslez"
-  },
-  "contributors": [
-    {
-      "name": "Stefan Pitek",
-      "role": "Collaborator"
-    }
-  ],
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/Agaslez/cerber-core/issues"
-  },
-  "homepage": "https://github.com/Agaslez/cerber-core#readme",
-  "peerDependencies": {
-    "typescript": ">=5.0.0"
-  },
-  "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^12.0.0"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.0",
-    "@types/node": "^20.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
-    "eslint": "^8.50.0",
-    "jest": "^29.7.0",
-    "prettier": "^3.0.0",
-    "ts-jest": "^29.1.0",
-    "typescript": "^5.3.0"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  },
-  "files": [
-    "dist",
-    "bin",
-    "examples",
-    ".cerber-example",
-    "solo",
-    "dev",
-    "team",
-    "LICENSE",
-    "README.md",
-    "CHANGELOG.md",
-    "USAGE_GUIDE.md"
-  ]
-}
+{
+  "name": "cerber-core",
+  "version": "1.1.6",
+  "description": "AI doesn't break your project. Lack of a contract does. Cerber is a contract-driven project guardian for AI-assisted development. It enforces a single source of truth (CERBER.md) across pre-commit, CI, and post-deploy health gates.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "bin": {
+    "cerber": "./bin/cerber",
+    "cerber-guardian": "./bin/cerber-guardian",
+    "cerber-health": "./bin/cerber-health",
+    "cerber-focus": "./bin/cerber-focus",
+    "cerber-morning": "./bin/cerber-morning",
+    "cerber-repair": "./bin/cerber-repair"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./guardian": "./dist/guardian/index.js",
+    "./cerber": "./dist/cerber/index.js",
+    "./types": "./dist/types.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepublishOnly": "npm run build",
+    "validate": "node bin/cerber-guardian",
+    "health-check": "node bin/cerber-health",
+    "morning": "node solo/scripts/cerber-daily-check.js",
+    "repair": "node solo/scripts/cerber-auto-repair.js",
+    "repair:dry": "node solo/scripts/cerber-auto-repair.js --dry-run",
+    "dashboard": "node solo/scripts/cerber-dashboard.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Agaslez/cerber-core.git"
+  },
+  "keywords": [
+    "ai",
+    "ai-agents",
+    "ai-coding",
+    "copilot",
+    "cursor",
+    "windsurf",
+    "llm",
+    "contract",
+    "contract-first",
+    "project-guard",
+    "single-source-of-truth",
+    "pre-commit",
+    "husky",
+    "guardrails",
+    "workflow-generator",
+    "ci-cd",
+    "github-actions",
+    "schema-enforcement",
+    "health-check",
+    "deployment-gate",
+    "dev-workflow",
+    "automation",
+    "architecture",
+    "validation",
+    "cerber",
+    "guardian"
+  ],
+  "author": {
+    "name": "Agata Sleziak",
+    "email": "agata@example.com",
+    "url": "https://github.com/Agaslez"
+  },
+  "contributors": [
+    {
+      "name": "Stefan Pitek",
+      "role": "Collaborator"
+    }
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Agaslez/cerber-core/issues"
+  },
+  "homepage": "https://github.com/Agaslez/cerber-core#readme",
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.50.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.0.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "examples",
+    ".cerber-example",
+    "solo",
+    "dev",
+    "team",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "USAGE_GUIDE.md"
+  ]
+}