// ZSH-NGINX — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

zsh-nginx is the vhost-lifecycle plugin for the Debian/Ubuntu nginx layout: $NGINX_DIR/sites-available/ stores configs, $NGINX_DIR/sites-enabled/ is a symlink farm pointing into the available tree. Three autoloaded zsh functions (en, dis, vhost) plus two service aliases (ngt for config-test, ngr for restart) cover the standard "create vhost → enable it → reload nginx" loop. Each function ships a paired #compdef completion driven by ls over the relevant sites-* directory — completion candidates are always real on-disk files, never a hand-maintained list that can drift. The vhost generator sed-substitutes {vhost}/{user}/{pool_port} into one of two templates (Symfony2 fastcgi or plain PHP-FPM) and optionally writes an /etc/hosts entry — turning a new vhost into a single command.

#FILE STRUCTURE

Three slices: autoload/ for the user-facing fns, src/ for the matching completions (one #compdef per fn), templates/ for the nginx config skeletons. The entrypoint registers both directories on fpath (autoload + completion) so a single source line covers the full surface.

$USER SURFACE

Five callable names. The plugin lives in the user's interactive shell; nothing runs at source time except env-var defaults + the sudo probe + 2 alias definitions + fpath append + autoload -Uz. First call to en/dis/vhost triggers the actual fn body via zsh's autoload machinery.

// VHOST FLAGS

@VHOST PIPELINE

From vhost foo.example to a live nginx site in 5 stages. Each stage gates on the previous — missing user, missing template, or failed enable will short-circuit with a colourised error and leave the system in a consistent state (no half-written config in sites-available, no dangling symlink in sites-enabled).

  vhost [-u USER] [-t TPL] [-n] [-w] NAME
       │
       ▼
  ┌─────────────────────────┐
  │ getopts: parse flags    │
  │   user   ← USER || $USER│
  │   tmpl   ← TPL  || $NGINX_VHOST_TEMPLATE
  │   enable ← (no -n)      │
  │   hosts  ← (-w)         │
  └─────────┬───────────────┘
            │
            ▼
  ┌─────────────────────────┐
  │ resolve template path   │
  │   $ZSH/plugins/nginx/   │
  │     templates/$TPL      │  ──── or ── raw path ── or ── default ─▶
  └─────────┬───────────────┘
            │
            ▼
  ┌─────────────────────────┐
  │ _vhost_generate         │
  │   user lookup (passwd)  │
  │   pool_port = "1" + UID │
  │   sed {vhost}{user}{pool_port}
  │     → $NAME.tmp         │
  │   $sudo mv $NAME.tmp    │
  │     → sites-available/  │
  └─────────┬───────────────┘
            │
            ▼ (if enable)
  ┌─────────────────────────┐
  │ en $NAME                │
  │   ln -s available/$NAME │
  │      enabled/$NAME      │
  │   (sudo)                │
  └─────────┬───────────────┘
            │
            ▼ (if -w)
  ┌─────────────────────────┐
  │ _write_hosts $NAME      │
  │   splice "127.0.0.1     │
  │   $NAME" into first     │
  │   line of /etc/hosts    │
  └─────────────────────────┘
            │
            ▼
  ┌─────────────────────────┐
  │ ngt && ngr              │ ← user-driven, not auto
  │ (verify + reload)       │
  └─────────────────────────┘

The pool-port trick (pool_port = "1" + UID) is the canonical multi-tenant PHP-FPM convention: each user gets a fastcgi socket on their own port, derived from /etc/passwd UID. UID 1000 → pool 11000, UID 1001 → 11001, etc. The template emits the literal unix:/var/run/php5-fpm.{user}.socket string — the pool_port is substituted in for templates that use it.

&COMPLETION

All three completions follow the same 8-line shape: a #compdef directive, an internal helper that runs ls -a against the relevant directory and pipes through awk to filter to lowercase-prefixed names, then compadd `helper` to feed candidates into the completion engine. The point: completion sources are live filesystem state, not a hand-maintained list.

The asymmetry is intentional. en's candidates are configs that exist but aren't symlinked (available). dis's candidates are configs that are currently active (enabled). vhost's candidates are project directories that don't yet have a vhost (~/www). Each completion answers exactly the question the user asks; no overlap, no confusion.

~TEMPLATES

Two stock templates, both targeting per-user PHP-FPM with a unix-socket fastcgi backend. Both deny .ht* dotfiles (Apache leftovers blocked by convention). Substitution uses {vhost}, {user}, {pool_port} — a 3-key sed pass. The choice was deliberate: bigger templating systems (mustache, jinja) would force a tool dep on the user's box; sed is in every POSIX install.

*TEST COVERAGE

28 zunit @test cases across 5 test files pin the plugin contract: aliases (ngt/ngr) are defined and reference $sudo; entrypoint defaults $NGINX_DIR and $NGINX_VHOST_TEMPLATE only when unset (idempotent re-source); every autoload fn is defined after sourcing the plugin; every completion has a #compdef directive matching its fn name; every source file parses cleanly under zsh -n. 21 additional .sh doc-hygiene gates pin the README, docs, workflow, and test-file structure.

?KEY DESIGN DECISIONS

Each call-out is a decision the implementation could have gone either way on, with the rationale for the path taken.

+COMPAT & DEPS

The plugin assumes Debian-style nginx layout (/etc/nginx/sites-available + /etc/nginx/sites-enabled) and per-user PHP-FPM on unix sockets. Anything else is BYO template. Zsh 5.x compat floor — no zsh 6 features. No build step, no install hook, no compiled output.

// ENV CONTRACT

!STRATEGIC POSITION

zsh-nginx is the smallest plugin in the MenkeTechnologies stack but covers a real ops loop: "I want a new local vhost on this dev box, now." Without the plugin, the same loop is ~5 hand-typed commands across cd /etc/nginx/sites-available, sudo cp template foo, sudo vim foo, sudo ln -s ../sites-available/foo ../sites-enabled/foo, and sudo service nginx restart. With the plugin it's vhost foo -w && ngt && ngr — same outcome, three commands, no manual sed.