locadot 1.5.7 → 1.6.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## Unreleased
+
+The version in `package.json` is still 1.5.7. The owner decides the bump. **2.0.0** is suggested because of the
+breaking items below.
+
+### Breaking
+- The proxy binds to `127.0.0.1` and `::1` only. Set `LOCADOT_BIND=0.0.0.0` for the old LAN-exposed behaviour.
+- The registry format is now v2 (`{version, hosts:{host:{target,…}}}`). The old `{host: port}` files are migrated
+  automatically, but older locadot versions can't read the new format.
+- `-h` means `--host` on every command. Help is `--help` only.
+- Bare `localhost` is reserved for the dashboard and can't be mapped.
+
+### Added
+- A control panel at `https://localhost` with a dark theme. You can add, edit and remove mappings, toggle CA trust and start-at-boot, see root/admin and privileged-port status,
+  tail and clear logs, and stop the proxy. (FEAT-05)
+- A token-protected JSON API for scripts and AI agents (`POST/PUT/DELETE /api/hosts`, `/api/startup`, `/api/trust`, `/api/logs`, `/api/proxy/stop`),
+  and `locadot token` to print the token. (FEAT-05)
+- Generic targets: `--target` takes a port, `host:port` or any http(s) URL (`google.localhost` → `https://google.com`).
+  `--insecure` accepts self-signed upstreams. Redirects and cookies are rewritten back to the `.localhost` name. (ENH-08)
+- A dashboard at `http(s)://localhost` shows each domain, its target, health, hits, errors and latency, with `/api/status`,
+  `/api/hosts` and `/healthz`. (ENH-09)
+- New commands and options: `status [--json]`, `doctor [--host]`, `open [host]`, `start`, `trust`, `untrust`,
+  `logs -n/--no-follow`, `list --json`, the `rm`/`ls` aliases, `--no-start`, and a full `path` listing. (ENH-02, ENH-04, ENH-10, FEAT-01, FEAT-02)
+- A trusted local CA with one certificate per domain served by SNI, pre-generated when a mapping loads. (BUG-02)
+- Environment variables `LOCADOT_HOME`, `LOCADOT_HTTP_PORT`, `LOCADOT_HTTPS_PORT`, `LOCADOT_BIND` and `LOCADOT_LOG_LEVEL`.
+- Test suite (`pnpm test`) and a `prepublishOnly` build.
+
+### Fixed
+- Upstream `Connection`/`Upgrade` headers are no longer forwarded. Apache sites proxied through locadot kept dropping the connection and lost assets. (BUG-12)
+- `stop`, `restart` and `kill` now actually stop the proxy. (BUG-01)
+- A failed start is reported with the log tail and exits 1. (BUG-07)
+- `update` accepts http targets and `add` accepts https ones. (BUG-03)
+- Ports are validated. (BUG-06)
+- An unknown host passed to `update` or `remove` exits 1. (BUG-10)
+- An unmapped host no longer causes a double response or a crash. (BUG-04)
+- The 502 page escapes the Host header. (BUG-05)
+- `startup:*` is consistent, and a proxy started at boot is visible to the CLI. (BUG-08)
+- Logs are kept across a restart. (BUG-09)
+- An empty lock file is no longer read as a running proxy. (BUG-11)
+- Every command exits non-zero on failure. (ENH-01)
+- Registry writes are atomic and locked, and a corrupt registry is backed up instead of wiped. (ENH-03)
+- The log is rotated above 5 MB. (ENH-05)
+- The proxy no longer loses its stderr when the CLI exits, and http-proxy's deprecation noise is silenced. (ENH-11)

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Avinash Kumar
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Avinash Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,138 +1,184 @@
-# locadot 🔐
-
-## ✨ Features
-
-- ✅ Automatically generates trusted local SSL certificates
-- 🔁 Reverse proxies `localhost:PORT ` → `https://your.custom.domain.localhost`
-- 🖥️ Works on Windows, macOS, and Linux
-- 🛠️ OS-specific guidance for host setup
-- ⚠️ Warns and exits if domain isn’t correctly mapped to a local IP
-- ❌ Only supports proxying to localhost ports – external IPs are not allowed for security
-
----
-
-## 🚀 Usage
-
-```bash
-npx locadot add --host dev.localhost --port 3350
-```
-
----
-
-## 📦 Commands
-
-##### ▶️ Default (Run Proxy)
-
-###### Starts a reverse proxy to the specified localhost port.
-
-```bash
-npx locadot add --host <custom.localhost> --port <localhost-port>
-```
-
-##### 🧾 Update existing host
-
-###### Update domains currently registered with locadot.
-
-```bash
-npx locadot update --host <your.localhost> --port <localhost-port>
-```
-
-
-##### 🧾 Remove existing host
-
-###### Remove domains currently registered with locadot.
-
-```bash
-npx locadot remove --host <your.localhost>
-```
-
-##### 🧾 View Registered Hosts
-
-###### Displays all domains currently registered with locadot.
-
-```bash
-npx locadot host
-```
-
-##### 📺 Watch Logs
-
-###### Continuously watches and outputs proxy logs in real time.
-
-```bash
-npx locadot watch:logs
-```
-
-##### 🧹 Clear Logs
-
-###### Clears all saved logs.
-
-```bash
-npx locadot clear:logs
-```
-
-##### 🧹 Clear Hosts
-
-###### Clears all existing hosts.
-
-```bash
-npx locadot clear:hosts
-```
-
-##### 🧹 Show Config Path
-
-###### Print the path of config files used.
-
-```bash
-npx locadot path
-```
-
-##### 🧹 Show Logs Path
-
-###### Print the path of logged files used.
-
-```bash
-npx locadot path:logs
-```
-
-
-##### 🧹 Show Hosts Path
-
-###### Print the path of hosts files used.
-
-```bash
-npx locadot path:hosts
-```
-
-##### 🔄 Restart Proxy
-
-###### Restarts the proxy server and reloads configuration.
-
-```bash
-npx locadot restart
-```
-
-##### 🛑 Stop All
-
-###### Stops all running locadot hosts and shuts down the proxy server.
-
-```bash
-npx locadot stop
-```
-
-##### 🛑 Kill
-
-###### Stops all running locadot hosts, clear logs and host mapping and shuts down the proxy server.
-
-```bash
-npx locadot kill
-```
-
----
-
-### 🙌 Contributing:
-
-Pull requests are welcome! Feel free to open issues for bugs or feature requests. Contributions help improve locadot for everyone, so don't hesitate to get involved.
-
----
-
-##### Made with ❤️ to make secure local development simple.
+# locadot 🔐
+
+HTTPS custom domains for local development. Point `https://app.localhost` at your dev server on port 3000, or
+`https://google.localhost` at any upstream URL, and see every mapping on a dashboard at `https://localhost`.
+
+## ✨ Features
+
+- ✅ **Trusted HTTPS for every domain.** locadot creates one local CA and issues a certificate per domain, served by SNI.
+  Run `locadot trust` once to add the CA to your system and browsers.
+- 🔁 **Any destination.** A local port (`--port 3000`), a host and port (`--target 192.168.1.5:8080`), or any URL
+  (`--target https://google.com`). Redirects and cookies are rewritten so the browser stays on the `.localhost` name.
+- 📋 **Control panel at `https://localhost`.** Add, edit and remove mappings, see health and traffic, and toggle CA trust and
+  start-at-boot. Includes a token-protected JSON API, so scripts and AI agents can do everything the page does.
+- 🔌 **WebSockets** are proxied too, so HMR and dev-server live reload work.
+- 🩺 **`status` and `doctor`** show why a domain isn't working: port conflicts, permissions, CA trust, a target that isn't answering.
+- 🛡️ **Local by default.** The proxy binds to `127.0.0.1` / `::1` only. Domains must end in `.localhost`, which browsers
+  resolve to your machine with no hosts-file edits.
+- 🖥️ Works on Linux, macOS and Windows. Optionally starts at boot or logon.
+
+---
+
+## 🚀 Quick start
+
+```bash
+npx locadot trust                                   # once: trust the locadot CA (asks for your password)
+npx locadot add --host app.localhost --port 3000    # https://app.localhost → http://localhost:3000
+npx locadot add --host google.localhost --target https://google.com
+npx locadot open                                    # opens the dashboard at https://localhost
+```
+
+> **Linux:** ports 80/443 need root. Either run locadot with `sudo`, or allow unprivileged binding once:
+> `sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80` (persist it in `/etc/sysctl.d/`). `locadot doctor` checks this for you.
+
+---
+
+## 📦 Commands
+
+### Mappings
+
+| Command | What it does |
+| --- | --- |
+| `locadot add --host <name>.localhost --port <port>` | Map a domain to `http://localhost:<port>`. Starts the proxy if it isn't running. |
+| `locadot add --host <name>.localhost --target <url>` | Map a domain to any upstream: `3000`, `127.0.0.1:8080`, `http://10.0.0.5:8080/app`, `https://google.com`. |
+| `locadot update --host <name>.localhost --port/--target …` | Change the destination of an existing domain. |
+| `locadot remove --host <name>.localhost` (`rm`) | Remove a domain. |
+| `locadot list` (`ls`, `host`) `[--json]` | Show all mappings. |
+| `locadot clear:hosts` | Remove all mappings. |
+| `locadot open [host]` | Open a domain, or the dashboard when no host is given, in your browser. |
+
+Options for `add` / `update`:
+
+| Option | Meaning |
+| --- | --- |
+| `-p, --port <port>` | Shorthand for `--target http://localhost:<port>`. |
+| `-t, --target <url>` | Any http(s) upstream. A bare `host:port` means `http://host:port`. |
+| `-k, --insecure` | Don't verify the TLS certificate of an `https` target (self-signed upstreams). |
+| `--no-start` | Save the mapping without starting the proxy. |
+
+### Proxy
+
+| Command | What it does |
+| --- | --- |
+| `locadot start` | Start the central proxy. Fails loudly with the reason if it can't bind its ports. |
+| `locadot stop` | Stop the proxy. Mappings and logs are kept. |
+| `locadot restart` | Stop, then start. |
+| `locadot kill` | Stop the proxy, remove all mappings and clear the logs. |
+| `locadot status [--json]` | Is it running, its PID, ports, number of hosts, CA trust, start-at-boot, dashboard URL. |
+| `locadot doctor [--host h]` | Check the proxy, ports, permissions, CA trust, the registry and every target. Exits 1 if anything fails. |
+
+### Certificates
+
+| Command | What it does |
+| --- | --- |
+| `locadot trust` | Add the locadot CA to the system trust store, plus the Chrome/Firefox NSS stores on Linux when `certutil` is installed. |
+| `locadot untrust` | Remove it again. |
+
+### Logs, files and startup
+
+| Command | What it does |
+| --- | --- |
+| `locadot logs [-n 50] [--no-follow]` | Print recent proxy logs and follow new ones. `watch:logs` is an alias. |
+| `locadot clear:logs` | Clear the log file. |
+| `locadot path` | Show every file locadot uses. `path:logs` and `path:hosts` print a single path. |
+| `locadot token` | Print the dashboard API token, for scripts and AI agents. |
+| `locadot startup:enable` / `startup:disable` / `startup:status` | Start the proxy at boot (Linux cron, macOS LaunchAgent) or logon (Windows scheduled task). |
+
+---
+
+## 📋 Dashboard & control panel
+
+Open `https://localhost` or `http://localhost` (or run `locadot open`). Requests for bare `localhost` / `127.0.0.1` / `::1`
+are answered by locadot itself, not proxied. The page is a dark control panel:
+
+- **System:** whether the proxy runs as root/admin, whether ports below 1024 can be bound (with the Linux sysctl fix when they
+  can't), CA trust with an on/off toggle, start-at-boot with an on/off toggle, ports, bind addresses and state dir. It also has a **Stop proxy** button.
+- **Proxies:** add a mapping (host + port / host:port / URL, and an optional "insecure TLS" box), edit a target inline, or remove one. The table shows
+  each source → destination with up/down, status, latency, hits, errors, last access and average ms. It refreshes every 5 s.
+- **Logs:** a live tail with refresh and clear.
+- **CLI / API snippets** you can copy.
+
+Trust and start-at-boot may need elevation. locadot asks the OS for it (polkit on Linux, the password dialog on macOS, UAC on Windows).
+If that isn't possible, for example on a headless Linux box, the panel shows the exact command to run instead: `sudo locadot trust`,
+`locadot startup:enable`, and so on.
+
+### JSON API (for scripts and AI agents)
+
+Everything the page does is a plain JSON API on the dashboard origin. The read routes are open to local callers. Every mutating route needs the
+`X-Locadot-Token` header. Get the token with `locadot token`. It lives in `<state dir>/.locadot-token` (mode 0600) and is regenerated
+each time the proxy starts.
+
+| Method & path | Body | Does |
+| --- | --- | --- |
+| `GET /api/status` | | Proxy info, uptime, host count, and `system` (`platform`, `isRoot`, `canBindPrivileged`, `unprivilegedPortStart`, `caTrusted`, `startup`, `stateDir`). |
+| `GET /api/hosts` | | Every mapping with urls, probe (`up`, `status`, `ms`) and stats. |
+| `GET /api/logs?lines=200` | | `{ lines: [...] }` |
+| `POST /api/hosts` | `{ "host": "app.localhost", "target": "3000", "insecure": false }` | Add a mapping (201; 409 if it exists). |
+| `PUT /api/hosts/:host` | `{ "target": "https://example.com", "insecure": false }` | Change a mapping (404 if unknown). |
+| `DELETE /api/hosts/:host` | | Remove a mapping. |
+| `POST /api/startup` | `{ "enabled": true }` | Start at boot on/off. |
+| `POST /api/trust` | `{ "trusted": true }` | Trust or untrust the CA. |
+| `POST /api/logs/clear` | | Clear the log. |
+| `POST /api/proxy/stop` | | Stop the proxy. Use `locadot start` to bring it back. |
+
+Errors are `{ "error": "...", "hint": "<CLI command>" }` with a 4xx/5xx status.
+
+```bash
+TOKEN=$(locadot token)
+curl -X POST http://localhost/api/hosts -H "X-Locadot-Token: $TOKEN" \
+  -H 'Content-Type: application/json' -d '{"host":"app.localhost","target":"3000"}'
+curl -X DELETE http://localhost/api/hosts/app.localhost -H "X-Locadot-Token: $TOKEN"
+```
+
+**Why a token:** any website you visit can make your browser send requests to `localhost`. Mutating routes therefore reject requests that:
+- lack the token, which other sites can't read;
+- carry a foreign `Origin`, including your own `*.localhost` apps;
+- are marked `Sec-Fetch-Site: cross-site`;
+- have a non-JSON body.
+
+The dashboard is served only for the bare `localhost` host names, which also blocks DNS rebinding.
+
+---
+
+## ⚙️ Configuration
+
+All optional, via environment variables. Set them for the CLI; the proxy it starts inherits them.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `LOCADOT_HOME` | OS app-data dir (`~/.config/locadot` on Linux) | Where the registry, logs, lock file and certs live. |
+| `LOCADOT_HTTP_PORT` | `80` | HTTP port of the proxy. |
+| `LOCADOT_HTTPS_PORT` | `443` | HTTPS port of the proxy. |
+| `LOCADOT_BIND` | `127.0.0.1,::1` | Comma-separated addresses to listen on. Use `0.0.0.0` to expose your mappings to your LAN (not recommended). |
+| `LOCADOT_LOG_LEVEL` | `info` | winston log level (`debug` logs every WebSocket upgrade). |
+
+With non-standard ports, URLs include the port: `https://app.localhost:8443`.
+
+---
+
+## ⚠️ Notes on remote targets
+
+`--target https://google.com` proxies the upstream with `Host` rewritten to the upstream's name.
+`Location` redirects pointing at the upstream's own host, and cookie domains, are rewritten to the `.localhost` name. A
+redirect to a *different* domain (for example `google.com` → `www.google.com`) takes the browser there directly. To stay on
+locadot, map the final host instead (`--target https://www.google.com`). Some sites refuse to be framed or proxied; that's up to
+the site.
+
+---
+
+## 🛠️ Contributing
+
+The code guide, architecture, and the tracker of bugs, enhancements, features and tech debt live in
+[`tasks/README.md`](tasks/README.md). Start there.
+
+```bash
+pnpm install
+pnpm build     # the CLI spawns dist/core.js, so build before trying proxy changes
+pnpm test      # unit + end-to-end tests; runs on spare ports, never touches 80/443
+```
+
+Pull requests are welcome.
+
+---
+
+##### Made with ❤️ to make secure local development simple.

package/dist/constants/index.js

@@ -6,17 +6,37 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const appdata_path_1 = __importDefault(require("appdata-path"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
-const PACKAGE_PATH = (0, appdata_path_1.default)("locadot");
-const LOGS = path_1.default.join(PACKAGE_PATH, ".locadot.log");
-const LOCK_FILE = path_1.default.join(PACKAGE_PATH, ".locadot.lock");
-const REGISTRY_FILE = path_1.default.join(PACKAGE_PATH, ".locadot-registry.json");
+// LOCADOT_HOME / LOCADOT_*_PORT let tests and hosts where 80/443 are taken run an isolated instance.
+const PACKAGE_PATH = process.env.LOCADOT_HOME
+    ? path_1.default.resolve(process.env.LOCADOT_HOME)
+    : (0, appdata_path_1.default)("locadot");
+const envPort = (name, fallback) => {
+    const value = Number(process.env[name]);
+    return Number.isInteger(value) && value > 0 && value < 65536 ? value : fallback;
+};
 class Constants {
 }
 Constants.paths = {
-    LOCK_FILE: LOCK_FILE,
-    REGISTRY_FILE: REGISTRY_FILE,
-    LOGS: LOGS,
+    HOME: PACKAGE_PATH,
+    LOCK_FILE: path_1.default.join(PACKAGE_PATH, ".locadot.lock"),
+    REGISTRY_FILE: path_1.default.join(PACKAGE_PATH, ".locadot-registry.json"),
+    REGISTRY_LOCK: path_1.default.join(PACKAGE_PATH, ".locadot-registry.lock"),
+    LOGS: path_1.default.join(PACKAGE_PATH, ".locadot.log"),
+    CERT_DIR: path_1.default.join(PACKAGE_PATH, "certs"),
+    // Secret for the dashboard's mutating API; rotated on every proxy start.
+    API_TOKEN: path_1.default.join(PACKAGE_PATH, ".locadot-token"),
+};
+Constants.server = {
+    httpPort: envPort("LOCADOT_HTTP_PORT", 80),
+    httpsPort: envPort("LOCADOT_HTTPS_PORT", 443),
+    // Loopback only unless the user opts in; see tasks/enhancements ENH-06.
+    bind: (process.env.LOCADOT_BIND || "127.0.0.1,::1")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean),
 };
+// Hosts that serve the dashboard instead of being proxied.
+Constants.dashboardHosts = ["localhost", "127.0.0.1", "::1"];
 Constants.platform = () => {
     const currentPlatform = os_1.default.platform();
     if (currentPlatform === "win32") {
@@ -33,10 +53,10 @@ Constants.platform = () => {
     }
 };
 Constants.proxyInfo = {
-    invalidHost: "❌ Invalid domain. Please use a valid localhost domain like dev.localhost, localhost, test.localhost, etc.",
-    hostExist: "❌ Domain already in use. Please choose another domain or stop the existing instance.",
-    hostNotFound: "❌ Domain not found. Please choose another domain or stop the existing instance.",
+    invalidHost: "❌ Invalid domain. Use a subdomain of localhost like dev.localhost or google.localhost (bare `localhost` is reserved for the dashboard).",
+    hostExist: "❌ Domain already mapped. Use `locadot update` to change its target.",
+    hostNotFound: "❌ Domain not found. Run `locadot list` to see mapped domains.",
     proxyClose: "☑️ Successfully stopped all locadot instances.",
-    softClose: "☑️ Successfully stopped central proxy..",
+    softClose: "☑️ Successfully stopped central proxy.",
 };
 exports.default = Constants;

package/dist/constants/template.js

@@ -1,67 +1,64 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.proxyNotFound = void 0;
-const proxyNotFound = (host) => `
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Proxy Error</title>
-  <style>
-    body {
-      background-color: #121212;
-      color: #f8d7da;
-      font-family: 'Segoe UI', sans-serif;
-      margin: 0;
-      padding: 20px;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      min-height: 90vh;
-    }
-
-    .error-box {
-      background-color: #1e1e1e;
-      border: 1px solid #d9534f;
-      padding: 24px;
-      border-radius: 8px;
-      max-width: 600px;
-      width: 100%;
-      box-shadow: 0 4px 15px rgba(0, 0, 0, 0.7);
-    }
-
-    .error-box code {
-      background: #2e2e2e;
-      color: #ffd5d5;
-      padding: 2px 6px;
-      border-radius: 4px;
-      font-family: monospace;
-    }
-
-    .error-box a {
-      color: #61dafb;
-      text-decoration: none;
-      font-weight: bold;
-    }
-
-    .error-box a:hover {
-      text-decoration: underline;
-    }
-  </style>
-</head>
-<body>
-  <div class="error-box">
-    <strong style="color: #ff6b6b;">Connection failed:</strong>
-    Proxy does not exist for 
-    <code>${host}</code>.<br/><br/>
-    Please use 
-    <code>npx locadot --host ${host} --port PORT</code><br/><br/>
-    <a href="https://github.com/avinashid/locadot#readme" target="_blank">
-      📘 View on GitHub
-    </a>
-  </div>
-</body>
-</html>
+exports.upstreamDown = exports.proxyNotFound = void 0;
+const escape_1 = require("../dashboard/escape");
+const page = (title, body, dashboardUrl) => `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${(0, escape_1.escapeHtml)(title)}</title>
+  <style>
+    body {
+      background-color: #121212;
+      color: #f8d7da;
+      font-family: 'Segoe UI', system-ui, sans-serif;
+      margin: 0;
+      padding: 20px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 90vh;
+    }
+    .error-box {
+      background-color: #1e1e1e;
+      border: 1px solid #d9534f;
+      padding: 24px;
+      border-radius: 8px;
+      max-width: 640px;
+      width: 100%;
+      box-shadow: 0 4px 15px rgba(0, 0, 0, 0.7);
+      line-height: 1.6;
+    }
+    .error-box code {
+      background: #2e2e2e;
+      color: #ffd5d5;
+      padding: 2px 6px;
+      border-radius: 4px;
+      font-family: monospace;
+    }
+    .error-box a { color: #61dafb; text-decoration: none; font-weight: bold; }
+    .error-box a:hover { text-decoration: underline; }
+  </style>
+</head>
+<body>
+  <div class="error-box">
+    ${body}
+    <br/><br/>
+    <a href="${(0, escape_1.escapeHtml)(dashboardUrl)}">📋 Open the locadot dashboard</a> ·
+    <a href="https://github.com/avinashid/locadot#readme" target="_blank" rel="noopener noreferrer">📘 Docs</a>
+  </div>
+</body>
+</html>
 `;
+const proxyNotFound = (host, dashboardUrl) => page("locadot: host not mapped", `<strong style="color: #ff6b6b;">Not mapped:</strong>
+    no locadot mapping exists for <code>${(0, escape_1.escapeHtml)(host)}</code>.<br/><br/>
+    Add one with<br/>
+    <code>npx locadot add --host ${(0, escape_1.escapeHtml)(host)} --port PORT</code><br/>
+    or<br/>
+    <code>npx locadot add --host ${(0, escape_1.escapeHtml)(host)} --target https://example.com</code>`, dashboardUrl);
 exports.proxyNotFound = proxyNotFound;
+const upstreamDown = (host, target, reason, dashboardUrl) => page("locadot: upstream unreachable", `<strong style="color: #ff6b6b;">Upstream unreachable:</strong>
+    <code>${(0, escape_1.escapeHtml)(host)}</code> → <code>${(0, escape_1.escapeHtml)(target)}</code><br/><br/>
+    ${(0, escape_1.escapeHtml)(reason)}. Is the app running?`, dashboardUrl);
+exports.upstreamDown = upstreamDown;

package/dist/core.js

@@ -1,13 +1,14 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const proxy_1 = __importDefault(require("./proxy"));
-const logger_1 = __importDefault(require("./utils/logger"));
-async function run() {
-    logger_1.default.info(`🔄 Starting central proxy.`);
-    await proxy_1.default.startCentralProxy();
-    logger_1.default.info("☑️ Central proxy started.");
+// Entry point of the detached proxy process. `--home <dir>` lets boot-time
+// launchers (root cron, SYSTEM task) use the invoking user's state dir.
+const homeIndex = process.argv.indexOf("--home");
+if (homeIndex > -1 && process.argv[homeIndex + 1]) {
+    process.env.LOCADOT_HOME = process.argv[homeIndex + 1];
 }
-run();
+process.env.LOCADOT_ROLE = "proxy";
+// Required after the env is set: constants read it at load time.
+const { startCentralProxy } = require("./server");
+startCentralProxy().catch((error) => {
+    console.error("❌ Failed to start central proxy", error);
+    process.exit(1);
+});