peekable 0.1.4 → 0.2.0

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();

package/dist/commands/upgrade.d.ts

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

package/dist/commands/upgrade.js

@@ -0,0 +1,63 @@
+import { spawn } from "node:child_process";
+import { Command } from "commander";
+import { api, ApiError } from "../api.js";
+import { CommandFailure, printCommandError } from "../command-error.js";
+import { requireConfig } from "../config.js";
+import { runWithTelemetry } from "../telemetry.js";
+export const upgradeCommand = new Command("upgrade")
+    .description("Upgrade a Peekable trial through Stripe Checkout")
+    .option("--json", "Output JSON")
+    .action(async (opts) => {
+    await runWithTelemetry("upgrade", async () => {
+        const config = requireConfig();
+        try {
+            const data = await api(config, "POST", "/billing/checkout", {});
+            const url = checkoutUrl(data?.url);
+            if (!url)
+                throw new Error("Checkout did not return a valid URL.");
+            if (opts.json) {
+                console.log(JSON.stringify({ url, sessionId: data.sessionId ?? null }));
+            }
+            else {
+                console.log("Complete your Peekable upgrade in Stripe Checkout:");
+                console.log(url);
+                openBrowserBestEffort(url);
+            }
+        }
+        catch (err) {
+            if (!opts.json
+                && err instanceof ApiError
+                && (err.details.code === "billing_account_exists"
+                    || err.details.code === "billing_account_requires_support")) {
+                console.error("Email support@peekable.fyi from your registered account email for help.");
+            }
+            printCommandError("Upgrade failed", err, opts.json);
+            throw new CommandFailure("Upgrade failed", { cause: err });
+        }
+    });
+});
+function checkoutUrl(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" || url.protocol === "http:" ? url.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function openBrowserBestEffort(url) {
+    try {
+        const child = process.platform === "darwin"
+            ? spawn("open", [url], { detached: true, stdio: "ignore" })
+            : process.platform === "win32"
+                ? spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" })
+                : spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
+        child.on("error", () => undefined);
+        child.unref();
+    }
+    catch {
+        // The URL remains printed for humans and coding agents to relay.
+    }
+}

package/dist/commands/watch.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { requireConfig } from "../config.js";
+import { postStartEvent, postFireAndForgetDebugEvent } from "../telemetry.js";
 export const watchCommand = new Command("watch")
     .argument("<session-id>", "Session ID to watch")
     .description("Watch for annotation notifications on a session")
@@ -8,8 +9,27 @@ export const watchCommand = new Command("watch")
     const wsUrl = config.url.replace(/^http/, "ws") + `/ws/${sessionId}`;
     let reconnectDelay = 1000;
     const maxDelay = 30000;
+    postStartEvent("cli_watch_started", { session_id: sessionId });
     function connect() {
-        const ws = new WebSocket(wsUrl);
+        const startedAt = Date.now();
+        let ws;
+        try {
+            // The constructor throws synchronously on a malformed URL (e.g. a
+            // config.url scheme that http->ws substitution didn't convert).
+            ws = new WebSocket(wsUrl);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`WebSocket connect failed: ${message}`);
+            postFireAndForgetDebugEvent("cli_ws_error", {
+                surface: "watch",
+                error_message: message.slice(0, 280),
+            }, { sessionId });
+            console.log(`Reconnecting in ${reconnectDelay / 1000}s...`);
+            setTimeout(connect, reconnectDelay);
+            reconnectDelay = Math.min(reconnectDelay * 2, maxDelay);
+            return;
+        }
         ws.addEventListener("open", () => {
             reconnectDelay = 1000;
             console.log(`Watching session ${sessionId} for annotations...`);
@@ -27,12 +47,26 @@ export const watchCommand = new Command("watch")
                 // Non-JSON messages (e.g. "reload") — ignore
             }
         });
-        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() - startedAt,
+                surface: "watch",
+            }, { sessionId });
             console.log(`Disconnected. Reconnecting in ${reconnectDelay / 1000}s...`);
             setTimeout(connect, reconnectDelay);
             reconnectDelay = Math.min(reconnectDelay * 2, maxDelay);
         });
-        ws.addEventListener("error", () => {
+        ws.addEventListener("error", (event) => {
+            const anyEvt = event;
+            const message = typeof anyEvt?.message === "string" ? anyEvt.message : "WebSocket error";
+            console.error(`WebSocket error: ${message}`);
+            postFireAndForgetDebugEvent("cli_ws_error", {
+                surface: "watch",
+                error_message: String(message).slice(0, 280),
+            }, { sessionId });
             // Error triggers close, which handles reconnection
         });
     }

package/dist/config.d.ts

@@ -3,6 +3,22 @@ export interface ShareConfig {
     api_key: string;
     name: string;
 }
+export declare const DEFAULT_SERVER_URL = "https://peekable.fyi";
+export type TryReadConfigResult = {
+    state: "ok";
+    config: ShareConfig;
+} | {
+    state: "missing";
+} | {
+    state: "corrupt";
+    parseError: string;
+};
+export declare class ConfigError extends Error {
+    reason: "missing" | "corrupt";
+    parseError?: string;
+    constructor(reason: "missing" | "corrupt", parseError?: string);
+}
+export declare function tryReadConfig(configFile?: string): TryReadConfigResult;
 export declare function readConfig(): ShareConfig | null;
 export declare function writeConfig(config: ShareConfig): void;
 export declare function requireConfig(): ShareConfig;

package/dist/config.js

@@ -1,36 +1,85 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
 import { getPeekableConfigDir, getPeekableConfigFile } from "./paths.js";
+export const DEFAULT_SERVER_URL = "https://peekable.fyi";
 const CONFIG_DIR = getPeekableConfigDir();
 const CONFIG_FILE = getPeekableConfigFile();
-export function readConfig() {
+export class ConfigError extends Error {
+    reason;
+    parseError;
+    constructor(reason, parseError) {
+        super(reason === "corrupt"
+            ? "Config file is corrupted. Run `peekable register` to reconfigure."
+            : "Not configured. Run `peekable register` first.");
+        this.name = "ConfigError";
+        this.reason = reason;
+        this.parseError = parseError;
+    }
+}
+export function tryReadConfig(configFile = CONFIG_FILE) {
     if (process.env.SHARE_URL && process.env.SHARE_API_KEY) {
         return {
-            url: process.env.SHARE_URL,
-            api_key: process.env.SHARE_API_KEY,
-            name: process.env.SHARE_NAME ?? "User",
+            state: "ok",
+            config: {
+                url: process.env.SHARE_URL,
+                api_key: process.env.SHARE_API_KEY,
+                name: process.env.SHARE_NAME ?? "User",
+            },
+        };
+    }
+    if (!existsSync(configFile))
+        return { state: "missing" };
+    let raw;
+    try {
+        raw = readFileSync(configFile, "utf-8");
+    }
+    catch (err) {
+        return {
+            state: "corrupt",
+            parseError: err instanceof Error ? err.message : String(err),
         };
     }
-    if (!existsSync(CONFIG_FILE))
-        return null;
     try {
-        const raw = readFileSync(CONFIG_FILE, "utf-8");
-        return JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            typeof parsed.url !== "string" ||
+            typeof parsed.api_key !== "string") {
+            return { state: "corrupt", parseError: "missing required fields" };
+        }
+        return {
+            state: "ok",
+            config: {
+                url: parsed.url,
+                api_key: parsed.api_key,
+                name: typeof parsed.name === "string" ? parsed.name : "User",
+            },
+        };
     }
-    catch {
-        return null;
+    catch (err) {
+        return {
+            state: "corrupt",
+            parseError: err instanceof Error ? err.message : String(err),
+        };
     }
 }
+export function readConfig() {
+    const result = tryReadConfig();
+    if (result.state === "ok")
+        return result.config;
+    return null;
+}
 export function writeConfig(config) {
     mkdirSync(CONFIG_DIR, { recursive: true });
     writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n");
 }
 export function requireConfig() {
-    const config = readConfig();
-    if (!config) {
-        console.error("Not configured. Run `peekable register` first.");
-        process.exit(1);
+    const result = tryReadConfig();
+    if (result.state === "ok")
+        return result.config;
+    if (result.state === "corrupt") {
+        throw new ConfigError("corrupt", result.parseError);
     }
-    return config;
+    throw new ConfigError("missing");
 }
 export function getConfigPath() {
     return CONFIG_FILE;

package/dist/index.js

@@ -13,7 +13,12 @@ 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 { reportCommand } from "./commands/report.js";
+import { upgradeCommand } from "./commands/upgrade.js";
 import { CLI_VERSION } from "./version.js";
+import { CommandFailure } from "./command-error.js";
+import { ConfigError } from "./config.js";
+import { postCrashBeacon } from "./telemetry.js";
 program
     .name("peekable")
     .description("Share HTML mockups with collaborators via peekable")
@@ -31,4 +36,34 @@ program.addCommand(resolveCommand);
 program.addCommand(proxyCommand);
 program.addCommand(doctorCommand);
 program.addCommand(uninstallCommand);
-program.parse();
+program.addCommand(reportCommand);
+program.addCommand(upgradeCommand);
+program.addHelpText("afterAll", `
+Telemetry:
+  Peekable CLI sends anonymous usage/failure telemetry to improve reliability.
+  Opt out with PEEKABLE_NO_TELEMETRY=1.
+`);
+async function main() {
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (err) {
+        if (err instanceof CommandFailure) {
+            // Command already printed its user-facing error via printCommandError.
+            process.exitCode = err.exitCode;
+            return;
+        }
+        if (err instanceof ConfigError) {
+            console.error(err.message);
+            process.exitCode = 1;
+            return;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(message);
+        // Unexpected crash (escaped every command handler) — fire the anonymous
+        // crash beacon so it isn't invisible server-side.
+        await postCrashBeacon(err);
+        process.exitCode = 1;
+    }
+}
+main();

package/dist/telemetry.d.ts

@@ -0,0 +1,26 @@
+export declare function isTelemetryDisabled(): boolean;
+/**
+ * Wrap a short-lived command action so success/failure telemetry is emitted.
+ * The command's original error (if any) is rethrown after telemetry settles.
+ */
+export declare function runWithTelemetry(commandName: string, fn: () => Promise<void>, context?: Record<string, unknown>): Promise<void>;
+/**
+ * Fire-and-forget start event for long-running commands (watch, proxy).
+ * The returned promise resolves once telemetry settles (or times out); callers
+ * may ignore it.
+ */
+export declare function postStartEvent(eventName: "cli_watch_started" | "cli_proxy_started" | string, metadata?: Record<string, unknown>): void;
+/**
+ * Fire-and-forget best-effort debug event with a 1s cap. Used for WS
+ * close/error handlers in long-running commands.
+ */
+export declare function postFireAndForgetDebugEvent(eventName: string, metadata?: Record<string, unknown>, opts?: {
+    sessionId?: string;
+    errorCode?: string;
+}): void;
+/**
+ * Last-resort crash beacon for errors that escape runWithTelemetry entirely
+ * (commander parse failures, module load errors). Anonymous, allowlisted,
+ * capped at FAILURE_TIMEOUT_MS so it never delays exit noticeably.
+ */
+export declare function postCrashBeacon(err: unknown): Promise<void>;