@rexaray008/nodeproxy 1.0.1 → 2.0.1

package/README copy.md

@@ -0,0 +1,283 @@
+# nodeproxy
+
+A tiny, zero-dependency reverse proxy for Node.js ("a mini nginx") with built-in Cloudflare Tunnel support — so a project running on your own machine can be reached at a real domain, with no port forwarding and no static IP.
+
+This README is a complete walkthrough from a fresh clone to a live public domain. Follow it top to bottom the first time; after that, day-to-day usage is a single command (Step 7).
+
+---
+
+## What you'll end up with
+
+```
+Internet  --https-->  Cloudflare edge  --tunnel-->  cloudflared (your machine)  -->  nodeproxy (port 8080)  -->  your project (e.g. port 3000)
+```
+
+Cloudflare terminates TLS and routes traffic through an outbound-only tunnel to `cloudflared` on your machine. `cloudflared` hands it to `nodeproxy`, which routes it to whichever local project you've configured. Nothing needs to be exposed on your router or firewall.
+
+---
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+- **Node.js 16 or newer** — check with `node -v`. Get it from https://nodejs.org if missing.
+- **A project already running locally** that you want to expose — e.g. something listening on `http://localhost:3000`. It can be anything (Express, Next.js, a static site server, etc.) — nodeproxy just forwards to it.
+- **(Only if using a real domain) A domain added to a Cloudflare account**, with its nameservers pointed at Cloudflare. The free plan is enough. If you just want to test locally without a public domain, skip Steps 5–7.
+- **(Linux only, for auto-install) `curl` and `sudo`** available in your shell.
+- **(macOS only, for auto-install) Homebrew** installed (https://brew.sh).
+
+---
+
+## Step 1 — Get the files
+
+Unzip the package and move into it:
+
+```bash
+unzip nodeproxy.zip
+cd nodeproxy
+```
+
+## Step 2 — Make the `nodeproxy` command available
+
+```bash
+npm link
+```
+
+This registers `nodeproxy` as a global command pointing at this folder. Verify it worked:
+
+```bash
+nodeproxy help
+```
+
+You should see the full command list. (If you'd rather not touch global npm links, you can run everything below as `node bin/cli.js ...` instead of `nodeproxy ...` — they're equivalent.)
+
+## Step 3 — Start the proxy for the first time
+
+```bash
+nodeproxy start
+```
+
+Expected output:
+```
+[nodeproxy] Using config: /path/to/nodeproxy.config.json
+[nodeproxy] (edit this file, or use "nodeproxy add <host> <target>", to change routing)
+[nodeproxy] HTTP listening on port 8080
+```
+
+On this first run, nodeproxy auto-creates `nodeproxy.config.json` next to the CLI, defaulting to: listen on port 8080, forward everything to `http://localhost:3000`.
+
+Leave this running and, in a second terminal, check it works:
+
+```bash
+curl http://localhost:8080
+```
+
+If your project is already running on port 3000, you'll see its response. If not, you'll get a `502 Bad Gateway` — that's expected until your project is up; it just means the proxy itself is working correctly.
+
+Stop it for now with `Ctrl+C` — you'll restart it with the tunnel in Step 7.
+
+## Step 4 — Point it at your actual project(s)
+
+If your project runs on a port other than 3000, edit `nodeproxy.config.json` directly, or:
+
+```bash
+nodeproxy add "*" http://localhost:YOUR_PORT
+```
+
+**Running more than one project?** Give each its own listener/port on the proxy side:
+
+```bash
+nodeproxy listen 9090
+nodeproxy add "*" http://localhost:4000 --port 9090
+```
+
+Now port 8080 and port 9090 on the proxy are two completely independent routes. You can also route by domain name instead of `*` if a single port should serve multiple domains — see `nodeproxy.config.json` for the `routes` array format (each entry is `{ host, targets, staticDir }`).
+
+Skip to Step 8 if you only want local routing and don't need a public domain yet.
+
+## Step 5 — One-time Cloudflare login and tunnel creation
+
+```bash
+nodeproxy tunnel setup --domain app.yourdomain.com --port 8080
+```
+
+Replace `app.yourdomain.com` with the actual subdomain you want live, and `8080` with whichever proxy port you want it to reach (from Step 4).
+
+What happens, in order:
+
+1. **cloudflared install check.** If missing, nodeproxy tries to install it automatically (Homebrew on macOS, direct binary download on Linux). If auto-install fails on your platform, it prints the exact manual install command and stops — just run that command and re-run `tunnel setup`.
+2. **Browser login.** If this machine hasn't authorized with Cloudflare before, your browser opens to a Cloudflare page. Log in and click **Authorize**. This is the one manual step in the entire setup — it's how Cloudflare's OAuth flow works and can't be scripted by any tool. It only happens once per machine.
+3. **Tunnel creation.** Creates a named tunnel (defaults to your domain with dots replaced by dashes, e.g. `app-yourdomain-com`).
+4. **Ingress config.** Writes `~/.cloudflared/<name>.yml` mapping your domain to `http://localhost:8080` (or whichever port you passed).
+5. **DNS routing.** Automatically adds the CNAME record in your Cloudflare DNS pointing your domain at the tunnel.
+
+Expected final output:
+```
+[tunnel] Done! "app.yourdomain.com" now points at your local port 8080.
+[tunnel] From now on, just run:  nodeproxy start --tunnel --name app-yourdomain-com
+```
+
+## Step 6 — DNS propagation
+
+Cloudflare DNS usually updates within seconds to a couple of minutes. You can check with:
+
+```bash
+dig app.yourdomain.com
+```
+
+You should see it resolving to Cloudflare's IPs (not your own). This confirms DNS is correctly routed — the tunnel itself only carries traffic once it's actually running (next step).
+
+## Step 7 — Go live (the one command you'll use from now on)
+
+```bash
+nodeproxy start --tunnel
+```
+
+This single command starts both the local proxy and the Cloudflare tunnel together. Expected output:
+```
+[nodeproxy] Using config: /path/to/nodeproxy.config.json
+[nodeproxy] HTTP listening on port 8080
+[tunnel] Starting cloudflared tunnel "app-yourdomain-com"...
+```
+
+Visit `https://app.yourdomain.com` in a browser — it should now serve your local project. TLS is handled entirely by Cloudflare's edge, so `https://` works immediately with no certificates on your end.
+
+If you created the tunnel with a custom `--name` in Step 5, pass it here too:
+```bash
+nodeproxy start --tunnel --name app2
+```
+
+## Step 8 — Verify everything end to end
+
+```bash
+# 1. Confirm the local proxy responds
+curl -H "Host: app.yourdomain.com" http://localhost:8080
+
+# 2. Confirm the public domain responds the same way
+curl https://app.yourdomain.com
+```
+
+Both should return the same content from your backend project. If step 1 works but step 2 doesn't, the issue is in the tunnel/DNS layer (see Troubleshooting). If step 1 itself fails, the issue is your local project or the `add`/`listen` routing config, not Cloudflare.
+
+---
+
+## Running multiple domains/projects through tunnels
+
+Repeat Steps 4–7 per project, giving each a distinct proxy port and tunnel name:
+
+```bash
+# Project A
+nodeproxy listen 8080   # if not already there by default
+nodeproxy add "*" http://localhost:3000 --port 8080
+nodeproxy tunnel setup --domain appA.yourdomain.com --port 8080 --name appA
+
+# Project B
+nodeproxy listen 9090
+nodeproxy add "*" http://localhost:4000 --port 9090
+nodeproxy tunnel setup --domain appB.yourdomain.com --port 9090 --name appB
+```
+
+Each tunnel needs its own `nodeproxy start --tunnel --name <name>` process, so run them in separate terminals (or as separate background services — see below).
+
+---
+
+## Keeping it running permanently (survive terminal close / reboot)
+
+`nodeproxy start --tunnel` runs in the foreground and stops if you close the terminal. For a server you want always-on, run it as a background service.
+
+**Linux (systemd)** — create `/etc/systemd/system/nodeproxy.service`:
+```ini
+[Unit]
+Description=nodeproxy with Cloudflare Tunnel
+After=network.target
+
+[Service]
+WorkingDirectory=/path/to/nodeproxy
+ExecStart=/usr/bin/env nodeproxy start --tunnel
+Restart=always
+User=YOUR_USERNAME
+
+[Install]
+WantedBy=multi-user.target
+```
+Then:
+```bash
+sudo systemctl enable --now nodeproxy
+sudo systemctl status nodeproxy
+```
+
+**macOS (launchd)** or a process manager like `pm2`/`forever` work equally well if you prefer those — the command to keep alive is just `nodeproxy start --tunnel`.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `502 Bad Gateway` from `curl localhost:8080` | Your local project isn't running, or is on a different port than configured | Start your project, or run `nodeproxy add "*" http://localhost:CORRECT_PORT` |
+| `404 Not Found (no matching route...)` | The `Host` header doesn't match any route and there's no `*` catch-all on that listener | Add a catch-all: `nodeproxy add "*" http://localhost:PORT --port PROXY_PORT` |
+| `tunnel setup` fails at install | Your platform isn't macOS/Linux auto-install, or missing `sudo`/Homebrew | Run the manual install command it printed, then re-run `tunnel setup` |
+| Browser doesn't open during login | Headless/remote machine (e.g. SSH session) | `cloudflared tunnel login` prints a URL to the terminal too — open it manually on any device and authorize |
+| `curl localhost:8080` works but the public domain doesn't | Tunnel isn't running, or DNS hasn't propagated yet | Confirm `nodeproxy start --tunnel` is actually running and check `dig yourdomain.com`; wait a minute and retry |
+| "Port X already has a listener" | You tried `nodeproxy listen` on a port that's already configured | Use `nodeproxy add ... --port X` directly instead of `listen` |
+| Changes to `nodeproxy.config.json` don't take effect | The proxy only reads the config at startup | Restart `nodeproxy start` (Ctrl+C, then run it again) |
+
+---
+
+## Command reference
+
+```
+nodeproxy start [--config <file>] [--tunnel] [--name <name>]
+                                          Start the proxy. --tunnel also starts
+                                          the Cloudflare tunnel alongside it.
+nodeproxy init  [--config <file>]        Just create the config file.
+nodeproxy add <host> <target> [--port <n>] [--config <file>]
+                                          Add/update a route on a listener.
+                                          <host> can be a real domain or "*".
+nodeproxy listen <port> [--config <file>]
+                                          Open a new, independent listener on
+                                          a new port.
+nodeproxy tunnel setup --domain <domain> [--name <name>] [--port <n>]
+                                          One-time: install cloudflared, log
+                                          in, create tunnel, route DNS.
+nodeproxy tunnel start [--name <name>]   Run just the tunnel (no local proxy).
+nodeproxy help                           Show all commands.
+```
+
+## Config file reference (`nodeproxy.config.json`)
+
+```json
+{
+  "logging": true,
+  "servers": [
+    {
+      "port": 8080,
+      "https": { "enabled": false, "key": "", "cert": "" },
+      "routes": [
+        { "host": "*", "targets": ["http://localhost:3000"], "staticDir": null }
+      ]
+    }
+  ]
+}
+```
+
+- `servers` — one entry per port the proxy listens on; each is fully independent.
+- `routes[].host` — a real hostname, or `"*"` as a catch-all for that listener.
+- `routes[].targets` — one or more backend URLs; 2+ enables automatic round-robin load balancing.
+- `routes[].staticDir` — set this and leave `targets` empty to serve static files from a folder instead of proxying.
+- `https` — only needed if you're terminating TLS yourself instead of using Cloudflare Tunnel (uncommon once you're using a tunnel, since Cloudflare's edge already handles TLS).
+
+## Project layout
+```
+bin/cli.js         CLI entrypoint
+lib/server.js      Core proxy engine (multi-listener routing, load balancing, static serving)
+lib/config.js      Config file loading/creation
+lib/cloudflare.js  Cloudflare Tunnel install/login/create/route/run helpers
+```
+
+## Known limitations
+- No automatic Let's Encrypt renewal for self-managed HTTPS (not needed with Cloudflare Tunnel)
+- One cert per listener if self-managing HTTPS (no per-domain SNI certs)
+- No rate limiting, caching, or WAF
+- Round-robin load balancing only
+- The Cloudflare browser-login click is inherently manual and one-time per machine — this is Cloudflare's security design, not a gap in this tool

package/README.md

@@ -1,100 +1,309 @@
 # nodeproxy
 
-A tiny, zero-dependency reverse proxy / web server for Node.js — think "a mini nginx" you can read in one sitting. No native code, no config-language DSL, just JSON.
+A tiny, zero-dependency reverse proxy for Node.js ("a mini nginx"), with:
+- **pm2 integration** — nodeproxy can start and keep your own project alive, so you don't have to manually run it first
+- **Cloudflare Tunnel integration** — expose your local machine on a real domain, no port forwarding, no static IP
 
-## Features
-- Host-based virtual routing (`api.example.com` → one backend, `app.example.com` → another)
-- Round-robin load balancing across multiple upstream targets per host
-- Wildcard `*` catch-all host for local dev
-- Static file fallback (serve a folder directly, no backend needed)
-- HTTPS support (bring your own cert/key)
-- Zero npm dependencies — pure Node.js `http`/`https` core modules
+This README is a complete walkthrough from a fresh clone to "my project is live at my domain, and it survives crashes/reboots." Follow it top to bottom the first time; after that, day-to-day usage is one command (Step 8).
 
-## One-command quick start
+---
+
+## What you'll end up with
+
+```
+Internet --https--> Cloudflare edge --tunnel--> cloudflared (your machine) --> nodeproxy (8080) --> pm2-managed project (3000)
+```
+
+pm2 keeps your project running (and restarts it if it crashes). nodeproxy forwards traffic to it. cloudflared carries traffic to your machine with no exposed ports. One `nodeproxy start --tunnel` brings all three layers up together.
+
+---
+
+## Prerequisites
+
+- **Node.js 16+** — check with `node -v`.
+- **npm** — used to auto-install `pm2` if it's missing (no manual install needed).
+- **(Only for a public domain) A domain on a Cloudflare account**, nameservers already pointed at Cloudflare. Free plan is fine.
+- **(Linux) `curl` and `sudo`** for cloudflared auto-install. **(macOS) Homebrew.**
+
+---
+
+
+
+## Step 1 — Register your project so nodeproxy starts it for you
+
+This is the part that removes the "start your project manually first" step. Point it at your project's start command:
 
 ```bash
-npx nodeproxy start
+nodeproxy app add myapp --cmd "npm start" --cwd /path/to/your/project
 ```
 
-That's it. On first run this:
-1. Creates `nodeproxy.config.json` in the current directory with sensible defaults
-2. Starts listening on port `8080`, forwarding everything to `http://localhost:3000`
+- `myapp` — any name you want, used for logs/status later
+- `--cmd` — whatever normally boots your project (`npm start`, `node server.js`, `yarn dev`, etc.)
+- `--cwd` — the folder that command should run from
 
-Edit `nodeproxy.config.json` and restart to change routing, or use the CLI helper below.
+This just registers it in `nodeproxy.config.json` — nothing starts yet. Repeat this for each project you have (see multi-project section below).
+
+**Already running your project some other way (Docker, a different process manager, always-on already)?** Skip this step entirely — nodeproxy will just proxy to whatever's listening on the port, same as before.
+
+## Step 2 — Point the proxy at it
+
+By default nodeproxy forwards port 8080 → `http://localhost:3000`. If your project runs on a different port:
+
+```bash
+nodeproxy add "*" http://localhost:YOUR_PORT
+```
+
+## Step 3 — First full local start
 
-### Install globally instead
 ```bash
-npm install -g nodeproxy
 nodeproxy start
 ```
-(publish this folder to npm first, or just `npm link` it locally — see below)
 
-### Run without installing (from this folder)
+Expected output — notice pm2 starting your app automatically, no manual `npm start` needed:
+```
+[nodeproxy] Using config: /path/to/nodeproxy.config.json
+[pm2] Starting "myapp" (npm start) in /path/to/your/project ...
+[PM2] Done.
+[nodeproxy] HTTP listening on port 8080
+```
+
+Verify:
 ```bash
-node bin/cli.js start
+curl http://localhost:8080
 ```
+You should see your project's actual response — even though you never typed `npm start` yourself.
 
-## Configuring routes
+Check on your app anytime with:
+```bash
+nodeproxy app list      # status of every registered app
+nodeproxy app logs myapp
+nodeproxy app stop myapp
+```
+
+Stop everything with `Ctrl+C` (nodeproxy) — your app keeps running under pm2 in the background even after that, exactly as pm2 is designed to. Use `nodeproxy app stop myapp` to actually stop it.
+
+## Step 4 — One-time Cloudflare login and tunnel creation
+
+Only needed if you want a real public domain (skip to Step 9 if you're only using this locally).
 
 ```bash
-# Route traffic for a host to a backend
-nodeproxy add example.com http://localhost:4000
+nodeproxy tunnel setup --domain app.yourdomain.com --port 8080
+```
+
+What happens, in order:
+1. **cloudflared install check** — auto-installed if missing (Homebrew on macOS, direct binary on Linux; manual instructions printed if your platform needs it).
+2. **Browser login** — opens once so you can click **Authorize** in your Cloudflare account. This is the *only* manual step in the whole setup; it's how Cloudflare's OAuth login works and cannot be scripted by any tool, including Cloudflare's own CLI.
+3. **Tunnel creation** — a named tunnel is created for you.
+4. **Ingress config** — written to `~/.cloudflared/<name>.yml`, mapping your domain to `http://localhost:8080`.
+5. **DNS routing** — the CNAME record is added to Cloudflare DNS automatically.
 
-# Add a second target on the same host for load balancing
-# (just edit the "targets" array in nodeproxy.config.json directly)
+Expected output:
+```
+[tunnel] Done! "app.yourdomain.com" now points at your local port 8080.
+[tunnel] From now on, just run:  nodeproxy start --tunnel --name app-yourdomain-com
 ```
 
-Example `nodeproxy.config.json`:
+## Step 5 — Check DNS propagated
 
-```json
-{
-  "port": 8080,
-  "https": { "enabled": false, "port": 8443, "key": "", "cert": "" },
-  "logging": true,
-  "routes": [
-    { "host": "app.example.com", "targets": ["http://localhost:4000", "http://localhost:4001"], "staticDir": null },
-    { "host": "static.example.com", "targets": [], "staticDir": "./public" },
-    { "host": "*", "targets": ["http://localhost:3000"], "staticDir": null }
-  ]
-}
+```bash
+dig app.yourdomain.com
 ```
+Should resolve to Cloudflare IPs within a minute or so.
 
-- `targets` with 2+ entries = automatic round-robin load balancing
-- `staticDir` set + empty `targets` = pure static file server for that host
-- `host: "*"` = catch-all, used when no other host matches (handy for local dev where you don't care about the `Host` header)
+## Step 6 — **Go live: the one command you'll use from now on**
 
-## HTTPS
+```bash
+nodeproxy start --tunnel
+```
 
-```json
-"https": {
-  "enabled": true,
-  "port": 8443,
-  "key": "/path/to/privkey.pem",
-  "cert": "/path/to/fullchain.pem"
-}
+This starts, in order: your registered app(s) via pm2 → the local proxy → the Cloudflare tunnel. Visit `https://app.yourdomain.com` — it should serve your project. TLS is handled by Cloudflare's edge automatically.
+
+## Step 7 — Verify from more than one place
+
+This matters — testing only from the machine running nodeproxy can hide DNS problems:
+
+```bash
+# From the same machine — hits the local proxy directly, bypassing Cloudflare entirely
+curl -H "Host: app.yourdomain.com" http://localhost:8080
+
+# From the same machine — the real public path, through Cloudflare
+curl https://app.yourdomain.com
+
+# From a phone on cellular data, or ask a friend to open it
+```
+
+If the first two work but a different device still can't reach it, jump straight to the "works on my machine, not on other devices" section below.
+
+---
+
+## "It works on my machine but not on another device/network"
+
+This is almost always **one specific cause**, not a bug in the proxy: the DNS record Cloudflare created for your tunnel is set to **"DNS only" (grey cloud)** instead of **"Proxied" (orange cloud)**. Tunnel hostnames (`*.cfargotunnel.com`) only resolve *publicly* when proxied — when they're not, they can fail to resolve for everyone except a device that happens to have cached/local name resolution, which is exactly what makes it look like "works for me, not for anyone else."
+
+Diagnose it directly instead of guessing:
+```bash
+nodeproxy tunnel doctor --domain app.yourdomain.com
 ```
 
-Get free certs from Let's Encrypt (e.g. via `certbot`) and point `key`/`cert` at the files. HTTP and HTTPS run side-by-side.
+This checks whether your domain actually resolves to a public IP address (not just whether a DNS record exists) and tells you exactly what's wrong. Example output when it's broken:
+```
+✗ Does NOT resolve to an IP address publicly — ENOTFOUND. This is almost always
+  because the DNS record is set to "DNS only" (grey cloud) in the Cloudflare
+  dashboard instead of "Proxied" (orange cloud). Fix: Cloudflare dashboard →
+  DNS → click the cloud icon next to this record so it turns orange, then
+  wait ~1 minute and retry.
+```
 
-## Local install / publish
+**The fix:** log into the Cloudflare dashboard → your domain → DNS → find the record for your subdomain → click the cloud icon next to it so it turns **orange** (Proxied) → wait about a minute → retest.
+
+Other, less common causes if the doctor says DNS is fine but it still doesn't work elsewhere:
+- `nodeproxy start --tunnel` isn't actually running at that moment — the tunnel only carries traffic while that process is alive.
+- You're testing from a network that blocks outbound HTTPS or has its own DNS overrides (rare, mostly corporate networks).
+- You created more than one tunnel for the same domain by accident — run `cloudflared tunnel list` and delete stale ones.
+
+---
+
+## Running more than one project
+
+Each project needs: its own pm2 app registration, its own proxy port, and (if public) its own tunnel.
 
 ```bash
-npm link          # makes the `nodeproxy` command available globally on this machine
-# or
-npm publish        # to publish it as a real npm package
+# Project A — port 8080
+nodeproxy app add appA --cmd "npm start" --cwd /path/to/project-a
+nodeproxy add "*" http://localhost:3000        # project A's actual listen port
+nodeproxy tunnel setup --domain appA.yourdomain.com --port 8080 --name appA
+
+# Project B — new port 9090
+nodeproxy app add appB --cmd "npm start" --cwd /path/to/project-b
+nodeproxy listen 9090
+nodeproxy add "*" http://localhost:4000 --port 9090   # project B's actual listen port
+nodeproxy tunnel setup --domain appB.yourdomain.com --port 9090 --name appB
 ```
 
-## Project layout
+Run each tunnel in its own terminal (or background service — see below):
+```bash
+nodeproxy start --tunnel --name appA
+nodeproxy start --tunnel --name appB
+```
+
+---
+
+## Making it survive a reboot / terminal close
+
+`nodeproxy start --tunnel` runs in the foreground. Your pm2-managed app itself will actually survive that terminal closing (pm2 daemonizes it), but the proxy and tunnel won't unless you run one of these:
+
+**pm2 boot persistence** (for your app surviving a full machine reboot):
+```bash
+pm2 startup     # prints a sudo command — copy/run it, once
+pm2 save        # nodeproxy already runs this for you after "start"
+```
+
+**systemd (Linux)** for the proxy+tunnel — create `/etc/systemd/system/nodeproxy.service`:
+```ini
+[Unit]
+Description=nodeproxy with Cloudflare Tunnel
+After=network.target
+
+[Service]
+WorkingDirectory=/path/to/nodeproxy
+ExecStart=/usr/bin/env nodeproxy start --tunnel
+Restart=always
+User=YOUR_USERNAME
+
+[Install]
+WantedBy=multi-user.target
 ```
-bin/cli.js      CLI entrypoint (start / init / add / help)
-lib/server.js   Core proxy engine (routing, load balancing, static serving)
-lib/config.js   Config file loading/creation
+```bash
+sudo systemctl enable --now nodeproxy
 ```
 
-## Limitations (intentional — this is a learning-scale project, not production nginx)
-- No automatic Let's Encrypt / ACME renewal — bring your own certs
-- No SNI-based multi-cert HTTPS (one cert for all HTTPS hosts)
-- No rate limiting, caching, or WAF features
-- Round-robin only (no least-connections/weighted balancing)
+macOS: use `launchd`, or just keep `nodeproxy start --tunnel` itself under pm2 too (`pm2 start "nodeproxy start --tunnel" --name gateway`).
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `502 Bad Gateway` locally | Your app isn't running, wrong port, or pm2 failed to start it | `nodeproxy app list` to check status; `nodeproxy app logs myapp` for errors |
+| `404 Not Found (no matching route...)` | No `*` catch-all or matching host on that listener | `nodeproxy add "*" http://localhost:PORT --port PROXY_PORT` |
+| pm2 app shows `errored` in `app list` | The `--cmd`/`--cwd` you registered doesn't actually start the app | Test the exact command manually in that folder first, then re-run `nodeproxy app add` |
+| Works locally, not on another device | DNS record not proxied (grey cloud) | `nodeproxy tunnel doctor --domain yourdomain.com` — see dedicated section above |
+| `tunnel setup` fails at install | Platform isn't auto-installable, or missing sudo/Homebrew | Run the manual command it prints, then retry |
+| Browser doesn't open during login | Headless/SSH session | `cloudflared tunnel login` also prints a URL — open it on any device |
+| Config changes don't take effect | Config is only read at startup | Restart `nodeproxy start` |
+
+---
+
+## Command reference
+
+```
+nodeproxy start [--config <file>] [--tunnel] [--name <name>]
+                                          Starts registered apps (pm2), then
+                                          the proxy, then the tunnel if
+                                          --tunnel is given. The one command.
+nodeproxy init  [--config <file>]        Just create the config file.
+nodeproxy add <host> <target> [--port <n>] [--config <file>]
+                                          Add/update a proxy route.
+nodeproxy listen <port> [--config <file>]
+                                          Open a new independent listener.
+
+nodeproxy app add <name> --cmd "<cmd>" [--cwd <dir>]
+                                          Register a project to be started
+                                          and kept alive via pm2.
+nodeproxy app list                       Show registered apps + live status.
+nodeproxy app logs <name>                Tail an app's logs.
+nodeproxy app stop <name>                Stop an app.
+
+nodeproxy tunnel setup --domain <domain> [--name <name>] [--port <n>]
+                                          One-time: install, log in, create
+                                          tunnel, route DNS.
+nodeproxy tunnel start [--name <name>]   Run just the tunnel.
+nodeproxy tunnel doctor --domain <domain>
+                                          Diagnose public-access DNS issues.
+
+nodeproxy help                           Show all commands.
+```
+
+## Config file reference (`nodeproxy.config.json`)
+
+```json
+{
+  "logging": true,
+  "apps": [
+    { "name": "myapp", "cmd": "npm start", "cwd": "/path/to/project" }
+  ],
+  "servers": [
+    {
+      "port": 8080,
+      "https": { "enabled": false, "key": "", "cert": "" },
+      "routes": [
+        { "host": "*", "targets": ["http://localhost:3000"], "staticDir": null }
+      ]
+    }
+  ]
+}
+```
+
+- `apps` — projects nodeproxy starts/keeps alive via pm2. Optional.
+- `servers` — one entry per proxy port; each fully independent.
+- `routes[].host` — real hostname or `"*"` catch-all.
+- `routes[].targets` — 2+ enables round-robin load balancing.
+- `routes[].staticDir` — serve static files instead of proxying.
+- `https` — only for self-managed TLS; not needed with Cloudflare Tunnel.
+
+## Project layout
+```
+bin/cli.js         CLI entrypoint
+lib/server.js      Core proxy engine
+lib/config.js      Config loading/creation
+lib/cloudflare.js  Cloudflare Tunnel install/login/create/route/run/diagnose
+lib/pm2.js         pm2 install/start/stop/list helpers
+```
 
-These are all reasonable next steps if you want to extend it.
+## Known limitations
+- No automatic Let's Encrypt renewal for self-managed HTTPS (not needed with Cloudflare Tunnel)
+- Round-robin load balancing only
+- The Cloudflare browser-login click is inherently manual and one-time per machine — Cloudflare's security design, not a gap here
+- `tunnel doctor` diagnoses the most common public-access failure (unproxied DNS); it isn't an exhaustive network debugger
+