peekable 0.6.0 → 0.6.1

package/dist/cliUpdateNotice.d.ts

@@ -0,0 +1,8 @@
+export type CliUpdateNotice = {
+    current: string;
+    latest: string;
+    min: string;
+    action: "recommended" | "required";
+};
+export declare function readCliUpdate(data: unknown): CliUpdateNotice | null;
+export declare function warnCliUpdateToStderr(notice: CliUpdateNotice): void;

package/dist/cliUpdateNotice.js

@@ -0,0 +1,34 @@
+// Surfaces the server's "your CLI is stale" notice that rides on the
+// session-create response (see src/cliVersion.ts server-side). A published CLI
+// can silently lag the server's capabilities; this makes that visible to both
+// humans (stderr) and agents (the --json payload) at the moment a session
+// starts. The fix is always `npm i -g peekable@latest` — never `peekable
+// upgrade`, which is the billing command.
+// Extract and validate the notice from a session-create response body.
+// Returns null when absent or malformed — a missing notice must never break
+// the command.
+export function readCliUpdate(data) {
+    if (!data || typeof data !== "object")
+        return null;
+    const u = data.cli_update;
+    if (!u || typeof u !== "object")
+        return null;
+    const notice = u;
+    if (typeof notice.current !== "string" || typeof notice.latest !== "string")
+        return null;
+    return {
+        current: notice.current,
+        latest: notice.latest,
+        min: typeof notice.min === "string" ? notice.min : notice.latest,
+        action: notice.action === "required" ? "required" : "recommended",
+    };
+}
+// Human-facing warning printed to stderr (so it never pollutes --json stdout).
+// Non-blocking: the command still runs on a stale CLI.
+export function warnCliUpdateToStderr(notice) {
+    const lead = notice.action === "required"
+        ? `⚠ Your Peekable CLI (v${notice.current}) is out of date — some features (e.g. tunnelling apps that call their own backend) may not work until you update.`
+        : `↑ A newer Peekable CLI is available (v${notice.current} → v${notice.latest}).`;
+    console.error(lead);
+    console.error("  Update: npm i -g peekable@latest");
+}

package/dist/commands/create.js

@@ -3,21 +3,27 @@ import { requireConfig } from "../config.js";
 import { api } from "../api.js";
 import { CommandFailure, printCommandError } from "../command-error.js";
 import { runWithTelemetry } from "../telemetry.js";
+import { readCliUpdate, warnCliUpdateToStderr } from "../cliUpdateNotice.js";
 export const createCommand = new Command("create")
     .argument("<name>", "Session name")
     .description("Create a new sharing session")
     .option("--json", "Output JSON")
+    .option("--no-slug", "Use an opaque hostname that omits the session name (for sensitive shares)")
     .action(async (name, opts) => {
     await runWithTelemetry("create", async () => {
         try {
             const config = requireConfig();
-            const data = await api(config, "POST", "/sessions", { name });
+            const data = await api(config, "POST", "/sessions", { name, slug: opts.slug });
+            const cliUpdate = readCliUpdate(data);
             if (opts.json) {
+                // data already carries cli_update when present; agents read it there.
                 console.log(JSON.stringify(data));
             }
             else {
                 console.log(`Created session: ${data.id}`);
                 console.log(`URL: ${data.url}`);
+                if (cliUpdate)
+                    warnCliUpdateToStderr(cliUpdate);
             }
         }
         catch (err) {

package/dist/commands/proxy.d.ts

@@ -1,2 +1,3 @@
 import { Command } from "commander";
 export declare const proxyCommand: Command;
+export declare function handleRequest(ws: WebSocket, msg: any, port: number, inflight: Map<string, AbortController>, fallbackPorts: Set<number>, pathPortCache: Map<string, number>, jsonOutput?: boolean): Promise<void>;

package/dist/commands/proxy.js

@@ -4,6 +4,7 @@ import { requireConfig } from "../config.js";
 import { api } from "../api.js";
 import { CommandFailure, printCommandError } from "../command-error.js";
 import { postStartEvent, postFireAndForgetDebugEvent } from "../telemetry.js";
+import { readCliUpdate, warnCliUpdateToStderr } from "../cliUpdateNotice.js";
 const MAX_RESPONSE_BYTES = 25 * 1024 * 1024; // 25 MB
 const TEXT_CONTENT_TYPES = [
     "text/",
@@ -34,6 +35,7 @@ export const proxyCommand = new Command("proxy")
     // Create or reuse session
     let sessionId;
     let shareUrl;
+    let cliUpdate = null;
     if (opts.session) {
         sessionId = opts.session;
         const baseDomain = new URL(config.url).hostname;
@@ -54,12 +56,16 @@ export const proxyCommand = new Command("proxy")
         }
         sessionId = data.id;
         shareUrl = data.url;
+        cliUpdate = readCliUpdate(data);
     }
     if (opts.json) {
-        console.log(JSON.stringify({ id: sessionId, url: shareUrl }));
+        // Agents read cli_update here to prompt the user to update.
+        console.log(JSON.stringify({ id: sessionId, url: shareUrl, ...(cliUpdate ? { cli_update: cliUpdate } : {}) }));
     }
     else {
         console.log(`Share URL: ${shareUrl}`);
+        if (cliUpdate)
+            warnCliUpdateToStderr(cliUpdate);
     }
     postStartEvent("cli_proxy_started", { session_id: sessionId, port });
     // Connect relay WebSocket
@@ -77,6 +83,7 @@ export const proxyCommand = new Command("proxy")
     const wsStartedAt = Date.now();
     const inflight = new Map();
     const fallbackPorts = new Set();
+    const pathPortCache = new Map();
     ws.addEventListener("open", () => {
         ws.send(JSON.stringify({
             type: "auth",
@@ -122,7 +129,7 @@ export const proxyCommand = new Command("proxy")
             return;
         }
         if (msg.type === "request") {
-            await handleRequest(ws, msg, port, inflight, fallbackPorts, opts.json);
+            await handleRequest(ws, msg, port, inflight, fallbackPorts, pathPortCache, opts.json);
         }
     });
     ws.addEventListener("close", (event) => {
@@ -174,12 +181,18 @@ export const proxyCommand = new Command("proxy")
         setTimeout(() => process.exit(0), 200);
     });
 });
-async function handleRequest(ws, msg, port, inflight, fallbackPorts, jsonOutput) {
+// Bounds pathPortCache so a long-lived session with many distinct paths can't
+// grow it without limit; oldest entries are evicted first (Map insertion order).
+const MAX_PATH_PORT_CACHE = 512;
+export async function handleRequest(ws, msg, port, inflight, fallbackPorts, pathPortCache, jsonOutput) {
     const ac = new AbortController();
     inflight.set(msg.id, ac);
     try {
-        const url = `http://localhost:${port}${msg.path}`;
-        // Build headers, skip host and x-forwarded-*
+        // Build headers, skip host and x-forwarded-*. Origin is always stamped as
+        // the PRIMARY port: a real browser tab on localhost:<primary> calling any
+        // backend port sends Origin http://localhost:<primary>. APIs with origin
+        // allowlists (better-auth trustedOrigins, CORS) reject a fabricated
+        // per-backend origin — that 403 broke login through tunnels.
         const headers = new Headers();
         if (Array.isArray(msg.headers)) {
             for (const [k, v] of msg.headers) {
@@ -189,7 +202,6 @@ async function handleRequest(ws, msg, port, inflight, fallbackPorts, jsonOutput)
                 headers.set(k, v);
             }
         }
-        headers.set("host", `localhost:${port}`);
         headers.set("origin", `http://localhost:${port}`);
         headers.set("accept-encoding", "identity");
         // Decode body
@@ -201,49 +213,84 @@ async function handleRequest(ws, msg, port, inflight, fallbackPorts, jsonOutput)
                 bytes[i] = binary.charCodeAt(i);
             body = bytes.buffer;
         }
-        let upstream = await fetch(url, {
-            method: msg.method ?? "GET",
-            headers,
-            body: body,
-            redirect: "manual",
-            signal: ac.signal,
-        });
-        // Detect when primary port can't handle the request — try fallback ports.
-        // Key signal: response is HTML but request didn't ask for HTML (fetch vs navigation)
-        const upstreamCt = upstream.headers.get("content-type") ?? "";
         const method = (msg.method ?? "GET").toUpperCase();
-        const requestAccept = (Array.isArray(msg.headers) ? msg.headers.find(([k]) => k.toLowerCase() === "accept")?.[1] : "") ?? "";
-        const requestExpectsHtml = requestAccept.includes("text/html");
-        const isModifyingMethod = method !== "GET" && method !== "HEAD";
-        const gotUnexpectedHtml = upstreamCt.includes("text/html") && !requestExpectsHtml;
-        const shouldTryFallback = (gotUnexpectedHtml || isModifyingMethod) && fallbackPorts.size > 0;
-        if (shouldTryFallback) {
-            for (const fbPort of fallbackPorts) {
-                if (fbPort === port)
-                    continue;
-                try {
-                    const fbHeaders = new Headers(headers);
-                    fbHeaders.set("host", `localhost:${fbPort}`);
-                    fbHeaders.set("origin", `http://localhost:${fbPort}`);
-                    const fbUrl = `http://localhost:${fbPort}${msg.path}`;
-                    const fbResp = await fetch(fbUrl, {
-                        method: msg.method ?? "GET",
-                        headers: fbHeaders,
-                        body: body,
-                        redirect: "manual",
-                        signal: ac.signal,
-                    });
-                    if (fbResp.status !== 404) {
-                        // Fallback port handled the request (any status other than 404) — use it
-                        upstream = fbResp;
-                        break;
-                    }
+        const fetchPort = (p) => {
+            const h = new Headers(headers);
+            h.set("host", `localhost:${p}`);
+            return fetch(`http://localhost:${p}${msg.path}`, {
+                method: msg.method ?? "GET",
+                headers: h,
+                body: body,
+                redirect: "manual",
+                signal: ac.signal,
+            });
+        };
+        // Per-path port memoization. Once a path is known to belong to a backend
+        // port, go straight there and SKIP the primary hop — this avoids the wasted
+        // primary round trip AND, for modifying methods, avoids executing the write
+        // twice (primary + fallback). Key excludes the query string so it stays
+        // small; the port that owns a path does not vary by query.
+        const cacheKey = `${method} ${(msg.path ?? "").split("?")[0]}`;
+        const preferred = pathPortCache.get(cacheKey);
+        let upstream;
+        let servedPort = port;
+        if (preferred !== undefined && preferred !== port) {
+            try {
+                const r = await fetchPort(preferred);
+                if (r.status !== 404) {
+                    upstream = r;
+                    servedPort = preferred;
                 }
-                catch {
-                    // Fallback port not reachable, continue
+            }
+            catch {
+                // Preferred port unreachable (backend restarted / moved) — fall through
+                // to the primary + rediscovery path and let the cache re-learn.
+                pathPortCache.delete(cacheKey);
+            }
+        }
+        if (upstream === undefined) {
+            upstream = await fetchPort(port);
+            servedPort = port;
+            // Detect when the primary port can't handle the request — try fallbacks.
+            // Key signal: response is HTML but request didn't ask for HTML (a fetch
+            // hitting the SPA catch-all), or any modifying method.
+            const upstreamCt = upstream.headers.get("content-type") ?? "";
+            const requestAccept = (Array.isArray(msg.headers) ? msg.headers.find(([k]) => k.toLowerCase() === "accept")?.[1] : "") ?? "";
+            const requestExpectsHtml = requestAccept.includes("text/html");
+            const isModifyingMethod = method !== "GET" && method !== "HEAD";
+            const gotUnexpectedHtml = upstreamCt.includes("text/html") && !requestExpectsHtml;
+            const shouldTryFallback = (gotUnexpectedHtml || isModifyingMethod) && fallbackPorts.size > 0;
+            if (shouldTryFallback) {
+                for (const fbPort of fallbackPorts) {
+                    if (fbPort === port)
+                        continue;
+                    try {
+                        const fbResp = await fetchPort(fbPort);
+                        if (fbResp.status !== 404) {
+                            // Fallback port handled the request (any status other than 404).
+                            upstream = fbResp;
+                            servedPort = fbPort;
+                            break;
+                        }
+                    }
+                    catch {
+                        // Fallback port not reachable, continue
+                    }
                 }
             }
         }
+        // Remember which backend port served this path so the next matching request
+        // skips the primary hop. Only cache non-primary wins — a primary-served path
+        // already takes the primary-first path with no wasted work.
+        if (servedPort !== port && upstream.status !== 404) {
+            pathPortCache.delete(cacheKey);
+            pathPortCache.set(cacheKey, servedPort);
+            if (pathPortCache.size > MAX_PATH_PORT_CACHE) {
+                const oldest = pathPortCache.keys().next().value;
+                if (oldest !== undefined)
+                    pathPortCache.delete(oldest);
+            }
+        }
         // Build response header tuples
         const respHeaders = [];
         upstream.headers.forEach((v, k) => {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "0.6.0";
+export declare const CLI_VERSION = "0.6.1";

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.6.0";
+export const CLI_VERSION = "0.6.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peekable",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "description": "Share HTML mockups with collaborators — CLI for peekable-server",
   "bin": {

package/skill/SKILL.md

@@ -24,6 +24,8 @@ When the user wants to share an HTML file (playground, mockup, brainstorming com
 
 If a session already exists for this topic, reuse it (push creates a new version, collaborators auto-reload).
 
+Session names are now visible in the share URL's subdomain (DNS and TLS SNI), not just to whoever opens the link. Avoid putting sensitive information in the session name. Use `peekable create "<name>" --no-slug` to get a nameless, opaque hostname when the name itself is sensitive.
+
 ### Share a video
 
 When the user wants to share a video for review:
@@ -119,6 +121,19 @@ peekable close <session-id> --json
 
 Free hosted accounts have an active-session cap. If create/proxy returns a limit error, run `peekable list --json`, close stale sessions, then retry.
 
+### Keep the CLI up to date
+
+When `peekable create` or `peekable proxy --json` returns a `cli_update` object, the installed CLI is behind the server. Tell the user to update before relying on the session:
+
+```
+npm i -g peekable@latest
+```
+
+- `"action": "recommended"` — a newer version is available; mention it, then continue.
+- `"action": "required"` — the installed version is missing fixes the current server depends on (e.g. tunnelling an app that calls its own backend). Surface this prominently and recommend updating before trusting the tunnel; the session still runs, but features may misbehave.
+
+Use `npm i -g peekable@latest` — never `peekable upgrade`, which is the billing/Stripe command, not a version update.
+
 ### Diagnose setup
 
 When sharing fails, auth looks broken, or a user asks for help debugging: