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

@@ -7,20 +7,50 @@ export const feedbackCommand = new Command("feedback")
     .option("--json", "Output JSON")
     .action(async (sessionId, opts) => {
     const config = requireConfig();
-    const data = await api(config, "GET", `/sessions/${sessionId}/feedback`);
+    const [eventsData, annotationsData] = await Promise.all([
+        api(config, "GET", `/sessions/${sessionId}/feedback`),
+        api(config, "GET", `/sessions/${sessionId}/annotations`).catch(() => ({ annotations: [] })),
+    ]);
     if (opts.json) {
-        console.log(JSON.stringify(data));
+        console.log(JSON.stringify({ ...eventsData, ...annotationsData }));
         return;
     }
-    if (data.feedback.length === 0) {
+    const hasFeedback = eventsData.feedback.length > 0;
+    const hasAnnotations = annotationsData.annotations && annotationsData.annotations.length > 0;
+    if (!hasFeedback && !hasAnnotations) {
         console.log("No feedback yet.");
         return;
     }
-    for (const group of data.feedback) {
-        console.log(`\n--- Version ${group.version} ---`);
-        for (const event of group.events) {
-            const who = event.viewer ?? "Anonymous";
-            console.log(`  ${who} chose "${event.choice}" — ${event.label}`);
+    // Display choice feedback
+    if (hasFeedback) {
+        console.log("\nChoice Feedback:");
+        for (const group of eventsData.feedback) {
+            console.log(`\n--- Version ${group.version} ---`);
+            for (const event of group.events) {
+                const who = event.viewer ?? "Anonymous";
+                console.log(`  ${who} chose "${event.choice}" — ${event.label}`);
+            }
+        }
+    }
+    // Display annotations
+    if (hasAnnotations) {
+        console.log("\nAnnotations:");
+        for (const group of annotationsData.annotations) {
+            console.log(`\n--- Version ${group.version} ---`);
+            for (const ann of group.items) {
+                const who = ann.viewer ?? "Anonymous";
+                const elementName = ann.element_name || "Unknown";
+                const selector = ann.selector || "";
+                console.log(`  [${who}] ${elementName} (${selector})`);
+                console.log(`    "${ann.note}"`);
+                if (ann.element_context?.computedStyles) {
+                    const styles = Object.entries(ann.element_context.computedStyles)
+                        .map(([key, val]) => `${key}: ${val}`)
+                        .join(", ");
+                    if (styles)
+                        console.log(`    Styles: ${styles}`);
+                }
+            }
         }
     }
 });

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.d.ts

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