peekable 0.5.0 → 0.6.1

package/dist/api.d.ts

@@ -1,6 +1,7 @@
 import { type ShareConfig } from "./config.js";
 export declare const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
 export declare const DEFAULT_UPLOAD_TIMEOUT_MS = 300000;
+export declare function sanitizeTerminalText(value: string): string;
 export declare const USER_AGENT: string;
 export declare class ApiError extends Error {
     status: number;
@@ -10,6 +11,7 @@ export declare class ApiError extends Error {
 export declare function api(config: ShareConfig, method: string, path: string, body?: unknown, opts?: {
     timeoutMs?: number;
 }): Promise<any>;
+export declare function apiBinary(config: ShareConfig, path: string): Promise<Buffer>;
 export declare function uploadVideo(config: ShareConfig, sessionId: string, opts: {
     video: Blob;
     filename: string;

package/dist/api.js

@@ -2,7 +2,7 @@ import { CLI_VERSION } from "./version.js";
 export const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
 export const DEFAULT_UPLOAD_TIMEOUT_MS = 300_000;
 const CONTROL_CHARS = new RegExp("[\\x00-\\x1f\\x7f-\\x9f]", "g");
-function sanitizeTerminalText(value) {
+export function sanitizeTerminalText(value) {
     return value.replace(CONTROL_CHARS, "").slice(0, 500);
 }
 export const USER_AGENT = `peekable-cli/${CLI_VERSION} (${process.platform}; ${process.arch}; node ${process.version})`;
@@ -31,6 +31,30 @@ export async function api(config, method, path, body, opts = {}) {
     }
     return res.json();
 }
+export async function apiBinary(config, path) {
+    const apiPath = path.startsWith("/api/") ? path.slice(4) : path;
+    const res = await fetchWithTimeout(`${config.url}/api${apiPath}`, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${config.api_key}`,
+            "User-Agent": USER_AGENT,
+        },
+    });
+    if (!res.ok) {
+        throw await buildApiError(res);
+    }
+    // Stored frames are server-capped at 120KB; anything past 1MB is a
+    // misbehaving server and must not be buffered into memory unbounded.
+    const declaredLength = Number(res.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > 1_000_000) {
+        throw new Error("frame exceeds 1MB");
+    }
+    const buffer = Buffer.from(await res.arrayBuffer());
+    if (buffer.byteLength > 1_000_000) {
+        throw new Error("frame exceeds 1MB");
+    }
+    return buffer;
+}
 export async function uploadVideo(config, sessionId, opts) {
     const form = new FormData();
     form.set("video", opts.video, opts.filename);

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/feedback.js

@@ -1,21 +1,65 @@
 import { Command } from "commander";
 import { requireConfig } from "../config.js";
-import { api } from "../api.js";
+import { api, apiBinary, sanitizeTerminalText } from "../api.js";
 import { CommandFailure, printCommandError } from "../command-error.js";
 import { runWithTelemetry } from "../telemetry.js";
+function formatTimecode(atS) {
+    const seconds = Number.isFinite(atS) ? Math.max(0, atS) : 0;
+    return `${Math.floor(seconds / 60)}:${String(Math.floor(seconds % 60)).padStart(2, "0")}`;
+}
+function isVideoAnnotation(annotation) {
+    return typeof annotation.comment === "string" && typeof annotation.at_s === "number";
+}
+const FRAME_URL_PATTERN = /^\/api\/sessions\/[A-Za-z0-9_-]+\/annotations\/[A-Za-z0-9_-]+\/frame$/;
+async function includeFrames(config, annotationsData) {
+    const items = Array.isArray(annotationsData.annotations)
+        ? annotationsData.annotations.flatMap((group) => Array.isArray(group.items) ? group.items : [])
+        : [];
+    const candidates = items.filter((item) => typeof item.frame_url === "string");
+    const frameItems = candidates.filter((item) => {
+        // Only canonical annotation-frame paths are fetched with the bearer key —
+        // a server response must not be able to steer the CLI at other endpoints.
+        if (FRAME_URL_PATTERN.test(item.frame_url))
+            return true;
+        item.frame_jpeg = null;
+        console.error(`Warning: skipping unexpected frame_url ${sanitizeTerminalText(item.frame_url)}`);
+        return false;
+    });
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < frameItems.length) {
+            const item = frameItems[nextIndex++];
+            try {
+                const frame = await apiBinary(config, item.frame_url);
+                item.frame_jpeg = `data:image/jpeg;base64,${frame.toString("base64")}`;
+            }
+            catch {
+                item.frame_jpeg = null;
+                console.error(`Warning: failed to fetch frame ${sanitizeTerminalText(item.frame_url)}`);
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(4, frameItems.length) }, () => worker()));
+}
 export const feedbackCommand = new Command("feedback")
     .argument("<session-id>", "Session ID")
     .description("Fetch feedback for a session")
     .option("--json", "Output JSON")
+    .option("--include-frames", "Inline frame JPEGs as data URIs (requires --json)")
     .action(async (sessionId, opts) => {
     await runWithTelemetry("feedback", async () => {
         try {
+            if (opts.includeFrames && !opts.json) {
+                throw new Error("--include-frames requires --json");
+            }
             const config = requireConfig();
             const [eventsData, annotationsData] = await Promise.all([
                 api(config, "GET", `/sessions/${sessionId}/feedback`),
                 api(config, "GET", `/sessions/${sessionId}/annotations`).catch(() => ({ annotations: [] })),
             ]);
             if (opts.json) {
+                if (opts.includeFrames)
+                    await includeFrames(config, annotationsData);
                 console.log(JSON.stringify({ ...eventsData, ...annotationsData }));
                 return;
             }
@@ -42,6 +86,15 @@ export const feedbackCommand = new Command("feedback")
                 for (const group of annotationsData.annotations) {
                     console.log(`\n--- Version ${group.version} ---`);
                     for (const ann of group.items) {
+                        if (isVideoAnnotation(ann)) {
+                            const layer = sanitizeTerminalText(typeof ann.resolved?.layer === "string" ? ann.resolved.layer : "(unresolved)");
+                            const status = ann.status === "addressed" && typeof ann.addressed_in === "number"
+                                ? `addressed in v${ann.addressed_in}`
+                                : sanitizeTerminalText(typeof ann.status === "string" ? ann.status : "");
+                            console.log(`  [${formatTimecode(ann.at_s)}] ${layer} — ${status}`);
+                            console.log(`    "${sanitizeTerminalText(ann.comment)}"`);
+                            continue;
+                        }
                         const who = ann.viewer ?? "Anonymous";
                         const elementName = ann.element_name || "Unknown";
                         const selector = ann.selector || "";

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.5.0";
+export declare const CLI_VERSION = "0.6.1";

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peekable",
-  "version": "0.5.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:
@@ -218,6 +233,7 @@ Video items come back in the same `peekable feedback <id> --json` payload as can
   },
   "comment": "unreadable at phone size — make it bigger",
   "status": "pending",                      // pending | resolved | addressed
+  "addressed_in": null,                    // always present; version that addressed it
   "frame_url": "/api/sessions/<id>/annotations/a_01j9x4kq/frame"
 }
 ```
@@ -243,3 +259,9 @@ The rule is an array of server annotation IDs:
 >   per-layer rather than per-item.
 
 Always use server annotation `id` values from `peekable feedback --json` in the array. If those IDs are unknown, use the layer-granularity fallback; it means the layer changed in response to feedback, not that a particular item was addressed.
+
+> an item whose id (or layer, in fallback) appears in the new manifest's `changed_by` renders as 'addressed in vN'
+
+Video items always include `addressed_in`; it is the addressing version when `status` is `addressed`, otherwise `null`.
+
+The non-JSON feedback view renders video comments with timecodes. Frame bytes remain by reference through `frame_url`; use `peekable feedback <id> --json --include-frames` to inline each frame as an item's `frame_jpeg` data URI.