# Generated Project Configuration

> **Auto-generated by `analyze_project`** (manually refined for v2)
> **Project:** nginx-proxy
> **Type:** CLI tool (single package)
> **Last Updated:** 2026-03-25

---

## 🚨 MANDATORY: Load CodeOps Rules Before Any Work

**Before ANY planning or implementation, the AI agent MUST load these rules
using the codeops-mcp tools:**

1. `get_rule("agents")` — Load agent behavior rules **(REQUIRED FIRST)**
2. `get_rule("code")` — Load coding standards
3. `get_rule("testing")` — Load testing workflows
4. `get_rule("git-commands")` — Load git commit protocols

These rules are **mandatory** and must be consulted before every task.
**Do NOT skip this step. Do NOT proceed without reading these documents.**

---

## Project Overview

- **Name:** @blendsdk/proxybuilder
- **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.
- **Type:** CLI tool (single package)
- **Version:** 2.0.0
- **Binary:** `proxybuilder`

## Toolchain

- **Language(s):** TypeScript (strict mode)
- **Framework(s):** yargs (CLI), Node.js built-in fs/path/child_process
- **Package Manager:** yarn
- **Test Framework:** Vitest
- **Node.js Minimum:** >= 20 LTS

**Manifest files found:** package.json, tsconfig.json

## Commands

All commands assume execution from the project root. Prefix all shell commands with `clear &&`.

### Build

```bash
clear && yarn build
```

### Test

```bash
clear && yarn test
```

### Verify (before commit)

```bash
# Full verification — run this before any git commit
clear && yarn build && yarn test
```

### Dev (run locally)

```bash
clear && node dist/index.js --help
```

## Project Structure

### Type: Single package (flat)

### Directory Layout

```
src/
  index.ts              # CLI entry point (yargs command router)
  builder.ts            # ProxyBuilder class — core proxy config logic
  config.ts             # ConfigManager — proxybuilder.json CRUD
  constants.ts          # Application-wide constants and defaults
  cron.ts               # Cron job installation helpers
  logger.ts             # Color-coded logging with verbosity control
  shell.ts              # Shell command executor with dry-run support
  template.ts           # Template engine ({{placeholder}} substitution)
  types.ts              # TypeScript interfaces and enums
  validator.ts          # Input validation (domain, upstream, email, etc.)
  commands/             # yargs command handlers (15 files)
    setup.ts            # Install system prerequisites
    init.ts             # Initialize proxybuilder working directory
    create.ts           # Create a new domain proxy
    delete.ts           # Delete a domain
    enable.ts           # Enable a disabled domain
    disable.ts          # Disable a domain
    update.ts           # Update domain configuration
    list.ts             # List all domains
    renew.ts            # Renew SSL certificates
    revoke.ts           # Revoke SSL certificate
    cert-info.ts        # Display certificate details
    dns-setup.ts        # Configure DNS provider credentials
    dns-challenge.ts    # Internal certbot hook callback (hidden)
    maintenance.ts      # Toggle maintenance mode
    status.ts           # System health overview
  dns/                  # DNS provider integrations
    provider.ts         # IDnsProvider interface + registry
    cloudns.ts          # ClouDNS implementation
    namecheap.ts        # Namecheap implementation
  templates/            # Nginx config templates (copied to dist/)
    nginx.conf          # Main nginx config
    proxy.conf          # Shared proxy headers
    letsencrypt.conf    # ACME challenge location
    maintenance.conf    # Maintenance mode check
    passthrough/        # Passthrough mode templates
      site.conf
      upstream.conf
      ssl.conf
    full/               # Full mode templates
      site.conf
      upstream.conf
      ssl.conf
      security.conf
      general.conf
      log.conf
    pages/              # HTML pages
      maintenance.html
      502.html
tests/                  # Vitest test files (192 tests)
  validator.test.ts     # Input validation (74 tests)
  template.test.ts      # Template engine (26 tests)
  config.test.ts        # ConfigManager CRUD (31 tests)
  logger.test.ts        # Logger level/file/format (24 tests)
  dns-provider.test.ts  # DNS provider registry (20 tests)
  constants.test.ts     # Constants validation (17 tests)
plans/
  proxybuilder-v2/      # v2 implementation plan (completed)
```

## Coding Conventions

### Naming

- **Files:** kebab-case (e.g., `cert-info.ts`, `dns-setup.ts`)
- **Classes:** PascalCase (e.g., `ProxyBuilder`, `ConfigManager`)
- **Interfaces:** PascalCase with `I` prefix (e.g., `IProxyConfig`, `IDomainConfig`)
- **Types/Enums:** PascalCase (e.g., `ProxyMode`, `LogLevel`)
- **Functions/Methods:** camelCase (e.g., `renderTemplate`, `getCertExpiry`)
- **Constants:** UPPER_SNAKE_CASE (e.g., `CERTBOT_BIN`, `DH_PARAM_BITS`, `FOLDERS`)

### Patterns

- **Command pattern:** Each command file exports `command`, `desc`, `builder`, `handler` (yargs module)
- **DNS provider pattern:** Plugin interface `IDnsProvider` with `registerProvider()` registry
- **Template engine:** `{{placeholder}}` substitution from `.conf` template files
- **Config storage:** Single `proxybuilder.json` file as source of truth
- **Proxy modes:** `passthrough` (SSL only) and `full` (headers, gzip, logging)

## Git & Commit Conventions

### Commit Scope

```
# Single package — use package name as scope:
# feat(proxybuilder): description
```

### Branch Strategy

- **Main branch:** `main`
- **Current development branch:** `v2`
- **Feature branches:** `feature/[name]`

## Special Rules (Project-Specific)

```
- CLI binary entry point: dist/index.js (#!/usr/bin/env node)
- Build copies src/templates/ to dist/templates/ (templates are runtime assets)
- The project manages real infrastructure (nginx, SSL certs) — changes must be tested carefully
- No shelljs dependency in v2 — uses Node.js child_process directly via Shell class
- DNS provider credentials stored with restricted file permissions (600)
- Maintenance mode uses file-based flag (no nginx reload needed)
- Two proxy modes: passthrough and full (each with own template set)
```

## Cross-References

The generic rule files that read this `project.md`:

- **make_plan.md** — Uses verify command, file paths, commit scope
- **code.md** — Uses language conventions, architecture rules
- **testing.md** — Uses test commands, test locations, test framework
- **git-commands.md** — Uses commit scope, verify command
- **agents.md** — Uses shell commands, verify command
- **plans.md** — Uses task file path patterns