peekable 0.1.4 → 0.2.0

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.2.0";

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peekable",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "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",