lizardtail 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lizardtail contributors
+
+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

@@ -0,0 +1,390 @@
+# lizardtail
+
+`lizardtail` runs a command, watches its output for a localhost server port, exposes that port with [Tailscale Serve](https://tailscale.com/kb/1242/tailscale-serve), and prints the private tailnet URL. Pass `--public` to use Tailscale Funnel intentionally.
+
+```bash
+lizardtail pnpm dev
+```
+
+```text
+Local: http://localhost:5173
+
+lizardtail: detected local server on http://127.0.0.1:5173
+lizardtail: serving via Tailscale: https://my-host.tailabc.ts.net:8443
+```
+
+Use it when your dev server is running on a remote machine and you want to open it from another device on your tailnet without manually copying ports or reconfiguring Tailscale Serve.
+
+## Features
+
+- Runs any command you pass it, such as `pnpm dev`, `npm run dev`, `bun run dev`, or `python -m http.server`.
+- Streams the child command's stdout/stderr normally.
+- Detects common dev-server output formats, including `http://localhost:5173`, `http://127.0.0.1:3000`, `started server on 0.0.0.0:8080`, and `PORT=4321`.
+- Ignores timing output like `ready in 500 ms` so it does not accidentally expose port `500`.
+- Waits briefly after the first candidate port so multi-process commands, such as Laravel plus Vite, can print the better app-server URL.
+- Waits for the detected port to accept local connections before exposing it.
+- Runs `tailscale serve --bg --https <tailscale-port> http://127.0.0.1:<port>`.
+- Prints the HTTPS MagicDNS URL for the current Tailscale device.
+- Supports an explicit `--port` when automatic detection is not possible.
+- Supports `--tailscale-port` when you want the MagicDNS URL to include a specific HTTPS port.
+- Detects Laravel + Vite dev output, exposes both servers, rewrites Laravel's `public/hot` file to the Tailscale Vite URL, and proxies Vite assets with CORS headers so module scripts can load cross-origin.
+- Uses a stable alternate Tailscale HTTPS port by default: first free port from `8443` upward.
+- Stays private to your tailnet by default.
+- Supports `--public` / `--funnel` for intentional public internet sharing through Tailscale Funnel.
+- Cleans up the Tailscale Serve/Funnel mappings it created when the child command exits or you press `Ctrl+C`.
+- Has editable blocked-port guardrails with default entries for common HTTP/HTTPS ingress ports.
+
+## Requirements
+
+- Node.js 20 or newer.
+- Tailscale installed and available as `tailscale` on `PATH`.
+- The device must be logged into Tailscale.
+- Tailscale Serve must be available for the device/tailnet.
+- For `--public`, Tailscale Funnel must be enabled for the device/tailnet.
+- Your user must be allowed to update Tailscale Serve/Funnel config. If `tailscale serve` or `tailscale funnel` says access is denied, run this once:
+
+  ```bash
+  sudo tailscale set --operator=$USER
+  ```
+
+Check Tailscale before using `lizardtail`:
+
+```bash
+tailscale status
+tailscale serve --help
+# Optional, only for --public:
+tailscale funnel --help
+```
+
+`lizardtail` exposes services to your private tailnet via Tailscale Serve by default. It only uses Tailscale Funnel, which publishes to the public internet, when you explicitly pass `--public` or `--funnel`.
+
+## Installation
+
+### From source
+
+```bash
+git clone https://github.com/dasomji/lizardtail.git
+cd lizardtail
+npm install
+npm run build
+npm link
+```
+
+Then run:
+
+```bash
+lizardtail --help
+```
+
+### During development
+
+You can run the TypeScript source directly:
+
+```bash
+npm run dev -- pnpm dev
+```
+
+Or build and run the compiled CLI:
+
+```bash
+npm run build
+node dist/index.js pnpm dev
+```
+
+## Usage
+
+```bash
+lizardtail [options] -- <command> [args...]
+lizardtail [options] <command> [args...]
+lizardtail help [topic]
+lizardtail config init
+```
+
+Use `--` when the command itself has flags that could be confused for `lizardtail` options:
+
+```bash
+lizardtail -- npm run dev -- --host 0.0.0.0
+```
+
+### Help
+
+```bash
+lizardtail help
+lizardtail help config
+```
+
+These commands are meant for both humans and coding agents: they describe usage, safety behavior, public/private exposure, and config file shape without needing to open the README.
+
+### Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--port <port>` | auto-detect | Expose this port instead of reading one from command output. |
+| `--host <host>` | `127.0.0.1` | Local host to pass to Tailscale Serve/Funnel. |
+| `--timeout <ms>` | `30000` | How long to wait for a port to appear in command output. |
+| `--tailscale-port <port>` | first free `8443+` | Expose the main app on this Tailscale HTTPS port and print it in the MagicDNS URL. Alias: `--https-port`. |
+| `--vite-tailscale-port <port>` | first free `8443+` | Expose a detected Laravel Vite asset server on this Tailscale HTTPS port. Alias: `--vite-https-port`. |
+| `--public`, `--funnel` | disabled | Use Tailscale Funnel for public internet access instead of private tailnet-only Serve. |
+| `--no-open-check` | enabled | Skip waiting for the local port to accept connections before calling Tailscale. |
+| `-h`, `--help` | | Show help. |
+
+## Examples
+
+### Vite / frontend dev server
+
+```bash
+lizardtail pnpm dev
+```
+
+If Vite is configured to bind to another host:
+
+```bash
+lizardtail --host localhost pnpm dev
+```
+
+### npm script with extra flags
+
+```bash
+lizardtail -- npm run dev -- --host 0.0.0.0
+```
+
+### Known port
+
+```bash
+lizardtail --port 3000 npm run dev
+```
+
+### MagicDNS URL with an explicit port
+
+By default, `lizardtail` uses the first free Tailscale HTTPS port from `8443` upward, so multiple projects can be served at the same time:
+
+```text
+https://my-host.tailabc.ts.net:8443
+```
+
+You can also choose the Tailscale HTTPS port explicitly:
+
+```bash
+lizardtail --tailscale-port 8450 pnpm dev
+```
+
+That prints a URL like:
+
+```text
+https://my-host.tailabc.ts.net:8450
+```
+
+### Laravel / `composer run dev`
+
+Laravel development commands often start both the PHP app server and the Vite asset server. When `lizardtail` sees both, it:
+
+1. exposes the Laravel app server;
+2. starts a small local proxy in front of Vite that adds CORS headers;
+3. exposes that Vite proxy on a separate Tailscale HTTPS port;
+4. writes `public/hot` to the Tailscale Vite URL so Laravel renders assets from the reachable Vite server.
+
+```bash
+lizardtail composer run dev
+```
+
+You can choose the Vite Tailscale port explicitly:
+
+```bash
+lizardtail --vite-tailscale-port 8453 composer run dev
+```
+
+`lizardtail` also sets `__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS` for the child command when it can read your Tailscale MagicDNS name. The local proxy handles CORS for module scripts loaded from the Vite Tailscale URL.
+
+If your app server lands on a known port and you only want to expose that server, you can force it:
+
+```bash
+lizardtail --port 8001 composer run dev
+```
+
+### Public internet sharing
+
+By default, URLs are only reachable from devices in your tailnet. To intentionally publish through Tailscale Funnel:
+
+```bash
+lizardtail --public pnpm dev
+```
+
+or:
+
+```bash
+lizardtail --funnel pnpm dev
+```
+
+This prints a public HTTPS URL such as:
+
+```text
+https://my-host.tailabc.ts.net:8443
+```
+
+Use this only for apps you are comfortable exposing publicly. Stop `lizardtail` with `Ctrl+C` to remove the Funnel mapping it created.
+
+### Editable blocked ports
+
+Lizard Tail ships with a small default blocked-port list for common HTTP/HTTPS ingress ports:
+
+```json
+{
+  "blockedPorts": [
+    {
+      "port": 80,
+      "scope": "both",
+      "reason": "Common HTTP ingress/proxy port. Blocking prevents dev exposure from replacing a production web route."
+    },
+    {
+      "port": 443,
+      "scope": "both",
+      "reason": "Common HTTPS ingress/proxy port. Lizard Tail defaults to high explicit Tailscale HTTPS ports instead."
+    }
+  ]
+}
+```
+
+Create an editable config file:
+
+```bash
+lizardtail config init
+```
+
+Lizard Tail searches the current working directory for:
+
+1. `lizardtail.config.json`
+2. `.lizardtail.json`
+
+You can also set `LIZARDTAIL_CONFIG=/path/to/config.json`.
+
+Each blocked-port entry has:
+
+- `port`: number from `1` to `65535`
+- `scope`: `"local"`, `"tailscale"`, or `"both"` — defaults to `"both"`
+- `reason`: explanation shown when the rule blocks an action
+
+If a config file exists, its `blockedPorts` list replaces the built-in default list. Keep, edit, or remove entries based on your own host.
+
+### Longer startup timeout
+
+```bash
+lizardtail --timeout 60000 pnpm dev
+```
+
+## How it works
+
+1. `lizardtail` starts the command you provide.
+2. It streams the command output to your terminal.
+3. It scans recent output for a local port.
+4. Once it finds a port, it waits for `127.0.0.1:<port>` or the configured `--host` to accept connections.
+5. It chooses the first free Tailscale HTTPS port from `8443` upward, unless `--tailscale-port` was provided. Ports in the configured blocked-port list are refused or skipped.
+6. It runs Tailscale Serve for private tailnet-only access:
+
+   ```bash
+   tailscale serve --bg --https <tailscale-port> http://<host>:<port>
+   ```
+
+   With `--public` / `--funnel`, it runs Tailscale Funnel for public internet access:
+
+   ```bash
+   tailscale funnel --bg --https <tailscale-port> http://<host>:<port>
+   ```
+
+   On older Tailscale versions, if that form fails for `127.0.0.1`/`localhost`, it falls back to the same command with just `<port>` as the target.
+
+7. It reads `tailscale status --json`, extracts the current device's MagicDNS name, and prints:
+
+   ```text
+   https://<device-name>.<tailnet>.ts.net:<tailscale-port>
+   ```
+
+## Shutdown behavior
+
+When the child command exits, or when you press `Ctrl+C`, `lizardtail` removes the Tailscale mappings it created for that run:
+
+```bash
+tailscale serve --https=<port> off
+# or, with --public:
+tailscale funnel --https=<port> off
+```
+
+It only tracks ports created by the current `lizardtail` process.
+
+## Troubleshooting
+
+### No port detected
+
+If the server does not print a recognizable port, pass it explicitly:
+
+```bash
+lizardtail --port 5173 pnpm dev
+```
+
+### Tailscale command fails
+
+Verify Tailscale is running and logged in:
+
+```bash
+tailscale status
+```
+
+Then check Serve support and current mappings:
+
+```bash
+tailscale serve --help
+tailscale serve status
+```
+
+### `Access denied: serve config denied`
+
+Some Tailscale installs only allow root, or the configured Tailscale operator, to change Serve config. If you see:
+
+```text
+Access denied: serve config denied
+Use 'sudo tailscale serve ...'
+To not require root, use 'sudo tailscale set --operator=$USER' once.
+```
+
+run:
+
+```bash
+sudo tailscale set --operator=$USER
+```
+
+Then rerun `lizardtail`. This is a one-time local machine setup step.
+
+### Browser cannot load assets
+
+Some frameworks, especially full-stack apps with separate backend and Vite dev servers, need more than one port exposed. `lizardtail` detects Laravel + Vite and exposes both automatically. For other multi-port setups, run a second `lizardtail --port <port> ...` command or configure Tailscale Serve manually with explicit high ports.
+
+### Host checks or CORS failures
+
+Some dev servers reject requests from the Tailscale hostname. Configure your dev server to allow the Tailscale MagicDNS host or to bind with the right host/CORS options. For example, Vite may need `--host 0.0.0.0` and framework-specific allowed-host settings.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+The test suite uses Node's built-in test runner through `tsx` and includes:
+
+- unit tests for argument parsing and port detection;
+- an integration-style CLI test with a fake `tailscale` executable and a real temporary HTTP server.
+
+## Contributing
+
+Issues and pull requests are welcome. Please include tests for behavior changes and run:
+
+```bash
+npm test
+```
+
+before opening a pull request.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/index.js

@@ -0,0 +1,786 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { existsSync, realpathSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { createServer, request as httpRequest } from "node:http";
+import net from "node:net";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const DEFAULT_TAILSCALE_HTTPS_PORT = 8443;
+const MAX_AUTO_TAILSCALE_HTTPS_PORT = 8999;
+const CONFIG_FILENAMES = ["lizardtail.config.json", ".lizardtail.json"];
+const DETECTION_SETTLE_MS = 1_500;
+const DEFAULT_CONFIG = {
+    blockedPorts: [
+        {
+            port: 80,
+            scope: "both",
+            reason: "Common HTTP ingress/proxy port. Blocking prevents dev exposure from replacing a production web route.",
+        },
+        {
+            port: 443,
+            scope: "both",
+            reason: "Common HTTPS ingress/proxy port. Lizard Tail defaults to high explicit Tailscale HTTPS ports instead.",
+        },
+    ],
+};
+export function printUsage() {
+    console.error(`Usage: lizardtail [options] -- <command> [args...]
+       lizardtail [options] <command> [args...]
+       lizardtail help [topic]
+       lizardtail config init
+
+Options:
+  --port <port>        Expose this port instead of detecting one from output.
+  --host <host>        Local host to expose. Default: 127.0.0.1
+  --timeout <ms>       Port-detection timeout. Default: ${DEFAULT_TIMEOUT_MS}
+  --tailscale-port <port>
+                       Expose the main app on this Tailscale HTTPS port. Default: first free ${DEFAULT_TAILSCALE_HTTPS_PORT}+ port.
+  --vite-tailscale-port <port>
+                       Expose a detected Laravel Vite server on this Tailscale HTTPS port.
+  --public, --funnel   Expose publicly on the internet with Tailscale Funnel instead of private tailnet-only Serve.
+  --no-open-check      Skip waiting for the local port to accept connections.
+  -h, --help           Show this help.
+
+Examples:
+  lizardtail pnpm dev
+  lizardtail --port 3000 npm run dev
+  lizardtail --tailscale-port 8450 pnpm dev
+  lizardtail --public pnpm dev
+  lizardtail help config
+`);
+}
+function printDetailedHelp(topic) {
+    if (topic === "config") {
+        console.log(`Lizard Tail configuration
+
+Config files, searched from the current working directory:
+  1. lizardtail.config.json
+  2. .lizardtail.json
+
+You can also set LIZARDTAIL_CONFIG=/path/to/config.json.
+
+Create a starter config:
+  lizardtail config init
+
+Config shape:
+${JSON.stringify(DEFAULT_CONFIG, null, 2)}
+
+blockedPorts entries:
+  port    Number from 1 to 65535.
+  scope   "local", "tailscale", or "both". Defaults to "both".
+  reason  Human-readable explanation shown when the rule blocks an action.
+
+If a config file exists, its blockedPorts list replaces the built-in default list. Keep the default entries if they matter for your host, or edit/remove them if your environment is different.`);
+        return;
+    }
+    console.log(`Lizard Tail
+
+Run a dev server command, detect its local port, and expose it through Tailscale.
+
+Common usage:
+  lizardtail pnpm dev
+  lizardtail --port 3000 npm run dev
+  lizardtail --tailscale-port 8450 pnpm dev
+  lizardtail --public pnpm dev
+
+Private vs public:
+  Default: private tailnet-only Tailscale Serve.
+  --public / --funnel: public internet exposure through Tailscale Funnel.
+
+Safety:
+  Lizard Tail always uses explicit high Tailscale HTTPS ports by default (${DEFAULT_TAILSCALE_HTTPS_PORT}+).
+  It never runs bare tailscale serve/funnel target commands.
+  It only removes mappings it created in the current process.
+  Ports can be blocked with lizardtail.config.json or .lizardtail.json.
+
+Help topics:
+  lizardtail help config
+
+Other commands:
+  lizardtail config init      Write a starter config file.
+`);
+}
+function usage() {
+    printUsage();
+    process.exit(2);
+}
+async function handleMetaCommand(argv) {
+    if (argv[0] === "help") {
+        printDetailedHelp(argv[1]);
+        return true;
+    }
+    if (argv[0] === "config" && argv[1] === "init") {
+        await writeDefaultConfigFile();
+        return true;
+    }
+    if (argv[0] === "init-config") {
+        await writeDefaultConfigFile();
+        return true;
+    }
+    return false;
+}
+async function writeDefaultConfigFile() {
+    const configPath = path.join(process.cwd(), "lizardtail.config.json");
+    if (existsSync(configPath))
+        throw new Error(`${configPath} already exists`);
+    await writeFile(configPath, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`);
+    console.log(`wrote ${configPath}`);
+}
+export function parseArgs(argv) {
+    const options = {
+        command: [],
+        host: "127.0.0.1",
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        openCheck: true,
+        public: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--") {
+            options.command = argv.slice(i + 1);
+            break;
+        }
+        if (arg === "-h" || arg === "--help") {
+            printUsage();
+            process.exit(0);
+        }
+        if (arg === "--no-open-check") {
+            options.openCheck = false;
+            continue;
+        }
+        if (arg === "--public" || arg === "--funnel") {
+            options.public = true;
+            continue;
+        }
+        if (arg === "--port") {
+            const value = argv[++i];
+            if (!value)
+                usage();
+            options.port = parsePort(value);
+            continue;
+        }
+        if (arg.startsWith("--port=")) {
+            options.port = parsePort(arg.slice("--port=".length));
+            continue;
+        }
+        if (arg === "--host") {
+            const value = argv[++i];
+            if (!value)
+                usage();
+            options.host = value;
+            continue;
+        }
+        if (arg.startsWith("--host=")) {
+            options.host = arg.slice("--host=".length);
+            continue;
+        }
+        if (arg === "--tailscale-port" || arg === "--https-port") {
+            const value = argv[++i];
+            if (!value)
+                usage();
+            options.tailscalePort = parsePort(value);
+            continue;
+        }
+        if (arg.startsWith("--tailscale-port=")) {
+            options.tailscalePort = parsePort(arg.slice("--tailscale-port=".length));
+            continue;
+        }
+        if (arg.startsWith("--https-port=")) {
+            options.tailscalePort = parsePort(arg.slice("--https-port=".length));
+            continue;
+        }
+        if (arg === "--vite-tailscale-port" || arg === "--vite-https-port") {
+            const value = argv[++i];
+            if (!value)
+                usage();
+            options.viteTailscalePort = parsePort(value);
+            continue;
+        }
+        if (arg.startsWith("--vite-tailscale-port=")) {
+            options.viteTailscalePort = parsePort(arg.slice("--vite-tailscale-port=".length));
+            continue;
+        }
+        if (arg.startsWith("--vite-https-port=")) {
+            options.viteTailscalePort = parsePort(arg.slice("--vite-https-port=".length));
+            continue;
+        }
+        if (arg === "--timeout") {
+            const value = argv[++i];
+            if (!value)
+                usage();
+            options.timeoutMs = parseTimeout(value);
+            continue;
+        }
+        if (arg.startsWith("--timeout=")) {
+            options.timeoutMs = parseTimeout(arg.slice("--timeout=".length));
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            console.error(`lizardtail: unknown option ${arg}`);
+            usage();
+        }
+        options.command = argv.slice(i);
+        break;
+    }
+    if (options.command.length === 0)
+        usage();
+    return options;
+}
+function parsePort(value) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        console.error(`lizardtail: invalid port: ${value}`);
+        process.exit(2);
+    }
+    return port;
+}
+function parseTimeout(value) {
+    const timeout = Number(value);
+    if (!Number.isInteger(timeout) || timeout < 1) {
+        console.error(`lizardtail: invalid timeout: ${value}`);
+        process.exit(2);
+    }
+    return timeout;
+}
+async function loadConfig() {
+    const configPath = findConfigPath();
+    if (!configPath)
+        return DEFAULT_CONFIG;
+    try {
+        const raw = await readFile(configPath, "utf8");
+        const parsed = JSON.parse(raw);
+        return normalizeConfig(parsed, configPath);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            throw new Error(`failed to parse ${configPath}: ${error.message}`);
+        throw error;
+    }
+}
+function findConfigPath() {
+    if (process.env.LIZARDTAIL_CONFIG)
+        return process.env.LIZARDTAIL_CONFIG;
+    for (const filename of CONFIG_FILENAMES) {
+        const candidate = path.join(process.cwd(), filename);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function normalizeConfig(config, source) {
+    if (!Array.isArray(config.blockedPorts)) {
+        throw new Error(`${source} must contain a blockedPorts array`);
+    }
+    return {
+        blockedPorts: config.blockedPorts.map((rule, index) => normalizeBlockedPortRule(rule, `${source}:blockedPorts[${index}]`)),
+    };
+}
+function normalizeBlockedPortRule(rule, label) {
+    const port = Number(rule.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw new Error(`${label}.port must be an integer from 1 to 65535`);
+    }
+    const scope = rule.scope ?? "both";
+    if (scope !== "local" && scope !== "tailscale" && scope !== "both") {
+        throw new Error(`${label}.scope must be "local", "tailscale", or "both"`);
+    }
+    const reason = typeof rule.reason === "string" && rule.reason.trim() ? rule.reason.trim() : "Blocked by lizardtail configuration.";
+    return { port, scope, reason };
+}
+function findBlockedPortRule(config, port, scope) {
+    return config.blockedPorts.find((rule) => rule.port === port && (rule.scope === "both" || rule.scope === scope || rule.scope === undefined));
+}
+function assertPortAllowed(config, port, scope) {
+    const rule = findBlockedPortRule(config, port, scope);
+    if (!rule)
+        return;
+    const label = scope === "tailscale" ? "Tailscale HTTPS" : "local";
+    throw new Error(`refusing to use ${label} port ${port}: ${rule.reason}`);
+}
+export function stripAnsi(input) {
+    return input.replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, "");
+}
+export function detectPortFromText(text) {
+    const candidates = detectPortCandidates(text);
+    candidates.sort((a, b) => b.score - a.score);
+    return candidates[0]?.port;
+}
+function detectPortCandidates(text) {
+    const clean = stripAnsi(text);
+    const candidates = [];
+    for (const line of clean.split(/\r?\n/)) {
+        candidates.push(...detectPortCandidatesFromLine(line));
+    }
+    return candidates;
+}
+function detectPortCandidatesFromLine(line) {
+    const candidates = [];
+    const lowerLine = line.toLowerCase();
+    const lineLooksLikeDuration = /\b\d{1,5}\s*ms\b/i.test(line);
+    const lineLooksLikeServer = /\b(server|listening|started|running)\b/i.test(line) || /\[server\]/i.test(line);
+    const lineLooksLikeVite = /\[vite\]|\bvite\b/i.test(line);
+    const localUrlPattern = /https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]|::1):(\d{1,5})/gi;
+    for (const match of line.matchAll(localUrlPattern)) {
+        const port = validDetectedPort(match[2]);
+        if (!port)
+            continue;
+        let score = 70;
+        if (lineLooksLikeServer)
+            score += 30;
+        if (lineLooksLikeVite)
+            score -= 15;
+        if (match[1] === "0.0.0.0")
+            score -= 10;
+        candidates.push({ port, score });
+    }
+    if (lineLooksLikeDuration)
+        return candidates;
+    const portPhrase = line.match(/\b(?:port|PORT)\s*(?:=|:|is|on)?\s*(\d{2,5})\b/);
+    if (portPhrase?.[1]) {
+        const port = validDetectedPort(portPhrase[1]);
+        if (port)
+            candidates.push({ port, score: lowerLine.includes("in use") ? 20 : 45 });
+    }
+    const serverPort = line.match(/\b(?:listening|started|running|server)\b[^\n\r]*:(\d{2,5})\b/i);
+    if (serverPort?.[1]) {
+        const port = validDetectedPort(serverPort[1]);
+        if (port)
+            candidates.push({ port, score: lineLooksLikeServer ? 60 : 40 });
+    }
+    return candidates;
+}
+function validDetectedPort(value) {
+    const port = Number(value);
+    return Number.isInteger(port) && port > 0 && port <= 65_535 ? port : undefined;
+}
+export function detectLaravelViteServers(text) {
+    const clean = stripAnsi(text);
+    const detection = {};
+    const appMatch = clean.match(/\[server\][^\n\r]*Server running on \[http:\/\/(?:127\.0\.0\.1|localhost|0\.0\.0\.0|\[::1\]|::1):(\d{1,5})\]/i);
+    const appPort = appMatch?.[1] ? validDetectedPort(appMatch[1]) : undefined;
+    if (appPort)
+        detection.appPort = appPort;
+    const viteMatch = [...clean.matchAll(/\[vite\][^\n\r]*(?:Local:)\s*http:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]|::1):(\d{1,5})\/?/gi)].at(-1);
+    const vitePort = viteMatch?.[2] ? validDetectedPort(viteMatch[2]) : undefined;
+    if (vitePort) {
+        detection.vitePort = vitePort;
+        detection.viteHost = normalizeLocalHost(viteMatch?.[1] ?? "localhost");
+    }
+    return detection;
+}
+function normalizeLocalHost(host) {
+    return host === "[::1]" || host === "::1" ? "localhost" : host;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isTailscaleServePermissionError(error) {
+    const message = errorMessage(error).toLowerCase();
+    return message.includes("access denied") && (message.includes("sudo tailscale serve") || message.includes("sudo tailscale funnel") || message.includes("operator"));
+}
+function tailscaleExposeCommand(target, tailscalePort, mode) {
+    return [mode, "--bg", "--https", String(tailscalePort), target];
+}
+function tailscaleUrl(dnsName, tailscalePort) {
+    return tailscalePort === undefined ? `https://${dnsName}` : `https://${dnsName}:${tailscalePort}`;
+}
+function tailscaleServePermissionHelp(target, tailscalePort, mode) {
+    const label = mode === "funnel" ? "Funnel" : "Serve";
+    return `Tailscale refused to update ${label} config without elevated privileges.
+
+Run this once to let your user manage Tailscale ${label}:
+
+  sudo tailscale set --operator=$USER
+
+Then rerun lizardtail.
+
+Or expose this server manually with:
+
+  sudo tailscale ${tailscaleExposeCommand(target, tailscalePort, mode).join(" ")}`;
+}
+async function exec(command, args, opts = {}) {
+    const childEnv = opts.env ?? process.env;
+    const child = spawn(command, args, {
+        stdio: [opts.input ? "pipe" : "ignore", "pipe", "pipe"],
+        env: childEnv,
+    });
+    let stdout = "";
+    let stderr = "";
+    if (!child.stdout || !child.stderr) {
+        throw new Error(`failed to capture output for ${command}`);
+    }
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+    });
+    if (opts.input) {
+        if (!child.stdin)
+            throw new Error(`failed to write input for ${command}`);
+        child.stdin.end(opts.input);
+    }
+    const [code, signal] = (await Promise.race([
+        once(child, "exit"),
+        once(child, "error").then(([error]) => {
+            throw error;
+        }),
+    ]));
+    if (code !== 0) {
+        const reason = signal ? `signal ${signal}` : `exit code ${code}`;
+        throw new Error(`${command} ${args.join(" ")} failed with ${reason}\n${stderr || stdout}`.trim());
+    }
+    return { stdout, stderr };
+}
+export async function waitForOpenPort(host, port, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const isOpen = await new Promise((resolve) => {
+            const socket = net.connect({ host, port });
+            const done = (result) => {
+                socket.destroy();
+                resolve(result);
+            };
+            socket.setTimeout(500);
+            socket.once("connect", () => done(true));
+            socket.once("timeout", () => done(false));
+            socket.once("error", () => done(false));
+        });
+        if (isOpen)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    throw new Error(`timed out waiting for ${host}:${port} to accept connections`);
+}
+async function getTailscaleDnsName() {
+    const { stdout } = await exec("tailscale", ["status", "--json"]);
+    const status = JSON.parse(stdout);
+    return status.Self?.DNSName?.replace(/\.$/, "");
+}
+async function getTailscaleExposureStatus(mode) {
+    try {
+        const { stdout } = await exec("tailscale", [mode, "status", "--json"]);
+        return JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+function collectTailscaleStatusPorts(status, usedPorts) {
+    if (!status?.Web)
+        return;
+    for (const key of Object.keys(status.Web)) {
+        const match = key.match(/:(\d{2,5})$/);
+        const port = match?.[1] ? validDetectedPort(match[1]) : undefined;
+        if (port)
+            usedPorts.add(port);
+    }
+}
+async function resolveTailscaleHttpsPort(_target, requestedPort, config = DEFAULT_CONFIG) {
+    if (requestedPort !== undefined)
+        return requestedPort;
+    return chooseTailscaleHttpsPort(undefined, config);
+}
+async function chooseTailscaleHttpsPort(excludedPort, config = DEFAULT_CONFIG) {
+    const usedPorts = new Set();
+    collectTailscaleStatusPorts(await getTailscaleExposureStatus("serve"), usedPorts);
+    collectTailscaleStatusPorts(await getTailscaleExposureStatus("funnel"), usedPorts);
+    for (let port = DEFAULT_TAILSCALE_HTTPS_PORT; port <= MAX_AUTO_TAILSCALE_HTTPS_PORT; port += 1) {
+        if (port === excludedPort || usedPorts.has(port) || findBlockedPortRule(config, port, "tailscale"))
+            continue;
+        return port;
+    }
+    throw new Error("could not find an available Tailscale HTTPS port");
+}
+async function writeLaravelHotFile(viteUrl) {
+    const publicDir = path.join(process.cwd(), "public");
+    if (!existsSync(publicDir))
+        return undefined;
+    const hotPath = path.join(publicDir, "hot");
+    await writeFile(hotPath, viteUrl);
+    return hotPath;
+}
+async function startCorsProxy(targetHost, targetPort) {
+    const server = createServer((incoming, response) => {
+        if (incoming.method === "OPTIONS") {
+            response.writeHead(204, corsHeaders());
+            response.end();
+            return;
+        }
+        const upstream = httpRequest({
+            host: targetHost,
+            port: targetPort,
+            method: incoming.method,
+            path: incoming.url,
+            headers: { ...incoming.headers, host: `${targetHost}:${targetPort}` },
+        }, (upstreamResponse) => {
+            response.writeHead(upstreamResponse.statusCode ?? 502, {
+                ...upstreamResponse.headers,
+                ...corsHeaders(),
+            });
+            upstreamResponse.pipe(response);
+        });
+        upstream.on("error", (error) => {
+            response.writeHead(502, corsHeaders());
+            response.end(`lizardtail Vite proxy error: ${error.message}`);
+        });
+        incoming.pipe(upstream);
+    });
+    server.on("upgrade", (request, socket, head) => {
+        const upstream = net.connect(targetPort, targetHost, () => {
+            upstream.write(`${request.method ?? "GET"} ${request.url ?? "/"} HTTP/${request.httpVersion}\r\n`);
+            for (const [name, value] of Object.entries(request.headers)) {
+                if (value === undefined)
+                    continue;
+                upstream.write(`${name}: ${Array.isArray(value) ? value.join(",") : value}\r\n`);
+            }
+            upstream.write(`\r\n`);
+            if (head.length > 0)
+                upstream.write(head);
+            socket.pipe(upstream).pipe(socket);
+        });
+        upstream.on("error", () => socket.destroy());
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("failed to start Vite CORS proxy");
+    return { host: "127.0.0.1", port: address.port };
+}
+function corsHeaders() {
+    return {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS",
+        "Access-Control-Allow-Headers": "*",
+    };
+}
+async function exposeWithTailscaleDetailed(host, port, tailscalePort, publicExposure = false, config) {
+    const resolvedConfig = config ?? (await loadConfig());
+    assertPortAllowed(resolvedConfig, port, "local");
+    await exec("tailscale", ["status"]);
+    const target = `http://${host}:${port}`;
+    const resolvedTailscalePort = await resolveTailscaleHttpsPort(target, tailscalePort, resolvedConfig);
+    assertPortAllowed(resolvedConfig, resolvedTailscalePort, "tailscale");
+    const mode = publicExposure ? "funnel" : "serve";
+    try {
+        await exec("tailscale", tailscaleExposeCommand(target, resolvedTailscalePort, mode));
+    }
+    catch (firstError) {
+        if (isTailscaleServePermissionError(firstError)) {
+            throw new Error(tailscaleServePermissionHelp(target, resolvedTailscalePort, mode));
+        }
+        if (host !== "127.0.0.1" && host !== "localhost")
+            throw firstError;
+        try {
+            await exec("tailscale", tailscaleExposeCommand(String(port), resolvedTailscalePort, mode));
+        }
+        catch (fallbackError) {
+            if (isTailscaleServePermissionError(fallbackError)) {
+                throw new Error(tailscaleServePermissionHelp(target, resolvedTailscalePort, mode));
+            }
+            throw fallbackError;
+        }
+    }
+    const { stdout } = await exec("tailscale", ["status", "--json"]);
+    const status = JSON.parse(stdout);
+    const dnsName = status.Self?.DNSName?.replace(/\.$/, "");
+    if (dnsName)
+        return { url: tailscaleUrl(dnsName, resolvedTailscalePort), httpsPort: resolvedTailscalePort, mode };
+    const ip = status.Self?.TailscaleIPs?.find((value) => /^\d+\.\d+\.\d+\.\d+$/.test(value));
+    if (ip)
+        return { url: tailscaleUrl(ip, resolvedTailscalePort), httpsPort: resolvedTailscalePort, mode };
+    throw new Error("could not determine this device's Tailscale DNS name or IP");
+}
+export async function exposeWithTailscale(host, port, tailscalePort, publicExposure = false) {
+    return (await exposeWithTailscaleDetailed(host, port, tailscalePort, publicExposure)).url;
+}
+async function removeTailscaleExposurePort(port, mode) {
+    await exec("tailscale", [mode, `--https=${port}`, "off"]);
+}
+export async function main() {
+    const argv = process.argv.slice(2);
+    if (await handleMetaCommand(argv))
+        return;
+    const options = parseArgs(argv);
+    const config = await loadConfig();
+    const [command, ...args] = options.command;
+    const tailscaleDnsName = await getTailscaleDnsName().catch(() => undefined);
+    const childEnv = { ...process.env, FORCE_COLOR: process.env.FORCE_COLOR ?? "1" };
+    if (tailscaleDnsName) {
+        childEnv.__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS = childEnv.__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS
+            ? `${childEnv.__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS},${tailscaleDnsName}`
+            : tailscaleDnsName;
+    }
+    const child = spawn(command, args, {
+        stdio: ["inherit", "pipe", "pipe"],
+        env: childEnv,
+    });
+    let exposed = false;
+    let exposing;
+    let recentOutput = "";
+    let detectionTimer;
+    const createdTailscalePorts = new Map();
+    const cleanupTailscaleServe = async () => {
+        for (const [port, mode] of createdTailscalePorts) {
+            try {
+                await removeTailscaleExposurePort(port, mode);
+                console.error(`lizardtail: removed Tailscale ${mode === "funnel" ? "Funnel" : "Serve"} mapping on HTTPS port ${port}`);
+            }
+            catch (error) {
+                console.error(`lizardtail: failed to remove Tailscale ${mode === "funnel" ? "Funnel" : "Serve"} mapping on HTTPS port ${port}: ${errorMessage(error)}`);
+            }
+        }
+        createdTailscalePorts.clear();
+    };
+    const stopChild = () => {
+        if (!child.killed)
+            child.kill("SIGTERM");
+    };
+    const expose = (port) => {
+        if (exposed || exposing)
+            return;
+        exposed = true;
+        exposing = (async () => {
+            const localUrl = `http://${options.host}:${port}`;
+            console.error(`\nlizardtail: detected local server on ${localUrl}`);
+            assertPortAllowed(config, port, "local");
+            if (options.openCheck)
+                await waitForOpenPort(options.host, port, 10_000);
+            const exposure = await exposeWithTailscaleDetailed(options.host, port, options.tailscalePort, options.public, config);
+            createdTailscalePorts.set(exposure.httpsPort, exposure.mode);
+            console.error(`lizardtail: serving via Tailscale: ${exposure.url}`);
+            console.error(`lizardtail: cleanup command: tailscale ${exposure.mode} --https=${exposure.httpsPort} off`);
+            console.error("");
+        })().catch((error) => {
+            console.error(`lizardtail: failed to expose server: ${errorMessage(error)}`);
+            stopChild();
+            process.exitCode = 1;
+        });
+    };
+    const exposeLaravelVite = (appPort, vitePort, viteHost) => {
+        if (exposed || exposing)
+            return;
+        exposed = true;
+        exposing = (async () => {
+            const appLocalUrl = `http://${options.host}:${appPort}`;
+            const viteLocalUrl = `http://${viteHost}:${vitePort}`;
+            console.error(`\nlizardtail: detected Laravel app server on ${appLocalUrl}`);
+            console.error(`lizardtail: detected Vite asset server on ${viteLocalUrl}`);
+            assertPortAllowed(config, appPort, "local");
+            assertPortAllowed(config, vitePort, "local");
+            if (options.openCheck) {
+                await waitForOpenPort(options.host, appPort, 10_000);
+                await waitForOpenPort(viteHost, vitePort, 10_000);
+            }
+            const appExposure = await exposeWithTailscaleDetailed(options.host, appPort, options.tailscalePort, options.public, config);
+            createdTailscalePorts.set(appExposure.httpsPort, appExposure.mode);
+            const viteProxy = await startCorsProxy(viteHost, vitePort);
+            const viteTailscalePort = options.viteTailscalePort ?? (await chooseTailscaleHttpsPort(appExposure.httpsPort, config));
+            const viteExposure = await exposeWithTailscaleDetailed(viteProxy.host, viteProxy.port, viteTailscalePort, options.public, config);
+            createdTailscalePorts.set(viteExposure.httpsPort, viteExposure.mode);
+            const hotPath = await writeLaravelHotFile(viteExposure.url);
+            console.error(`lizardtail: serving Laravel via Tailscale: ${appExposure.url}`);
+            console.error(`lizardtail: serving Vite assets via Tailscale: ${viteExposure.url}`);
+            console.error(`lizardtail: proxying Vite through local CORS proxy: http://${viteProxy.host}:${viteProxy.port} -> ${viteLocalUrl}`);
+            if (hotPath)
+                console.error(`lizardtail: wrote Laravel Vite hot file: ${hotPath}`);
+            console.error(`lizardtail: cleanup command: tailscale ${appExposure.mode} --https=${appExposure.httpsPort} off`);
+            console.error(`lizardtail: cleanup command: tailscale ${viteExposure.mode} --https=${viteExposure.httpsPort} off`);
+            console.error("");
+        })().catch((error) => {
+            console.error(`lizardtail: failed to expose Laravel/Vite servers: ${errorMessage(error)}`);
+            stopChild();
+            process.exitCode = 1;
+        });
+    };
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    const inspectChunk = (chunk) => {
+        recentOutput = (recentOutput + chunk).slice(-8_000);
+        const detectedPort = detectPortFromText(recentOutput);
+        if (!detectedPort || exposed || exposing)
+            return;
+        if (detectionTimer)
+            clearTimeout(detectionTimer);
+        detectionTimer = setTimeout(() => {
+            detectionTimer = undefined;
+            const laravelVite = detectLaravelViteServers(recentOutput);
+            if (laravelVite.appPort && laravelVite.vitePort) {
+                exposeLaravelVite(laravelVite.appPort, laravelVite.vitePort, laravelVite.viteHost ?? "localhost");
+                return;
+            }
+            const settledPort = detectPortFromText(recentOutput);
+            if (settledPort)
+                expose(settledPort);
+        }, DETECTION_SETTLE_MS);
+    };
+    child.stdout.on("data", (chunk) => {
+        process.stdout.write(chunk);
+        if (!options.port)
+            inspectChunk(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+        process.stderr.write(chunk);
+        if (!options.port)
+            inspectChunk(chunk);
+    });
+    child.on("error", (error) => {
+        console.error(`lizardtail: failed to start ${command}: ${error.message}`);
+        process.exit(1);
+    });
+    if (options.port)
+        expose(options.port);
+    const timeout = options.port
+        ? undefined
+        : setTimeout(() => {
+            if (!exposed) {
+                console.error(`lizardtail: no server port detected within ${options.timeoutMs}ms`);
+                stopChild();
+                process.exitCode = 1;
+            }
+        }, options.timeoutMs);
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.once(signal, () => {
+            child.kill(signal);
+        });
+    }
+    const [code, signal] = (await once(child, "exit"));
+    if (timeout)
+        clearTimeout(timeout);
+    if (detectionTimer)
+        clearTimeout(detectionTimer);
+    if (exposing)
+        await exposing;
+    await cleanupTailscaleServe();
+    if (signal)
+        process.kill(process.pid, signal);
+    process.exit(code ?? process.exitCode ?? 0);
+}
+function isCliEntrypoint() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+    }
+    catch {
+        return false;
+    }
+}
+if (isCliEntrypoint()) {
+    main().catch((error) => {
+        console.error(`lizardtail: ${errorMessage(error)}`);
+        process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "lizardtail",
+  "version": "0.1.0",
+  "description": "Run a dev server command, detect its port, expose it with Tailscale Serve or Funnel, and print the URL.",
+  "type": "module",
+  "bin": {
+    "lizardtail": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "test": "npm run build && tsx --test tests/**/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "tailscale",
+    "serve",
+    "dev-server",
+    "cli",
+    "tailnet",
+    "localhost"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "homepage": "https://github.com/dasomji/lizardtail#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dasomji/lizardtail.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dasomji/lizardtail/issues"
+  }
+}