peekable 0.1.4 → 0.1.5

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,11 @@ 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 { 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 +35,33 @@ program.addCommand(resolveCommand);
 program.addCommand(proxyCommand);
 program.addCommand(doctorCommand);
 program.addCommand(uninstallCommand);
-program.parse();
+program.addCommand(reportCommand);
+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>;

package/dist/telemetry.js

@@ -0,0 +1,297 @@
+import { ApiError, postDebugEvent, USER_AGENT } from "./api.js";
+import { tryReadConfig, DEFAULT_SERVER_URL, ConfigError } from "./config.js";
+import { CLI_VERSION } from "./version.js";
+import { CommandFailure } from "./command-error.js";
+const SUCCESS_TIMEOUT_MS = 1000;
+const FAILURE_TIMEOUT_MS = 2000;
+const MAX_ERROR_MESSAGE_LEN = 280;
+const ALLOWED_BEACON_EVENTS = new Set([
+    "cli_register_failed",
+    "cli_config_corrupt",
+    "cli_connect_failed",
+    "cli_preauth_failed",
+    "cli_crash",
+]);
+export function isTelemetryDisabled() {
+    return process.env.PEEKABLE_NO_TELEMETRY === "1";
+}
+function baseMetadata() {
+    return {
+        os: process.platform,
+        arch: process.arch,
+        node: process.version,
+    };
+}
+function truncate(input, max) {
+    return input.length <= max ? input : input.slice(0, max);
+}
+// Commands wrap their real error in CommandFailure before it escapes to
+// runWithTelemetry; classification (ApiError request_id, ConfigError reason)
+// must look at the underlying error, not the wrapper.
+function unwrapCause(err) {
+    let current = err;
+    while (current instanceof CommandFailure && current.cause !== undefined) {
+        current = current.cause;
+    }
+    return current;
+}
+// Stack traces and fs error messages embed absolute paths under the user's
+// home directory (which carries the OS username). Redact before transmission.
+function redactHomePaths(text) {
+    const home = process.env.HOME || process.env.USERPROFILE;
+    if (!home || home.length < 4)
+        return text;
+    return text.split(home).join("~");
+}
+function extractErrorCode(err) {
+    if (err instanceof CommandFailure && err.cause !== undefined) {
+        return extractErrorCode(err.cause);
+    }
+    if (err instanceof ApiError) {
+        return String(err.status);
+    }
+    if (err instanceof ConfigError) {
+        return err.reason === "corrupt" ? "config_corrupt" : "config_missing";
+    }
+    if (err && typeof err === "object") {
+        const anyErr = err;
+        if (typeof anyErr.code === "string" && anyErr.code)
+            return anyErr.code;
+        if (anyErr.cause && typeof anyErr.cause.code === "string")
+            return anyErr.cause.code;
+        if (typeof anyErr.name === "string" && anyErr.name && anyErr.name !== "Error") {
+            return anyErr.name;
+        }
+    }
+    return "unknown";
+}
+function extractErrorMessage(err) {
+    if (err instanceof CommandFailure && err.cause instanceof Error) {
+        return truncate(err.cause.message ?? "", MAX_ERROR_MESSAGE_LEN);
+    }
+    if (err instanceof Error)
+        return truncate(err.message ?? "", MAX_ERROR_MESSAGE_LEN);
+    return truncate(String(err), MAX_ERROR_MESSAGE_LEN);
+}
+function looksLikeConnectFailure(err) {
+    const code = extractErrorCode(err);
+    const connCodes = new Set([
+        "ECONNREFUSED",
+        "ENOTFOUND",
+        "EAI_AGAIN",
+        "ETIMEDOUT",
+        "ECONNRESET",
+        "EHOSTUNREACH",
+        "ENETUNREACH",
+        "UND_ERR_CONNECT_TIMEOUT",
+        "UND_ERR_SOCKET",
+    ]);
+    return connCodes.has(code);
+}
+function resolveBeaconTarget() {
+    if (process.env.SHARE_URL)
+        return process.env.SHARE_URL;
+    const cfg = tryReadConfig();
+    if (cfg.state === "ok")
+        return cfg.config.url;
+    return DEFAULT_SERVER_URL;
+}
+async function raceTimeout(promise, ms) {
+    await Promise.race([
+        promise.then(() => undefined, () => undefined),
+        new Promise((resolve) => {
+            const t = setTimeout(resolve, ms);
+            // don't hold the loop open beyond needed
+            if (typeof t === "object" && t && typeof t.unref === "function") {
+                t.unref();
+            }
+        }),
+    ]);
+}
+async function beaconPost(eventName, extraMetadata) {
+    if (!ALLOWED_BEACON_EVENTS.has(eventName))
+        return;
+    const url = resolveBeaconTarget();
+    const payload = {
+        event_name: eventName,
+        cli_version: CLI_VERSION,
+        ...baseMetadata(),
+    };
+    if (typeof extraMetadata.error_code === "string") {
+        payload.error_code = extraMetadata.error_code;
+    }
+    if (typeof extraMetadata.command === "string") {
+        payload.command = extraMetadata.command;
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FAILURE_TIMEOUT_MS);
+    try {
+        await fetch(`${url}/api/cli/beacon`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": USER_AGENT,
+            },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        // fire and forget
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function completedEventName(commandName) {
+    return `cli_${commandName}_completed`;
+}
+function failedEventName(commandName) {
+    return `cli_${commandName}_failed`;
+}
+async function sendAuthenticatedDebugEvent(eventName, status, commandName, durationMs, metadata, errorCode, sessionId) {
+    const cfg = tryReadConfig();
+    if (cfg.state !== "ok")
+        return false;
+    try {
+        await postDebugEvent(cfg.config, {
+            event_name: eventName,
+            session_id: sessionId,
+            source: "cli",
+            command: commandName,
+            cli_version: CLI_VERSION,
+            status,
+            duration_ms: durationMs,
+            error_code: errorCode,
+            metadata,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 async function runWithTelemetry(commandName, fn, context) {
+    if (isTelemetryDisabled()) {
+        await fn();
+        return;
+    }
+    const start = Date.now();
+    let caught;
+    try {
+        await fn();
+    }
+    catch (err) {
+        caught = err;
+    }
+    const durationMs = Date.now() - start;
+    // Context is read after fn() so the command can populate it as it learns
+    // things (file size, fragment hints). session_id rides the envelope's
+    // dedicated column; everything else lands in metadata.
+    const { session_id: contextSessionId, ...contextMetadata } = context ?? {};
+    const sessionId = typeof contextSessionId === "string" ? contextSessionId : undefined;
+    if (caught === undefined) {
+        const p = sendAuthenticatedDebugEvent(completedEventName(commandName), "ok", commandName, durationMs, { ...baseMetadata(), ...contextMetadata }, undefined, sessionId);
+        await raceTimeout(p, SUCCESS_TIMEOUT_MS);
+        return;
+    }
+    const errorCode = extractErrorCode(caught);
+    const unwrapped = unwrapCause(caught);
+    const metadata = {
+        ...baseMetadata(),
+        ...contextMetadata,
+        error_message: redactHomePaths(extractErrorMessage(caught)),
+    };
+    const cfgForServerUrl = tryReadConfig();
+    if (cfgForServerUrl.state === "ok") {
+        metadata.server_url = cfgForServerUrl.config.url;
+    }
+    // Prefer the underlying error's stack — CommandFailure's own stack only
+    // points at the command's catch block.
+    const stackSource = unwrapped instanceof Error && unwrapped.stack ? unwrapped : caught;
+    if (stackSource instanceof Error && stackSource.stack) {
+        metadata.stack_summary = redactHomePaths(stackSource.stack.split("\n").slice(0, 9).join("\n").slice(0, 2000));
+    }
+    if (unwrapped instanceof ApiError && typeof unwrapped.details.request_id === "string") {
+        metadata.request_id = unwrapped.details.request_id;
+    }
+    const p = (async () => {
+        const sent = await sendAuthenticatedDebugEvent(failedEventName(commandName), "error", commandName, durationMs, metadata, errorCode, sessionId);
+        if (sent)
+            return;
+        // Fall back to anonymous beacon for pre-auth failures. Specific names
+        // first; cli_preauth_failed is the catch-all so no failure class is
+        // completely dark just because the user has no config yet.
+        let beaconEvent;
+        if (unwrapped instanceof ConfigError && unwrapped.reason === "corrupt") {
+            beaconEvent = "cli_config_corrupt";
+        }
+        else if (commandName === "register") {
+            beaconEvent = "cli_register_failed";
+        }
+        else if (looksLikeConnectFailure(caught)) {
+            beaconEvent = "cli_connect_failed";
+        }
+        else {
+            beaconEvent = "cli_preauth_failed";
+        }
+        await beaconPost(beaconEvent, { error_code: errorCode, command: commandName });
+    })();
+    await raceTimeout(p, FAILURE_TIMEOUT_MS);
+    throw caught;
+}
+/**
+ * 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 function postStartEvent(eventName, metadata = {}) {
+    if (isTelemetryDisabled())
+        return;
+    const cfg = tryReadConfig();
+    if (cfg.state !== "ok")
+        return;
+    const started = postDebugEvent(cfg.config, {
+        event_name: eventName,
+        source: "cli",
+        cli_version: CLI_VERSION,
+        metadata: { ...baseMetadata(), ...metadata },
+    }).catch(() => undefined);
+    // fire-and-forget: don't await
+    void started;
+}
+/**
+ * Fire-and-forget best-effort debug event with a 1s cap. Used for WS
+ * close/error handlers in long-running commands.
+ */
+export function postFireAndForgetDebugEvent(eventName, metadata = {}, opts = {}) {
+    if (isTelemetryDisabled())
+        return;
+    const cfg = tryReadConfig();
+    if (cfg.state !== "ok")
+        return;
+    const p = postDebugEvent(cfg.config, {
+        event_name: eventName,
+        source: "cli",
+        cli_version: CLI_VERSION,
+        session_id: opts.sessionId,
+        error_code: opts.errorCode,
+        metadata: { ...baseMetadata(), ...metadata },
+    }).catch(() => undefined);
+    void raceTimeout(p, SUCCESS_TIMEOUT_MS);
+}
+/**
+ * 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 async function postCrashBeacon(err) {
+    if (isTelemetryDisabled())
+        return;
+    const p = beaconPost("cli_crash", { error_code: extractErrorCode(err) });
+    await raceTimeout(p, FAILURE_TIMEOUT_MS);
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "0.1.4";
+export declare const CLI_VERSION = "0.1.5";

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.4";
+export const CLI_VERSION = "0.1.5";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peekable",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Share HTML mockups with collaborators — CLI for peekable-server",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "dev": "tsx src/index.ts"
+    "dev": "tsx src/index.ts",
+    "test": "vitest run"
   },
   "dependencies": {
     "commander": "^12"
@@ -16,7 +17,8 @@
   "devDependencies": {
     "typescript": "^5",
     "tsx": "^4",
-    "@types/node": "^22"
+    "@types/node": "^22",
+    "vitest": "^3"
   },
   "files": [
     "dist",