peekable 0.1.0 → 0.1.2

package/dist/commands/proxy.js

@@ -0,0 +1,280 @@
+import { Command } from "commander";
+import { watch } from "fs";
+import { requireConfig } from "../config.js";
+import { api } from "../api.js";
+import { printCommandError } from "../command-error.js";
+const MAX_RESPONSE_BYTES = 25 * 1024 * 1024; // 25 MB
+const TEXT_CONTENT_TYPES = [
+    "text/",
+    "application/json",
+    "application/javascript",
+    "application/xml",
+    "image/svg+xml",
+];
+function isTextContentType(ct) {
+    return TEXT_CONTENT_TYPES.some((t) => ct.includes(t));
+}
+export const proxyCommand = new Command("proxy")
+    .argument("<port>", "Local port to proxy")
+    .description("Proxy a local dev server through a peekable share URL")
+    .option("--name <name>", "Session name", "Proxy")
+    .option("--session <id>", "Reuse an existing session ID")
+    .option("--watch <dir>", "Watch directory for changes and trigger reload")
+    .option("--takeover", "Take over an existing relay connection")
+    .option("--json", "Output JSON")
+    .action(async (portArg, opts) => {
+    const config = requireConfig();
+    // Validate port
+    const port = parseInt(portArg, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+        printCommandError("Proxy failed", new Error("Invalid port: must be 1-65535"), opts.json);
+        process.exit(1);
+    }
+    // Create or reuse session
+    let sessionId;
+    let shareUrl;
+    if (opts.session) {
+        sessionId = opts.session;
+        const baseDomain = new URL(config.url).hostname;
+        shareUrl = `https://${sessionId}.${baseDomain}`;
+    }
+    else {
+        let data;
+        try {
+            data = await api(config, "POST", "/sessions", {
+                name: opts.name,
+                mode: "proxy",
+                proxy_target: `localhost:${port}`,
+            });
+        }
+        catch (err) {
+            printCommandError("Proxy session failed", err, opts.json);
+            process.exit(1);
+        }
+        sessionId = data.id;
+        shareUrl = data.url;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ id: sessionId, url: shareUrl }));
+    }
+    else {
+        console.log(`Share URL: ${shareUrl}`);
+    }
+    // Connect relay WebSocket
+    const wsUrl = config.url.replace(/^http/, "ws") + "/ws/relay/" + sessionId;
+    const ws = new WebSocket(wsUrl);
+    const inflight = new Map();
+    const fallbackPorts = new Set();
+    ws.addEventListener("open", () => {
+        ws.send(JSON.stringify({
+            type: "auth",
+            token: config.api_key,
+            takeover: !!opts.takeover,
+        }));
+    });
+    ws.addEventListener("message", async (event) => {
+        let msg;
+        try {
+            msg = JSON.parse(typeof event.data === "string" ? event.data : "");
+        }
+        catch {
+            return;
+        }
+        if (msg.type === "auth_ok") {
+            if (!opts.json) {
+                console.log("Relay connected. Waiting for viewers...");
+            }
+            return;
+        }
+        if (msg.type === "error" && !msg.id) {
+            console.error(`Relay error: ${msg.message ?? msg.error}`);
+            process.exit(1);
+        }
+        if (msg.type === "discovered_port") {
+            const p = msg.port;
+            if (typeof p === "number" && p !== port && !fallbackPorts.has(p)) {
+                fallbackPorts.add(p);
+                if (!opts.json)
+                    console.log(`Discovered backend on port ${p}`);
+            }
+            return;
+        }
+        if (msg.type === "cancel") {
+            const ac = inflight.get(msg.id);
+            if (ac) {
+                ac.abort();
+                inflight.delete(msg.id);
+            }
+            return;
+        }
+        if (msg.type === "request") {
+            await handleRequest(ws, msg, port, inflight, fallbackPorts);
+        }
+    });
+    ws.addEventListener("close", () => {
+        if (!opts.json) {
+            console.log("Relay disconnected.");
+        }
+        process.exit(0);
+    });
+    ws.addEventListener("error", (e) => {
+        console.error("WebSocket error:", e.message ?? e);
+        process.exit(1);
+    });
+    // File watching
+    if (opts.watch) {
+        let debounce = null;
+        watch(opts.watch, { recursive: true }, () => {
+            if (debounce)
+                clearTimeout(debounce);
+            debounce = setTimeout(async () => {
+                try {
+                    await api(config, "POST", `/sessions/${sessionId}/reload`, {});
+                    if (!opts.json) {
+                        console.log("File change detected, reload triggered.");
+                    }
+                }
+                catch (err) {
+                    console.error("Reload failed:", err.message);
+                }
+            }, 500);
+        });
+    }
+    // Shutdown
+    process.on("SIGINT", () => {
+        ws.close();
+        process.exit(0);
+    });
+});
+async function handleRequest(ws, msg, port, inflight, fallbackPorts) {
+    const ac = new AbortController();
+    inflight.set(msg.id, ac);
+    try {
+        const url = `http://localhost:${port}${msg.path}`;
+        // Build headers, skip host and x-forwarded-*
+        const headers = new Headers();
+        if (Array.isArray(msg.headers)) {
+            for (const [k, v] of msg.headers) {
+                const lower = k.toLowerCase();
+                if (lower === "host" || lower.startsWith("x-forwarded-") || lower === "origin" || lower === "referer")
+                    continue;
+                headers.set(k, v);
+            }
+        }
+        headers.set("host", `localhost:${port}`);
+        headers.set("origin", `http://localhost:${port}`);
+        headers.set("accept-encoding", "identity");
+        // Decode body
+        let body;
+        if (msg.body) {
+            const binary = atob(msg.body);
+            const bytes = new Uint8Array(binary.length);
+            for (let i = 0; i < binary.length; i++)
+                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;
+                    }
+                }
+                catch {
+                    // Fallback port not reachable, continue
+                }
+            }
+        }
+        // Build response header tuples
+        const respHeaders = [];
+        upstream.headers.forEach((v, k) => {
+            respHeaders.push([k, v]);
+        });
+        // Read body
+        const respBuffer = await upstream.arrayBuffer();
+        if (respBuffer.byteLength > MAX_RESPONSE_BYTES) {
+            ws.send(JSON.stringify({
+                type: "response",
+                id: msg.id,
+                status: 502,
+                headers: [["content-type", "text/plain"]],
+                body: "Response too large (>25MB)",
+            }));
+            return;
+        }
+        const ct = upstream.headers.get("content-type") ?? "";
+        let respBody;
+        let encoding;
+        if (isTextContentType(ct)) {
+            respBody = new TextDecoder().decode(respBuffer);
+        }
+        else {
+            // Base64 encode binary
+            const bytes = new Uint8Array(respBuffer);
+            let binary = "";
+            for (let i = 0; i < bytes.length; i++) {
+                binary += String.fromCharCode(bytes[i]);
+            }
+            respBody = btoa(binary);
+            encoding = "base64";
+        }
+        const response = {
+            type: "response",
+            id: msg.id,
+            status: upstream.status,
+            headers: respHeaders,
+            body: respBody,
+        };
+        if (encoding)
+            response.encoding = encoding;
+        ws.send(JSON.stringify(response));
+    }
+    catch (err) {
+        if (ac.signal.aborted)
+            return;
+        const message = err.cause?.code === "ECONNREFUSED"
+            ? "ECONNREFUSED"
+            : err.message ?? "Upstream fetch failed";
+        ws.send(JSON.stringify({
+            type: "response",
+            id: msg.id,
+            status: 502,
+            headers: [["content-type", "text/plain"]],
+            body: message,
+        }));
+    }
+    finally {
+        inflight.delete(msg.id);
+    }
+}

package/dist/commands/push-url.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const pushUrlCommand: Command;

package/dist/commands/push-url.js

@@ -0,0 +1,136 @@
+import { Command } from "commander";
+import { requireConfig } from "../config.js";
+import { api, fetchWithTimeout } from "../api.js";
+import { printCommandError } from "../command-error.js";
+const FETCH_TIMEOUT_MS = 30_000;
+const MAX_HTML_BYTES = 5 * 1024 * 1024;
+export const pushUrlCommand = new Command("push-url")
+    .argument("<session-id>", "Session ID")
+    .argument("<url>", "URL that returns an HTML response")
+    .description("Fetch an HTML response from a URL and push it as a new version")
+    .option("--json", "Output JSON")
+    .option("--allow-remote", "Allow snapshotting a non-localhost URL")
+    .option("--allow-private", "Allow snapshotting a private-network URL")
+    .option("-y, --yes", "Confirm the fetched HTML can be uploaded to the session")
+    .addHelpText("after", `
+Use this when a running page returns a mostly self-contained HTML response you want to share.
+For standalone HTML files, use: peekable push <session-id> <file>
+For live dev servers with routes/assets/interactivity, use: peekable proxy <port>
+
+Note: this does not execute JavaScript, use browser cookies, or inline external assets.
+Remote URLs require --allow-remote --yes because the fetched HTML is uploaded to the session.
+`)
+    .action(async (sessionId, urlArg, opts) => {
+    try {
+        const config = requireConfig();
+        const url = parseHttpUrl(urlArg);
+        validateSnapshotTarget(url, opts);
+        const html = await fetchHtml(url);
+        const data = await api(config, "POST", `/sessions/${sessionId}/push`, {
+            html,
+            source_path: url.toString(),
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(data));
+        }
+        else {
+            console.log(`Pushed v${data.version} to ${sessionId} from ${url.toString()}`);
+        }
+    }
+    catch (err) {
+        printCommandError("Push URL failed", err, opts.json);
+        process.exit(1);
+    }
+});
+function parseHttpUrl(urlArg) {
+    let url;
+    try {
+        url = new URL(urlArg);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${urlArg}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error("URL must use http or https");
+    }
+    return url;
+}
+function validateSnapshotTarget(url, opts) {
+    const local = isLocalhost(url.hostname);
+    const privateNetwork = !local && isPrivateNetworkHost(url.hostname);
+    if (!local && !opts.allowRemote) {
+        throw new Error("push-url snapshots localhost by default. Pass --allow-remote --yes to upload HTML from a remote URL.");
+    }
+    if (privateNetwork && !opts.allowPrivate) {
+        throw new Error("Private-network URLs require --allow-private --yes so internal pages are not uploaded accidentally.");
+    }
+    if ((!local || privateNetwork) && !opts.yes) {
+        throw new Error("Pass --yes to confirm the fetched HTML can be uploaded to the session.");
+    }
+}
+async function fetchHtml(url) {
+    let res;
+    try {
+        res = await fetchWithTimeout(url, {
+            headers: { Accept: "text/html,*/*;q=0.8" },
+            redirect: "follow",
+        }, FETCH_TIMEOUT_MS);
+    }
+    catch (err) {
+        throw err;
+    }
+    if (!res.ok) {
+        throw new Error(`Failed to fetch ${url.toString()}: HTTP ${res.status}`);
+    }
+    const contentType = res.headers.get("content-type") ?? "";
+    if (!contentType.toLowerCase().includes("text/html")) {
+        throw new Error(`Expected text/html from ${url.toString()}, got ${contentType || "no content-type"}`);
+    }
+    const declaredLength = Number(res.headers.get("content-length") ?? 0);
+    if (declaredLength > MAX_HTML_BYTES) {
+        throw new Error(`HTML response is too large (${declaredLength} bytes, max ${MAX_HTML_BYTES})`);
+    }
+    return readTextWithLimit(res, MAX_HTML_BYTES);
+}
+async function readTextWithLimit(res, maxBytes) {
+    if (!res.body) {
+        const text = await res.text();
+        if (new TextEncoder().encode(text).byteLength > maxBytes) {
+            throw new Error(`HTML response is too large (max ${maxBytes} bytes)`);
+        }
+        return text;
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new Error(`HTML response is too large (max ${maxBytes} bytes)`);
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder("utf-8").decode(bytes);
+}
+function isLocalhost(hostname) {
+    const host = hostname.toLowerCase();
+    return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+}
+function isPrivateNetworkHost(hostname) {
+    const host = hostname.toLowerCase();
+    if (!host.includes("."))
+        return true;
+    if (host.endsWith(".local"))
+        return true;
+    return /^(10\.|192\.168\.|169\.254\.|172\.(1[6-9]|2\d|3[0-1])\.)/.test(host);
+}

package/dist/commands/push.js

@@ -1,20 +1,40 @@
 import { Command } from "commander";
 import { readFileSync } from "fs";
+import { resolve } from "path";
 import { requireConfig } from "../config.js";
 import { api } from "../api.js";
+import { printCommandError } from "../command-error.js";
 export const pushCommand = new Command("push")
     .argument("<session-id>", "Session ID")
-    .argument("<file>", "HTML file path")
-    .description("Push an HTML file as a new version")
+    .argument("<file>", "Standalone HTML file path")
+    .description("Push a standalone HTML file as a new version")
     .option("--json", "Output JSON")
+    .addHelpText("after", `
+Use this for complete HTML documents with their own <html>/<body> shell.
+For an HTML response snapshot, use: peekable push-url <session-id> <url>
+For a live dev server, use: peekable proxy <port>
+`)
     .action(async (sessionId, file, opts) => {
-    const config = requireConfig();
-    const html = readFileSync(file, "utf-8");
-    const data = await api(config, "POST", `/sessions/${sessionId}/push`, { html });
-    if (opts.json) {
-        console.log(JSON.stringify(data));
+    try {
+        const config = requireConfig();
+        const html = readFileSync(file, "utf-8");
+        if (!opts.json && looksLikeHtmlFragment(html)) {
+            console.error("\x1b[33mNote:\x1b[0m this file looks like an HTML fragment. It may render unstyled when shared standalone. If it is part of a parent app, prefer `peekable push-url <session> <url>`. For live dev servers (React/Vite/Next), use `peekable proxy <port>`.");
+        }
+        const source_path = resolve(file);
+        const data = await api(config, "POST", `/sessions/${sessionId}/push`, { html, source_path });
+        if (opts.json) {
+            console.log(JSON.stringify(data));
+        }
+        else {
+            console.log(`Pushed v${data.version} to ${sessionId}`);
+        }
     }
-    else {
-        console.log(`Pushed v${data.version} to ${sessionId}`);
+    catch (err) {
+        printCommandError("Push failed", err, opts.json);
+        process.exit(1);
     }
 });
+function looksLikeHtmlFragment(html) {
+    return !/<\s*(html|body)(?:\s|>)/i.test(html);
+}

package/dist/commands/register.js

@@ -6,6 +6,7 @@ export const registerCommand = new Command("register")
     .description("Register for an API key")
     .requiredOption("--name <name>", "Your display name")
     .requiredOption("--email <email>", "Your email address")
+    .option("--invite-code <code>", "Beta invite code")
     .option("--url <url>", "Server URL", DEFAULT_URL)
     .option("--json", "Output JSON")
     .action(async (opts) => {
@@ -21,9 +22,18 @@ export const registerCommand = new Command("register")
         process.exit(1);
     }
     try {
-        const data = await apiNoAuth(opts.url, "POST", "/register", {
+        const inviteCode = typeof opts.inviteCode === "string"
+            ? opts.inviteCode
+            : process.env.PEEKABLE_INVITE_CODE;
+        const body = {
             name: opts.name,
             email: opts.email,
+        };
+        if (inviteCode) {
+            body.invite_code = inviteCode;
+        }
+        const data = await apiNoAuth(opts.url, "POST", "/register", {
+            ...body,
         });
         writeConfig({
             url: opts.url,

package/dist/commands/resolve.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const resolveCommand: Command;

package/dist/commands/resolve.js

@@ -0,0 +1,20 @@
+import { Command } from "commander";
+import { requireConfig } from "../config.js";
+import { api } from "../api.js";
+export const resolveCommand = new Command("resolve")
+    .argument("<session-id>", "Session ID")
+    .argument("<annotation-ids...>", "Annotation IDs to resolve")
+    .description("Mark annotations as resolved")
+    .option("--json", "Output JSON")
+    .action(async (sessionId, annotationIds, opts) => {
+    const config = requireConfig();
+    const data = await api(config, "PATCH", `/sessions/${sessionId}/annotations/resolve`, {
+        annotationIds,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(data));
+    }
+    else {
+        console.log(`Resolved ${data.resolved} annotation(s).`);
+    }
+});

package/dist/commands/uninstall.d.ts

@@ -0,0 +1,21 @@
+import { Command } from "commander";
+import { rmSync } from "fs";
+type RemoveTarget = typeof rmSync;
+type UninstallTarget = {
+    label: string;
+    path: string;
+    existed: boolean;
+    removed: boolean;
+    error?: string;
+};
+type UninstallResult = {
+    status: "ok" | "partial";
+    targets: UninstallTarget[];
+    npmUninstallCommand: string;
+    note: string;
+};
+export declare function removeLocalPeekableFiles(home?: string, removeTarget?: RemoveTarget): UninstallResult;
+export declare function formatUninstallResult(result: UninstallResult): string;
+export declare function createUninstallCommand(): Command;
+export declare const uninstallCommand: Command;
+export {};

package/dist/commands/uninstall.js

@@ -0,0 +1,81 @@
+import { Command } from "commander";
+import { existsSync, rmSync } from "fs";
+import { homedir } from "os";
+import { getClaudePeekableSkillDir, getPeekableConfigDir } from "../paths.js";
+function getUninstallTargets(home = homedir()) {
+    return [
+        {
+            label: "Peekable config",
+            path: getPeekableConfigDir(home),
+        },
+        {
+            label: "Claude Code skill",
+            path: getClaudePeekableSkillDir(home),
+        },
+    ];
+}
+export function removeLocalPeekableFiles(home = homedir(), removeTarget = rmSync) {
+    const targets = getUninstallTargets(home).map((target) => {
+        const existed = existsSync(target.path);
+        if (!existed) {
+            return { ...target, existed, removed: false };
+        }
+        try {
+            removeTarget(target.path, { recursive: true, force: true });
+        }
+        catch (error) {
+            return {
+                ...target,
+                existed,
+                removed: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+        return {
+            ...target,
+            existed,
+            removed: !existsSync(target.path),
+        };
+    });
+    const hasFailure = targets.some((target) => target.error || (target.existed && !target.removed));
+    return {
+        status: hasFailure ? "partial" : "ok",
+        targets,
+        npmUninstallCommand: "npm uninstall -g peekable",
+        note: "This only removes local Peekable files. It does not delete hosted sessions or account data.",
+    };
+}
+export function formatUninstallResult(result) {
+    const lines = result.targets.map((target) => {
+        if (target.error) {
+            return `${target.label}: failed to remove (${target.path}) - ${target.error}`;
+        }
+        if (!target.existed) {
+            return `${target.label}: not found (${target.path})`;
+        }
+        return `${target.label}: ${target.removed ? "removed" : "not removed"} (${target.path})`;
+    });
+    lines.push("");
+    lines.push(`To remove the CLI package, run: ${result.npmUninstallCommand}`);
+    lines.push(result.note);
+    lines.push("For hosted account or data deletion, contact support.");
+    return lines.join("\n");
+}
+export function createUninstallCommand() {
+    return new Command("uninstall")
+        .description("Remove local Peekable config and installed Claude Code skill")
+        .option("--json", "Output JSON")
+        .action((opts) => {
+        const result = removeLocalPeekableFiles();
+        if (opts.json) {
+            console.log(JSON.stringify(result));
+        }
+        else {
+            console.log(formatUninstallResult(result));
+        }
+        if (result.status !== "ok") {
+            process.exitCode = 1;
+        }
+    });
+}
+export const uninstallCommand = createUninstallCommand();

package/dist/commands/watch.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const watchCommand: Command;

package/dist/commands/watch.js

@@ -0,0 +1,40 @@
+import { Command } from "commander";
+import { requireConfig } from "../config.js";
+export const watchCommand = new Command("watch")
+    .argument("<session-id>", "Session ID to watch")
+    .description("Watch for annotation notifications on a session")
+    .action(async (sessionId) => {
+    const config = requireConfig();
+    const wsUrl = config.url.replace(/^http/, "ws") + `/ws/${sessionId}`;
+    let reconnectDelay = 1000;
+    const maxDelay = 30000;
+    function connect() {
+        const ws = new WebSocket(wsUrl);
+        ws.addEventListener("open", () => {
+            reconnectDelay = 1000;
+            console.log(`Watching session ${sessionId} for annotations...`);
+        });
+        ws.addEventListener("message", (event) => {
+            try {
+                const msg = JSON.parse(String(event.data));
+                if (msg.type === "annotations_submitted") {
+                    const viewer = msg.viewer || "Someone";
+                    console.log(`\n📝 ${viewer} submitted annotations on v${msg.version}`);
+                    console.log(`   Run: /peekable review ${sessionId}`);
+                }
+            }
+            catch {
+                // Non-JSON messages (e.g. "reload") — ignore
+            }
+        });
+        ws.addEventListener("close", () => {
+            console.log(`Disconnected. Reconnecting in ${reconnectDelay / 1000}s...`);
+            setTimeout(connect, reconnectDelay);
+            reconnectDelay = Math.min(reconnectDelay * 2, maxDelay);
+        });
+        ws.addEventListener("error", () => {
+            // Error triggers close, which handles reconnection
+        });
+    }
+    connect();
+});