cerber-core 1.1.9 → 1.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +96 -12
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -11,17 +11,37 @@ Enforces `CERBER.md` across pre-commit, CI, and optional post-deploy gates.
11
11
 
12
12
  ---
13
13
 
14
- ## 🚀 Quick Start
14
+ ## How to use Cerber (the intended workflow)
15
15
 
16
+ Cerber is simple: **you write the rules once in `CERBER.md`**, Cerber enforces them forever (pre-commit + CI + optional post-deploy).
17
+
18
+ **Roadmap → translated into CERBER.md contract → enforced automatically on every commit/push.**
19
+
20
+ ### 1) Install
16
21
  ```bash
17
22
  npm i -D cerber-core
18
- npx cerber init
19
- # fill CERBER.md contract
23
+ ```
24
+
25
+ ### 2) Generate CERBER.md
26
+ ```bash
20
27
  npx cerber init
21
28
  ```
22
29
 
23
- ## 🩺 Verify
30
+ If CERBER.md did not exist, Cerber creates a template and stops.
31
+ Now **YOU fill the contract** (ideally with an AI assistant).
32
+
33
+ ### 3) Teach Cerber using your roadmap (fastest way)
34
+
35
+ Take your project roadmap + repo structure and paste it into ChatGPT/Claude/Cursor with the **Cerber Contract Translator prompt** (see below).
24
36
 
37
+ Then:
38
+ - Paste the generated contract into `CERBER.md`
39
+ - Run init again to generate hooks/workflows/templates:
40
+ ```bash
41
+ npx cerber init
42
+ ```
43
+
44
+ ### 4) Verify everything (Doctor)
25
45
  ```bash
26
46
  npx cerber doctor
27
47
  ```
@@ -32,17 +52,81 @@ npx cerber doctor
32
52
  - `3` ❌ Missing schema (strict mode)
33
53
  - `4` ❌ Missing hook/workflow
34
54
 
55
+ ### 5) Commit and push (Guardian + CI)
56
+
57
+ - `git commit` → Guardian validates staged changes (blocks violations)
58
+ - `git push` → GitHub Actions validates again in CI
59
+
60
+ ---
61
+
62
+ ## What Cerber enforces (in practice)
63
+
64
+ - **Pre-commit (Guardian):** Blocks committing obvious violations (secrets, forbidden patterns, missing required imports, etc.)
65
+ - **CI (GitHub Actions):** Re-validates on push/PR and protects the workflow itself (`cerber-integrity` job)
66
+ - **Optional post-deploy:** Can validate production health if enabled in contract
67
+
35
68
  ---
36
69
 
37
- ## 🤖 For AI Agents (Copilot/Cursor/Windsurf/Claude)
70
+ ## Cerber Contract Translator (Copy/Paste Prompt)
71
+
72
+ > Use this to generate a production-ready `CERBER.md` from your roadmap.
73
+ > Cerber does NOT design your architecture. It enforces what you write.
74
+
75
+ **PROMPT:**
76
+
77
+ ```
78
+ You are a "Cerber Contract Translator". Convert my roadmap + repo structure into a `CERBER.md` contract.
79
+
80
+ RULES:
81
+ - Do NOT invent architecture or rules.
82
+ - Only translate what I explicitly provide.
83
+ - If something is missing, ask up to 10 questions in a `QUESTIONS` section and leave placeholders.
84
+ - Output must be a complete `CERBER.md` with:
85
+ 1) CERBER_CONTRACT (YAML)
86
+ 2) ROADMAP_AS_LAW (milestones)
87
+ 3) AI_AGENT_RULES (no guessing)
88
+ 4) PROTECTED_ASSETS
89
+ 5) CERBER_OVERRIDE (TTL safety fuse)
90
+ 6) QUESTIONS
91
+
92
+ INPUT I PROVIDE:
93
+ - Roadmap (what we are building, milestones, priorities)
94
+ - Repo structure (`tree -L 3` or folder list)
95
+ - Tech stack + commands for smoke/e2e/build
96
+ - Integrations (Stripe/Ghost/Cloudinary/etc.)
97
+ - What files/paths are "protected" from deletion
98
+
99
+ Now generate `CERBER.md`.
100
+ ```
101
+
102
+ ---
103
+
104
+ ## For AI Agents (Copilot / Cursor / Windsurf / Claude / etc.)
105
+
106
+ **Single rule:** `CERBER.md` is the ONLY source of truth.
107
+
108
+ ### Agent must follow this protocol
109
+
110
+ 1) **If `CERBER.md` is missing:**
111
+ - Run `npx cerber init` to generate template
112
+ - STOP (user must provide contract content)
113
+
114
+ 2) **If `CERBER.md` exists:**
115
+ - Read it first
116
+ - Execute exactly what it says
117
+ - Do NOT invent rules, do NOT infer architecture
118
+
119
+ 3) **Schema policy (important):**
120
+ - If `schema.mode: strict` → DO NOT generate schema files
121
+ - If `schema.mode: template_only` → you may generate only the minimal template (NOT decisions)
122
+
123
+ 4) **Safety rules:**
124
+ - Never disable or rename CI job id: `cerber-ci`
125
+ - Never remove: `CERBER.md`, `.github/workflows/cerber.yml`, `scripts/cerber-guardian.mjs`, `.husky/pre-commit`, `.github/CODEOWNERS`
126
+ - Never bypass checks using `continue-on-error`
127
+ - Never use `cat <<EOF` for TS/JS (corrupts `${}` template literals)
38
128
 
39
- - **CERBER.md is the ONLY source of truth**
40
- - If CERBER.md is missing → generate template and **STOP**
41
- - Never guess architecture. Never invent rules.
42
- - **schema.mode:**
43
- - `strict` → require schema file (never generate)
44
- - `template_only` → generate minimal helper template
45
- - **NO HEREDOC:** Never use `cat <<EOF` for TS/JS (corrupts `${}`template literals)
129
+ **If a required rule is not present in `CERBER.md` → ASK USER or FAIL FAST.**
46
130
 
47
131
  ---
48
132
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cerber-core",
3
- "version": "1.1.9",
3
+ "version": "1.1.10",
4
4
  "description": "Contract-first project guardian for AI-assisted development. Enforces CERBER.md across pre-commit, CI, and optional post-deploy gates.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",