peekable 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,100 @@
+# Peekable CLI
+
+Share local HTML mockups, HTML response snapshots, and localhost apps with collaborators.
+Reviewers annotate the page in the browser; you pull structured feedback back into
+your terminal.
+
+## Install
+
+```bash
+npm install -g peekable
+```
+
+## First Run
+
+```bash
+peekable register --name "Your Name" --email "you@example.com" --invite-code "your-invite-code"
+peekable init
+peekable create "My first review"
+```
+
+`peekable create` prints a session ID and share URL. Use the session ID with one
+of the publish commands below.
+
+## Pick The Right Publish Command
+
+Use `push` for a complete standalone HTML file:
+
+```bash
+peekable push <session-id> ./out.html
+```
+
+Use `push-url` when a running page returns a mostly self-contained HTML response
+you want to capture:
+
+```bash
+peekable push-url <session-id> http://localhost:3000
+```
+
+Use `proxy` for a live localhost app with routes, assets, and interactivity:
+
+```bash
+peekable proxy 3000 --name "Homepage review"
+```
+
+## Pull Feedback
+
+```bash
+peekable feedback <session-id>
+peekable watch <session-id>
+peekable resolve <session-id> <annotation-id>
+```
+
+## Free Early Access Limits
+
+The hosted free early-access tier allows 3 active sessions per user. Close old
+sessions when you are done:
+
+```bash
+peekable list
+peekable close <session-id>
+```
+
+Viewer connections are capped on the hosted service so early access stays
+reliable for everyone.
+
+`push-url` snapshots localhost by default. To upload HTML fetched from a remote
+URL, pass `--allow-remote --yes`; for private-network URLs, also pass
+`--allow-private`.
+
+## Debug Setup
+
+If something feels off, run:
+
+```bash
+peekable doctor
+peekable doctor --json
+```
+
+For a deeper connectivity check that creates, pushes, and closes a temporary
+session:
+
+```bash
+peekable doctor --test-push
+```
+
+The doctor output intentionally avoids HTML payloads, annotation text, and API
+keys so it is safe to paste into a support thread.
+
+## Remove Local Setup
+
+To remove Peekable from your machine:
+
+```bash
+peekable uninstall
+npm uninstall -g peekable
+```
+
+`peekable uninstall` removes local config at `~/.peekable` and the installed
+Claude Code skill at `~/.claude/skills/peekable`. It does not delete hosted
+sessions or account data.

package/dist/api.d.ts

@@ -1,3 +1,25 @@
 import { type ShareConfig } from "./config.js";
-export declare function api(config: ShareConfig, method: string, path: string, body?: unknown): Promise<any>;
-export declare function apiNoAuth(url: string, method: string, path: string, body?: unknown): Promise<any>;
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
+export declare class ApiError extends Error {
+    status: number;
+    details: Record<string, unknown>;
+    constructor(status: number, details: Record<string, unknown>, fallback: string);
+}
+export declare function api(config: ShareConfig, method: string, path: string, body?: unknown, opts?: {
+    timeoutMs?: number;
+}): Promise<any>;
+export declare function postDebugEvent(config: ShareConfig, body: {
+    event_name: string;
+    session_id?: string;
+    source?: "cli";
+    command?: string;
+    cli_version?: string;
+    status?: string;
+    duration_ms?: number;
+    error_code?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<any>;
+export declare function apiNoAuth(url: string, method: string, path: string, body?: unknown, opts?: {
+    timeoutMs?: number;
+}): Promise<any>;
+export declare function fetchWithTimeout(input: string | URL, init?: RequestInit, timeoutMs?: number): Promise<Response>;

package/dist/api.js

@@ -1,27 +1,65 @@
-export async function api(config, method, path, body) {
-    const res = await fetch(`${config.url}/api${path}`, {
+export const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+export class ApiError extends Error {
+    status;
+    details;
+    constructor(status, details, fallback) {
+        super(typeof details.error === "string" ? details.error : fallback);
+        this.name = "ApiError";
+        this.status = status;
+        this.details = details;
+    }
+}
+export async function api(config, method, path, body, opts = {}) {
+    const res = await fetchWithTimeout(`${config.url}/api${path}`, {
         method,
         headers: {
             Authorization: `Bearer ${config.api_key}`,
             "Content-Type": "application/json",
         },
         body: body ? JSON.stringify(body) : undefined,
-    });
+    }, opts.timeoutMs);
     if (!res.ok) {
-        const err = await res.json().catch(() => ({ error: res.statusText }));
-        throw new Error(err.error ?? res.statusText);
+        throw await buildApiError(res);
     }
     return res.json();
 }
-export async function apiNoAuth(url, method, path, body) {
-    const res = await fetch(`${url}/api${path}`, {
+export async function postDebugEvent(config, body) {
+    return api(config, "POST", "/debug-events", body);
+}
+export async function apiNoAuth(url, method, path, body, opts = {}) {
+    const res = await fetchWithTimeout(`${url}/api${path}`, {
         method,
         headers: { "Content-Type": "application/json" },
         body: body ? JSON.stringify(body) : undefined,
-    });
+    }, opts.timeoutMs);
     if (!res.ok) {
-        const err = await res.json().catch(() => ({ error: res.statusText }));
-        throw new Error(err.error ?? res.statusText);
+        throw await buildApiError(res);
     }
     return res.json();
 }
+export async function fetchWithTimeout(input, init = {}, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(input, {
+            ...init,
+            signal: init.signal ?? controller.signal,
+        });
+    }
+    catch (err) {
+        if (err?.name === "AbortError") {
+            throw new Error(`Request timed out after ${Math.round(timeoutMs / 1000)}s`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function buildApiError(res) {
+    const details = await res.json().catch(() => ({ error: res.statusText }));
+    const body = details && typeof details === "object" && !Array.isArray(details)
+        ? details
+        : { error: res.statusText };
+    return new ApiError(res.status, body, res.statusText);
+}

package/dist/command-error.d.ts

@@ -0,0 +1,3 @@
+export declare function errorPayload(err: unknown): Record<string, unknown>;
+export declare function getErrorMessage(err: unknown): string;
+export declare function printCommandError(prefix: string, err: unknown, json?: boolean): void;

package/dist/command-error.js

@@ -0,0 +1,23 @@
+import { ApiError } from "./api.js";
+export function errorPayload(err) {
+    if (err instanceof ApiError) {
+        return {
+            error: err.message,
+            ...err.details,
+            status: err.status,
+        };
+    }
+    return { error: getErrorMessage(err) };
+}
+export function getErrorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+export function printCommandError(prefix, err, json) {
+    if (json) {
+        console.log(JSON.stringify(errorPayload(err)));
+        return;
+    }
+    console.error(`${prefix}: ${getErrorMessage(err)}`);
+}

package/dist/commands/create.js

@@ -1,18 +1,25 @@
 import { Command } from "commander";
 import { requireConfig } from "../config.js";
 import { api } from "../api.js";
+import { printCommandError } from "../command-error.js";
 export const createCommand = new Command("create")
     .argument("<name>", "Session name")
     .description("Create a new sharing session")
     .option("--json", "Output JSON")
     .action(async (name, opts) => {
     const config = requireConfig();
-    const data = await api(config, "POST", "/sessions", { name });
-    if (opts.json) {
-        console.log(JSON.stringify(data));
+    try {
+        const data = await api(config, "POST", "/sessions", { name });
+        if (opts.json) {
+            console.log(JSON.stringify(data));
+        }
+        else {
+            console.log(`Created session: ${data.id}`);
+            console.log(`URL: ${data.url}`);
+        }
     }
-    else {
-        console.log(`Created session: ${data.id}`);
-        console.log(`URL: ${data.url}`);
+    catch (err) {
+        printCommandError("Create failed", err, opts.json);
+        process.exit(1);
     }
 });

package/dist/commands/doctor.d.ts

@@ -0,0 +1,21 @@
+import { Command } from "commander";
+export type DoctorStatus = "ok" | "failed" | "skipped";
+export interface DoctorReport {
+    cliVersion: string;
+    nodeVersion: string;
+    configPath: string;
+    configured: boolean;
+    serverUrl: string | null;
+    health: DoctorStatus;
+    auth: DoctorStatus;
+    activeSessions: number | null;
+    maxActiveSessions: number | null;
+    activeSessionUnlimited?: boolean;
+    testPush: DoctorStatus;
+    errors?: string[];
+}
+export declare const doctorCommand: Command;
+export declare function runDoctor(opts?: {
+    testPush?: boolean;
+}): Promise<DoctorReport>;
+export declare function formatDoctorReport(report: DoctorReport): string;

package/dist/commands/doctor.js

@@ -0,0 +1,141 @@
+import { Command } from "commander";
+import { api, fetchWithTimeout } from "../api.js";
+import { getConfigPath, readConfig } from "../config.js";
+import { getErrorMessage } from "../command-error.js";
+import { formatQuota } from "../quota.js";
+import { CLI_VERSION } from "../version.js";
+export const doctorCommand = new Command("doctor")
+    .description("Print a support snapshot for debugging Peekable setup")
+    .option("--json", "Output JSON")
+    .option("--test-push", "Create, push, and close a temporary test session")
+    .action(async (opts) => {
+    const report = await runDoctor({ testPush: Boolean(opts.testPush) });
+    if (opts.json) {
+        console.log(JSON.stringify(report));
+        return;
+    }
+    console.log(formatDoctorReport(report));
+});
+export async function runDoctor(opts = {}) {
+    const config = readConfig();
+    const report = {
+        cliVersion: CLI_VERSION,
+        nodeVersion: process.version,
+        configPath: redactHomePath(getConfigPath()),
+        configured: Boolean(config),
+        serverUrl: config?.url ?? null,
+        health: "skipped",
+        auth: "skipped",
+        activeSessions: null,
+        maxActiveSessions: null,
+        activeSessionUnlimited: false,
+        testPush: "skipped",
+        errors: [],
+    };
+    if (!config) {
+        report.errors.push("Not configured. Run `peekable register` first.");
+        return report;
+    }
+    try {
+        const res = await fetchWithTimeout(`${config.url}/health`);
+        report.health = res.ok ? "ok" : "failed";
+        if (!res.ok)
+            report.errors.push(`Health check failed: HTTP ${res.status}`);
+    }
+    catch (err) {
+        report.health = "failed";
+        report.errors.push(`Health check failed: ${getErrorMessage(err)}`);
+    }
+    try {
+        const data = await getUsageSnapshot(config);
+        report.auth = "ok";
+        report.activeSessions = data.limits?.activeSessions ?? null;
+        report.maxActiveSessions = data.limits?.maxActiveSessions ?? null;
+        report.activeSessionUnlimited = Boolean(data.limits?.unlimited);
+    }
+    catch (err) {
+        report.auth = "failed";
+        report.errors.push(`Auth check failed: ${getErrorMessage(err)}`);
+    }
+    if (opts.testPush && report.auth === "ok") {
+        try {
+            const session = await api(config, "POST", "/sessions", { name: "__peekable_doctor__" });
+            try {
+                await api(config, "POST", `/sessions/${session.id}/push`, {
+                    html: "<html><body><p>Peekable doctor test</p></body></html>",
+                });
+                report.testPush = "ok";
+            }
+            finally {
+                await api(config, "DELETE", `/sessions/${session.id}`).catch(() => undefined);
+            }
+        }
+        catch (err) {
+            report.testPush = "failed";
+            report.errors.push(`Test push failed: ${getErrorMessage(err)}`);
+        }
+    }
+    if (report.errors?.length === 0)
+        delete report.errors;
+    return report;
+}
+export function formatDoctorReport(report) {
+    const lines = [
+        `Peekable CLI: ${report.cliVersion}`,
+        `Node: ${report.nodeVersion}`,
+        `Config: ${report.configured ? report.configPath : "missing"}`,
+        `Server: ${formatServer(report)}`,
+        `Auth: ${formatAuth(report.auth)}`,
+        `Active sessions: ${formatQuota(report.activeSessions, report.maxActiveSessions, report.activeSessionUnlimited)}`,
+        `Test push: ${report.testPush}`,
+    ];
+    if (report.activeSessions !== null &&
+        report.maxActiveSessions !== null &&
+        !report.activeSessionUnlimited &&
+        report.activeSessions >= report.maxActiveSessions) {
+        lines.push("Free plan limit reached. Close one with `peekable close <id>`.");
+    }
+    if (report.errors?.length) {
+        lines.push("", "Errors:");
+        for (const error of report.errors)
+            lines.push(`- ${error}`);
+    }
+    return lines.join("\n");
+}
+function formatServer(report) {
+    if (!report.serverUrl)
+        return "not configured";
+    if (report.health === "ok")
+        return `${report.serverUrl} reachable`;
+    if (report.health === "failed")
+        return `${report.serverUrl} unreachable`;
+    return `${report.serverUrl} not checked`;
+}
+function formatAuth(status) {
+    if (status === "ok")
+        return "valid";
+    if (status === "failed")
+        return "failed";
+    return "not checked";
+}
+async function getUsageSnapshot(config) {
+    try {
+        return await api(config, "GET", "/me/usage");
+    }
+    catch {
+        const data = await api(config, "GET", "/sessions");
+        return {
+            limits: {
+                activeSessions: data.limits?.activeSessions ?? data.sessions?.length ?? null,
+                maxActiveSessions: data.limits?.maxActiveSessions ?? null,
+                unlimited: Boolean(data.limits?.unlimited),
+            },
+        };
+    }
+}
+function redactHomePath(path) {
+    const home = process.env.HOME;
+    if (!home || !path.startsWith(home))
+        return path;
+    return `~${path.slice(home.length)}`;
+}

package/dist/commands/init.js

@@ -1,10 +1,10 @@
 import { Command } from "commander";
 import { existsSync, mkdirSync, cpSync } from "fs";
 import { join, dirname } from "path";
-import { homedir } from "os";
 import { fileURLToPath } from "url";
 import { requireConfig } from "../config.js";
 import { api } from "../api.js";
+import { getClaudeDir, getClaudePeekableSkillDir } from "../paths.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 export const initCommand = new Command("init")
     .description("Set up peekable — install Claude Code skill and verify connection")
@@ -31,11 +31,11 @@ export const initCommand = new Command("init")
     if (!opts.json)
         console.log("Connection verified.");
     // 2. Detect Claude Code and install skill
-    const claudeDir = join(homedir(), ".claude");
+    const claudeDir = getClaudeDir();
     const claudeCodeDetected = existsSync(claudeDir);
     result.claude_code = claudeCodeDetected;
     if (claudeCodeDetected) {
-        const skillDir = join(claudeDir, "skills", "peekable");
+        const skillDir = getClaudePeekableSkillDir();
         // Resolve skill source relative to compiled output location
         const skillSource = join(__dirname, "..", "..", "skill", "SKILL.md");
         if (existsSync(skillSource)) {

package/dist/commands/list.js

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { requireConfig } from "../config.js";
 import { api } from "../api.js";
+import { formatQuota } from "../quota.js";
 export const listCommand = new Command("list")
     .description("List active sessions")
     .option("--json", "Output JSON")
@@ -12,10 +13,20 @@ export const listCommand = new Command("list")
         return;
     }
     if (data.sessions.length === 0) {
-        console.log("No active sessions.");
+        if (data.limits) {
+            console.log(`No active sessions. (${formatQuota(data.limits.activeSessions, data.limits.maxActiveSessions, data.limits.unlimited)})`);
+        }
+        else {
+            console.log("No active sessions.");
+        }
         return;
     }
-    console.log("Active sessions:");
+    if (data.limits) {
+        console.log(`Active sessions (${formatQuota(data.limits.activeSessions, data.limits.maxActiveSessions, data.limits.unlimited)}):`);
+    }
+    else {
+        console.log("Active sessions:");
+    }
     for (const s of data.sessions) {
         console.log(`  ${s.id}  ${s.name}  (${new Date(s.created_at).toLocaleDateString()})`);
     }

package/dist/commands/proxy.js

@@ -2,6 +2,7 @@ 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/",
@@ -26,7 +27,7 @@ export const proxyCommand = new Command("proxy")
     // Validate port
     const port = parseInt(portArg, 10);
     if (isNaN(port) || port < 1 || port > 65535) {
-        console.error("Invalid port: must be 1-65535");
+        printCommandError("Proxy failed", new Error("Invalid port: must be 1-65535"), opts.json);
         process.exit(1);
     }
     // Create or reuse session
@@ -38,11 +39,18 @@ export const proxyCommand = new Command("proxy")
         shareUrl = `https://${sessionId}.${baseDomain}`;
     }
     else {
-        const data = await api(config, "POST", "/sessions", {
-            name: opts.name,
-            mode: "proxy",
-            proxy_target: `localhost:${port}`,
-        });
+        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;
     }

package/dist/commands/push-url.js

@@ -1,32 +1,45 @@
 import { Command } from "commander";
 import { requireConfig } from "../config.js";
-import { api } from "../api.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 a rendered HTML page")
-    .description("Fetch a rendered HTML page from a URL and push it as a new version")
+    .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 wraps fragment content with the CSS/layout shell you want to share.
+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: authenticated pages may snapshot as logged-out because this command does not use browser cookies.
+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) => {
-    const config = requireConfig();
-    const url = parseHttpUrl(urlArg);
-    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()}`);
+    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) {
@@ -42,26 +55,30 @@ function parseHttpUrl(urlArg) {
     }
     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) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
     let res;
     try {
-        res = await fetch(url, {
+        res = await fetchWithTimeout(url, {
             headers: { Accept: "text/html,*/*;q=0.8" },
             redirect: "follow",
-            signal: controller.signal,
-        });
+        }, FETCH_TIMEOUT_MS);
     }
     catch (err) {
-        if (err?.name === "AbortError") {
-            throw new Error(`Timed out fetching ${url.toString()} after ${FETCH_TIMEOUT_MS / 1000}s`);
-        }
         throw err;
     }
-    finally {
-        clearTimeout(timeout);
-    }
     if (!res.ok) {
         throw new Error(`Failed to fetch ${url.toString()}: HTTP ${res.status}`);
     }
@@ -69,5 +86,51 @@ async function fetchHtml(url) {
     if (!contentType.toLowerCase().includes("text/html")) {
         throw new Error(`Expected text/html from ${url.toString()}, got ${contentType || "no content-type"}`);
     }
-    return res.text();
+    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

@@ -3,6 +3,7 @@ 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>", "Standalone HTML file path")
@@ -10,22 +11,28 @@ export const pushCommand = new Command("push")
     .option("--json", "Output JSON")
     .addHelpText("after", `
 Use this for complete HTML documents with their own <html>/<body> shell.
-For a rendered page snapshot, use: peekable push-url <session-id> <url>
+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");
-    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>`.");
+    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}`);
+        }
     }
-    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}`);
+    catch (err) {
+        printCommandError("Push failed", err, opts.json);
+        process.exit(1);
     }
 });
 function looksLikeHtmlFragment(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/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/config.js

@@ -1,8 +1,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-const CONFIG_DIR = join(homedir(), ".peekable");
-const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+import { getPeekableConfigDir, getPeekableConfigFile } from "./paths.js";
+const CONFIG_DIR = getPeekableConfigDir();
+const CONFIG_FILE = getPeekableConfigFile();
 export function readConfig() {
     if (process.env.SHARE_URL && process.env.SHARE_API_KEY) {
         return {

package/dist/index.js

@@ -11,10 +11,13 @@ import { watchCommand } from "./commands/watch.js";
 import { resolveCommand } from "./commands/resolve.js";
 import { proxyCommand } from "./commands/proxy.js";
 import { pushUrlCommand } from "./commands/push-url.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { uninstallCommand } from "./commands/uninstall.js";
+import { CLI_VERSION } from "./version.js";
 program
     .name("peekable")
     .description("Share HTML mockups with collaborators via peekable")
-    .version("0.1.1");
+    .version(CLI_VERSION);
 program.addCommand(registerCommand);
 program.addCommand(initCommand);
 program.addCommand(createCommand);
@@ -26,4 +29,6 @@ program.addCommand(closeCommand);
 program.addCommand(watchCommand);
 program.addCommand(resolveCommand);
 program.addCommand(proxyCommand);
+program.addCommand(doctorCommand);
+program.addCommand(uninstallCommand);
 program.parse();

package/dist/paths.d.ts

@@ -0,0 +1,4 @@
+export declare function getPeekableConfigDir(home?: string): string;
+export declare function getPeekableConfigFile(home?: string): string;
+export declare function getClaudeDir(home?: string): string;
+export declare function getClaudePeekableSkillDir(home?: string): string;

package/dist/paths.js

@@ -0,0 +1,14 @@
+import { homedir } from "os";
+import { join } from "path";
+export function getPeekableConfigDir(home = homedir()) {
+    return join(home, ".peekable");
+}
+export function getPeekableConfigFile(home = homedir()) {
+    return join(getPeekableConfigDir(home), "config.json");
+}
+export function getClaudeDir(home = homedir()) {
+    return join(home, ".claude");
+}
+export function getClaudePeekableSkillDir(home = homedir()) {
+    return join(getClaudeDir(home), "skills", "peekable");
+}

package/dist/quota.d.ts

@@ -0,0 +1 @@
+export declare function formatQuota(active: number | null, max: number | null, unlimited?: boolean): string;

package/dist/quota.js

@@ -0,0 +1,7 @@
+export function formatQuota(active, max, unlimited) {
+    if (unlimited)
+        return active === null ? "unknown / unlimited" : `${active} / unlimited`;
+    if (active === null || max === null)
+        return "unknown";
+    return `${active} / ${max}`;
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const CLI_VERSION = "0.1.2";

package/dist/version.js

@@ -0,0 +1 @@
+export const CLI_VERSION = "0.1.2";

package/package.json

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

package/skill/SKILL.md

@@ -18,21 +18,21 @@ When the user wants to share an HTML file (playground, mockup, brainstorming com
 1. Create a session: `peekable create "<name>" --json`
 2. Inspect the file before pushing:
    - If it contains `<html>` or `<body>`, push it directly: `peekable push <session-id> <file-path> --json`
-   - If it looks like an HTML fragment, do not push it blindly. If you know the rendered page URL, snapshot that instead: `peekable push-url <session-id> <url> --json`
-   - If it looks like a fragment and no rendered URL is known, ask for the localhost/page URL.
+   - If it looks like an HTML fragment, do not push it blindly. If you know a localhost URL that returns the full HTML response, snapshot that instead: `peekable push-url <session-id> <url> --json`
+   - If it looks like a fragment and no localhost/page URL is known, ask for it.
 3. Return the URL to the user
 
 If a session already exists for this topic, reuse it (push creates a new version, collaborators auto-reload).
 
-### Snapshot a rendered page
+### Snapshot an HTML response
 
-When a local companion page or simple server wraps fragment content with styles, use:
+When a local companion page or simple server returns a mostly self-contained HTML response, use:
 
 ```bash
 peekable push-url <session-id> <url> --json
 ```
 
-Use this for rendered pages where the useful CSS/layout comes from the running page shell. `push-url` fetches the HTML response at the URL and pushes that snapshot. It accepts any `http` or `https` URL; authenticated pages may snapshot as logged-out unless the page is publicly reachable without browser cookies.
+`push-url` fetches the HTML response at the URL and pushes that snapshot. It does not execute JavaScript, use browser cookies, or inline external assets. Prefer `peekable proxy` for live React/Vite/Next apps with routes/assets/interactivity. It snapshots localhost by default; remote URLs require `--allow-remote --yes`, and private-network URLs also require `--allow-private`.
 
 ### Check feedback
 
@@ -72,6 +72,24 @@ peekable list --json
 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.
+
+### Diagnose setup
+
+When sharing fails, auth looks broken, or a user asks for help debugging:
+
+```bash
+peekable doctor --json
+```
+
+For a deeper check that creates, pushes, and closes a temporary session:
+
+```bash
+peekable doctor --test-push --json
+```
+
+Doctor output is designed to be safe for support: it does not include API keys, HTML payloads, or annotation text.
+
 ### Watch for annotations
 
 Start a background listener for annotation notifications: