localpreview 0.2.3 → 0.2.5

package/README.md

@@ -8,8 +8,9 @@ server to a public URL.
 ```sh
 localpreview connect 3000
 localpreview connect https://localhost:3000
-localpreview connect 3000 --name proyecto
+localpreview connect 3000 --name my-app
 localpreview connect 3000 -l
+localpreview connect 5173 --capture localhost:4000
 ```
 
 `localpreview <target>` is still accepted as a deprecated compatibility alias and
@@ -21,6 +22,38 @@ Targets are parsed by `@localpreview/protocol`:
 - URLs must use `http` or `https`.
 - URL targets must include an explicit port.
 
+Run `localpreview -h` for public help. When `LOCALPREVIEW_ADMIN_TOKEN` is set in
+the environment, global help also lists admin commands.
+
+## Admin commands
+
+Subdomain cleanup is an admin-only operation. Export `LOCALPREVIEW_ADMIN_TOKEN`
+before running `clean`:
+
+```sh
+export LOCALPREVIEW_ADMIN_TOKEN=your-token
+localpreview clean my-app --force
+localpreview clean --all --force -l
+```
+
+Admin authorization is read from the environment only.
+
+`localpreview clean -h` and `localpreview list -h` show full admin help only when
+`LOCALPREVIEW_ADMIN_TOKEN` is set. Without it, you get public help plus a note
+that admin commands require the variable.
+
+Inspect active tunnels, Redis inventory drift, and sandbox leftovers without
+printing tokens or preview URLs:
+
+```sh
+localpreview list
+localpreview list --limit 20 --skip 20 -l
+```
+
+The list view prints a compact summary, page details, and a practical table with
+subdomain, short tunnel/sandbox ids, age, relay health, sandbox status, and the
+control-plane note for each row.
+
 ## Runtime Flow
 
 1. The CLI validates the target and optional `--name`.
@@ -42,6 +75,7 @@ browser -> control-plane -> relay -> CLI WebSocket -> local target
 The package is structured as small Effect-backed services:
 
 - `src/command.ts`: command parsing, legacy alias handling, and top-level flow.
+- `src/cli-ui.ts`: help text, terminal styling, and log formatting.
 - `src/config.ts`: runtime defaults and environment-derived limits.
 - `src/control-plane.ts`: tunnel create/delete HTTP adapter.
 - `src/relay-client.ts`: WebSocket lifecycle, signals, and relay event handling.
@@ -55,7 +89,8 @@ Effect.
 ## Defaults and Limits
 
 - Control-plane URL precedence:
-  `-l|--local` > `https://localpreview.dev`
+  `-l` / `--local` (shorthand for `--control-plane http://localhost:3000`) >
+  `https://localpreview.dev`
 - Request body limit: `10 MB`
 - Response body limit: `50 MB`
 - Local request timeout: `30 seconds`
@@ -66,6 +101,7 @@ Effect.
 Optional environment overrides:
 
 ```sh
+LOCALPREVIEW_ADMIN_TOKEN=...          # required for `clean` and `list`
 LOCALPREVIEW_REQUEST_BODY_LIMIT_BYTES=10485760
 LOCALPREVIEW_RESPONSE_BODY_LIMIT_BYTES=52428800
 LOCALPREVIEW_REQUEST_TIMEOUT_MS=30000
@@ -110,5 +146,6 @@ For a local end-to-end run, start the relay and control-plane first:
 ```sh
 pnpm dev:relay
 pnpm dev:web
+export LOCALPREVIEW_ADMIN_TOKEN=your-local-token
 pnpm localpreview connect 3000 -l
 ```

package/dist/capture-route.d.ts

@@ -26,6 +26,7 @@ export type ResolvedRoute = {
     readonly kind: "capture";
     readonly target: TunnelTarget;
 } | {
+    readonly capturePath: ParsedCapturePath;
     readonly kind: "invalid-capture";
     readonly message: string;
 } | {

package/dist/capture-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capture-route.d.ts","sourceRoot":"","sources":["../src/capture-route.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,wBAAwB,CAAC;AAEhC,eAAO,MAAM,mBAAmB,4BAA4B,CAAC;AAE7D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;CAC7C,CAAC;AAEF,KAAK,sBAAsB,GACvB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;CACpB,CAAC;AAEN;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,aAAa,MAAM,KAAG,sBA+CtD,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,4BAA4B,GAAI,QAAQ,iBAAiB,KAAG,MAC6B,CAAC;AAEvG,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,GAAI,UAAU,MAAM,KAAG,MACA,CAAC;AAE1D,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B,CAAC;AAEN,qFAAqF;AACrF,eAAO,MAAM,YAAY,GACvB,aAAa,MAAM,EACnB,eAAe,YAAY,EAC3B,UAAU,aAAa,CAAC,aAAa,CAAC,KACrC,aAyBF,CAAC"}
+{"version":3,"file":"capture-route.d.ts","sourceRoot":"","sources":["../src/capture-route.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,wBAAwB,CAAC;AAEhC,eAAO,MAAM,mBAAmB,4BAA4B,CAAC;AAE7D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;CAC7C,CAAC;AAEF,KAAK,sBAAsB,GACvB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;CACpB,CAAC;AAEN;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,aAAa,MAAM,KAAG,sBA+CtD,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,4BAA4B,GAAI,QAAQ,iBAAiB,KAAG,MAC6B,CAAC;AAEvG,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,GAAI,UAAU,MAAM,KAAG,MACA,CAAC;AAE1D,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B,CAAC;AAEN,qFAAqF;AACrF,eAAO,MAAM,YAAY,GACvB,aAAa,MAAM,EACnB,eAAe,YAAY,EAC3B,UAAU,aAAa,CAAC,aAAa,CAAC,KACrC,aA0BF,CAAC"}

package/dist/capture-route.js

@@ -59,6 +59,7 @@ export const resolveRoute = (requestPath, primaryTarget, captures) => {
     const capture = findCapture(captures, parsed.hostname, parsed.port);
     if (capture === undefined) {
         return {
+            capturePath: parsed,
             kind: "invalid-capture",
             message: `Capture route is not allowlisted: ${parsed.hostname}:${parsed.port}.`,
         };

package/dist/capture-shim.d.ts

@@ -1,8 +1,12 @@
 import type { CaptureTarget } from "@localpreview/protocol";
 import { encodeCaptureHostname } from "./capture-route.js";
 export { encodeCaptureHostname };
+type CaptureShimPrimaryTarget = {
+    readonly hostname: string;
+    readonly port: number;
+};
 /** Generates the inline browser shim injected into proxied HTML responses. */
-export declare const buildCaptureShimScript: (captures: ReadonlyArray<CaptureTarget>) => string;
+export declare const buildCaptureShimScript: (primary: CaptureShimPrimaryTarget, captures: ReadonlyArray<CaptureTarget>) => string;
 /** Injects the capture shim into an HTML document string. */
 export declare const injectCaptureShim: (html: string, shimScript: string) => string;
 /** Returns true when the response looks like HTML suitable for shim injection. */

package/dist/capture-shim.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capture-shim.d.ts","sourceRoot":"","sources":["../src/capture-shim.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAuB,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhF,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAEjC,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,GAAI,UAAU,aAAa,CAAC,aAAa,CAAC,KAAG,MAU/E,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,EAAE,YAAY,MAAM,KAAG,MAcpE,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,cAAc,GAAI,aAAa,MAAM,GAAG,IAAI,KAAG,OACa,CAAC;AAE1E,6DAA6D;AAC7D,eAAO,MAAM,0BAA0B,GACrC,SAAS,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAChD,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAI9B,CAAC;AAEL,qFAAqF;AACrF,eAAO,MAAM,mBAAmB,GAAI,QAAQ;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CACrC,KAAG,MAAkE,CAAC"}
+{"version":3,"file":"capture-shim.d.ts","sourceRoot":"","sources":["../src/capture-shim.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAuB,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhF,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAEjC,KAAK,wBAAwB,GAAG;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,GACjC,SAAS,wBAAwB,EACjC,UAAU,aAAa,CAAC,aAAa,CAAC,KACrC,MAWF,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,EAAE,YAAY,MAAM,KAAG,MAcpE,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,cAAc,GAAI,aAAa,MAAM,GAAG,IAAI,KAAG,OACa,CAAC;AAE1E,6DAA6D;AAC7D,eAAO,MAAM,0BAA0B,GACrC,SAAS,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAChD,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAI9B,CAAC;AAEL,qFAAqF;AACrF,eAAO,MAAM,mBAAmB,GAAI,QAAQ;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CACrC,KAAG,MAAkE,CAAC"}

package/dist/capture-shim.js

@@ -1,15 +1,16 @@
 import { CAPTURE_PATH_PREFIX, encodeCaptureHostname } from "./capture-route.js";
 export { encodeCaptureHostname };
 /** Generates the inline browser shim injected into proxied HTML responses. */
-export const buildCaptureShimScript = (captures) => {
+export const buildCaptureShimScript = (primary, captures) => {
     const config = JSON.stringify({
         captures: captures.map((capture) => ({
             hostname: capture.hostname,
             port: capture.port,
         })),
         prefix: CAPTURE_PATH_PREFIX,
+        primary,
     });
-    return `(function(){var cfg=${config};var caps=cfg.captures;var prefix=cfg.prefix;function normHost(h){return h==="::1"?"[::1]":h.toLowerCase();}function matchesCapture(url){var host=normHost(url.hostname);var port=url.port?Number(url.port):(url.protocol==="https:"?443:80);for(var i=0;i<caps.length;i++){var cap=caps[i];if(normHost(cap.hostname)===host&&cap.port===port){return true;}}return false;}function rewriteUrl(input){var url=new URL(input,window.location.href);if(!matchesCapture(url)){return input;}var proto=url.protocol.replace(":","");var host=encodeURIComponent(normHost(url.hostname));var path=url.pathname+url.search;return prefix+"/"+proto+"/"+host+"/"+url.port+path;}function warnUnsupported(api,url){console.error("[localpreview] "+api+" to captured local backend is not supported in v1: "+url+". Use fetch/XHR or run localpreview connect for that service directly.");}var origFetch=window.fetch;window.fetch=function(input,init){try{var url=typeof input==="string"?input:input instanceof URL?input.href:input.url;if(typeof url==="string"&&/^https?:\\/\\//.test(url)){var rewritten=rewriteUrl(url);if(rewritten!==url){return origFetch.call(this,rewritten,init);}}}catch(e){}return origFetch.call(this,input,init);};if(typeof XMLHttpRequest!=="undefined"){var origOpen=XMLHttpRequest.prototype.open;XMLHttpRequest.prototype.open=function(method,url){try{if(typeof url==="string"&&/^https?:\\/\\//.test(url)){var rewritten=rewriteUrl(url);if(rewritten!==url){return origOpen.call(this,method,rewritten);}}}catch(e){}return origOpen.apply(this,arguments);};}if(typeof window.WebSocket!=="undefined"){var OrigWebSocket=window.WebSocket;window.WebSocket=function(url,protocols){try{var parsed=new URL(url,window.location.href);if(matchesCapture(parsed)){warnUnsupported("WebSocket",url);throw new Error("LocalPreview does not proxy WebSocket connections to captured backends in v1.");}}catch(e){if(e instanceof Error&&e.message.indexOf("LocalPreview")!==-1){throw e;}}return protocols===undefined?new OrigWebSocket(url):new OrigWebSocket(url,protocols);};if(OrigWebSocket.prototype){window.WebSocket.prototype=OrigWebSocket.prototype;}}if(typeof window.EventSource!=="undefined"){var OrigEventSource=window.EventSource;window.EventSource=function(url,init){try{var parsed=new URL(url,window.location.href);if(matchesCapture(parsed)){warnUnsupported("EventSource",url);throw new Error("LocalPreview does not proxy EventSource connections to captured backends in v1.");}}catch(e){if(e instanceof Error&&e.message.indexOf("LocalPreview")!==-1){throw e;}}return init===undefined?new OrigEventSource(url):new OrigEventSource(url,init);};if(OrigEventSource.prototype){window.EventSource.prototype=OrigEventSource.prototype;}}})();`;
+    return `(function(){var cfg=${config};var caps=cfg.captures;var primary=cfg.primary;var prefix=cfg.prefix;var eventsPath="/__localpreview/events";var reported={};function normHost(h){return h==="::1"?"[::1]":h.toLowerCase();}function isLoopbackHost(h){var lower=normHost(h);if(lower==="localhost"||lower==="127.0.0.1"||lower==="[::1]")return true;return lower.endsWith(".localhost");}function loopbackGroup(h){var lower=normHost(h);if(lower==="localhost"||lower==="127.0.0.1"||lower==="[::1]")return "__loopback__";return lower;}function sameLoopbackPort(host,port,otherHost,otherPort){return port===otherPort&&loopbackGroup(host)===loopbackGroup(otherHost);}function dedupeKey(proto,host,port){var group=loopbackGroup(host);return proto+"://"+(group==="__loopback__"?group:normHost(host))+":"+port;}function urlPort(url){return url.port?Number(url.port):(url.protocol==="https:"||url.protocol==="wss:"?443:80);}function matchesCapture(url){var host=normHost(url.hostname);var port=urlPort(url);for(var i=0;i<caps.length;i++){var cap=caps[i];if(sameLoopbackPort(host,port,cap.hostname,cap.port))return true;}return false;}function isPrimaryPort(url){return sameLoopbackPort(url.hostname,urlPort(url),primary.hostname,primary.port);}function isAllowlisted(url){return matchesCapture(url)||isPrimaryPort(url);}function reportMissing(url,transport,method){try{if(!isLoopbackHost(url.hostname))return;if(isAllowlisted(url))return;var proto=url.protocol.replace(":","");if(proto!=="http"&&proto!=="https"&&proto!=="ws"&&proto!=="wss")return;var host=normHost(url.hostname);var port=urlPort(url);var key=dedupeKey(proto,host,port);if(reported[key])return;reported[key]=true;var payload={protocol:proto,hostname:host,port:port,transport:transport};if(typeof method==="string"&&method){payload.method=method;}var body=JSON.stringify({type:"missing-capture",payload:payload});if(typeof navigator!=="undefined"&&navigator.sendBeacon){navigator.sendBeacon(eventsPath,body);}else{fetch(eventsPath,{method:"POST",body:body,keepalive:true});}}catch(e){}}function rewriteUrl(input){var url=new URL(input,window.location.href);if(!matchesCapture(url)){return input;}var proto=url.protocol.replace(":","");var host=encodeURIComponent(normHost(url.hostname));var path=url.pathname+url.search;return prefix+"/"+proto+"/"+host+"/"+url.port+path;}function warnUnsupported(api,url){console.error("[localpreview] "+api+" to captured local backend is not supported in v1: "+url+". Use fetch/XHR or run localpreview connect for that service directly.");}function fetchMethod(input,init){if(init&&typeof init==="object"&&typeof init.method==="string")return init.method.toUpperCase();if(typeof Request!=="undefined"&&input instanceof Request)return input.method.toUpperCase();return "GET";}var origFetch=window.fetch;window.fetch=function(input,init){try{var url=typeof input==="string"?input:input instanceof URL?input.href:input.url;if(typeof url==="string"&&/^https?:\\/\\//.test(url)){var parsed=new URL(url,window.location.href);reportMissing(parsed,"fetch",fetchMethod(input,init));var rewritten=rewriteUrl(url);if(rewritten!==url){return origFetch.call(this,rewritten,init);}}}catch(e){}return origFetch.call(this,input,init);};if(typeof XMLHttpRequest!=="undefined"){var origOpen=XMLHttpRequest.prototype.open;XMLHttpRequest.prototype.open=function(method,url){try{if(typeof url==="string"&&/^https?:\\/\\//.test(url)){var parsed=new URL(url,window.location.href);reportMissing(parsed,"xhr",typeof method==="string"?method.toUpperCase():undefined);var rewritten=rewriteUrl(url);if(rewritten!==url){return origOpen.call(this,method,rewritten);}}}catch(e){}return origOpen.apply(this,arguments);};}if(typeof window.WebSocket!=="undefined"){var OrigWebSocket=window.WebSocket;window.WebSocket=function(url,protocols){try{var parsed=new URL(url,window.location.href);reportMissing(parsed,"websocket");if(matchesCapture(parsed)){warnUnsupported("WebSocket",url);throw new Error("LocalPreview does not proxy WebSocket connections to captured backends in v1.");}}catch(e){if(e instanceof Error&&e.message.indexOf("LocalPreview")!==-1){throw e;}}return protocols===undefined?new OrigWebSocket(url):new OrigWebSocket(url,protocols);};if(OrigWebSocket.prototype){window.WebSocket.prototype=OrigWebSocket.prototype;}}if(typeof window.EventSource!=="undefined"){var OrigEventSource=window.EventSource;window.EventSource=function(url,init){try{var parsed=new URL(url,window.location.href);reportMissing(parsed,"eventsource");if(matchesCapture(parsed)){warnUnsupported("EventSource",url);throw new Error("LocalPreview does not proxy EventSource connections to captured backends in v1.");}}catch(e){if(e instanceof Error&&e.message.indexOf("LocalPreview")!==-1){throw e;}}return init===undefined?new OrigEventSource(url):new OrigEventSource(url,init);};if(OrigEventSource.prototype){window.EventSource.prototype=OrigEventSource.prototype;}}})();`;
 };
 /** Injects the capture shim into an HTML document string. */
 export const injectCaptureShim = (html, shimScript) => {

package/dist/cli-ui.d.ts

@@ -0,0 +1,36 @@
+import type { ListTunnelsResponse } from "@localpreview/protocol";
+export declare const ADMIN_TOKEN_ENV = "LOCALPREVIEW_ADMIN_TOKEN";
+export declare const hasAdminTokenInEnv: (env?: NodeJS.ProcessEnv) => boolean;
+export declare const formatWarning: (message: string) => string;
+export declare const formatCliError: (message: string) => string;
+export declare const formatStatus: (message: string) => string;
+export declare const formatRelayReconnect: (message: string) => string;
+export declare const formatRequestOutbound: (method: string, path: string) => string;
+export declare const formatCapturedRequestOutbound: (method: string, targetUrl: string) => string;
+export declare const formatRequestInbound: (status: number, path: string, durationMs: number) => string;
+export declare const formatCapturedRequestInbound: (status: number, targetUrl: string, durationMs: number) => string;
+export declare const formatMissingCaptureWarning: (options: {
+    readonly origin: string;
+    readonly method?: string;
+    readonly suggestedCommand: string;
+    readonly transport?: string;
+}) => string;
+export declare const formatRequestError: (path: string, message: string) => string;
+export declare const formatInvalidCaptureRouteError: (options: {
+    readonly hostname: string;
+    readonly method: string;
+    readonly path: string;
+    readonly port: number;
+}) => string;
+export declare const removedAdminTokenFlagMessage: () => string;
+export declare const adminTokenRequiredMessage: () => string;
+export type HelpRenderOptions = {
+    readonly env?: NodeJS.ProcessEnv;
+};
+export declare const renderGlobalHelp: (options?: HelpRenderOptions) => string;
+export declare const renderConnectHelp: () => string;
+export declare const renderCleanHelp: (options?: HelpRenderOptions) => string;
+export declare const renderListHelp: (options?: HelpRenderOptions) => string;
+export declare const formatListTunnelsOutput: (response: ListTunnelsResponse) => string;
+export declare const formatCompactAge: (activeForMs: number | undefined) => string;
+//# sourceMappingURL=cli-ui.d.ts.map

package/dist/cli-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-ui.d.ts","sourceRoot":"","sources":["../src/cli-ui.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAkB,MAAM,wBAAwB,CAAC;AAIlF,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAE1D,eAAO,MAAM,kBAAkB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,OAGzE,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,KAAG,MAQ/C,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,KAAG,MAQhD,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,MAM9C,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,SAAS,MAAM,KAAG,MACT,CAAC;AAE/C,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,MASpE,CAAC;AAEF,eAAO,MAAM,6BAA6B,GAAI,QAAQ,MAAM,EAAE,WAAW,MAAM,KAAG,MAUjF,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,EAAE,YAAY,MAAM,KAAG,MAgBvF,CAAC;AAEF,eAAO,MAAM,4BAA4B,GACvC,QAAQ,MAAM,EACd,WAAW,MAAM,EACjB,YAAY,MAAM,KACjB,MAiBF,CAAC;AAIF,eAAO,MAAM,2BAA2B,GAAI,SAAS;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,KAAG,MAiBH,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,KAAG,MASlE,CAAC;AAEF,eAAO,MAAM,8BAA8B,GAAI,SAAS;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,KAAG,MAaH,CAAC;AAKF,eAAO,MAAM,4BAA4B,QAAO,MAA0C,CAAC;AAE3F,eAAO,MAAM,yBAAyB,QAAO,MACkD,CAAC;AAEhG,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC,CAAC;AAiDF,eAAO,MAAM,gBAAgB,GAAI,UAAS,iBAAsB,KAAG,MASlE,CAAC;AAEF,eAAO,MAAM,iBAAiB,QAAO,MAuBjC,CAAC;AAEL,eAAO,MAAM,eAAe,GAAI,UAAS,iBAAsB,KAAG,MA+BjE,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,UAAS,iBAAsB,KAAG,MA+BhE,CAAC;AAaF,eAAO,MAAM,uBAAuB,GAAI,UAAU,mBAAmB,KAAG,MAkEvE,CAAC;AAwCF,eAAO,MAAM,gBAAgB,GAAI,aAAa,MAAM,GAAG,SAAS,KAAG,MA0BlE,CAAC"}

package/dist/cli-ui.js

@@ -0,0 +1,351 @@
+import pc from "picocolors";
+import { LOCAL_CONTROL_PLANE_URL } from "./config.js";
+import { CLI_PACKAGE_VERSION } from "./version.js";
+export const ADMIN_TOKEN_ENV = "LOCALPREVIEW_ADMIN_TOKEN";
+export const hasAdminTokenInEnv = (env = process.env) => {
+    const token = env[ADMIN_TOKEN_ENV];
+    return token !== undefined && token.length > 0;
+};
+export const formatWarning = (message) => {
+    const prefix = "Warning:";
+    if (!pc.isColorSupported) {
+        return `${prefix} ${message}`;
+    }
+    return `${pc.yellow(prefix)} ${message}`;
+};
+export const formatCliError = (message) => {
+    const prefix = "Error:";
+    if (!pc.isColorSupported) {
+        return `${prefix} ${message}`;
+    }
+    return `${pc.red(prefix)} ${message}`;
+};
+export const formatStatus = (message) => {
+    if (!pc.isColorSupported) {
+        return message;
+    }
+    return pc.cyan(message);
+};
+export const formatRelayReconnect = (message) => formatWarning(`${message}; reconnecting...`);
+export const formatRequestOutbound = (method, path) => {
+    const arrow = "→";
+    const line = `${arrow} ${method} ${path}`;
+    if (!pc.isColorSupported) {
+        return line;
+    }
+    return `${pc.dim(arrow)} ${pc.bold(method)} ${path}`;
+};
+export const formatCapturedRequestOutbound = (method, targetUrl) => {
+    const arrow = "→";
+    const label = "CAPTURED";
+    const line = `${arrow} ${label} ${method} ${targetUrl}`;
+    if (!pc.isColorSupported) {
+        return line;
+    }
+    return `${pc.dim(arrow)} ${formatCaptureBadge(label)} ${pc.bold(method)} ${targetUrl}`;
+};
+export const formatRequestInbound = (status, path, durationMs) => {
+    const arrow = "←";
+    const line = `${arrow} ${status} ${path} ${durationMs}ms`;
+    if (!pc.isColorSupported) {
+        return line;
+    }
+    const statusText = status >= 500
+        ? pc.red(String(status))
+        : status >= 400
+            ? pc.yellow(String(status))
+            : pc.green(String(status));
+    return `${pc.dim(arrow)} ${statusText} ${path} ${pc.dim(`${durationMs}ms`)}`;
+};
+export const formatCapturedRequestInbound = (status, targetUrl, durationMs) => {
+    const arrow = "←";
+    const label = "CAPTURED";
+    const line = `${arrow} ${label} ${status} ${targetUrl} ${durationMs}ms`;
+    if (!pc.isColorSupported) {
+        return line;
+    }
+    const statusText = status >= 500
+        ? pc.red(String(status))
+        : status >= 400
+            ? pc.yellow(String(status))
+            : pc.green(String(status));
+    return `${pc.dim(arrow)} ${formatCaptureBadge(label)} ${statusText} ${targetUrl} ${pc.dim(`${durationMs}ms`)}`;
+};
+const formatCaptureBadge = (label) => pc.yellow(pc.dim(` ${label} `));
+export const formatMissingCaptureWarning = (options) => {
+    const transportNote = options.transport === "websocket" || options.transport === "eventsource"
+        ? " WebSocket/EventSource may still fail in preview."
+        : "";
+    const arrow = "←";
+    const requestLabel = options.method ?? options.transport ?? "request";
+    const lines = [
+        `${arrow} ${requestLabel} ${options.origin}`,
+        `  Browser tried to reach uncaptured loopback backend ${options.origin}. Restart with: ${options.suggestedCommand}.${transportNote}`,
+    ];
+    if (!pc.isColorSupported) {
+        return lines.join("\n");
+    }
+    return lines.map((line) => pc.red(line)).join("\n");
+};
+export const formatRequestError = (path, message) => {
+    const arrow = "←";
+    const line = `${arrow} error ${path} ${message}`;
+    if (!pc.isColorSupported) {
+        return line;
+    }
+    return `${pc.dim(arrow)} ${pc.red("error")} ${path} ${pc.red(message)}`;
+};
+export const formatInvalidCaptureRouteError = (options) => {
+    const arrow = "←";
+    const origin = `${options.hostname}:${options.port}`;
+    const lines = [
+        `${arrow} ${options.method} ${options.path}`,
+        `  Browser tried to reach blocked loopback backend ${origin}. Allow it with --capture ${origin}.`,
+    ];
+    if (!pc.isColorSupported) {
+        return lines.join("\n");
+    }
+    return lines.map((line) => pc.red(line)).join("\n");
+};
+const REMOVED_ADMIN_TOKEN_FLAG_MESSAGE = "The --admin-token flag was removed. Set the LOCALPREVIEW_ADMIN_TOKEN environment variable instead.";
+export const removedAdminTokenFlagMessage = () => REMOVED_ADMIN_TOKEN_FLAG_MESSAGE;
+export const adminTokenRequiredMessage = () => `Admin commands require ${ADMIN_TOKEN_ENV}. Export it in your shell, then rerun the command.`;
+const heading = (text) => (pc.isColorSupported ? pc.bold(text) : text);
+const commandName = (text) => (pc.isColorSupported ? pc.cyan(text) : text);
+const flagName = (text) => (pc.isColorSupported ? pc.yellow(text) : text);
+const dim = (text) => (pc.isColorSupported ? pc.dim(text) : text);
+const localFlagHelpLine = () => `  ${flagName("-l")}, ${flagName("--local")}              Shorthand for ${flagName("--control-plane")} ${dim(LOCAL_CONTROL_PLANE_URL)}`;
+const joinLines = (lines) => lines.join("\n");
+const publicUsageLines = () => [
+    heading("localpreview — expose local dev servers through a public preview URL"),
+    "",
+    heading("Usage"),
+    `  ${commandName("localpreview")} ${commandName("connect")} <port|target-url> [options]`,
+    `  ${commandName("localpreview")} ${flagName("--version")}`,
+    `  ${commandName("localpreview")} ${flagName("-h")} | ${flagName("--help")}`,
+    "",
+    heading("Commands"),
+    `  ${commandName("connect")}    Start a tunnel to your local target`,
+    "",
+    heading("Global options"),
+    `  ${flagName("-h")}, ${flagName("--help")}     Show help`,
+    `  ${flagName("--version")}      Show version (${CLI_PACKAGE_VERSION})`,
+];
+const publicExamplesLines = () => [
+    "",
+    heading("Examples"),
+    `  ${dim("localpreview connect 3000")}`,
+    `  ${dim("localpreview connect 5173 --capture localhost:4000")}`,
+    `  ${dim("localpreview connect https://localhost:3000 --name my-app")}`,
+    `  ${dim("localpreview connect 3000 -l")}`,
+    `  ${dim("localpreview connect 3000 --control-plane https://staging.localpreview.dev")}`,
+];
+const adminSectionLines = () => [
+    "",
+    heading("Admin commands"),
+    `  ${dim(`Requires ${ADMIN_TOKEN_ENV} in the environment.`)}`,
+    `  ${commandName("clean")}       Remove subdomains from the control plane`,
+    `  ${commandName("list")}        List active tunnels and inventory orphans`,
+];
+export const renderGlobalHelp = (options = {}) => {
+    const env = options.env ?? process.env;
+    const lines = [...publicUsageLines(), ...publicExamplesLines()];
+    if (hasAdminTokenInEnv(env)) {
+        lines.push(...adminSectionLines());
+    }
+    return joinLines(lines);
+};
+export const renderConnectHelp = () => joinLines([
+    heading("localpreview connect — start a tunnel to a local target"),
+    "",
+    heading("Usage"),
+    `  ${commandName("localpreview")} ${commandName("connect")} <port|target-url> [options]`,
+    `  ${commandName("localpreview")} <port|target-url> [options]    ${dim("(deprecated alias)")}`,
+    "",
+    heading("Arguments"),
+    `  <port|target-url>    Local port (e.g. 3000) or full http(s) URL with explicit port`,
+    "",
+    heading("Options"),
+    `  ${flagName("--name")} <subdomain>       Request a public subdomain`,
+    `  ${flagName("--capture")} <host:port>     Expose an extra loopback backend through the preview URL`,
+    localFlagHelpLine(),
+    `  ${flagName("--control-plane")} <url>    Remote control plane base URL (HTTPS required off localhost)`,
+    `  ${flagName("-h")}, ${flagName("--help")}               Show this help`,
+    "",
+    heading("Examples"),
+    `  ${dim("localpreview connect 3000")}`,
+    `  ${dim("localpreview connect 5173 --capture localhost:4000")}`,
+    `  ${dim("localpreview connect https://localhost:3000 --name my-app")}`,
+    `  ${dim("localpreview connect 3000 -l")}`,
+]);
+export const renderCleanHelp = (options = {}) => {
+    const env = options.env ?? process.env;
+    if (!hasAdminTokenInEnv(env)) {
+        return joinLines([renderGlobalHelp(options), "", adminTokenRequiredMessage()]);
+    }
+    return joinLines([
+        heading("localpreview clean — admin subdomain cleanup"),
+        "",
+        heading("Usage"),
+        `  ${commandName("localpreview")} ${commandName("clean")} <subdomain> [options]`,
+        `  ${commandName("localpreview")} ${commandName("clean")} ${flagName("--all")} ${flagName("--force")} [options]`,
+        "",
+        heading("Arguments"),
+        `  <subdomain>          Subdomain to remove from the control plane`,
+        "",
+        heading("Options"),
+        `  ${flagName("--force")}               Force cleanup when relays are still connected`,
+        `  ${flagName("--all")}                 Bulk cleanup (requires ${flagName("--force")})`,
+        localFlagHelpLine(),
+        `  ${flagName("--control-plane")} <url>    Control plane base URL`,
+        `  ${flagName("-h")}, ${flagName("--help")}               Show this help`,
+        "",
+        dim(`Authorization uses ${ADMIN_TOKEN_ENV} from the environment.`),
+        "",
+        heading("Examples"),
+        `  ${dim("localpreview clean my-app --force")}`,
+        `  ${dim("localpreview clean --all --force -l")}`,
+        `  ${dim("localpreview clean demo --control-plane https://staging.localpreview.dev --force")}`,
+    ]);
+};
+export const renderListHelp = (options = {}) => {
+    const env = options.env ?? process.env;
+    if (!hasAdminTokenInEnv(env)) {
+        return joinLines([renderGlobalHelp(options), "", adminTokenRequiredMessage()]);
+    }
+    return joinLines([
+        heading("localpreview list — inspect tunnel inventory"),
+        "",
+        heading("Usage"),
+        `  ${commandName("localpreview")} ${commandName("list")} [options]`,
+        "",
+        dim("Shows active tunnels, Redis inventory drift, and sandbox leftovers without revealing tokens or preview URLs."),
+        "",
+        heading("Options"),
+        `  ${flagName("--limit")} <n>             Page size (default 100)`,
+        `  ${flagName("--skip")} <n>              Offset into the sorted inventory (default 0)`,
+        localFlagHelpLine(),
+        `  ${flagName("--control-plane")} <url>    Control plane base URL`,
+        `  ${flagName("-h")}, ${flagName("--help")}               Show this help`,
+        "",
+        dim(`Authorization uses ${ADMIN_TOKEN_ENV} from the environment.`),
+        "",
+        heading("Examples"),
+        `  ${dim("localpreview list")}`,
+        `  ${dim("localpreview list --limit 20 --skip 20 -l")}`,
+        `  ${dim("localpreview list --control-plane <control-plane-url>")}`,
+    ]);
+};
+const LIST_COLUMNS = [
+    "kind",
+    "subdomain",
+    "tunnel",
+    "age",
+    "relay",
+    "sandbox",
+    "sandbox id",
+    "note",
+];
+export const formatListTunnelsOutput = (response) => {
+    const lines = [];
+    lines.push(heading("Tunnel inventory"));
+    lines.push("");
+    for (const warning of response.warnings ?? []) {
+        lines.push(formatWarning(warning));
+    }
+    if ((response.warnings?.length ?? 0) > 0) {
+        lines.push("");
+    }
+    lines.push(heading("Summary"));
+    lines.push(`  tracked: ${response.counts.tracked}   redis orphans: ${response.counts["redis-orphan"]}   sandbox orphans: ${response.counts["sandbox-orphan"]}`);
+    lines.push("");
+    lines.push(heading("Page"));
+    lines.push(`  showing: ${response.items.length} of ${response.total}   skip: ${response.skip}   limit: ${response.limit}`);
+    const nextSkip = response.skip + response.limit;
+    if (nextSkip < response.total) {
+        lines.push(`  next: localpreview list --skip ${nextSkip} --limit ${response.limit}`);
+    }
+    if (response.items.length === 0) {
+        lines.push("");
+        lines.push(dim("No active tunnels or inventory orphans on this page."));
+        return joinLines(lines);
+    }
+    const rows = response.items.map(formatListTunnelRow);
+    const widths = LIST_COLUMNS.map((column, index) => Math.max(column.length, ...rows.map((row) => row[index]?.length ?? 0)));
+    lines.push("");
+    lines.push(heading("Items"));
+    lines.push(LIST_COLUMNS.map((column, index) => column.padEnd(widths[index] ?? column.length)).join("  "));
+    lines.push(widths.map((width) => "-".repeat(width)).join("  "));
+    for (const row of rows) {
+        lines.push(row
+            .map((cell, index) => cell.padEnd(widths[index] ?? cell.length))
+            .join("  "));
+    }
+    if (response.items.some((item) => item.relayHealthWarning !== undefined && item.relayHealthWarning.length > 0)) {
+        lines.push("");
+        lines.push(dim("Relay values ending in ! include a health warning from the control plane."));
+    }
+    return joinLines(lines);
+};
+const formatListTunnelRow = (item) => [
+    formatListItemKind(item.kind),
+    item.subdomain ?? "-",
+    formatShortId(item.tunnelId),
+    formatCompactAge(item.activeForMs),
+    formatRelayHealth(item),
+    item.sandboxStatus ?? "-",
+    formatShortId(item.sandboxId),
+    item.reason ?? item.orphanReason ?? "-",
+];
+const formatListItemKind = (kind) => {
+    switch (kind) {
+        case "tracked-tunnel":
+            return "tracked";
+        case "redis-orphan":
+            return "redis-orphan";
+        case "redis-index-orphan":
+            return "redis-index";
+        case "sandbox-orphan":
+            return "sandbox-orphan";
+        default: {
+            const unreachable = kind;
+            throw new Error(`Unhandled tunnel list item kind: ${String(unreachable)}`);
+        }
+    }
+};
+const formatRelayHealth = (item) => {
+    const base = item.relayHealth;
+    if (item.relayHealthWarning !== undefined && item.relayHealthWarning.length > 0) {
+        return `${base}!`;
+    }
+    return base;
+};
+export const formatCompactAge = (activeForMs) => {
+    if (activeForMs === undefined) {
+        return "unknown";
+    }
+    const totalMinutes = Math.floor(activeForMs / 60_000);
+    if (totalMinutes < 1) {
+        return `${Math.max(1, Math.floor(activeForMs / 1_000))}s`;
+    }
+    if (totalMinutes < 60) {
+        return `${totalMinutes}m`;
+    }
+    const totalHours = Math.floor(totalMinutes / 60);
+    const minutes = totalMinutes % 60;
+    if (totalHours < 24) {
+        return minutes === 0 ? `${totalHours}h` : `${totalHours}h ${minutes}m`;
+    }
+    const days = Math.floor(totalHours / 24);
+    const hours = totalHours % 24;
+    return hours === 0 ? `${days}d` : `${days}d ${hours}h`;
+};
+const formatShortId = (value) => {
+    if (value === undefined || value.length === 0) {
+        return "-";
+    }
+    if (value.length <= 12) {
+        return value;
+    }
+    return `${value.slice(0, 8)}…`;
+};

package/dist/command.d.ts

@@ -2,4 +2,5 @@ import { Effect } from "effect";
 import { CliUsageError, type CliRuntimeError } from "./errors.js";
 export declare const runCli: (argv: ReadonlyArray<string>) => Effect.Effect<void, CliRuntimeError | CliUsageError>;
 export declare const normalizeCliArgs: (argv: ReadonlyArray<string>) => ReadonlyArray<string>;
+export declare const buildConnectOriginalArgv: (argv: ReadonlyArray<string>, legacy: boolean) => ReadonlyArray<string>;
 //# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAQA,OAAO,EAAW,MAAM,EAAiB,MAAM,QAAQ,CAAC;AAOxD,OAAO,EAAE,aAAa,EAAgB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AA8BhF,eAAO,MAAM,MAAM,GACjB,MAAM,aAAa,CAAC,MAAM,CAAC,KAC1B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,GAAG,aAAa,CAkBrD,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,MAAM,aAAa,CAAC,MAAM,CAAC,KAAG,aAAa,CAAC,MAAM,CAC1C,CAAC"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAQA,OAAO,EAAW,MAAM,EAAiB,MAAM,QAAQ,CAAC;AAkBxD,OAAO,EAAE,aAAa,EAAgB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAwChF,eAAO,MAAM,MAAM,GACjB,MAAM,aAAa,CAAC,MAAM,CAAC,KAC1B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,GAAG,aAAa,CAmBrD,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,MAAM,aAAa,CAAC,MAAM,CAAC,KAAG,aAAa,CAAC,MAAM,CAC1C,CAAC;AAE1C,eAAO,MAAM,wBAAwB,GACnC,MAAM,aAAa,CAAC,MAAM,CAAC,EAC3B,QAAQ,OAAO,KACd,aAAa,CAAC,MAAM,CAAmE,CAAC"}