peekable 0.1.4 → 0.1.5

package/dist/api.d.ts

@@ -1,5 +1,6 @@
 import { type ShareConfig } from "./config.js";
 export declare const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
+export declare const USER_AGENT: string;
 export declare class ApiError extends Error {
     status: number;
     details: Record<string, unknown>;

package/dist/api.js

@@ -1,4 +1,6 @@
+import { CLI_VERSION } from "./version.js";
 export const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+export const USER_AGENT = `peekable-cli/${CLI_VERSION} (${process.platform}; ${process.arch}; node ${process.version})`;
 export class ApiError extends Error {
     status;
     details;
@@ -15,6 +17,7 @@ export async function api(config, method, path, body, opts = {}) {
         headers: {
             Authorization: `Bearer ${config.api_key}`,
             "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
         },
         body: body ? JSON.stringify(body) : undefined,
     }, opts.timeoutMs);
@@ -29,7 +32,10 @@ export async function postDebugEvent(config, body) {
 export async function apiNoAuth(url, method, path, body, opts = {}) {
     const res = await fetchWithTimeout(`${url}/api${path}`, {
         method,
-        headers: { "Content-Type": "application/json" },
+        headers: {
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+        },
         body: body ? JSON.stringify(body) : undefined,
     }, opts.timeoutMs);
     if (!res.ok) {
@@ -40,9 +46,14 @@ export async function apiNoAuth(url, method, path, body, opts = {}) {
 export async function fetchWithTimeout(input, init = {}, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const headers = new Headers(init.headers);
+    if (!headers.has("User-Agent")) {
+        headers.set("User-Agent", USER_AGENT);
+    }
     try {
         return await fetch(input, {
             ...init,
+            headers,
             signal: init.signal ?? controller.signal,
         });
     }
@@ -61,5 +72,12 @@ async function buildApiError(res) {
     const body = details && typeof details === "object" && !Array.isArray(details)
         ? details
         : { error: res.statusText };
+    // Every response carries X-Request-Id, but only 500 bodies embed it —
+    // lift it from the header so 4xx failures stay correlatable too.
+    if (typeof body.request_id !== "string") {
+        const headerRequestId = res.headers.get("x-request-id");
+        if (headerRequestId)
+            body.request_id = headerRequestId;
+    }
     return new ApiError(res.status, body, res.statusText);
 }

package/dist/command-error.d.ts

@@ -1,3 +1,11 @@
+export declare class CommandFailure extends Error {
+    exitCode: number;
+    cause?: unknown;
+    constructor(message: string, opts?: {
+        exitCode?: number;
+        cause?: unknown;
+    });
+}
 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

@@ -1,4 +1,14 @@
 import { ApiError } from "./api.js";
+export class CommandFailure extends Error {
+    exitCode;
+    cause;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "CommandFailure";
+        this.exitCode = opts.exitCode ?? 1;
+        this.cause = opts.cause;
+    }
+}
 export function errorPayload(err) {
     if (err instanceof ApiError) {
         return {
@@ -10,14 +20,31 @@ export function errorPayload(err) {
     return { error: getErrorMessage(err) };
 }
 export function getErrorMessage(err) {
+    if (err instanceof CommandFailure) {
+        if (err.cause instanceof Error)
+            return err.cause.message;
+        return err.message;
+    }
     if (err instanceof Error)
         return err.message;
     return String(err);
 }
+function getRequestId(err) {
+    const source = err instanceof CommandFailure ? err.cause : err;
+    if (source instanceof ApiError) {
+        const rid = source.details.request_id;
+        if (typeof rid === "string" && rid)
+            return rid;
+    }
+    return undefined;
+}
 export function printCommandError(prefix, err, json) {
+    const cause = err instanceof CommandFailure && err.cause !== undefined ? err.cause : err;
     if (json) {
-        console.log(JSON.stringify(errorPayload(err)));
+        console.log(JSON.stringify(errorPayload(cause)));
         return;
     }
-    console.error(`${prefix}: ${getErrorMessage(err)}`);
+    const requestId = getRequestId(err);
+    const suffix = requestId ? ` (request_id: ${requestId})` : "";
+    console.error(`${prefix}: ${getErrorMessage(err)}${suffix}`);
 }

package/dist/commands/close.js

@@ -1,17 +1,27 @@
 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 closeCommand = new Command("close")
     .argument("<session-id>", "Session ID")
     .description("Close a session")
     .option("--json", "Output JSON")
     .action(async (sessionId, opts) => {
-    const config = requireConfig();
-    await api(config, "DELETE", `/sessions/${sessionId}`);
-    if (opts.json) {
-        console.log(JSON.stringify({ ok: true }));
-    }
-    else {
-        console.log(`Closed session ${sessionId}`);
-    }
+    await runWithTelemetry("close", async () => {
+        try {
+            const config = requireConfig();
+            await api(config, "DELETE", `/sessions/${sessionId}`);
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: true }));
+            }
+            else {
+                console.log(`Closed session ${sessionId}`);
+            }
+        }
+        catch (err) {
+            printCommandError("Close failed", err, opts.json);
+            throw new CommandFailure("Close failed", { cause: err });
+        }
+    });
 });

package/dist/commands/create.js

@@ -1,25 +1,28 @@
 import { Command } from "commander";
 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 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();
-    try {
-        const data = await api(config, "POST", "/sessions", { name });
-        if (opts.json) {
-            console.log(JSON.stringify(data));
+    await runWithTelemetry("create", async () => {
+        try {
+            const config = requireConfig();
+            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);
+            throw new CommandFailure("Create failed", { cause: err });
         }
-    }
-    catch (err) {
-        printCommandError("Create failed", err, opts.json);
-        process.exit(1);
-    }
+    });
 });

package/dist/commands/doctor.d.ts

@@ -3,19 +3,47 @@ export type DoctorStatus = "ok" | "failed" | "skipped";
 export interface DoctorReport {
     cliVersion: string;
     nodeVersion: string;
+    os: string;
+    osRelease: string;
+    arch: string;
+    isTty: boolean;
     configPath: string;
     configured: boolean;
     serverUrl: string | null;
     health: DoctorStatus;
     auth: DoctorStatus;
+    identity: DoctorStatus;
+    identityName?: string | null;
+    identityEmail?: string | null;
     activeSessions: number | null;
     maxActiveSessions: number | null;
     activeSessionUnlimited?: boolean;
     testPush: DoctorStatus;
     errors?: string[];
 }
+/**
+ * Scalar-only snapshot suitable for authenticated telemetry. Excludes raw
+ * error strings, identity fields, and any path or free-form text.
+ */
+export interface DoctorScalarSnapshot {
+    cli_version: string;
+    node_version: string;
+    os: string;
+    os_release: string;
+    arch: string;
+    is_tty: boolean;
+    configured: boolean;
+    health: DoctorStatus;
+    auth: DoctorStatus;
+    identity: DoctorStatus;
+    test_push: DoctorStatus;
+    active_sessions: number | null;
+    max_active_sessions: number | null;
+    active_session_unlimited: boolean;
+}
 export declare const doctorCommand: Command;
 export declare function runDoctor(opts?: {
     testPush?: boolean;
 }): Promise<DoctorReport>;
+export declare function toScalarSnapshot(report: DoctorReport): DoctorScalarSnapshot;
 export declare function formatDoctorReport(report: DoctorReport): string;

package/dist/commands/doctor.js

@@ -1,31 +1,84 @@
 import { Command } from "commander";
-import { api, fetchWithTimeout } from "../api.js";
-import { getConfigPath, readConfig } from "../config.js";
-import { getErrorMessage } from "../command-error.js";
+import { release } from "os";
+import { api, fetchWithTimeout, postDebugEvent } from "../api.js";
+import { ConfigError, getConfigPath, readConfig, tryReadConfig } from "../config.js";
+import { CommandFailure, getErrorMessage } from "../command-error.js";
 import { formatQuota } from "../quota.js";
 import { CLI_VERSION } from "../version.js";
+import { runWithTelemetry } from "../telemetry.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")
+    .option("--report", "Send a scalar snapshot to Peekable as authenticated telemetry")
     .action(async (opts) => {
-    const report = await runDoctor({ testPush: Boolean(opts.testPush) });
-    if (opts.json) {
-        console.log(JSON.stringify(report));
-        return;
-    }
-    console.log(formatDoctorReport(report));
+    await runWithTelemetry("doctor", async () => {
+        const report = await runDoctor({ testPush: Boolean(opts.testPush) });
+        if (opts.json) {
+            console.log(JSON.stringify(report));
+        }
+        else {
+            console.log(formatDoctorReport(report));
+        }
+        if (opts.report) {
+            const configResult = tryReadConfig();
+            if (configResult.state !== "ok") {
+                // Distinguish corrupt from missing so telemetry classifies the
+                // beacon as cli_config_corrupt rather than the generic catch-all.
+                if (configResult.state === "corrupt") {
+                    const msg = "Cannot send doctor report: config file is corrupted. Run `peekable register` to reconfigure.";
+                    console.error(msg);
+                    throw new CommandFailure(msg, {
+                        cause: new ConfigError("corrupt", configResult.parseError),
+                    });
+                }
+                console.error("Cannot send doctor report: not configured. Run `peekable register` first.");
+                throw new CommandFailure("Not configured");
+            }
+            const config = configResult.config;
+            const snapshot = toScalarSnapshot(report);
+            if (!opts.json) {
+                console.log("\nSending doctor report:");
+                console.log(JSON.stringify(snapshot, null, 2));
+            }
+            try {
+                await postDebugEvent(config, {
+                    event_name: "cli_doctor_ran",
+                    source: "cli",
+                    command: "doctor",
+                    cli_version: CLI_VERSION,
+                    status: "ok",
+                    metadata: {
+                        ...snapshot,
+                        diagnostics_json: JSON.stringify(snapshot),
+                    },
+                });
+                if (!opts.json)
+                    console.log("Report sent.");
+            }
+            catch (err) {
+                if (!opts.json)
+                    console.error(`Report send failed: ${getErrorMessage(err)}`);
+                throw new CommandFailure("Report send failed", { cause: err });
+            }
+        }
+    });
 });
 export async function runDoctor(opts = {}) {
     const config = readConfig();
     const report = {
         cliVersion: CLI_VERSION,
         nodeVersion: process.version,
+        os: process.platform,
+        osRelease: release(),
+        arch: process.arch,
+        isTty: Boolean(process.stdout.isTTY),
         configPath: redactHomePath(getConfigPath()),
         configured: Boolean(config),
         serverUrl: config?.url ?? null,
         health: "skipped",
         auth: "skipped",
+        identity: "skipped",
         activeSessions: null,
         maxActiveSessions: null,
         activeSessionUnlimited: false,
@@ -57,6 +110,19 @@ export async function runDoctor(opts = {}) {
         report.auth = "failed";
         report.errors.push(`Auth check failed: ${getErrorMessage(err)}`);
     }
+    try {
+        const me = await api(config, "GET", "/me");
+        report.identity = "ok";
+        if (me && typeof me === "object") {
+            const anyMe = me;
+            report.identityName = typeof anyMe.name === "string" ? anyMe.name : null;
+            report.identityEmail = typeof anyMe.email === "string" ? anyMe.email : null;
+        }
+    }
+    catch (err) {
+        report.identity = "failed";
+        report.errors.push(`Identity check failed: ${getErrorMessage(err)}`);
+    }
     if (opts.testPush && report.auth === "ok") {
         try {
             const session = await api(config, "POST", "/sessions", { name: "__peekable_doctor__" });
@@ -79,13 +145,34 @@ export async function runDoctor(opts = {}) {
         delete report.errors;
     return report;
 }
+export function toScalarSnapshot(report) {
+    return {
+        cli_version: report.cliVersion,
+        node_version: report.nodeVersion,
+        os: report.os,
+        os_release: report.osRelease,
+        arch: report.arch,
+        is_tty: report.isTty,
+        configured: report.configured,
+        health: report.health,
+        auth: report.auth,
+        identity: report.identity,
+        test_push: report.testPush,
+        active_sessions: report.activeSessions,
+        max_active_sessions: report.maxActiveSessions,
+        active_session_unlimited: Boolean(report.activeSessionUnlimited),
+    };
+}
 export function formatDoctorReport(report) {
     const lines = [
         `Peekable CLI: ${report.cliVersion}`,
         `Node: ${report.nodeVersion}`,
+        `OS: ${report.os} ${report.osRelease} (${report.arch})`,
+        `TTY: ${report.isTty ? "yes" : "no"}`,
         `Config: ${report.configured ? report.configPath : "missing"}`,
         `Server: ${formatServer(report)}`,
         `Auth: ${formatAuth(report.auth)}`,
+        `Identity: ${formatIdentity(report)}`,
         `Active sessions: ${formatQuota(report.activeSessions, report.maxActiveSessions, report.activeSessionUnlimited)}`,
         `Test push: ${report.testPush}`,
     ];
@@ -118,6 +205,19 @@ function formatAuth(status) {
         return "failed";
     return "not checked";
 }
+function formatIdentity(report) {
+    if (report.identity === "ok") {
+        const parts = [];
+        if (report.identityName)
+            parts.push(report.identityName);
+        if (report.identityEmail)
+            parts.push(`<${report.identityEmail}>`);
+        return parts.length ? parts.join(" ") : "ok";
+    }
+    if (report.identity === "failed")
+        return "failed";
+    return "not checked";
+}
 async function getUsageSnapshot(config) {
     try {
         return await api(config, "GET", "/me/usage");

package/dist/commands/feedback.js

@@ -1,56 +1,66 @@
 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 feedbackCommand = new Command("feedback")
     .argument("<session-id>", "Session ID")
     .description("Fetch feedback for a session")
     .option("--json", "Output JSON")
     .action(async (sessionId, opts) => {
-    const config = requireConfig();
-    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({ ...eventsData, ...annotationsData }));
-        return;
-    }
-    const hasFeedback = eventsData.feedback.length > 0;
-    const hasAnnotations = annotationsData.annotations && annotationsData.annotations.length > 0;
-    if (!hasFeedback && !hasAnnotations) {
-        console.log("No feedback yet.");
-        return;
-    }
-    // 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}`);
+    await runWithTelemetry("feedback", async () => {
+        try {
+            const config = requireConfig();
+            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({ ...eventsData, ...annotationsData }));
+                return;
             }
-        }
-    }
-    // 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}`);
+            const hasFeedback = eventsData.feedback.length > 0;
+            const hasAnnotations = annotationsData.annotations && annotationsData.annotations.length > 0;
+            if (!hasFeedback && !hasAnnotations) {
+                console.log("No feedback yet.");
+                return;
+            }
+            // 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}`);
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            printCommandError("Feedback failed", err, opts.json);
+            throw new CommandFailure("Feedback failed", { cause: err });
         }
-    }
+    });
 });

package/dist/commands/init.js

@@ -5,6 +5,8 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { requireConfig } from "../config.js";
 import { api } from "../api.js";
+import { CommandFailure } from "../command-error.js";
+import { runWithTelemetry } from "../telemetry.js";
 import { getClaudeDir, getClaudePeekableSkillDir, getCodexDir, getCodexPeekableSkillDir, } from "../paths.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 function installPeekableSkill(appName, appDir, skillDir, skillSource, jsonOutput) {
@@ -57,50 +59,54 @@ export const initCommand = new Command("init")
     .description("Set up peekable — install Claude Code/Codex skills and verify connection")
     .option("--json", "Output JSON")
     .action(async (opts) => {
-    const config = requireConfig();
-    const result = { status: "ok" };
-    // 1. Test connection
-    try {
-        const res = await fetch(`${config.url}/health`);
-        if (!res.ok)
-            throw new Error("Health check failed");
-    }
-    catch {
-        const msg = `Cannot reach server at ${config.url}`;
+    await runWithTelemetry("init", async () => {
+        const config = requireConfig();
+        const result = { status: "ok" };
+        // 1. Test connection
+        try {
+            const res = await fetch(`${config.url}/health`);
+            if (!res.ok)
+                throw new Error("Health check failed");
+        }
+        catch (err) {
+            const msg = `Cannot reach server at ${config.url}`;
+            if (opts.json) {
+                console.log(JSON.stringify({ status: "error", error: msg }));
+            }
+            else {
+                console.error(msg);
+            }
+            // Preserve the fetch error so telemetry can classify the connection
+            // failure (ECONNREFUSED vs DNS vs timeout).
+            throw new CommandFailure(msg, { cause: err });
+        }
+        if (!opts.json)
+            console.log("Connection verified.");
+        // 2. Detect local agent tools and install skill
+        const skillSource = join(__dirname, "..", "..", "skill", "SKILL.md");
+        Object.assign(result, installLocalAgentSkills(skillSource, opts.json));
+        // 3. Test push
+        try {
+            const session = await api(config, "POST", "/sessions", { name: "__share_init_test__" });
+            await api(config, "POST", `/sessions/${session.id}/push`, {
+                html: "<html><body><p>Share init test</p></body></html>",
+            });
+            await api(config, "DELETE", `/sessions/${session.id}`);
+            result.test_push = "passed";
+            if (!opts.json)
+                console.log("Test push verified.");
+        }
+        catch (err) {
+            result.test_push = "failed";
+            result.test_error = err.message;
+            if (!opts.json)
+                console.error(`Test push failed: ${err.message}`);
+        }
         if (opts.json) {
-            console.log(JSON.stringify({ status: "error", error: msg }));
+            console.log(JSON.stringify(result));
         }
         else {
-            console.error(msg);
+            console.log(formatInitNextSteps(result));
         }
-        process.exit(1);
-    }
-    if (!opts.json)
-        console.log("Connection verified.");
-    // 2. Detect local agent tools and install skill
-    const skillSource = join(__dirname, "..", "..", "skill", "SKILL.md");
-    Object.assign(result, installLocalAgentSkills(skillSource, opts.json));
-    // 3. Test push
-    try {
-        const session = await api(config, "POST", "/sessions", { name: "__share_init_test__" });
-        await api(config, "POST", `/sessions/${session.id}/push`, {
-            html: "<html><body><p>Share init test</p></body></html>",
-        });
-        await api(config, "DELETE", `/sessions/${session.id}`);
-        result.test_push = "passed";
-        if (!opts.json)
-            console.log("Test push verified.");
-    }
-    catch (err) {
-        result.test_push = "failed";
-        result.test_error = err.message;
-        if (!opts.json)
-            console.error(`Test push failed: ${err.message}`);
-    }
-    if (opts.json) {
-        console.log(JSON.stringify(result));
-    }
-    else {
-        console.log(formatInitNextSteps(result));
-    }
+    });
 });