locadot 1.6.0-beta.3 → 1.6.0-beta.5

package/CHANGELOG.md

@@ -2,9 +2,12 @@
 
 ## Unreleased
 
-The version in `package.json` is 1.6.0-beta.3 (published under the `beta` tag). The owner decides the bump. **2.0.0** is suggested because of the
+The version in `package.json` is 1.6.0-beta.5 (published under the `beta` tag). The owner decides the bump. **2.0.0** is suggested because of the
 breaking items below.
 
+### Changed
+- Internal restructure into `cli/commands/*`, `server/*` and `proxy/*` modules. There are no behaviour changes; see `tasks/README.md`.
+
 ### 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
@@ -13,7 +16,10 @@ breaking items below.
 - Bare `localhost` is reserved for the dashboard and can't be mapped.
 
 ### Added
-- `--cors` per mapping (CLI, API and dashboard). `Origin`/`Referer` are sent as the target's own origin, CORS preflights are answered locally, and any origin may call the domain with credentials. (ENH-12)
+- `locadot tunnel --host <h>` (with `--off`, and `tunnel:install`) shares a mapping on a public `https://*.trycloudflare.com` URL through a Cloudflare quick tunnel, with no account needed. `cloudflared` is downloaded on demand into the state dir. The dashboard has a Cloudflare Tunnel card, a Public URL column and Share/Unshare per row. The API accepts `PUT /api/hosts/:host {"tunnel": true}` and has `POST /api/cloudflared/install`. The `--cors` pass-through is disabled for tunnel visitors.
+- The dashboard is redesigned: a neutral palette that follows the system light/dark theme, a responsive grid and a single Traffic column.
+- `locadot start --port <http> --https-port <https>` (also on `restart`) runs the proxy on other ports than 80/443. The choice is saved in the state dir, so `add`, `status`, `open` and start-at-boot keep using it; `--port 80 --https-port 443` goes back. Running it while the proxy is up on other ports restarts it on the new ones.
+- `--cors` per mapping (CLI, API and dashboard). `Origin`/`Referer` are sent as the target's own origin, CORS preflights are answered locally, and any origin may call the domain with credentials. Absolute URLs of other mapped domains in text responses are rewritten to their `.localhost` names, and a mapped caller is sent as its real origin, so a site plus its API both work locally. Pages also get a small script that sends calls to any other origin through the page's own origin (`/__locadot/x/…`), so no mapping per API or third-party domain is needed. (ENH-12, BUG-15)
 - 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`),

package/README.md

@@ -29,7 +29,8 @@ npx locadot open                                    # opens the dashboard at htt
 ```
 
 > **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.
+> `sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80` (persist it in `/etc/sysctl.d/`). Or use other ports:
+> `locadot start --port 8080 --https-port 8443` (URLs then include the port). `locadot doctor` checks this for you.
 
 ---
 
@@ -54,20 +55,34 @@ Options for `add` / `update`:
 | `-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). |
-| `--cors` / `--no-cors` | Bypass CORS for this domain. The upstream gets `Origin`/`Referer` as its own origin, preflights are answered locally, any origin may read responses (with credentials), and cookies become `SameSite=None` over HTTPS. URLs hard-coded in pages still go to the real domain. |
+| `--cors` / `--no-cors` | Bypass CORS for this domain. The upstream gets `Origin`/`Referer` as its own origin, preflights are answered locally, any origin may read responses (with credentials), and cookies become `SameSite=None` over HTTPS. The page's calls to other domains go through locadot automatically, with no extra mapping (see [Sites that call other domains](#sites-that-call-other-domains---cors)). |
 | `--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 start [--port 8080] [--https-port 8443]` | Start the central proxy. Default ports are 80 and 443. Ports you pass are remembered for later commands and start-at-boot, and a running proxy is moved to them. 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 restart [--port …] [--https-port …]` | 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. |
 
+### Sharing (Cloudflare Tunnel)
+
+| Command | What it does |
+| --- | --- |
+| `locadot tunnel --host app.localhost` | Share a mapping on a public `https://<random>.trycloudflare.com` URL through a Cloudflare quick tunnel. No Cloudflare account is needed. `cloudflared` is downloaded on first use. |
+| `locadot tunnel --host app.localhost --off` | Stop sharing it. |
+| `locadot tunnel` | List the shared mappings and their public URLs. |
+| `locadot tunnel:install` | Download `cloudflared` into the state dir (`<state>/bin`). Set `LOCADOT_CLOUDFLARED` to use your own binary; one on `PATH` is also picked up. |
+
+The tunnel runs inside the proxy, so a shared mapping keeps working after `restart` and comes back at boot. Redirects to the
+target are rewritten to the public URL. **Anyone with the link can reach the mapping**, so only share what you'd put online.
+For safety, the `--cors` pass-through (`/__locadot/x/…`) is turned off for visitors coming through the tunnel, so the tunnel
+can't be used to reach other hosts from your machine. The dashboard can also do this: use **Share** / **Unshare** on a row.
+
 ### Certificates
 
 | Command | What it does |
@@ -90,12 +105,13 @@ Options for `add` / `update`:
 ## 📋 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:
+are answered by locadot itself, not proxied. The page is a control panel that follows the system light/dark theme:
 
 - **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 optional "Insecure TLS" and "Bypass CORS" boxes), 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.
+  each source → destination with up/down, status, latency, its public tunnel URL and traffic (hits, errors, average ms). It refreshes every 5 s.
+- **Cloudflare Tunnel:** whether `cloudflared` is installed (with an **Install** button), and a **Share** button per row that puts the mapping on a public URL.
 - **Logs:** a live tail with refresh and clear.
 - **CLI / API snippets** you can copy.
 
@@ -148,8 +164,8 @@ All optional, via environment variables. Set them for the CLI; the proxy it star
 | 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_HTTP_PORT` | `80` | HTTP port of the proxy. Overrides the port saved by `locadot start --port`. |
+| `LOCADOT_HTTPS_PORT` | `443` | HTTPS port of the proxy. Overrides the port saved by `locadot start --https-port`. |
 | `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). |
 
@@ -165,6 +181,26 @@ redirect to a *different* domain (for example `google.com` → `www.google.com`)
 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.
 
+### Sites that call other domains (`--cors`)
+
+A frontend that calls its API or third-party services by absolute URL works with just the site mapped:
+
+```bash
+locadot add --host signalsant.localhost --target https://signalsant.com --cors
+```
+
+- **Pass-through.** HTML pages get a small script (`/__locadot/shim.js`) as the first thing in `<head>`. It sends `fetch`,
+  `XMLHttpRequest`, `EventSource`, `WebSocket` and `sendBeacon` calls to other origins through the page's own origin
+  (`/__locadot/x/https/api.signalsant.com/…`). The browser sees a same-origin request, so CORS never applies, and locadot
+  forwards it with `Origin: https://signalsant.com`. Only the page itself can use it: requests from other sites get a 403.
+- **Cookies.** The page's cookies are forwarded only to the same site (`api.signalsant.com`), never to third parties.
+  Cookies set by third parties are dropped.
+- **Mapped domains.** If you also map a domain (`api.signalsant.localhost` → `https://api.signalsant.com --cors`), its URLs in
+  HTML/JS/CSS/JSON are rewritten to the `.localhost` name and it's called there directly.
+
+Rewritten responses are buffered and sent uncompressed. Event streams and binary files pass through untouched. Not covered:
+requests made by web workers or service workers, and `<form>` posts or `<img>`/`<script>` tags (these don't need CORS).
+
 ---
 
 ## 🛠️ Contributing

package/dist/cli/commands/doctor.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doctor = doctor;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const localhost_1 = __importDefault(require("../../lib/localhost"));
+const proxy_control_1 = __importDefault(require("../../lib/proxy-control"));
+const registry_1 = __importDefault(require("../../lib/registry"));
+const constants_1 = __importDefault(require("../../constants"));
+const trust_1 = require("../../utils/trust");
+const shared_1 = require("../shared");
+async function doctor(options) {
+    let failures = 0;
+    const check = (ok, label, hint) => {
+        if (ok === undefined)
+            (0, shared_1.print)(`➖ ${label}`);
+        else
+            (0, shared_1.print)(`${ok ? "✅" : "❌"} ${label}${!ok && hint ? `\n     → ${hint}` : ""}`);
+        if (ok === false)
+            failures++;
+    };
+    const info = proxy_control_1.default.running();
+    check(Boolean(info), `Proxy process ${info ? `running (pid ${info.pid})` : "not running"}`, "Run `locadot start` and read the error it prints.");
+    for (const port of [constants_1.default.server.httpPort, constants_1.default.server.httpsPort]) {
+        const listening = await localhost_1.default.isPortListening(port);
+        if (info) {
+            check(listening, `Port ${port} answering`, "The proxy is running but not listening; check `locadot logs`.");
+        }
+        else if (listening) {
+            check(false, `Port ${port} is free`, `Something else holds port ${port}. Find it with \`sudo lsof -i :${port}\`, or pick another with \`locadot start ${port === constants_1.default.server.httpPort ? "--port" : "--https-port"} <port>\`.`);
+        }
+    }
+    if (info && (await localhost_1.default.isPortListening(constants_1.default.server.httpPort))) {
+        const probe = await localhost_1.default.probe(`http://127.0.0.1:${constants_1.default.server.httpPort}/healthz`);
+        check(probe.up && probe.status === 200, "Dashboard responds", "Another program may be answering on the proxy port.");
+    }
+    if (os_1.default.platform() === "linux" && Math.min(constants_1.default.server.httpPort, constants_1.default.server.httpsPort) < 1024) {
+        let unprivileged = 1024;
+        try {
+            unprivileged = Number(fs_1.default.readFileSync("/proc/sys/net/ipv4/ip_unprivileged_port_start", "utf8"));
+        }
+        catch { }
+        const canBind = process.getuid?.() === 0 || unprivileged <= Math.min(constants_1.default.server.httpPort, constants_1.default.server.httpsPort);
+        check(canBind || Boolean(info), "Allowed to bind ports 80/443", "Run with sudo, or allow it once: `sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80` (persist in /etc/sysctl.d/).");
+    }
+    const trusted = await (0, trust_1.isCATrusted)().catch(() => false);
+    check(trusted, "Locadot CA trusted by the system", `Run \`locadot trust\`. Manual steps:\n${(0, trust_1.trustInstructions)()}`);
+    try {
+        const registry = registry_1.default.read();
+        check(true, `Registry readable (${Object.keys(registry.hosts).length} host(s))`);
+        const hosts = options.host ? [localhost_1.default.requireHost(options.host)] : Object.keys(registry.hosts);
+        for (const host of hosts) {
+            const entry = registry.hosts[host];
+            if (!entry) {
+                check(false, `${host} is mapped`, `locadot add --host ${host} --port <port>`);
+                continue;
+            }
+            const probe = await localhost_1.default.probe(entry.target, 2000, entry.insecure);
+            check(probe.up, `${host} → ${entry.target} ${probe.up ? `answers (${probe.status}, ${probe.ms}ms)` : `unreachable (${probe.error})`}`, "Start the app, or fix the target with `locadot update`.");
+        }
+    }
+    catch (error) {
+        check(false, "Registry readable", error.message);
+    }
+    (0, shared_1.print)(failures ? `\n${failures} problem(s) found.` : "\nAll checks passed.");
+    if (failures)
+        process.exitCode = 1;
+}

package/dist/cli/commands/files.js

@@ -0,0 +1,89 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logs = logs;
+exports.clearLogs = clearLogs;
+exports.logPath = logPath;
+exports.hostPath = hostPath;
+exports.configPath = configPath;
+exports.token = token;
+const localhost_1 = __importStar(require("../../lib/localhost"));
+const locadot_file_1 = __importDefault(require("../../lib/locadot-file"));
+const proxy_control_1 = __importDefault(require("../../lib/proxy-control"));
+const constants_1 = __importDefault(require("../../constants"));
+const file_1 = __importDefault(require("../../utils/file"));
+const certs_1 = require("../../utils/certs");
+const shared_1 = require("../shared");
+function logs(options) {
+    const lines = options.lines ? localhost_1.default.parsePort(options.lines) : 50;
+    if (options.follow === false) {
+        console.log(file_1.default.lastLines("LOGS", lines).join("\n") || "(log is empty)");
+        return;
+    }
+    locadot_file_1.default.watchLogs(lines);
+}
+function clearLogs() {
+    locadot_file_1.default.clearLogs();
+    (0, shared_1.print)("☑️ Logs successfully cleared.");
+}
+function logPath() {
+    console.log(constants_1.default.paths.LOGS);
+}
+function hostPath() {
+    console.log(constants_1.default.paths.REGISTRY_FILE);
+}
+function configPath() {
+    const rows = [
+        ["State dir", constants_1.default.paths.HOME],
+        ["Registry", constants_1.default.paths.REGISTRY_FILE],
+        ["Lock file", constants_1.default.paths.LOCK_FILE],
+        ["Logs", constants_1.default.paths.LOGS],
+        ["Certs", constants_1.default.paths.CERT_DIR],
+        ["CA cert", (0, certs_1.caCertPath)()],
+        ["API token", constants_1.default.paths.API_TOKEN],
+        ["Config", constants_1.default.paths.CONFIG_FILE],
+    ];
+    rows.forEach(([label, value]) => console.log(`${label.padEnd(10)} ${value}`));
+}
+/** For scripts and AI agents driving the dashboard API. */
+function token() {
+    const token = proxy_control_1.default.running() ? file_1.default.read("API_TOKEN")?.trim() : undefined;
+    if (!token)
+        throw new localhost_1.InputError("❌ The proxy isn't running, so there's no API token. Run `locadot start`.");
+    console.log(token);
+}

package/dist/cli/commands/hosts.js

@@ -0,0 +1,108 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.add = add;
+exports.update = update;
+exports.remove = remove;
+exports.list = list;
+exports.clearHosts = clearHosts;
+const localhost_1 = __importStar(require("../../lib/localhost"));
+const registry_1 = __importDefault(require("../../lib/registry"));
+const hosts_1 = __importDefault(require("../../lib/hosts"));
+const urls_1 = require("../../lib/urls");
+const shared_1 = require("../shared");
+const resolveTarget = (options) => {
+    if (options.port !== undefined && options.target !== undefined) {
+        throw new localhost_1.InputError("❌ Use either --port or --target, not both.");
+    }
+    if (options.port !== undefined)
+        return `http://localhost:${localhost_1.default.parsePort(options.port)}`;
+    if (options.target !== undefined)
+        return localhost_1.default.parseTarget(options.target);
+    throw new localhost_1.InputError("❌ Missing destination. Pass --port <port> or --target <url>.");
+};
+const mapping = (options) => ({
+    host: options.host,
+    target: resolveTarget(options),
+    insecure: options.insecure,
+    cors: options.cors,
+});
+const warnIfDown = async (entry) => {
+    const probe = await localhost_1.default.probe(entry.target, 1500, entry.insecure);
+    if (!probe.up)
+        (0, shared_1.print)(`⚠️  Nothing answered at ${entry.target} yet (${probe.error}). The mapping is saved anyway.`);
+};
+async function add(options) {
+    const { host, entry } = await hosts_1.default.add(mapping(options));
+    await (0, shared_1.ensureRunning)(options);
+    (0, shared_1.print)(`✅ ${(0, urls_1.urlFor)(host)} → ${entry.target}`);
+    if (!localhost_1.default.isLocalTarget(entry.target)) {
+        (0, shared_1.print)("ℹ️  Remote target: redirects to other domains will leave the .localhost name.");
+    }
+    await warnIfDown(entry);
+}
+async function update(options) {
+    const { host, entry } = await hosts_1.default.update(mapping(options));
+    await (0, shared_1.ensureRunning)(options);
+    (0, shared_1.print)(`✅ Updated ${(0, urls_1.urlFor)(host)} → ${entry.target}`);
+    await warnIfDown(entry);
+}
+async function remove(options) {
+    const { host } = await hosts_1.default.remove(options);
+    (0, shared_1.print)(`🗑️  Removed ${host}.`);
+}
+async function list(options) {
+    const hosts = Object.entries(registry_1.default.read().hosts).sort(([a], [b]) => a.localeCompare(b));
+    if (options.json) {
+        console.log(JSON.stringify(hosts.map(([host, entry]) => ({ host, url: (0, urls_1.urlFor)(host), ...entry })), null, 2));
+        return;
+    }
+    if (!hosts.length) {
+        (0, shared_1.print)("No hosts mapped. Add one: npx locadot add --host app.localhost --port 3000");
+        return;
+    }
+    const width = Math.max(...hosts.map(([host]) => (0, urls_1.urlFor)(host).length));
+    for (const [host, entry] of hosts) {
+        (0, shared_1.print)(`${(0, urls_1.urlFor)(host).padEnd(width)}  →  ${entry.target}${entry.insecure ? "  (insecure)" : ""}${entry.cors ? "  (cors)" : ""}`);
+    }
+    (0, shared_1.print)(`☑️ Total: ${hosts.length}.`);
+}
+async function clearHosts() {
+    await registry_1.default.mutate((registry) => (registry.hosts = {}));
+    (0, shared_1.print)("☑️ All hosts removed.");
+}

package/dist/cli/commands/index.js

@@ -0,0 +1,43 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const hosts = __importStar(require("./hosts"));
+const proxy = __importStar(require("./proxy"));
+const files = __importStar(require("./files"));
+const system = __importStar(require("./system"));
+const tunnel = __importStar(require("./tunnel"));
+const doctor_1 = require("./doctor");
+const Commands = { ...hosts, ...proxy, ...files, ...system, ...tunnel, doctor: doctor_1.doctor };
+exports.default = Commands;

package/dist/cli/commands/proxy.js

@@ -0,0 +1,100 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.status = status;
+exports.start = start;
+exports.stop = stop;
+exports.restart = restart;
+exports.kill = kill;
+const fs_1 = __importDefault(require("fs"));
+const localhost_1 = require("../../lib/localhost");
+const proxy_control_1 = __importDefault(require("../../lib/proxy-control"));
+const registry_1 = __importDefault(require("../../lib/registry"));
+const urls_1 = require("../../lib/urls");
+const constants_1 = __importDefault(require("../../constants"));
+const file_1 = __importDefault(require("../../utils/file"));
+const startup_1 = __importDefault(require("../../utils/startup"));
+const trust_1 = require("../../utils/trust");
+const shared_1 = require("../shared");
+/** Applies --port/--https-port and saves them, so `add`, `status`, `open` and boot startup use the same ports. */
+const usePorts = (options) => {
+    if (options.port === undefined && options.httpsPort === undefined)
+        return false;
+    const parse = (value, flag) => {
+        if (value === undefined)
+            return undefined;
+        const port = constants_1.default.validPort(value);
+        if (!port)
+            throw new localhost_1.InputError(`❌ ${flag} must be a port between 1 and 65535, got "${value}".`);
+        return port;
+    };
+    const httpPort = parse(options.port, "--port") ?? constants_1.default.server.httpPort;
+    const httpsPort = parse(options.httpsPort, "--https-port") ?? constants_1.default.server.httpsPort;
+    if (httpPort === httpsPort)
+        throw new localhost_1.InputError(`❌ HTTP and HTTPS can't share port ${httpPort}.`);
+    Object.assign(constants_1.default.server, { httpPort, httpsPort });
+    file_1.default.ensureDir();
+    fs_1.default.writeFileSync(constants_1.default.paths.CONFIG_FILE, JSON.stringify({ httpPort, httpsPort }, null, 2) + "\n");
+    return true;
+};
+async function status(options) {
+    const info = proxy_control_1.default.running();
+    const hosts = Object.keys(registry_1.default.read().hosts).length;
+    const [trusted, startup] = await Promise.all([(0, trust_1.isCATrusted)().catch(() => undefined), startup_1.default.isEnabled()]);
+    const report = {
+        running: Boolean(info),
+        pid: info?.pid,
+        version: info?.version,
+        startedAt: info?.startedAt,
+        httpPort: info?.httpPort ?? constants_1.default.server.httpPort,
+        httpsPort: info?.httpsPort ?? constants_1.default.server.httpsPort,
+        bind: info?.bind ?? constants_1.default.server.bind,
+        hosts,
+        caTrusted: trusted,
+        startupEnabled: startup,
+        dashboard: (0, urls_1.urlFor)("localhost"),
+        stateDir: constants_1.default.paths.HOME,
+    };
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    (0, shared_1.print)(info ? `🟢 Proxy running (pid ${info.pid}${info.startedAt ? `, since ${info.startedAt}` : ""})` : "🔴 Proxy not running");
+    (0, shared_1.print)(`   Ports:     http ${report.httpPort}, https ${report.httpsPort} on ${report.bind.join(", ")}`);
+    (0, shared_1.print)(`   Hosts:     ${hosts}`);
+    (0, shared_1.print)(`   CA:        ${trusted === undefined ? "unknown" : trusted ? "trusted" : "not trusted (run `locadot trust`)"}`);
+    (0, shared_1.print)(`   Startup:   ${startup ? "enabled" : "disabled"}`);
+    (0, shared_1.print)(`   Dashboard: ${report.dashboard}`);
+    (0, shared_1.print)(`   State dir: ${report.stateDir}`);
+}
+async function start(options = {}) {
+    const moved = usePorts(options);
+    const running = proxy_control_1.default.running();
+    // Already up on other ports: the new ones only take effect after a restart.
+    if (running && (running.httpPort !== constants_1.default.server.httpPort || running.httpsPort !== constants_1.default.server.httpsPort)) {
+        const info = await proxy_control_1.default.restart();
+        (0, shared_1.print)(`🔁 Proxy restarted on http ${info.httpPort}, https ${info.httpsPort} (pid ${info.pid}).`);
+    }
+    else {
+        const info = await proxy_control_1.default.start();
+        (0, shared_1.print)(running ? `☑️ Proxy already running (pid ${info.pid}).` : `🚀 Central proxy started (pid ${info.pid}).`);
+        if (moved || !running)
+            (0, shared_1.print)(`   Ports:     http ${info.httpPort}, https ${info.httpsPort}`);
+    }
+    (0, shared_1.print)(`   Dashboard: ${(0, urls_1.urlFor)("localhost")}`);
+}
+async function stop() {
+    const stopped = await proxy_control_1.default.stop();
+    (0, shared_1.print)(stopped ? constants_1.default.proxyInfo.softClose : "☑️ Proxy was not running.");
+}
+async function restart(options = {}) {
+    usePorts(options);
+    const info = await proxy_control_1.default.restart();
+    (0, shared_1.print)(`☑️ Proxy restarted on http ${info.httpPort}, https ${info.httpsPort} (pid ${info.pid}).`);
+}
+async function kill() {
+    await proxy_control_1.default.kill();
+    (0, shared_1.print)(constants_1.default.proxyInfo.proxyClose);
+}

package/dist/cli/commands/system.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.open = open;
+exports.trust = trust;
+exports.untrust = untrust;
+exports.enableStartup = enableStartup;
+exports.disableStartup = disableStartup;
+exports.statusStartup = statusStartup;
+const os_1 = __importDefault(require("os"));
+const child_process_1 = require("child_process");
+const localhost_1 = __importDefault(require("../../lib/localhost"));
+const urls_1 = require("../../lib/urls");
+const startup_1 = __importDefault(require("../../utils/startup"));
+const certs_1 = require("../../utils/certs");
+const trust_1 = require("../../utils/trust");
+const shared_1 = require("../shared");
+async function open(host) {
+    const url = (0, urls_1.urlFor)(host ? localhost_1.default.requireHost(host) : "localhost");
+    const [command, args] = os_1.default.platform() === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : os_1.default.platform() === "darwin"
+            ? ["open", [url]]
+            : ["xdg-open", [url]];
+    try {
+        // windows-hide-exempt: run from the user's terminal (no popup), and hiding `cmd /c start` can hide the browser too.
+        (0, child_process_1.spawn)(command, args, { detached: true, stdio: "ignore" }).on("error", () => { }).unref();
+    }
+    catch { }
+    (0, shared_1.print)(url);
+}
+async function trust() {
+    await (0, trust_1.trustCA)();
+    (0, shared_1.print)(`✅ Locadot CA trusted (${(0, certs_1.caCertPath)()}). Restart your browser if it was open.`);
+}
+async function untrust() {
+    await (0, trust_1.untrustCA)();
+    (0, shared_1.print)("✅ Locadot CA removed from the trust store.");
+}
+async function enableStartup() {
+    await startup_1.default.enable();
+}
+async function disableStartup() {
+    await startup_1.default.disable();
+}
+async function statusStartup() {
+    (0, shared_1.print)((await startup_1.default.isEnabled()) ? "enabled" : "disabled");
+}