Cline rules

1# Generated Project Configuration
2 
3> **Auto-generated by `analyze_project`**, customized manually
4> **Project:** blue-green
5> **Type:** infrastructure + TypeScript CLI
6> **Last updated:** 2026-06-11
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 
20**Roadmap directive:** If `plans/00-roadmap.md` exists, you MUST read it at the start of every task and update it at every lifecycle stage transition. See `get_rule("roadmap")`.
21 
22These rules are **mandatory** and must be consulted before every task.
23**Do NOT skip this step. Do NOT proceed without reading these documents.**
24 
25---
26 
27## Project Overview
28 
29- **Name:** blue-green
30- **Description:** Blue-green deployment template and scaffold generator for BlendSDK/WebAFX applications. Provides zero-downtime deployments via Nginx-based blue/green routing, designed to run behind ProxyBuilder for SSL termination. Includes a curl-installable scaffold system that generates project-specific deployment infrastructure, and a TypeScript Deploy CLI that orchestrates deployments from CI runners via SSH.
31- **Type:** infrastructure + TypeScript CLI
32 
33### Architecture
34 
35```
36Internet → ProxyBuilder (SSL termination, passthrough mode)
37         → HTTP → Blue-Green Nginx (security hardening, rate limiting, blue/green routing)
38         → App replicas (BlendSDK/WebAFX)
39```
40 
41- **ProxyBuilder passthrough mode:** Only does SSL termination + basic proxy headers (Host, X-Real-IP, X-Forwarded-For/Proto/Host/Port). NO security headers, no gzip, no WAF.
42- **Blue-Green Nginx:** Handles ALL security hardening, rate limiting, and blue/green traffic routing.
43- **Ecosystem stack:** Every app = BlendSDK/WebAFX + blue-green template + ProxyBuilder
44 
45### Deploy CLI
46 
47The Deploy CLI is a TypeScript tool bundled via esbuild into a single JavaScript file (`deploy-cli.js`). It runs on CI runners and orchestrates blue-green deployments to remote servers over SSH.
48 
49- **Source:** `src/deploy-cli/` (TypeScript, ~2800 lines across 15 files)
50- **Bundle output:** `scaffold/templates/deployment/scripts/deploy-cli.js` (~41KB, ESM format)
51- **Bundler:** esbuild (configured in `esbuild.config.mjs`)
52- **Commands:** prepare, switch, deploy, upload, deploy-config, operate, registry
53- **Two-phase deploy:** prepare (build/pull + start + health) → barrier → switch (nginx swap)
54- **Multi-server support:** Parallel execution with configurable batching (`--max-parallel`)
55- **Strategy auto-detection:** In-place (tarball + local build) or registry (pull pre-built image)
56 
57### Deployment Strategies
58 
59| Strategy | How it works | When to use |
60|----------|-------------|-------------|
61| `in-place` | Upload tarball, Docker builds locally on each server | Simple setups, few servers |
62| `registry` | Build once on CI, push to registry, servers pull | Many servers, faster deploys |
63 
64Strategy is auto-detected at runtime by `remote-ops.sh` based on `REGISTRY_URL` in `.env`.
65 
66### Scaffold System
67 
68```
69curl -fsSL <repo-url>/install.sh | bash
70  → Downloads repo tarball
71  → Runs scaffold/scaffold.js (Node.js, zero external deps, built-in readline)
72  → Interactive prompts: project name, app port, nginx port, entrypoint, replicas
73  → Conditional: strategy, PostgreSQL, Redis, pg-backup (yes/no prompts)
74  → Generates deployment/ directory with fully configured infrastructure
75```
76 
77- **Entry point:** `install.sh` (thin bash wrapper, downloads repo, invokes scaffold.js)
78- **Generator:** `scaffold/scaffold.js` (~580 lines, zero external dependencies)
79- **Templates:** `scaffold/templates/` (42 template files for deployment infrastructure)
80- **Partials:** `scaffold/partials/` (16 conditional partial files for strategy/PostgreSQL/Redis/pg-backup)
81- **Template placeholders:** `{{PROJECT_NAME}}`, `{{APP_PORT}}`, `{{NGINX_PORT}}`, `{{ENTRYPOINT}}`, `{{APP_REPLICAS}}`, `{{APP_BUILD_SECTION}}`
82- **Conditional generation:** `{{PARTIAL_*}}` placeholders inject content from `scaffold/partials/` based on user answers
83- **Comment-wrapped placeholders:** In bash templates, `# {{PARTIAL}}` so `bash -n` syntax checks pass on raw templates
84- **Conflict detection:** Skips existing files by default; `--force` flag overwrites
85 
86### Docker Compose Profiles
87 
88| Profile | Services |
89|---------|----------|
90| `core` | nginx, postgres, redis |
91| `blue` | app-blue replicas |
92| `green` | app-green replicas |
93| `all` | core + blue + green |
94| `db` | postgres only |
95 
96### Nginx Modular Config
97 
98```
99nginx/nginx.conf              — Main config, includes all modules
100nginx/conf.d/                  — Server-level config (server-name)
101nginx/includes/                — Shared includes (headers, proxy, timeouts, etc.)
102nginx/locations/               — Location blocks (health, ping, status, default)
103nginx/upstreams/               — Upstream definitions (blue, green, active)
104```
105 
106## Toolchain
107 
108- **Language(s):** TypeScript (Deploy CLI), Docker, Nginx config, Bash scripts, Node.js (app + scaffold)
109- **Framework(s):** BlendSDK/WebAFX (app layer)
110- **Package Manager:** npm
111- **Bundler:** esbuild (bundles TypeScript Deploy CLI to single JS file)
112- **Test Framework:** Node.js built-in test runner (`node:test`) for Deploy CLI
113- **Test Runner:** `node --experimental-strip-types --test src/deploy-cli/__tests__/*.test.ts`
114- **Scaffold Runtime:** Node.js (zero external dependencies, built-in readline)
115 
116**Manifest files found:** package.json, docker-compose.yml, app/package.json, scaffold/package.json, tsconfig.json
117 
118## Commands
119 
120All commands assume execution from the project root. Prefix all shell commands with `clear && sleep [delay] &&` (see Terminal Delay below).
121 
122### Terminal Delay
123 
124- **Delay (seconds):** 3
125- The `clear` ensures a clean terminal; the `sleep` gives VS Code time to initialize the terminal before the command runs.
126- Adjust the delay for your environment: `1` for fast machines, `3` (default) for normal, `5` for slower environments.
127- All command examples below use `sleep 3` — replace `3` with your configured delay.
128 
129### Build
130 
131```bash
132# Build Deploy CLI bundle
133clear && sleep 3 && npm run build:cli
134 
135# Build Docker containers
136clear && sleep 3 && docker compose build
137```
138 
139### Test / Validate
140 
141```bash
142# Run Deploy CLI unit tests (57 tests)
143clear && sleep 3 && npm run test:cli
144 
145# Validate docker-compose configuration
146clear && sleep 3 && docker compose config
147 
148# Type-check TypeScript
149clear && sleep 3 && npx tsc --noEmit
150```
151 
152### Verify (before commit)
153 
154```bash
155# Full verification — run this before any git commit
156clear && sleep 3 && npm run verify && bash -n scaffold/templates/deployment/scripts/remote-ops.sh
157```
158 
159### Blue-Green Switch
160 
161```bash
162# Switch active environment (blue↔green)
163clear && sleep 3 && bash scripts/switch-environment.sh
164```
165 
166### Scaffold (run from target project)
167 
168```bash
169# Install scaffold into a new project (from target project root)
170curl -fsSL https://raw.githubusercontent.com/blendsdk/blue-green/master/install.sh | bash
171 
172# Or run scaffold.js directly during development
173clear && sleep 3 && node scaffold/scaffold.js
174```
175 
176## Project Structure
177 
178### Type: Single repository
179 
180### Directory Layout
181 
182```
183install.sh                     — Curl-installable entry point (downloads repo, runs scaffold.js)
184package.json                   — Root package.json (type: module, esbuild + TypeScript devDeps)
185tsconfig.json                  — TypeScript config (strict, ESNext, noEmit)
186esbuild.config.mjs             — esbuild bundler config for Deploy CLI
187app/                           — Application container (BlendSDK/WebAFX)
188  Dockerfile                   — Multi-stage Node.js build
189  package.json                 — App dependencies
190  server.js                    — Application entry point
191  start.sh                     — Container startup script
192  healthcheck.sh               — Docker health check script
193data/
194  postgresql/                  — PostgreSQL data volume mount
195nginx/                         — Nginx configuration (modular)
196  nginx.conf                   — Main config
197  conf.d/                      — Server-level includes
198  includes/                    — Shared config fragments
199  locations/                   — Location blocks (numbered for ordering)
200  upstreams/                   — Blue/green/active upstream definitions
201src/deploy-cli/                — Deploy CLI TypeScript source
202  index.ts                     — Entry point, argument parser, command dispatcher
203  types.ts                     — All interfaces and type definitions
204  lib/                         — Core libraries
205    process.ts                 — Spawn helper with timeout and stream capture
206    logger.ts                  — Structured output with emoji prefixes
207    ssh.ts                     — SSH setup, exec, SCP upload, cleanup
208    config.ts                  — Config resolution ({ENV} placeholders)
209    inventory.ts               — Server inventory resolution (scope/filter)
210  commands/                    — Command implementations
211    shared.ts                  — Common infrastructure (parseDeployOptions, executeOnServers)
212    upload.ts                  — Multi-step file upload to servers
213    deploy-config.ts           — Config file deployment from secrets
214    operate.ts                 — Generic remote-ops.sh subcommand runner
215    prepare.ts                 — Blue-green prepare (phase 1)
216    switch.ts                  — Blue-green switch (phase 2)
217    deploy.ts                  — Coordinated deploy with barrier
218    registry.ts                — Docker build + push (CI-side)
219  __tests__/                   — Unit tests (57 tests)
220    config.test.ts             — Config resolution tests (13)
221    inventory.test.ts          — Server inventory tests (24)
222    parser.test.ts             — Argument parser tests (20)
223    fixtures/                  — Test fixture files
224      deploy-config.json       — Test config fixture
225      deploy-inventory.json    — Test inventory fixture
226scaffold/                      — Scaffold generator system
227  package.json                 — CJS override (type: commonjs for scaffold.js)
228  scaffold.js                  — Interactive generator (~580 lines, Node.js, zero deps)
229  templates/                   — Template files (42 files, mirrors deployment structure)
230    .gitignore.template        — Generated .gitignore for target projects
231    deploy-config.json         — Deploy configuration template
232    deploy-inventory.json      — Server inventory template
233    deploy-package.sh          — Deploy packaging script template
234    deployment/                — Full deployment infrastructure templates
235      .env.example             — Environment variable template
236      docker-compose.yml       — Docker Compose template with conditional services
237      Dockerfile               — App Dockerfile template
238      pg-backup.sh             — PostgreSQL backup script (conditional)
239      nginx/                   — Nginx config templates (mirrors nginx/ structure)
240        nginx.conf
241        conf.d/server-name.conf
242        includes/*.conf        — All include templates
243        locations/*.conf       — All location templates
244        upstreams/*.conf       — All upstream templates
245      scripts/                 — Deployment scripts (3 files)
246        deploy-cli.js          — Deploy CLI bundle (ESM, ~41KB)
247        remote-ops.sh          — Remote operations script (SSH commands)
248        health-check-wait.sh   — Health check wait script
249    .github/                   — GitHub Actions workflow templates
250      SECRETS-SETUP.md         — GitHub Secrets documentation
251      workflows/
252        build-test.yml         — CI: build + test on every push/PR
253        release-single.yml     — CD: single-server release
254        release-multi.yml      — CD: multi-server release (three-job barrier)
255        operations-single.yml  — Ops: single-server operations
256        operations-multi.yml   — Ops: multi-server operations
257    local_data/                — Local data directory template
258      .gitkeep                 — Keeps directory in git
259    scripts/                   — Project-level script templates
260      push-secrets.sh          — Secret pushing script template
261  partials/                    — Conditional partial files (16 files)
262    compose-build-inplace.yml  — In-place Docker build section
263    compose-build-registry.yml — Registry Docker image section
264    docker-compose-postgres.yml  — PostgreSQL service block
265    docker-compose-redis.yml     — Redis service block
266    docker-compose-pgbackup.yml  — pg-backup service block
267    env-postgres.txt             — PostgreSQL env vars
268    env-redis.txt                — Redis env vars
269    env-backup.txt               — Backup env vars
270    env-registry.txt             — Registry env vars
271    remote-ops-database-commands.sh   — Database command functions
272    remote-ops-dispatcher-database.sh — Database dispatcher entries
273    remote-ops-health-check-db.sh     — Database health check
274    remote-ops-help-database.sh       — Database help text
275    operations-database-options.yml   — GitHub Actions database options
276    operations-database-steps.yml     — GitHub Actions database steps
277plans/                         — Implementation plans and notes
278  deploy-cli/                  — Deploy CLI implementation plan (9 phases, 66 tasks)
279    00-index.md                — Plan index
280    01-requirements.md         — Requirements document
281    02-current-state.md        — Current state analysis
282    03-deploy-cli-architecture.md — Deploy CLI architecture
283    04-remote-ops-updates.md   — Remote ops two-phase + registry updates
284    05-registry-deployment.md  — Registry deployment templates
285    06-workflow-refactoring.md — Workflow YAML refactoring
286    07-scaffold-updates.md     — Scaffold generator updates
287    08-scaffoldapp-migration.md — ScaffoldApp migration
288    09-testing-strategy.md     — Testing strategy
289    99-execution-plan.md       — Execution plan (66/66 tasks complete)
290  scaffold-deployment/         — Scaffold system implementation plan (47/47 tasks complete)
291  remove-internet-mode/        — Completed: removed internet/certbot mode
292  refactor-blue-green/         — Original refactoring plan
293  security-hardening/          — Security hardening plan (in progress)
294  security-hardening-notes.md  — Future security improvements
295scripts/                       — Operational scripts
296  agent.sh                     — VS Code agent mode switching
297  health-check-wait.sh         — Wait for healthy containers
298  switch-environment.sh        — Blue↔green environment switcher
299```
300 
301## Coding Conventions
302 
303### Naming
304 
305- **Files:** kebab-case (`switch-environment.sh`, `proxy_headers.conf`)
306- **TypeScript files:** kebab-case (`deploy-config.ts`, `shared.ts`)
307- **Nginx configs:** Numbered prefix for ordering in `locations/` (`10-health.conf`, `99-default.conf`)
308- **Scripts:** kebab-case with descriptive names
309- **Environment variables:** UPPER_SNAKE_CASE (`ACTIVE_ENV`, `APP_REPLICAS`)
310- **Template files:** Same name as target output file (e.g., `docker-compose.yml` template → generates `docker-compose.yml`)
311- **Partial files:** Descriptive kebab-case with service prefix (`docker-compose-postgres.yml`, `env-redis.txt`, `remote-ops-health-check-db.sh`)
312 
313### TypeScript / Deploy CLI Style
314 
315- **Import convention:** All internal imports use `.ts` extensions for `--experimental-strip-types` compatibility
316- **Module format:** ESM (`"type": "module"` in root package.json)
317- **Type imports:** Use `import type { ... }` for type-only imports
318- **JSDoc comments:** Required on all exported functions and interfaces
319- **Constants:** UPPER_SNAKE_CASE for module-level constants
320- **Error handling:** Commands exit with `process.exit(1)` on failure, never throw uncaught
321- **No private members:** Use `protected` instead of `private` (per code.md)
322 
323### Nginx Config Style
324 
325- Use `include` directives for modularity — one concern per file
326- Comment every config file with its purpose
327- Reference ProxyBuilder in upstream/architecture comments
328- Use `conf.d/`, `includes/`, `locations/`, `upstreams/` subdirectories
329 
330### Shell Script Style
331 
332- Always include `#!/bin/bash` shebang
333- Use `set -e` for error handling
334- Add descriptive comments explaining purpose
335 
336### Scaffold Template Style
337 
338- **Placeholders:** Use `{{UPPER_SNAKE_CASE}}` for variable substitution (e.g., `{{PROJECT_NAME}}`, `{{APP_PORT}}`)
339- **Conditional partials:** Use `{{PARTIAL_NAME}}` for content injection from `scaffold/partials/`
340- **Comment wrapping:** In bash/shell templates, wrap partials in comments: `# {{PARTIAL_NAME}}` so `bash -n` passes on raw templates
341- **Template mirroring:** Templates in `scaffold/templates/deployment/` mirror the exact directory structure of the generated output
342- **Zero dependencies:** scaffold.js uses only Node.js built-in modules (`fs`, `path`, `readline`)
343 
344## Git & Commit Conventions
345 
346### Commit Scope
347 
348```
349# Use module/feature as scope:
350# feat(deploy-cli): description
351# feat(nginx): description
352# feat(docker): description
353# feat(scripts): description
354# feat(scaffold): description
355# chore(plans): description
356# docs(readme): description
357```
358 
359### Valid Scopes
360 
361- `deploy-cli` — Deploy CLI TypeScript source and tests
362- `nginx` — Nginx configuration changes
363- `docker` — Docker Compose, Dockerfile changes
364- `scripts` — Script additions/modifications
365- `app` — Application code changes
366- `scaffold` — Scaffold generator, templates, partials, install.sh
367- `plans` — Plan documents
368- `readme` / `docs` — Documentation
369- `env` — Environment variable changes
370- `security` — Security-related changes
371 
372### Branch Strategy
373 
374- **Main branch:** `master`
375- **Feature branches:** `feature/[name]`
376 
377## Special Rules (Project-Specific)
378 
379### ProxyBuilder Awareness
380 
381- This template NEVER handles SSL/TLS directly — ProxyBuilder does SSL termination
382- HSTS headers are set at the Nginx layer but work because ProxyBuilder passes them through to browsers over HTTPS
383- Security headers are ALL set at the blue-green Nginx layer (ProxyBuilder is a "dumb passthrough")
384- No certbot, no SSL certificates, no HTTPS port in this template
385 
386### Environment Variables
387 
388- Core env vars: `COMPOSE_PROJECT_NAME`, `APP_REPLICAS`, `ACTIVE_ENV`, `NGINX_HTTP_PORT`
389- Service-specific: `HEALTH_CHECK_*`, `POSTGRES_*`, `REDIS_*`
390- Registry-specific: `REGISTRY_URL`, `REGISTRY_USER`, `REGISTRY_PASSWORD`, `IMAGE_NAME`
391- No `NGINX_MODE`, `NGINX_HTTPS_PORT`, `DOMAIN_NAME`, or `CERTBOT_EMAIL` (removed in remove-internet-mode)
392 
393### Security Model (rated 7/10)
394 
395- Strong SSL at edge (ProxyBuilder), comprehensive headers at Nginx layer
396- Rate limiting, IP anonymization via trusted_proxies
397- Known gaps documented in `plans/security-hardening-notes.md`:
398  - trusted_proxies too broad (trusts all private ranges)
399  - No per-endpoint rate limits
400  - CSP not flexible for HTML apps
401  - No WAF
402 
403### Deploy CLI Rules
404 
405- **Bundle format:** ESM — runs in contexts where parent `package.json` has `"type": "module"`
406- **scaffold/package.json** has `"type": "commonjs"` for scaffold.js — the bundle under `scaffold/templates/` inherits CJS context locally, but works in generated projects
407- **SSH key is optional:** CI environments may provide key via `SSH_PRIVATE_KEY` env var, or use pre-configured SSH agents
408- **Jump host:** Uses `ProxyCommand` with `ssh -W %h:%p` (not `ProxyJump`) for older SSH compatibility
409- **DEPLOY_PATH:** Must be absolute path (`/opt/app`), NOT `~/path` (tilde expands on CI runner, not remote server)
410- **Two-phase deploy safety:** If ANY server fails prepare, the deploy command aborts without switching any server
411 
412### Scaffold System Rules
413 
414- **Template placeholders** (`{{...}}`) are replaced at generation time — they do NOT appear in generated output
415- **Partial injection** is all-or-nothing: if user says "no" to PostgreSQL, the entire PostgreSQL partial is omitted (empty string)
416- **Conflict detection:** scaffold.js skips files that already exist unless `--force` is passed
417- **Generated output structure:** Target project gets `deployment/`, `scripts/push-secrets.sh`, `deploy-config.json`, `deploy-inventory.json`, `deploy-package.sh`, `.gitignore`, `local_data/.gitkeep`, `.github/workflows/`, `.github/SECRETS-SETUP.md`
418- **No runtime dependencies:** scaffold.js and all generated scripts use only bash and Node.js built-ins
419- **install.sh requirements:** Must work with `curl -fsSL <url> | bash` — no interactivity in the download phase, interactivity starts when scaffold.js runs
420- **GitHub Actions workflows** are generated into `.github/workflows/` — single-server gets `release.yml` + `operations.yml`, multi-server gets `release-multi.yml` + `operations-multi.yml`
421 
422## Cross-References
423 
424The generic rule files that read this `project.md`:
425 
426- **make_plan.md** — Uses verify command, file paths, commit scope, task file path patterns
427- **code.md** — Uses language conventions, architecture rules
428- **testing.md** — Uses test commands, test locations, test framework
429- **git-commands.md** — Uses commit scope, verify command
430- **agents.md** — Uses shell commands, verify command
431- **requirements.md** — Uses project type, tech stack, and conventions for requirements discovery
432- **retro_requirements.md** — Uses project type, tech stack for codebase analysis adaptation
433- **techdocs.md** — Uses project type, tech stack for documentation generation
434- **upgrade_plan.md** — Uses project context for upgrade compatibility checks
435- **grill_me.md** — Uses project context for deep disambiguation before planning or requirements
436- **preflight.md** — Uses project type, tech stack, and conventions for grounded quality audits
437- **roadmap.md** — Tracks RDs/plans across the feature-set lifecycle if a roadmap exists (make_roadmap)
438