@hamedb89/localghost 0.1.9 → 0.1.12

package/docs/ghost-tunnel.md

@@ -9,7 +9,7 @@ Ghost Tunnel is the production-facing Localghost entrypoint for apps that want a
 For Social Workouts, the default namespace is:
 
 ```txt
-<route>-<project>-<owner>.ghost.socialworkouts.app
+<route>-<project>-<owner>.ghost.moonlit-otter.example
 ```
 
 The feature is off by default. Opt in from `localghost.config.mjs`:
@@ -19,18 +19,20 @@ import { defineLocalghostConfig } from "@hamedb89/localghost";
 
 export default defineLocalghostConfig({
   ghostTunnel: {
-    domains: "socialworkouts.app",
-    mode: "manual"
+    domains: "moonlit-otter.example",
+    mode: "manual",
+    adapter: "vercel",
+    transport: "none"
   }
 });
 ```
 
-With `ghostTunnel: { domains }`, route output and Vite startup output use local defaults for `route`, `project`, and `owner`, then fill the configured domain:
+With `ghostTunnel: { domains }` in the default manual mode, route output and Vite startup output use local defaults for `route`, `project`, and `owner`, then fill the configured domain:
 
 ```txt
 localghost ghost tunnel
   mode: manual
-  expected: https://app-decision-layer-hamed.ghost.socialworkouts.app/
+  expected: https://app-decision-layer-hamed.ghost.moonlit-otter.example/
 ```
 
 Without `domains`, the log keeps the production domain wildcarded with `*`:
@@ -43,12 +45,65 @@ localghost ghost tunnel
 
 `manual` is the default activation mode. `ghostTunnel: "manual"` and `ghostTunnel: "public"` are shorthand modes. Use `enabled: false` to keep domains/config in the file without exposing the tunnel surface.
 
+Public mode keeps the namespace flexible unless you configure a preview. This is useful for deployed wildcard endpoints that react to whichever route arrives:
+
+```txt
+localghost ghost tunnel
+  mode: public
+  configured: https://<route>-<project>-<owner>.ghost.moonlit-otter.example/
+```
+
+The adapter describes where the wildcard ingress runs. The transport describes how that deployed ingress reaches your local machine. The lowest-risk smoke path is the same-project Vercel adapter with no public-to-local transport:
+
+```js
+export default defineLocalghostConfig({
+  ghostTunnel: {
+    domains: "copper-comet.example",
+    mode: "public",
+    requireAuth: false,
+    adapter: {
+      provider: "vercel",
+      strategy: "same-project"
+    },
+    transport: "none"
+  }
+});
+```
+
+`transport: "none"` means the wildcard host is intercepted by the deployed app and resolved against `.ghosttunnel`, but no live public-to-local stream is established yet. This is the right first slice for proving routing, exact-host lookup, and response semantics before adding a real transport.
+
+The split is intentional:
+
+- `adapter`: where ingress lives, for example the same Vercel project or a separate relay app.
+- `transport`: how public traffic gets back to your local machine.
+
+Today `transport: "none"`, `transport: "ip"`, and `transport: "tunnel"` are implemented. The `tunnel` transport is the drop-in shared-state version: deployed ingress queues the request in Redis, the local agent polls that queue, forwards to `127.0.0.1:<port>`, and writes the response back.
+
+`transport: "ip"` is the thinnest direct-address transport. The deployed ingress still validates the ghost host and resolves the exact route from `.ghosttunnel`, but the shared URL also carries a signed IP transport token. The handler then redirects to that address plus the configured local port. This keeps the route and port in repo truth while making the shared address explicit.
+
+For LAN or private-address use, opt in explicitly:
+
+```js
+export default defineLocalghostConfig({
+  ghostTunnel: {
+    domains: "copper-comet.example",
+    mode: "public",
+    requireAuth: false,
+    adapter: "vercel",
+    transport: {
+      kind: "ip",
+      allowPrivateNetworkAddress: true
+    }
+  }
+});
+```
+
 Use object form to override defaults or provide a concrete preview URL:
 
 ```js
 export default defineLocalghostConfig({
   ghostTunnel: {
-    domains: "socialworkouts.app",
+    domains: "moonlit-otter.example",
     preview: {
       route: "plan",
       project: "summer-base",
@@ -63,9 +118,170 @@ export default defineLocalghostConfig({
 1. Add `ghostTunnel: { domains: "your-domain.com" }`, `ghostTunnel: "manual"`, or `ghostTunnel.preview` to `localghost.config.mjs`.
 2. Point the wildcard DNS record for `*.ghost.<your-domain>` at the deployed app.
 3. Route `*.ghost.<your-domain>` to the same production app that serves the Vite build.
-4. In production request handling, read the Localghost project config without resolving local `.localghost` setup.
-5. Construct tunnel URLs from `route`, `project`, and `owner`.
-6. Validate the incoming request host, protocol, and auth before serving the tunnel surface.
+4. Add a same-project ingress handler that intercepts the wildcard host before the static app shell.
+5. In that handler, read the Localghost project config without resolving local `.localghost` setup.
+6. Construct tunnel URLs from `route`, `project`, and `owner`.
+7. Validate the incoming request host, protocol, and auth before serving the tunnel surface.
+8. For `transport: "tunnel"`, provide Redis REST env vars to the deployed handler and run `localghost tunnel` beside the local dev server.
+
+## Exact Route File
+
+Use `.ghosttunnel` as the exact-host companion to `.localghost`:
+
+```txt
+decisionlayer-decision-layer-hamedbahrami.ghost.copper-comet.example 5173
+notes-decision-layer-hamedbahrami.ghost.copper-comet.example 4173
+```
+
+The format matches `.localghost`: one exact host and one local port per line. Localghost exposes `readGhostTunnelEntries()`, `findGhostTunnelEntry()`, and `resolveGhostTunnelRequest()` so a same-project ingress handler can parse the wildcard host and look up its exact local target without inventing a second config format.
+
+## Same-Project Vercel Handler
+
+For a drop-in Vite app on Vercel, connect `*.ghost.<your-domain>` to the same project, then rewrite ghost hosts into a function instead of the static app:
+
+```json
+{
+  "rewrites": [
+    {
+      "source": "/:path*",
+      "has": [{ "type": "host", "value": "(.*)\\.ghost\\.copper-comet\\.example" }],
+      "destination": "/api/ghost"
+    }
+  ]
+}
+```
+
+Then the handler can resolve the request and return a safe relay status, a signed IP redirect, or a Redis-backed tunnel response:
+
+```ts
+import { createVercelGhostTunnelHandler } from "@hamedb89/localghost";
+
+export default createVercelGhostTunnelHandler({
+  cwd: process.cwd(),
+  domain: "copper-comet.example",
+  authenticated: false,
+  ipSigningSecret: process.env.LOCALGHOST_IP_SIGNING_SECRET
+});
+```
+
+`ipSigningSecret` is only required for `transport: "ip"`. For `transport: "tunnel"`, the handler uses the Redis REST env vars above unless you pass a custom `tunnelStore`.
+
+## Signed IP URLs
+
+Use `constructGhostTunnelIpUrl()` to create a shareable URL for `transport: "ip"`:
+
+```ts
+import { constructGhostTunnelIpUrl } from "@hamedb89/localghost";
+
+const url = constructGhostTunnelIpUrl({
+  domain: "copper-comet.example",
+  route: "decisionlayer",
+  project: "decision-layer",
+  owner: "hamedbahrami",
+  path: "/week/1",
+  address: "203.0.113.10",
+  signingSecret: process.env.LOCALGHOST_IP_SIGNING_SECRET!,
+  ghostTunnel: {
+    mode: "public",
+    domains: "copper-comet.example",
+    transport: "ip"
+  }
+});
+```
+
+That shared URL still uses the wildcard ghost host, but it also carries a signed `__localghost=...` token. The deployed handler verifies that token against the exact ghost host, reads the local port from `.ghosttunnel`, and redirects to the direct address:
+
+```txt
+https://decisionlayer-decision-layer-hamedbahrami.ghost.copper-comet.example/week/1?__localghost=...
+  -> http://203.0.113.10:5173/week/1
+```
+
+This is intentionally simple and explicit:
+
+- the repo owns the route and port through `.ghosttunnel`
+- the shared link owns the direct address
+- the deployed handler only accepts signed IP claims bound to the exact ghost host
+
+It is not a hidden reverse proxy. After redirect, the browser talks directly to the target address.
+
+## Redis Tunnel Transport
+
+Use `transport: "tunnel"` when you want the shared URL to keep going through the deployed Ghost Tunnel host instead of redirecting the browser to a direct IP address:
+
+```js
+export default defineLocalghostConfig({
+  ghostTunnel: {
+    domains: "copper-comet.example",
+    mode: "public",
+    requireAuth: false,
+    adapter: "vercel",
+    transport: {
+      kind: "tunnel",
+      store: {
+        provider: "vercel-redis",
+        env: "auto"
+      }
+    }
+  }
+});
+```
+
+`env: "auto"` reads Redis REST variables from the deployed function environment. The current lookup order is:
+
+```txt
+LOCALGHOST_REDIS_REST_URL / LOCALGHOST_REDIS_REST_TOKEN
+UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN
+KV_REST_API_URL / KV_REST_API_TOKEN
+REDIS_REST_API_URL / REDIS_REST_API_TOKEN
+```
+
+For Vercel, add a Redis Marketplace integration to the project and make sure it exposes REST URL/token variables to the Production environment. Legacy Vercel KV REST variables still work, but new projects should treat Redis as the current provider shape.
+
+Run the local agent next to your dev server:
+
+```sh
+localghost tunnel
+```
+
+The agent reads `localghost.config.mjs`, reads exact hosts from `.ghosttunnel`, sends short route heartbeats to Redis, polls for queued requests, and serves them from local ports. It does not open arbitrary targets; each public host must exist in `.ghosttunnel`.
+
+The MVP transport is polling-based and intentionally bounded. It is good for app previews and demos, not large uploads, streaming responses, or high-throughput production traffic. Defaults are a 25 second ingress wait window, 30 second route heartbeat, 60 second request TTL, 1 MiB request body cap, and 5 MiB response body cap. Override those on `transport` only when the app needs it.
+
+## Vercel DNS
+
+For Vercel, add the Ghost Tunnel wildcard domain to the project first:
+
+```txt
+*.ghost.copper-comet.example
+```
+
+Then create the DNS record that points that wildcard at the same Vercel project. In Vercel-managed DNS, the record name is relative to the zone:
+
+```txt
+Name:  *.ghost
+Type:  ALIAS
+Value: <the Vercel DNS target shown for the project>
+TTL:   60
+```
+
+For example, if Vercel shows `cname.vercel-dns-016.com` as the project target, use the fully-qualified value with the trailing dot when the DNS form requires it:
+
+```txt
+Name:  *.ghost
+Type:  ALIAS
+Value: cname.vercel-dns-016.com.
+TTL:   60
+```
+
+When DNS is managed somewhere else, use the provider's wildcard subdomain shape:
+
+```txt
+Name:  *.ghost
+Type:  CNAME
+Value: cname.vercel-dns-016.com.
+```
+
+Do not use only `*` for Ghost Tunnel. A record named `*` covers `anything.copper-comet.example`, but Ghost Tunnel URLs look like `decisionlayer-decision-layer-hamed.ghost.copper-comet.example`, so the wildcard must live under `ghost`.
 
 ```ts
 import {
@@ -77,7 +293,7 @@ import {
 const { config } = await readLocalghostProjectConfig();
 
 const url = constructGhostTunnelUrl({
-  domain: "socialworkouts.app",
+  domain: "moonlit-otter.example",
   route: "plan",
   project: "summer-base",
   owner: "hamed",
@@ -86,13 +302,13 @@ const url = constructGhostTunnelUrl({
 
 const route = assertSecureGhostTunnelRequest({
   host: request.headers.get("host") ?? "",
-  domain: "socialworkouts.app",
+  domain: "moonlit-otter.example",
   protocol: request.url.startsWith("https:") ? "https" : "http",
   authenticated: Boolean(session),
   ghostTunnel: config.ghostTunnel
 });
 
-// url is https://plan-summer-base-hamed.ghost.socialworkouts.app/
+// url is https://plan-summer-base-hamed.ghost.moonlit-otter.example/
 // route.namespace is { route: "plan", project: "summer-base", owner: "hamed" }.
 ```
 
@@ -101,7 +317,7 @@ When `ghostTunnel.preview` is configured, Localghost logs the concrete preview U
 ```txt
 localghost ghost tunnel
   mode: manual
-  expected: https://plan-summer-base-hamed.ghost.socialworkouts.app/
+  expected: https://plan-summer-base-hamed.ghost.moonlit-otter.example/
 ```
 
 In an interactive Vite terminal, press `g` to show the Ghost Tunnel configuration and open a numbered concrete URL. Wildcard `*` URLs are shown for observability, but the menu only opens configured concrete domains.
@@ -115,7 +331,7 @@ The default namespace tags are `route`, `project`, and `owner`, joined with `-`.
 ```js
 export default defineLocalghostConfig({
   ghostTunnel: {
-    domains: "socialworkouts.app"
+    domains: "moonlit-otter.example"
   }
 });
 ```
@@ -150,7 +366,7 @@ For custom tags, pass extra values to the constructor:
 
 ```ts
 constructGhostTunnelUrl({
-  domain: "socialworkouts.app",
+  domain: "moonlit-otter.example",
   route: "plan",
   project: "summer-base",
   owner: "hamed",
@@ -165,7 +381,7 @@ constructGhostTunnelUrl({
 
 - `ghostTunnel` is opt-in and resolves to disabled unless the project config enables it.
 - The default production entry host is `ghost.<your-domain>`, with a wildcard of `*.ghost.<your-domain>`.
-- The default wildcard label must be `route-project-owner`, such as `plan-summer-base-hamed.ghost.socialworkouts.app`.
+- The default wildcard label must be `route-project-owner`, such as `plan-summer-base-hamed.ghost.moonlit-otter.example`.
 - The configured spread tag may contain the namespace separator. By default, that is `project`.
 - Other namespace values cannot include the namespace separator, because parsing must be reversible.
 - Host labels must be DNS-safe lowercase ASCII labels after normalization.
@@ -175,7 +391,7 @@ constructGhostTunnelUrl({
 
 ## Relay Security
 
-Localghost relay is private by default. Public requests can select a Ghost Tunnel route, but they must never select the local target URL, hostname, IP, or port. There must be no `/proxy?url=...` style endpoint.
+Localghost relay is private by default. Public requests can select a Ghost Tunnel route, but they must never select an arbitrary local target URL or port. There must be no `/proxy?url=...` style endpoint.
 
 Route registration goes through an authenticated local agent:
 
@@ -186,7 +402,7 @@ import {
 } from "@hamedb89/localghost";
 
 const claim = signRelayRouteClaim({
-  host: "plan-summer-base-hamed.ghost.socialworkouts.app",
+  host: "plan-summer-base-hamed.ghost.moonlit-otter.example",
   scope: "socialworkouts:preview",
   agentId: "local-agent-1",
   expiresAt: new Date(Date.now() + 10 * 60 * 1000).toISOString()
@@ -220,6 +436,20 @@ The relay helpers enforce these rules:
 - `renderRelayOfflineResponse()` returns a safe offline page with no secrets or stack traces.
 - Vite integration continues to generate explicit `allowedHosts`; it never sets `allowedHosts: true`.
 
+For `transport: "ip"`, the handler uses a signed IP token instead of an open target selector:
+
+- `constructGhostTunnelIpUrl()` signs `{ host, address, protocol, expiresAt }`.
+- `resolveGhostTunnelIpRedirect()` rejects tampered, expired, wrong-host, or private-network claims unless private-network IPs are explicitly allowed.
+- The redirect target port still comes from the exact `.ghosttunnel` entry, not from the shared URL.
+
+For `transport: "tunnel"`, the handler uses the shared store instead of a target selector:
+
+- The deployed handler resolves the exact host from `.ghosttunnel`, then checks for a live route heartbeat.
+- The local agent only heartbeats exact hosts from `.ghosttunnel`.
+- Request and response bodies are size-limited and encoded through the store.
+- Hop-by-hop and `x-localghost-*` internal headers are stripped before forwarding.
+- If the route is missing, offline, or times out, the deployed handler returns a safe status page instead of leaking target details.
+
 Run the guardrail tests locally:
 
 ```sh

package/docs/localghost.1.md

@@ -7,6 +7,7 @@ localghost - friendly local hostnames for app repos
 ## Synopsis
 
 ```sh
+localghost [--cwd path] [--dry-run]
 localghost init [--write-scripts] [--config file] [--host host] [--port port]
 localghost doctor
 localghost setup [--project name] [--config file] [--config-pattern regex] [--https|--ssl]
@@ -15,12 +16,26 @@ localghost reset [--project name]
 localghost teardown [--project name] [--remove-caddyfile]
 localghost status [--ready] [--json]
 localghost ps [--json]
+localghost tunnel [--cwd path] [--config file] [--config-pattern regex] [--ghost-config file] [--target-host host]
 localghost update [--json]
-localghost dev [--config file] [--config-pattern regex] [--https|--ssl] [--setup] [--trust]
-localghost run [--config file] [--config-pattern regex] [--https|--ssl] [--setup] [--trust] [--dynamic-port] -- command
+localghost dev [--config file] [--config-pattern regex] [--https|--ssl] [--auto-repair yes|no] [--trust]
+localghost run [--config file] [--config-pattern regex] [--https|--ssl] [--auto-repair yes|no] [--trust] [--dynamic-port] -- command
 localghost print [--config file] [--config-pattern regex]
 ```
 
+With no subcommand, Localghost detects the package manager from `packageManager` or a lockfile, prefers a non-recursive `dev:raw` script, falls back to `dev`, and runs the result through the normal Caddy lifecycle. `--dry-run` prints the detected command without checking or changing machine setup. Set `command: ["pnpm", "dev:web"]` in `localghost.config.mjs` when inference should be explicit.
+
+For multiple independently started applications, configure `services` in `localghost.config.mjs`. Each service declares a unique name and host plus its project-relative working directory, requested port, and optional command. Bare `localghost` starts one Caddy process and all service commands, passes service-specific `LOCALGHOST_PORT`, `VITE_PORT`, and `LOCALGHOST_SERVICE` variables, and stops the group when any process exits.
+
+```js
+export default {
+  services: [
+    { name: "web", cwd: "apps/web", host: "xyz.localhost", port: 5173, command: ["pnpm", "dev"] },
+    { name: "api", cwd: "apps/api", host: "api.xyz.localhost", port: 8787, command: ["pnpm", "dev"] }
+  ]
+};
+```
+
 ## Description
 
 Localghost reads `.localghost`, optionally reads `localghost.config.mjs`, writes a managed `/etc/hosts` block, records `ops/local/localghost-state.json`, generates `ops/local/Caddyfile`, and runs a Caddy local proxy. The project name is derived from `package.json`, port `5173` is the fallback, HTTP is the default, dynamic ports are on by default, and local HTTPS is explicit with `--https`, `--ssl`, or `https: true` in `localghost.config.mjs`. It is intentionally small and explicit: no hidden installs, no full hosts-file rewrites, no surprise browser tabs, and no broad Vite `allowedHosts: true` shortcut.
@@ -78,6 +93,15 @@ Validates the HTTPS Caddyfile and runs `caddy trust --config <Caddyfile>` so bro
 localghost trust
 ```
 
+### repair
+
+Reconciles the managed hosts block, regenerates and validates the Caddyfile, and refreshes project setup state. Use `--https --trust` to also re-run Caddy's local certificate trust step.
+
+```sh
+localghost repair
+localghost repair --https --trust
+```
+
 ### teardown
 
 Removes the managed Localghost block from `/etc/hosts` for the selected project and records the action in `ops/local/localghost-state.json`. It leaves `ops/local/Caddyfile` in place unless `--remove-caddyfile` is passed.
@@ -112,6 +136,16 @@ localghost ps
 localghost ps --json
 ```
 
+### tunnel
+
+Runs the local Ghost Tunnel agent for `ghostTunnel.transport: "tunnel"`. The command reads the Localghost project config, reads exact public hosts from `.ghosttunnel`, sends route heartbeats to the configured Redis REST store, polls for queued requests, and serves them from the matching local port.
+
+```sh
+localghost tunnel
+```
+
+Use `--ghost-config <file>` when the exact route file is not `.ghosttunnel`. Use `--target-host <host>` when the local app listens somewhere other than `127.0.0.1`.
+
 ### update
 
 Checks npm for a newer Localghost release. Pass `--json` for scripts and agents.
@@ -130,7 +164,7 @@ localghost routes
 
 ### dev
 
-Requires setup to be ready, writes `ops/local/Caddyfile`, validates it, and runs Caddy. Supports `--config` and `--config-pattern`. HTTP is the default. Pass `--https` or `--ssl` to run a local HTTPS proxy. Pass `--setup` to explicitly allow `dev` to run setup first when setup is missing or stale. Pass `--trust` to force the Caddy trust step before the proxy stays running.
+Performs a read-only readiness check, repairs stale setup when needed, writes and validates `ops/local/Caddyfile`, and runs Caddy. Supports `--config` and `--config-pattern`. HTTP is the default. Pass `--https` or `--ssl` to run a local HTTPS proxy, `--auto-repair=no` for strict failure behavior, or `--trust` to force the Caddy trust step before the proxy stays running.
 
 ```sh
 localghost dev
@@ -146,15 +180,17 @@ localghost run --trust -- vite
 localghost run --dynamic-port=no -- vite
 ```
 
-By default, Localghost starts at the configured port and walks upward until `127.0.0.1:<port>` is free. Pass `--dynamic-port=no` when you want strict fixed-port behavior. Pass `--setup` to explicitly allow setup when the hosts block is missing or stale.
+By default, Localghost starts at the configured port and walks upward until `127.0.0.1:<port>` is free. It performs a read-only readiness check and repairs stale setup before starting the child. Pass `--dynamic-port=no` for strict fixed-port behavior or `--auto-repair=no` to fail instead of repairing.
 
-When `localghost.config.mjs` exists, `run`, `dev`, `setup`, `status`, `routes`, and the Vite plugin use it as an override layer. Most repos can skip it; add it only for decisions like `https: true`, `dynamicPort: false`, `wwwAlias: false`, custom ports, explicit project names, or the production `ghostTunnel` opt-in.
+When `localghost.config.mjs` exists, `run`, `dev`, `setup`, `status`, `routes`, and the Vite plugin use it as an override layer. Most repos can skip it; add it only for decisions like `https: true`, `dynamicPort: false`, `autoRepair: false`, `wwwAlias: false`, custom ports, explicit project names, or the production `ghostTunnel` opt-in.
 
 `ghostTunnel` does not change local Caddy or `/etc/hosts` setup. It marks `<route>-<project>-<owner>.ghost.<domain>` as a production app entrypoint. Use `ghostTunnel: { domains: "example.com", mode: "manual" }` when the production base domain is known, or omit `domains` to keep logs wildcarded as `https://<route>-<project>-<owner>.ghost.*/`. Production code can call `readLocalghostProjectConfig()`, `constructGhostTunnelUrl()`, and `assertSecureGhostTunnelRequest()` to read the flag, construct default tunnel URLs, validate the wildcard host shape, require HTTPS by default, and require an app-authenticated request by default.
 
-Relay helpers are private by default. Registration requires an authenticated local-agent bearer token plus an exact signed route claim. Targets must be explicit local host/port objects, dangerous ports are blocked, private/LAN targets require explicit opt-in, internal and hop-by-hop headers are stripped, sensitive logs are redacted, and offline agents get a safe 503 page.
+`ghostTunnel.transport` is separate from the deployment adapter. `transport: "none"` proves ingress and exact-route lookup without forwarding. `transport: "ip"` signs a direct address into the shared URL, verifies that token against the exact ghost host, and redirects to the signed address plus the local port from `.ghosttunnel`. `transport: "tunnel"` uses Redis REST env vars plus `localghost tunnel` to queue deployed requests for a local agent. For LAN or private-address IP redirects, set `transport: { kind: "ip", allowPrivateNetworkAddress: true }` explicitly.
+
+Relay helpers are private by default. Registration requires an authenticated local-agent bearer token plus an exact signed route claim. Targets must be explicit local host/port objects, dangerous ports are blocked, private/LAN targets require explicit opt-in, internal and hop-by-hop headers are stripped, sensitive logs are redacted, and offline agents get a safe 503 page. The IP transport follows the same posture: the shared URL carries only a signed `{ host, address, protocol, expiresAt }` claim, while the redirect port still comes from the exact `.ghosttunnel` entry.
 
-When `ghostTunnel` is configured, route output and Vite startup logs print local defaults for `route`, `project`, and `owner`. Add `ghostTunnel.domains` to fill one or more production base domains. When `ghostTunnel.preview` is configured with `route`, `project`, and `owner`, they print the concrete URL, inheriting `ghostTunnel.domains` unless `preview.domain` is set. In an interactive Vite terminal, press `g` to show Ghost Tunnel configuration and open a numbered concrete URL.
+When `ghostTunnel` is configured, route output and Vite startup logs print the production URL shape. Manual mode can fill local defaults for `route`, `project`, and `owner`; public mode leaves those slots as `<route>`, `<project>`, and `<owner>` unless `ghostTunnel.preview` pins a concrete URL. Add `ghostTunnel.domains` to fill one or more production base domains. When `ghostTunnel.preview` is configured with `route`, `project`, and `owner`, logs print the concrete URL, inheriting `ghostTunnel.domains` unless `preview.domain` is set. In an interactive Vite terminal, press `g` to show Ghost Tunnel configuration and open a numbered concrete URL.
 
 `dev` and `run` register active sessions in a user-local activity file so `localghost ps` can show what is running across projects.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hamedb89/localghost",
-  "version": "0.1.9",
+  "version": "0.1.12",
   "description": "Friendly local hostnames for app repos with .localghost, Caddy, /etc/hosts, and Vite.",
   "type": "module",
   "bin": {
@@ -45,6 +45,7 @@
     "macos:widget:build": "bash apps/macos-widget/build.sh",
     "dev": "tsx src/cli.ts",
     "test": "npm run build && node --test tests/*.test.mjs",
+    "test:e2e": "npm run build && node --test tests/e2e/*.test.mjs",
     "test:coverage": "npm run build && LOCALGHOST_TEST_SOURCE=1 node --import tsx --test --experimental-test-coverage --test-coverage-include=src/relay.ts --test-coverage-include=src/tunnel.ts --test-coverage-lines=90 --test-coverage-branches=75 --test-coverage-functions=100 tests/*.test.mjs",
     "test:cli": "npm run build && node --test tests/cli.test.mjs",
     "typecheck": "tsc --noEmit",