locadot 1.6.0-beta.4 → 1.6.0-beta.6

package/CHANGELOG.md

@@ -2,9 +2,12 @@
 
 ## Unreleased
 
-The version in `package.json` is 1.6.0-beta.4 (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.6 (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,6 +16,8 @@ breaking items below.
 - Bare `localhost` is reserved for the dashboard and can't be mapped.
 
 ### Added
+- `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`. `--cors` also works for tunnel visitors (the shim, preflights and origin rewriting to the public URL), but their pass-through calls may only reach public addresses; loopback, LAN and metadata addresses are refused at connect time.
+- 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,

package/README.md

@@ -69,6 +69,23 @@ Options for `add` / `update`:
 | `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.
+`--cors` works through the tunnel too: CORS headers and preflights, the pass-through shim, and the target's own
+origin in pages rewritten to the public URL (other shared mappings get their public URLs too). For safety, a tunnel visitor's
+pass-through calls may only go to public addresses: loopback, LAN, link-local and cloud-metadata addresses are refused, checked
+on the address actually dialled, so the tunnel can't be used to reach your machine or network. The dashboard can also do this:
+use **Share** / **Unshare** on a row.
+
 ### Certificates
 
 | Command | What it does |
@@ -91,12 +108,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.
 

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");
+}

package/dist/cli/commands/tunnel.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.installTunnel = installTunnel;
+exports.tunnel = tunnel;
+const http_1 = __importDefault(require("http"));
+const localhost_1 = __importStar(require("../../lib/localhost"));
+const hosts_1 = __importDefault(require("../../lib/hosts"));
+const constants_1 = __importDefault(require("../../constants"));
+const tunnel_1 = require("../../proxy/tunnel");
+const shared_1 = require("../shared");
+const TUNNEL_TIMEOUT_MS = 45000;
+/** Tunnel state lives in the proxy process; ask it over the local read-only API. */
+const tunnelRows = () => new Promise((resolve, reject) => {
+    const req = http_1.default.get({ host: "127.0.0.1", port: constants_1.default.server.httpPort, path: "/api/hosts", headers: { Host: "localhost" }, timeout: 5000 }, (res) => {
+        let body = "";
+        res.on("data", (chunk) => (body += chunk));
+        res.on("end", () => {
+            try {
+                resolve(JSON.parse(body).filter((row) => Boolean(row.tunnel?.enabled)));
+            }
+            catch {
+                reject(new localhost_1.InputError("❌ The proxy didn't answer /api/hosts. Is it running? Try `locadot status`."));
+            }
+        });
+    });
+    req.on("timeout", () => req.destroy(new Error("timeout")));
+    req.on("error", () => reject(new localhost_1.InputError("❌ The proxy isn't running. Run `locadot start`.")));
+});
+async function installTunnel() {
+    const existing = (0, tunnel_1.cloudflaredInfo)(true);
+    if (existing.installed) {
+        (0, shared_1.print)(`☑️ cloudflared ${existing.version ?? ""} is already installed (${existing.path}).`);
+        return;
+    }
+    (0, shared_1.print)("⬇️  Downloading cloudflared from github.com/cloudflare/cloudflared…");
+    const info = await (0, tunnel_1.installCloudflared)();
+    (0, shared_1.print)(`✅ cloudflared ${info.version ?? ""} installed at ${info.path}`);
+}
+/** Shares a mapping on a public trycloudflare.com URL, or lists what's shared when no host is given. */
+async function tunnel(options) {
+    if (!options.host) {
+        const shared = await tunnelRows();
+        if (!shared.length)
+            (0, shared_1.print)("Nothing is shared. Share a mapping: locadot tunnel --host app.localhost");
+        for (const row of shared)
+            (0, shared_1.print)(`${row.host}  →  ${row.tunnel.url ?? row.tunnel.status}${row.tunnel.error ? ` (${row.tunnel.error})` : ""}`);
+        return;
+    }
+    const host = localhost_1.default.requireHost(options.host);
+    if (options.off) {
+        await hosts_1.default.setTunnel({ host, tunnel: false });
+        (0, shared_1.print)(`🔒 ${host} is no longer public.`);
+        return;
+    }
+    if (!(0, tunnel_1.cloudflaredInfo)(true).installed)
+        await installTunnel();
+    await hosts_1.default.setTunnel({ host, tunnel: true });
+    await (0, shared_1.ensureRunning)();
+    const deadline = Date.now() + TUNNEL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        const state = (await tunnelRows()).find((row) => row.host === host)?.tunnel;
+        if (state?.status === "up") {
+            (0, shared_1.print)(`🌍 ${host} is public at ${state.url}`);
+            (0, shared_1.print)("   Anyone with the link can reach it. Stop with: locadot tunnel --host " + host + " --off");
+            return;
+        }
+        if (state?.status === "error")
+            throw new localhost_1.InputError(`❌ Tunnel for ${host} failed: ${state.error}`);
+        await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    throw new localhost_1.InputError(`❌ Tunnel for ${host} didn't come up within ${TUNNEL_TIMEOUT_MS / 1000}s. See \`locadot logs\`.`);
+}

package/dist/cli/shared.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureRunning = exports.print = void 0;
+const proxy_control_1 = __importDefault(require("../lib/proxy-control"));
+const logger_1 = __importDefault(require("../utils/logger"));
+const print = (message) => logger_1.default.info(message);
+exports.print = print;
+/** The proxy only picks up mappings once running; a failure here must not be hidden. */
+const ensureRunning = async (options = {}) => {
+    if (options.start === false)
+        return;
+    const wasRunning = proxy_control_1.default.running();
+    const info = await proxy_control_1.default.start();
+    if (!wasRunning)
+        (0, exports.print)(`🚀 Central proxy started (pid ${info.pid}).`);
+};
+exports.ensureRunning = ensureRunning;