Cline rules

1# Generated Project Configuration
2 
3> **Auto-generated by `analyze_project`** (manually refined for v2)
4> **Project:** nginx-proxy
5> **Type:** CLI tool (single package)
6> **Last Updated:** 2026-03-25
7 
8---
9 
10## 🚨 MANDATORY: Load CodeOps Rules Before Any Work
11 
12**Before ANY planning or implementation, the AI agent MUST load these rules
13using the codeops-mcp tools:**
14 
151. `get_rule("agents")` — Load agent behavior rules **(REQUIRED FIRST)**
162. `get_rule("code")` — Load coding standards
173. `get_rule("testing")` — Load testing workflows
184. `get_rule("git-commands")` — Load git commit protocols
19 
20These rules are **mandatory** and must be consulted before every task.
21**Do NOT skip this step. Do NOT proceed without reading these documents.**
22 
23---
24 
25## Project Overview
26 
27- **Name:** @blendsdk/proxybuilder
28- **Description:** Nginx reverse proxy configuration builder CLI tool. Generates nginx proxy configs, manages SSL certificates via Let's Encrypt (including wildcard certs via DNS-01), handles domain-based reverse proxy setups with round-robin load balancing, and provides file-based maintenance mode.
29- **Type:** CLI tool (single package)
30- **Version:** 2.0.0
31- **Binary:** `proxybuilder`
32 
33## Toolchain
34 
35- **Language(s):** TypeScript (strict mode)
36- **Framework(s):** yargs (CLI), Node.js built-in fs/path/child_process
37- **Package Manager:** yarn
38- **Test Framework:** Vitest
39- **Node.js Minimum:** >= 20 LTS
40 
41**Manifest files found:** package.json, tsconfig.json
42 
43## Commands
44 
45All commands assume execution from the project root. Prefix all shell commands with `clear &&`.
46 
47### Build
48 
49```bash
50clear && yarn build
51```
52 
53### Test
54 
55```bash
56clear && yarn test
57```
58 
59### Verify (before commit)
60 
61```bash
62# Full verification — run this before any git commit
63clear && yarn build && yarn test
64```
65 
66### Dev (run locally)
67 
68```bash
69clear && node dist/index.js --help
70```
71 
72## Project Structure
73 
74### Type: Single package (flat)
75 
76### Directory Layout
77 
78```
79src/
80  index.ts              # CLI entry point (yargs command router)
81  builder.ts            # ProxyBuilder class — core proxy config logic
82  config.ts             # ConfigManager — proxybuilder.json CRUD
83  constants.ts          # Application-wide constants and defaults
84  cron.ts               # Cron job installation helpers
85  logger.ts             # Color-coded logging with verbosity control
86  shell.ts              # Shell command executor with dry-run support
87  template.ts           # Template engine ({{placeholder}} substitution)
88  types.ts              # TypeScript interfaces and enums
89  validator.ts          # Input validation (domain, upstream, email, etc.)
90  commands/             # yargs command handlers (15 files)
91    setup.ts            # Install system prerequisites
92    init.ts             # Initialize proxybuilder working directory
93    create.ts           # Create a new domain proxy
94    delete.ts           # Delete a domain
95    enable.ts           # Enable a disabled domain
96    disable.ts          # Disable a domain
97    update.ts           # Update domain configuration
98    list.ts             # List all domains
99    renew.ts            # Renew SSL certificates
100    revoke.ts           # Revoke SSL certificate
101    cert-info.ts        # Display certificate details
102    dns-setup.ts        # Configure DNS provider credentials
103    dns-challenge.ts    # Internal certbot hook callback (hidden)
104    maintenance.ts      # Toggle maintenance mode
105    status.ts           # System health overview
106  dns/                  # DNS provider integrations
107    provider.ts         # IDnsProvider interface + registry
108    cloudns.ts          # ClouDNS implementation
109    namecheap.ts        # Namecheap implementation
110  templates/            # Nginx config templates (copied to dist/)
111    nginx.conf          # Main nginx config
112    proxy.conf          # Shared proxy headers
113    letsencrypt.conf    # ACME challenge location
114    maintenance.conf    # Maintenance mode check
115    passthrough/        # Passthrough mode templates
116      site.conf
117      upstream.conf
118      ssl.conf
119    full/               # Full mode templates
120      site.conf
121      upstream.conf
122      ssl.conf
123      security.conf
124      general.conf
125      log.conf
126    pages/              # HTML pages
127      maintenance.html
128      502.html
129tests/                  # Vitest test files (192 tests)
130  validator.test.ts     # Input validation (74 tests)
131  template.test.ts      # Template engine (26 tests)
132  config.test.ts        # ConfigManager CRUD (31 tests)
133  logger.test.ts        # Logger level/file/format (24 tests)
134  dns-provider.test.ts  # DNS provider registry (20 tests)
135  constants.test.ts     # Constants validation (17 tests)
136plans/
137  proxybuilder-v2/      # v2 implementation plan (completed)
138```
139 
140## Coding Conventions
141 
142### Naming
143 
144- **Files:** kebab-case (e.g., `cert-info.ts`, `dns-setup.ts`)
145- **Classes:** PascalCase (e.g., `ProxyBuilder`, `ConfigManager`)
146- **Interfaces:** PascalCase with `I` prefix (e.g., `IProxyConfig`, `IDomainConfig`)
147- **Types/Enums:** PascalCase (e.g., `ProxyMode`, `LogLevel`)
148- **Functions/Methods:** camelCase (e.g., `renderTemplate`, `getCertExpiry`)
149- **Constants:** UPPER_SNAKE_CASE (e.g., `CERTBOT_BIN`, `DH_PARAM_BITS`, `FOLDERS`)
150 
151### Patterns
152 
153- **Command pattern:** Each command file exports `command`, `desc`, `builder`, `handler` (yargs module)
154- **DNS provider pattern:** Plugin interface `IDnsProvider` with `registerProvider()` registry
155- **Template engine:** `{{placeholder}}` substitution from `.conf` template files
156- **Config storage:** Single `proxybuilder.json` file as source of truth
157- **Proxy modes:** `passthrough` (SSL only) and `full` (headers, gzip, logging)
158 
159## Git & Commit Conventions
160 
161### Commit Scope
162 
163```
164# Single package — use package name as scope:
165# feat(proxybuilder): description
166```
167 
168### Branch Strategy
169 
170- **Main branch:** `main`
171- **Current development branch:** `v2`
172- **Feature branches:** `feature/[name]`
173 
174## Special Rules (Project-Specific)
175 
176```
177- CLI binary entry point: dist/index.js (#!/usr/bin/env node)
178- Build copies src/templates/ to dist/templates/ (templates are runtime assets)
179- The project manages real infrastructure (nginx, SSL certs) — changes must be tested carefully
180- No shelljs dependency in v2 — uses Node.js child_process directly via Shell class
181- DNS provider credentials stored with restricted file permissions (600)
182- Maintenance mode uses file-based flag (no nginx reload needed)
183- Two proxy modes: passthrough and full (each with own template set)
184```
185 
186## Cross-References
187 
188The generic rule files that read this `project.md`:
189 
190- **make_plan.md** — Uses verify command, file paths, commit scope
191- **code.md** — Uses language conventions, architecture rules
192- **testing.md** — Uses test commands, test locations, test framework
193- **git-commands.md** — Uses commit scope, verify command
194- **agents.md** — Uses shell commands, verify command
195- **plans.md** — Uses task file path patterns
196