peekable 0.1.4 → 0.1.5

package/dist/commands/list.js

@@ -2,32 +2,42 @@ import { Command } from "commander";
 import { requireConfig } from "../config.js";
 import { api } from "../api.js";
 import { formatQuota } from "../quota.js";
+import { CommandFailure, printCommandError } from "../command-error.js";
+import { runWithTelemetry } from "../telemetry.js";
 export const listCommand = new Command("list")
     .description("List active sessions")
     .option("--json", "Output JSON")
     .action(async (opts) => {
-    const config = requireConfig();
-    const data = await api(config, "GET", "/sessions");
-    if (opts.json) {
-        console.log(JSON.stringify(data));
-        return;
-    }
-    if (data.sessions.length === 0) {
-        if (data.limits) {
-            console.log(`No active sessions. (${formatQuota(data.limits.activeSessions, data.limits.maxActiveSessions, data.limits.unlimited)})`);
+    await runWithTelemetry("list", async () => {
+        try {
+            const config = requireConfig();
+            const data = await api(config, "GET", "/sessions");
+            if (opts.json) {
+                console.log(JSON.stringify(data));
+                return;
+            }
+            if (data.sessions.length === 0) {
+                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;
+            }
+            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()})`);
+            }
         }
-        else {
-            console.log("No active sessions.");
+        catch (err) {
+            printCommandError("List failed", err, opts.json);
+            throw new CommandFailure("List failed", { cause: err });
         }
-        return;
-    }
-    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,7 +2,8 @@ import { Command } from "commander";
 import { watch } from "fs";
 import { requireConfig } from "../config.js";
 import { api } from "../api.js";
-import { printCommandError } from "../command-error.js";
+import { CommandFailure, printCommandError } from "../command-error.js";
+import { postStartEvent, postFireAndForgetDebugEvent } from "../telemetry.js";
 const MAX_RESPONSE_BYTES = 25 * 1024 * 1024; // 25 MB
 const TEXT_CONTENT_TYPES = [
     "text/",
@@ -28,7 +29,7 @@ export const proxyCommand = new Command("proxy")
     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);
+        throw new CommandFailure("Invalid port");
     }
     // Create or reuse session
     let sessionId;
@@ -49,7 +50,7 @@ export const proxyCommand = new Command("proxy")
         }
         catch (err) {
             printCommandError("Proxy session failed", err, opts.json);
-            process.exit(1);
+            throw new CommandFailure("Proxy session failed", { cause: err });
         }
         sessionId = data.id;
         shareUrl = data.url;
@@ -60,9 +61,20 @@ export const proxyCommand = new Command("proxy")
     else {
         console.log(`Share URL: ${shareUrl}`);
     }
+    postStartEvent("cli_proxy_started", { session_id: sessionId, port });
     // Connect relay WebSocket
     const wsUrl = config.url.replace(/^http/, "ws") + "/ws/relay/" + sessionId;
-    const ws = new WebSocket(wsUrl);
+    let ws;
+    try {
+        // The constructor throws synchronously on a malformed URL; fail the
+        // command cleanly instead of escaping the action handler.
+        ws = new WebSocket(wsUrl);
+    }
+    catch (err) {
+        printCommandError("Relay connection failed", err, opts.json);
+        throw new CommandFailure("Relay connection failed", { cause: err });
+    }
+    const wsStartedAt = Date.now();
     const inflight = new Map();
     const fallbackPorts = new Set();
     ws.addEventListener("open", () => {
@@ -88,7 +100,9 @@ export const proxyCommand = new Command("proxy")
         }
         if (msg.type === "error" && !msg.id) {
             console.error(`Relay error: ${msg.message ?? msg.error}`);
-            process.exit(1);
+            process.exitCode = 1;
+            ws.close();
+            return;
         }
         if (msg.type === "discovered_port") {
             const p = msg.port;
@@ -108,18 +122,31 @@ export const proxyCommand = new Command("proxy")
             return;
         }
         if (msg.type === "request") {
-            await handleRequest(ws, msg, port, inflight, fallbackPorts);
+            await handleRequest(ws, msg, port, inflight, fallbackPorts, opts.json);
         }
     });
-    ws.addEventListener("close", () => {
+    ws.addEventListener("close", (event) => {
+        const closeEvent = event;
+        postFireAndForgetDebugEvent("cli_ws_disconnected", {
+            code: closeEvent?.code,
+            reason: typeof closeEvent?.reason === "string" ? closeEvent.reason.slice(0, 120) : undefined,
+            uptime_ms: Date.now() - wsStartedAt,
+            surface: "proxy",
+        }, { sessionId });
         if (!opts.json) {
             console.log("Relay disconnected.");
         }
-        process.exit(0);
+        // Exit cleanly after telemetry attempts to flush
+        setTimeout(() => process.exit(process.exitCode ?? 0), 200);
     });
     ws.addEventListener("error", (e) => {
-        console.error("WebSocket error:", e.message ?? e);
-        process.exit(1);
+        const message = e?.message ?? String(e);
+        console.error("WebSocket error:", message);
+        postFireAndForgetDebugEvent("cli_ws_error", {
+            surface: "proxy",
+            error_message: String(message).slice(0, 280),
+        }, { sessionId });
+        process.exitCode = 1;
     });
     // File watching
     if (opts.watch) {
@@ -143,10 +170,11 @@ export const proxyCommand = new Command("proxy")
     // Shutdown
     process.on("SIGINT", () => {
         ws.close();
-        process.exit(0);
+        // give telemetry a beat, then exit
+        setTimeout(() => process.exit(0), 200);
     });
 });
-async function handleRequest(ws, msg, port, inflight, fallbackPorts) {
+async function handleRequest(ws, msg, port, inflight, fallbackPorts, jsonOutput) {
     const ac = new AbortController();
     inflight.set(msg.id, ac);
     try {
@@ -263,9 +291,13 @@ async function handleRequest(ws, msg, port, inflight, fallbackPorts) {
     catch (err) {
         if (ac.signal.aborted)
             return;
-        const message = err.cause?.code === "ECONNREFUSED"
+        const isEconnRefused = err?.cause?.code === "ECONNREFUSED";
+        const message = isEconnRefused
             ? "ECONNREFUSED"
             : err.message ?? "Upstream fetch failed";
+        if (isEconnRefused && !jsonOutput) {
+            console.error(`Upstream ECONNREFUSED: no local server responding on port ${port} for ${msg.method ?? "GET"} ${msg.path}`);
+        }
         ws.send(JSON.stringify({
             type: "response",
             id: msg.id,

package/dist/commands/push-url.js

@@ -1,7 +1,8 @@
 import { Command } from "commander";
 import { requireConfig } from "../config.js";
 import { api, fetchWithTimeout } from "../api.js";
-import { printCommandError } from "../command-error.js";
+import { CommandFailure, printCommandError } from "../command-error.js";
+import { runWithTelemetry } from "../telemetry.js";
 const FETCH_TIMEOUT_MS = 30_000;
 const MAX_HTML_BYTES = 5 * 1024 * 1024;
 export const pushUrlCommand = new Command("push-url")
@@ -21,26 +22,28 @@ Note: this does not execute JavaScript, use browser cookies, or inline external
 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));
+    await runWithTelemetry("push_url", async () => {
+        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()}`);
+            }
         }
-        else {
-            console.log(`Pushed v${data.version} to ${sessionId} from ${url.toString()}`);
+        catch (err) {
+            printCommandError("Push URL failed", err, opts.json);
+            throw new CommandFailure("Push URL failed", { cause: err });
         }
-    }
-    catch (err) {
-        printCommandError("Push URL failed", err, opts.json);
-        process.exit(1);
-    }
+    });
 });
 function parseHttpUrl(urlArg) {
     let url;

package/dist/commands/push.js

@@ -3,7 +3,8 @@ import { readFileSync } from "fs";
 import { resolve } from "path";
 import { requireConfig } from "../config.js";
 import { api } from "../api.js";
-import { printCommandError } from "../command-error.js";
+import { CommandFailure, printCommandError } from "../command-error.js";
+import { runWithTelemetry } from "../telemetry.js";
 export const pushCommand = new Command("push")
     .argument("<session-id>", "Session ID")
     .argument("<file>", "Standalone HTML file path")
@@ -15,25 +16,30 @@ 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) => {
-    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 telemetryContext = { session_id: sessionId };
+    await runWithTelemetry("push", async () => {
+        try {
+            const config = requireConfig();
+            const html = readFileSync(file, "utf-8");
+            telemetryContext.file_bytes = Buffer.byteLength(html, "utf-8");
+            telemetryContext.looks_like_fragment = looksLikeHtmlFragment(html);
+            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));
+        catch (err) {
+            printCommandError("Push failed", err, opts.json);
+            throw new CommandFailure("Push failed", { cause: err });
         }
-        else {
-            console.log(`Pushed v${data.version} to ${sessionId}`);
-        }
-    }
-    catch (err) {
-        printCommandError("Push failed", err, opts.json);
-        process.exit(1);
-    }
+    }, telemetryContext);
 });
 function looksLikeHtmlFragment(html) {
     return !/<\s*(html|body)(?:\s|>)/i.test(html);

package/dist/commands/register.js

@@ -1,57 +1,62 @@
 import { Command } from "commander";
-import { writeConfig, readConfig } from "../config.js";
+import { writeConfig, readConfig, DEFAULT_SERVER_URL } from "../config.js";
 import { apiNoAuth } from "../api.js";
-import { printCommandError } from "../command-error.js";
-const DEFAULT_URL = "https://peekable.fyi";
+import { CommandFailure, printCommandError } from "../command-error.js";
+import { runWithTelemetry } from "../telemetry.js";
 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("--url <url>", "Server URL", DEFAULT_SERVER_URL)
     .option("--json", "Output JSON")
     .action(async (opts) => {
-    const existing = readConfig();
-    if (existing) {
-        if (opts.json) {
-            console.log(JSON.stringify({ error: "Already registered. Config exists at ~/.peekable/config.json" }));
+    await runWithTelemetry("register", async () => {
+        const existing = readConfig();
+        if (existing) {
+            if (opts.json) {
+                console.log(JSON.stringify({ error: "Already registered. Config exists at ~/.peekable/config.json" }));
+            }
+            else {
+                console.error("Already registered. Config exists at ~/.peekable/config.json");
+                console.error("Delete ~/.peekable/config.json to re-register.");
+            }
+            throw new CommandFailure("Already registered.");
         }
-        else {
-            console.error("Already registered. Config exists at ~/.peekable/config.json");
-            console.error("Delete ~/.peekable/config.json to re-register.");
+        try {
+            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,
+                api_key: data.api_key,
+                name: opts.name,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify({ api_key: data.api_key, url: opts.url, name: opts.name }));
+            }
+            else {
+                console.log(`Registered as ${opts.name}.`);
+                console.log(`API key saved to ~/.peekable/config.json`);
+                console.log("Peekable CLI sends anonymous usage/failure telemetry to improve reliability. Opt out: PEEKABLE_NO_TELEMETRY=1");
+                console.log(`\nNext step: run \`peekable init\` to complete setup.`);
+            }
         }
-        process.exit(1);
-    }
-    try {
-        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;
+        catch (err) {
+            if (err instanceof CommandFailure)
+                throw err;
+            printCommandError("Registration failed", err, opts.json);
+            throw new CommandFailure("Registration failed", { cause: err });
         }
-        const data = await apiNoAuth(opts.url, "POST", "/register", {
-            ...body,
-        });
-        writeConfig({
-            url: opts.url,
-            api_key: data.api_key,
-            name: opts.name,
-        });
-        if (opts.json) {
-            console.log(JSON.stringify({ api_key: data.api_key, url: opts.url, name: opts.name }));
-        }
-        else {
-            console.log(`Registered as ${opts.name}.`);
-            console.log(`API key saved to ~/.peekable/config.json`);
-            console.log(`\nNext step: run \`peekable init\` to complete setup.`);
-        }
-    }
-    catch (err) {
-        printCommandError("Registration failed", err, opts.json);
-        process.exit(1);
-    }
+    });
 });

package/dist/commands/report.d.ts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+import { type DoctorScalarSnapshot } from "./doctor.js";
+export interface ReportPayload {
+    message: string;
+    diagnostics?: DoctorScalarSnapshot;
+}
+export declare function buildReportPayload(opts: {
+    message: string;
+    diagnostics: boolean;
+}): Promise<ReportPayload>;
+export declare const reportCommand: Command;

package/dist/commands/report.js

@@ -0,0 +1,107 @@
+import { Command } from "commander";
+import * as readline from "readline";
+import { api } from "../api.js";
+import { requireConfig, ConfigError } from "../config.js";
+import { CommandFailure, printCommandError } from "../command-error.js";
+import { runWithTelemetry } from "../telemetry.js";
+import { runDoctor, toScalarSnapshot } from "./doctor.js";
+const MAX_MESSAGE_LEN = 2000;
+async function promptForMessage() {
+    // Piped/closed stdin never answers the question; without a TTY, don't prompt.
+    if (!process.stdin.isTTY)
+        return "";
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        return await new Promise((resolve) => {
+            rl.question("What went wrong? ", (answer) => resolve(answer));
+            // stdin EOF closes the interface without ever invoking the question
+            // callback — resolve empty instead of hanging the process.
+            rl.once("close", () => resolve(""));
+        });
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function buildReportPayload(opts) {
+    const message = opts.message.slice(0, MAX_MESSAGE_LEN);
+    if (!opts.diagnostics)
+        return { message };
+    const doctor = await runDoctor();
+    return { message, diagnostics: toScalarSnapshot(doctor) };
+}
+export const reportCommand = new Command("report")
+    .argument("[message...]", "Message to send")
+    .description("Report a problem or send feedback to the Peekable team")
+    .option("--no-diagnostics", "Opt out of sending diagnostics")
+    .option("--json", "Output JSON")
+    .action(async (messageParts, opts) => {
+    await runWithTelemetry("report", async () => {
+        let config;
+        try {
+            config = requireConfig();
+        }
+        catch (err) {
+            if (err instanceof ConfigError) {
+                const friendly = err.reason === "corrupt"
+                    ? "Config file is corrupted. Run `peekable register` to reconfigure."
+                    : "Peekable isn't configured yet. Run `peekable register` first, or file an issue at https://github.com/peekable/peekable/issues.";
+                if (opts.json) {
+                    console.log(JSON.stringify({ error: friendly }));
+                }
+                else {
+                    console.error(friendly);
+                }
+                throw new CommandFailure("Report requires registration", { cause: err });
+            }
+            throw err;
+        }
+        let message = messageParts.join(" ").trim();
+        if (!message) {
+            try {
+                message = (await promptForMessage()).trim();
+            }
+            catch {
+                message = "";
+            }
+        }
+        if (!message) {
+            const msg = "No message provided.";
+            if (opts.json) {
+                console.log(JSON.stringify({ error: msg }));
+            }
+            else {
+                console.error(msg);
+            }
+            throw new CommandFailure(msg);
+        }
+        // Diagnostics ON by default; commander sets opts.diagnostics = false when --no-diagnostics passed.
+        const includeDiagnostics = opts.diagnostics !== false;
+        const payload = await buildReportPayload({ message, diagnostics: includeDiagnostics });
+        if (!opts.json) {
+            console.log("Sending report:");
+            console.log(JSON.stringify(payload, null, 2));
+        }
+        try {
+            const res = await api(config, "POST", "/cli/report", payload);
+            const requestId = res && typeof res === "object" && typeof res.request_id === "string"
+                ? res.request_id
+                : undefined;
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: true, request_id: requestId }));
+            }
+            else {
+                console.log("Report submitted. Thanks — we read every one.");
+                if (requestId)
+                    console.log(`Request ID: ${requestId}`);
+            }
+        }
+        catch (err) {
+            printCommandError("Report failed", err, opts.json);
+            throw new CommandFailure("Report failed", { cause: err });
+        }
+    });
+});

package/dist/commands/resolve.js

@@ -1,20 +1,30 @@
 import { Command } from "commander";
 import { requireConfig } from "../config.js";
 import { api } from "../api.js";
+import { CommandFailure, printCommandError } from "../command-error.js";
+import { runWithTelemetry } from "../telemetry.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,
+    await runWithTelemetry("resolve", async () => {
+        try {
+            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).`);
+            }
+        }
+        catch (err) {
+            printCommandError("Resolve failed", err, opts.json);
+            throw new CommandFailure("Resolve failed", { cause: err });
+        }
     });
-    if (opts.json) {
-        console.log(JSON.stringify(data));
-    }
-    else {
-        console.log(`Resolved ${data.resolved} annotation(s).`);
-    }
 });

package/dist/commands/uninstall.js

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { existsSync, rmSync } from "fs";
 import { homedir } from "os";
 import { getClaudePeekableSkillDir, getCodexPeekableSkillDir, getPeekableConfigDir } from "../paths.js";
+import { runWithTelemetry } from "../telemetry.js";
 function getUninstallTargets(home = homedir()) {
     return [
         {
@@ -69,17 +70,19 @@ 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;
-        }
+        .action(async (opts) => {
+        await runWithTelemetry("uninstall", async () => {
+            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();