@buildinternet/uploads 0.10.1 → 0.11.0

package/dist/commands.js

@@ -15,8 +15,10 @@ import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
 import { applyFrame, resolveFrameId } from "./frame.js";
 import { buildCliProvenance } from "./provenance.js";
 import { formatByteSize } from "./format-bytes.js";
+import { formatUsageHuman } from "./format-usage.js";
 import { packageVersion } from "./package-version.js";
-import { writeCommandHelp } from "./cli-style.js";
+import { colorEnabled, writeCommandHelp } from "./cli-style.js";
+export { formatUsageHuman } from "./format-usage.js";
 /** Read a local file (or `-` for stdin). Missing path → FILE_NOT_FOUND (exit 2). */
 export function readFileArg(fileArg) {
     try {
@@ -1112,12 +1114,20 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
 // --- usage / reconcile / purge ---
 const USAGE_HELP = `uploads usage [--workspace <name>]
 
-Show workspace storage and monthly upload counters (and limits when set).
+Show workspace storage and monthly upload counters.
+
+When the API reports workspace quotas (typical on uploads.sh cloud /
+self-serve plans), human output includes progress bars toward those caps.
+Self-hosted or unlimited operator workspaces get usage totals only, plus a
+short unmetered note — no invented limits.
 
 Examples:
   uploads --env-file .env usage
   uploads usage --json
 `;
+function formatCount(n) {
+    return Number.isFinite(n) ? Math.trunc(n).toLocaleString("en-US") : String(n);
+}
 export async function runUsage(ctx, args, help = false) {
     if (help || parseCommandArgs(args).help) {
         writeCommandHelp(USAGE_HELP);
@@ -1128,14 +1138,7 @@ export async function runUsage(ctx, args, help = false) {
         await writeJson(result);
         return 0;
     }
-    const lines = [
-        `workspace: ${result.workspace}`,
-        `bytes:     ${result.bytes}${result.maxStorageBytes != null ? ` / ${result.maxStorageBytes} (${result.storageRemainingBytes} remaining)` : ""}`,
-        `objects:   ${result.objects}`,
-        `uploads:   ${result.uploadsInPeriod} this period (${result.periodStart})${result.maxUploadsPerPeriod != null ? ` / ${result.maxUploadsPerPeriod} (${result.uploadsRemaining} remaining)` : ""}`,
-        `updated:   ${result.updatedAt}`,
-    ];
-    await writeStdout(lines.join("\n") + "\n");
+    await writeStdout(formatUsageHuman(result, { color: colorEnabled(process.stdout) }).join("\n") + "\n");
     return 0;
 }
 const RECONCILE_HELP = `uploads reconcile [--workspace <name>]
@@ -1298,7 +1301,7 @@ export async function runDoctor(ctx, args, help = false) {
     ];
     if (report.usage) {
         lines.push(report.usage.ok
-            ? `usage:     ${report.usage.bytes} bytes, ${report.usage.objects} objects, ${report.usage.uploadsInPeriod} uploads this period`
+            ? `usage:     ${formatByteSize(report.usage.bytes ?? 0)}, ${formatCount(report.usage.objects ?? 0)} objects, ${formatCount(report.usage.uploadsInPeriod ?? 0)} uploads this period`
             : `usage:     failed — ${report.usage.error ?? "unknown"}`);
     }
     if (report.warning)

package/dist/format-usage.d.ts

@@ -0,0 +1,38 @@
+export type UsageSnapshotLike = {
+    workspace: string;
+    bytes: number;
+    objects: number;
+    uploadsInPeriod: number;
+    periodStart: string;
+    updatedAt: string;
+    maxStorageBytes?: number;
+    storageRemainingBytes?: number;
+    maxUploadsPerPeriod?: number;
+    uploadsRemaining?: number;
+};
+export type FormatUsageOptions = {
+    /** IANA zone or undefined for the host local zone. */
+    timeZone?: string;
+    /** Color the bar fill (TTY / FORCE_COLOR). Default false. */
+    color?: boolean;
+    /** Progress track width in cells. Default 20. */
+    barWidth?: number;
+};
+/** True when the API reported any cumulative workspace quota. */
+export declare function isUsageMetered(result: UsageSnapshotLike): boolean;
+/** 0–100, one decimal. Missing/invalid caps → no bar. Matches web `usagePct`. */
+export declare function usagePct(value: number, max: number | undefined): number | null;
+/** Web thresholds: high ≥85, full ≥100. */
+export declare function usageLevel(pct: number): "normal" | "high" | "full";
+/**
+ * Terminal meter: `[████░░░░░░░░░░░░░░░░]  20%`
+ * At least one filled cell when pct > 0 so tiny usage is still visible.
+ */
+export declare function formatProgressBar(pct: number, opts?: {
+    width?: number;
+    color?: boolean;
+}): string;
+/** Host-local time by default; pass `timeZone` for stable tests. */
+export declare function formatUsageTimestamp(iso: string, timeZone?: string): string;
+/** Human-readable lines for `uploads usage` (not JSON). */
+export declare function formatUsageHuman(result: UsageSnapshotLike, opts?: FormatUsageOptions): string[];

package/dist/format-usage.js

@@ -0,0 +1,125 @@
+/**
+ * Human formatting for `uploads usage` — sizes, progress bars (mirrors web
+ * account meters when workspace quotas exist), and local timestamps.
+ *
+ * Metered vs unmetered is derived from the usage payload: cloud / self-serve
+ * workspaces ship with `maxStorageBytes` / `maxUploadsPerPeriod`; self-host
+ * and operator workspaces usually omit them (unlimited). Progress bars only
+ * appear for fields that have a positive cap — never invent a budget.
+ */
+import { formatByteSize } from "./format-bytes.js";
+import { BRAND } from "./cli-brand.js";
+/** True when the API reported any cumulative workspace quota. */
+export function isUsageMetered(result) {
+    return (usagePct(result.bytes, result.maxStorageBytes) !== null ||
+        usagePct(result.uploadsInPeriod, result.maxUploadsPerPeriod) !== null);
+}
+/** 0–100, one decimal. Missing/invalid caps → no bar. Matches web `usagePct`. */
+export function usagePct(value, max) {
+    if (typeof max !== "number" || !(max > 0) || !Number.isFinite(value))
+        return null;
+    return Math.min(100, Math.max(0, Math.round((value / max) * 1000) / 10));
+}
+/** Web thresholds: high ≥85, full ≥100. */
+export function usageLevel(pct) {
+    if (pct >= 100)
+        return "full";
+    if (pct >= 85)
+        return "high";
+    return "normal";
+}
+/**
+ * Terminal meter: `[████░░░░░░░░░░░░░░░░]  20%`
+ * At least one filled cell when pct > 0 so tiny usage is still visible.
+ */
+export function formatProgressBar(pct, opts = {}) {
+    const width = opts.width ?? 20;
+    const clamped = Math.min(100, Math.max(0, pct));
+    let filled = Math.round((clamped / 100) * width);
+    if (clamped > 0 && filled === 0)
+        filled = 1;
+    if (clamped >= 100)
+        filled = width;
+    filled = Math.min(width, Math.max(0, filled));
+    const fillChar = "█";
+    const emptyChar = "░";
+    const body = fillChar.repeat(filled) + emptyChar.repeat(width - filled);
+    const bar = opts.color ? colorizeBar(body, filled, usageLevel(clamped)) : body;
+    const label = formatPctLabel(clamped);
+    return `[${bar}] ${label.padStart(5)}`;
+}
+function formatPctLabel(pct) {
+    if (Number.isInteger(pct))
+        return `${pct}%`;
+    return `${pct.toFixed(1)}%`;
+}
+function colorizeBar(body, filled, level) {
+    if (filled <= 0)
+        return paint(body, BRAND.muted);
+    const fill = body.slice(0, filled);
+    const empty = body.slice(filled);
+    const tone = level === "full" ? BRAND.accent : level === "high" ? BRAND.body : BRAND.green;
+    return paint(fill, tone) + paint(empty, BRAND.muted);
+}
+function paint(text, c) {
+    return `\u001b[38;2;${c.r};${c.g};${c.b}m${text}\u001b[0m`;
+}
+function formatCount(n) {
+    return Number.isFinite(n) ? Math.trunc(n).toLocaleString("en-US") : String(n);
+}
+/** Host-local time by default; pass `timeZone` for stable tests. */
+export function formatUsageTimestamp(iso, timeZone) {
+    const ms = Date.parse(iso);
+    if (!Number.isFinite(ms))
+        return iso;
+    try {
+        return new Intl.DateTimeFormat("en-US", {
+            year: "numeric",
+            month: "short",
+            day: "numeric",
+            hour: "numeric",
+            minute: "2-digit",
+            timeZoneName: "short",
+            ...(timeZone ? { timeZone } : {}),
+        }).format(new Date(ms));
+    }
+    catch {
+        return iso;
+    }
+}
+/** Human-readable lines for `uploads usage` (not JSON). */
+export function formatUsageHuman(result, opts = {}) {
+    const width = opts.barWidth ?? 20;
+    const color = opts.color === true;
+    const metered = isUsageMetered(result);
+    const lines = [`workspace: ${result.workspace}`];
+    const storagePct = usagePct(result.bytes, result.maxStorageBytes);
+    if (storagePct !== null && result.maxStorageBytes != null) {
+        const detail = `${formatByteSize(result.bytes)} / ${formatByteSize(result.maxStorageBytes)}` +
+            (result.storageRemainingBytes != null
+                ? ` (${formatByteSize(result.storageRemainingBytes)} free)`
+                : "");
+        const bar = formatProgressBar(storagePct, { width, color });
+        lines.push(`storage:   ${bar}  ${detail}`);
+    }
+    else {
+        lines.push(`storage:   ${formatByteSize(result.bytes)}`);
+    }
+    lines.push(`objects:   ${formatCount(result.objects)}`);
+    const uploadsPct = usagePct(result.uploadsInPeriod, result.maxUploadsPerPeriod);
+    if (uploadsPct !== null && result.maxUploadsPerPeriod != null) {
+        const detail = `${formatCount(result.uploadsInPeriod)} / ${formatCount(result.maxUploadsPerPeriod)} this period (${result.periodStart})`;
+        const bar = formatProgressBar(uploadsPct, { width, color });
+        lines.push(`uploads:   ${bar}  ${detail}`);
+    }
+    else {
+        // Unmetered (or no upload cap): period counter only — not a quota fraction.
+        lines.push(`uploads:   ${formatCount(result.uploadsInPeriod)} this period (${result.periodStart})`);
+    }
+    lines.push(`updated:   ${formatUsageTimestamp(result.updatedAt, opts.timeZone)}`);
+    if (!metered) {
+        // Self-host / operator unlimited: report usage without implying a plan.
+        lines.push("note:      unmetered — no storage or upload quotas on this workspace");
+    }
+    return lines;
+}

package/dist/mcp/server.d.ts

@@ -16,4 +16,6 @@ export declare function createMcpServer(opts: {
         version: string;
     };
     tools: McpTool[];
+    /** API base for telemetry (honors uploads --api-url). */
+    apiUrl?: string;
 }): McpServer;

package/dist/mcp/server.js

@@ -8,6 +8,7 @@
  * stdio transport lives in ./stdio.ts; logs must never go to stdout.
  */
 import { UploadsError } from "../errors.js";
+import { errorCodeFromUnknown, recordEvent } from "../telemetry.js";
 export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(["2025-06-18", "2025-03-26", "2024-11-05"]);
 const LATEST_PROTOCOL_VERSION = "2025-06-18";
@@ -24,7 +25,7 @@ function toolErrorText(err) {
     return err instanceof Error ? err.message : String(err);
 }
 export function createMcpServer(opts) {
-    const { serverInfo, tools } = opts;
+    const { serverInfo, tools, apiUrl } = opts;
     async function callTool(id, params) {
         const name = params.name;
         const tool = typeof name === "string" ? tools.find((t) => t.name === name) : undefined;
@@ -34,8 +35,16 @@ export function createMcpServer(opts) {
         if (typeof args !== "object" || args === null || Array.isArray(args)) {
             return errorResponse(id, -32602, "tool arguments must be an object");
         }
+        const start = Date.now();
+        const command = `tool ${tool.name}`.slice(0, 120);
         try {
             const result = await tool.handler(args);
+            recordEvent({
+                surface: "mcp",
+                command,
+                exitCode: 0,
+                durationMs: Date.now() - start,
+            }, { apiUrl });
             return response(id, {
                 content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
                 structuredContent: result,
@@ -43,6 +52,13 @@ export function createMcpServer(opts) {
             });
         }
         catch (err) {
+            recordEvent({
+                surface: "mcp",
+                command,
+                exitCode: 1,
+                durationMs: Date.now() - start,
+                errorCode: errorCodeFromUnknown(err),
+            }, { apiUrl });
             return response(id, {
                 content: [{ type: "text", text: toolErrorText(err) }],
                 isError: true,

package/dist/mcp/tools.js

@@ -19,6 +19,8 @@ import { rewriteKeyExtension } from "../optimize.js";
 import { buildCliProvenance } from "../provenance.js";
 import { execRunner, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
 import { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
+import { attachmentFromText, buildReportPayload, parseReportType, REPORT_TYPES, submitReport, validateReportMessage, } from "../report.js";
+import { resolveApiUrl } from "../config.js";
 function optBool(args, name) {
     const v = args[name];
     if (v === undefined || v === null)
@@ -773,5 +775,87 @@ export function createUploadsMcpTools(opts) {
                 return buildDoctorReport(config, client);
             },
         },
+        {
+            name: "report",
+            description: "Send an explicit diagnostic report to the uploads team (message + optional text log). " +
+                "Only call this when the user asked to submit feedback, a bug report, or error logs — " +
+                "never automatically. Do not include tokens, secrets, or private file contents. " +
+                "Same as `uploads report`.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    message: {
+                        type: "string",
+                        description: "Short description of the problem (required, 5–4000 chars).",
+                    },
+                    type: {
+                        type: "string",
+                        description: `One of: ${REPORT_TYPES.join(", ")} (default: other).`,
+                    },
+                    contact: {
+                        type: "string",
+                        description: "Optional contact for follow-up (email or handle).",
+                    },
+                    command: {
+                        type: "string",
+                        description: "Command that failed (e.g. put) — name only, no paths or args.",
+                    },
+                    errorCode: {
+                        type: "string",
+                        description: "Optional UploadsError code (e.g. KEY_POLICY).",
+                    },
+                    attachmentText: {
+                        type: "string",
+                        description: "Optional text log/trace body the user consented to send (max 256 KiB). Not a file path.",
+                    },
+                    attachmentFilename: {
+                        type: "string",
+                        description: "Filename label for attachmentText (default: trace.txt).",
+                    },
+                },
+                required: ["message"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const messageRaw = optString(args, "message");
+                if (!messageRaw)
+                    usage("message is required");
+                const validated = validateReportMessage(messageRaw);
+                if (!validated.ok)
+                    usage(validated.error);
+                const typeRaw = optString(args, "type");
+                if (typeRaw && !parseReportType(typeRaw)) {
+                    usage(`type must be one of: ${REPORT_TYPES.join(", ")}`);
+                }
+                const type = parseReportType(typeRaw) ?? "other";
+                let attachment;
+                const attachmentText = optString(args, "attachmentText");
+                if (attachmentText) {
+                    try {
+                        attachment = attachmentFromText(attachmentText, optString(args, "attachmentFilename") ?? "trace.txt");
+                    }
+                    catch (err) {
+                        usage(err instanceof Error ? err.message : String(err));
+                    }
+                }
+                const payload = buildReportPayload(validated.message, {
+                    type,
+                    contact: optString(args, "contact"),
+                    surface: "mcp",
+                    command: optString(args, "command"),
+                    errorCode: optString(args, "errorCode"),
+                    attachment,
+                });
+                const apiUrl = resolveApiUrl(globals);
+                const result = await submitReport(payload, { apiUrl });
+                if (!result.ok)
+                    usage(`couldn't send report: ${result.error}`);
+                return {
+                    ok: true,
+                    id: result.id,
+                    hasAttachment: result.hasAttachment,
+                };
+            },
+        },
     ];
 }

package/dist/report.d.ts

@@ -0,0 +1,68 @@
+export declare const REPORT_TYPES: readonly ["bug", "error", "idea", "other"];
+export type ReportType = (typeof REPORT_TYPES)[number];
+export declare const MIN_REPORT_MESSAGE = 5;
+export declare const MAX_REPORT_MESSAGE = 4000;
+export declare const MAX_REPORT_ATTACHMENT_BYTES: number;
+export interface ReportAttachment {
+    filename: string;
+    contentType: string;
+    body: string;
+}
+export interface ReportPayload {
+    message: string;
+    type: ReportType;
+    contact?: string;
+    surface: "cli" | "mcp";
+    cliVersion: string;
+    clientKind: string;
+    agentName?: string;
+    anonId?: string;
+    os: string;
+    arch: string;
+    runtime: string;
+    command?: string;
+    errorCode?: string;
+    attachment?: ReportAttachment;
+}
+export interface SubmitReportOptions {
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export type ValidateMessageResult = {
+    ok: true;
+    message: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function validateReportMessage(raw: string): ValidateMessageResult;
+export declare function parseReportType(raw: string | undefined): ReportType | undefined;
+/**
+ * Load a local text file as an attachment. Rejects oversized / missing files.
+ * Callers must have obtained the path from explicit user input (`--file`).
+ */
+export declare function loadReportAttachment(path: string): ReportAttachment;
+/** Build attachment from an in-memory string (MCP / piped text). */
+export declare function attachmentFromText(body: string, filename?: string, contentType?: string): ReportAttachment;
+export declare function buildReportPayload(message: string, opts?: {
+    type?: ReportType;
+    contact?: string;
+    surface?: "cli" | "mcp";
+    command?: string;
+    errorCode?: string;
+    attachment?: ReportAttachment;
+}, deps?: {
+    version?: string;
+    dataDir?: string;
+    includeAnonId?: boolean;
+}): ReportPayload;
+export type SubmitReportResult = {
+    ok: true;
+    id: string;
+    hasAttachment: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function submitReport(payload: ReportPayload, opts?: SubmitReportOptions): Promise<SubmitReportResult>;
+export declare function reportFallbackHint(): string;

package/dist/report.js

@@ -0,0 +1,152 @@
+/**
+ * Explicit, permissioned diagnostic report submission.
+ *
+ * Unlike automatic telemetry, nothing is sent unless the user (or an agent
+ * they instructed) runs `uploads report` / the MCP `report` tool.
+ *
+ * Optional log/trace attachments are text-only, capped, and stored server-side
+ * in R2 under an unguessable key. Never auto-attaches files from disk.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { basename } from "node:path";
+import { DEFAULT_API_URL } from "./config.js";
+import { packageVersion } from "./package-version.js";
+import { detectClientKind, detectRuntime, getOrCreateAnonId, isTelemetryEnabled, } from "./telemetry.js";
+export const REPORT_TYPES = ["bug", "error", "idea", "other"];
+export const MIN_REPORT_MESSAGE = 5;
+export const MAX_REPORT_MESSAGE = 4000;
+export const MAX_REPORT_ATTACHMENT_BYTES = 256 * 1024;
+const POST_TIMEOUT_MS = 15_000;
+const ISSUES_URL = "https://github.com/buildinternet/uploads/issues";
+export function validateReportMessage(raw) {
+    const message = raw.trim();
+    if (message.length < MIN_REPORT_MESSAGE) {
+        return { ok: false, error: "message is too short — add a sentence or two" };
+    }
+    if (message.length > MAX_REPORT_MESSAGE) {
+        return {
+            ok: false,
+            error: `message is too long (max ${MAX_REPORT_MESSAGE} chars)`,
+        };
+    }
+    return { ok: true, message };
+}
+export function parseReportType(raw) {
+    if (!raw)
+        return undefined;
+    return REPORT_TYPES.includes(raw) ? raw : undefined;
+}
+/**
+ * Load a local text file as an attachment. Rejects oversized / missing files.
+ * Callers must have obtained the path from explicit user input (`--file`).
+ */
+export function loadReportAttachment(path) {
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch (err) {
+        if (err?.code === "ENOENT") {
+            throw new Error(`file not found: ${path}`, { cause: err });
+        }
+        throw err;
+    }
+    if (size > MAX_REPORT_ATTACHMENT_BYTES) {
+        throw new Error(`attachment exceeds ${MAX_REPORT_ATTACHMENT_BYTES} bytes (got ${size})`);
+    }
+    const body = readFileSync(path, "utf8");
+    // Re-check UTF-8 byte length (stat is filesystem size).
+    const bytes = new TextEncoder().encode(body).byteLength;
+    if (bytes > MAX_REPORT_ATTACHMENT_BYTES) {
+        throw new Error(`attachment exceeds ${MAX_REPORT_ATTACHMENT_BYTES} bytes after read`);
+    }
+    const filename = basename(path) || "attachment.txt";
+    const lower = filename.toLowerCase();
+    const contentType = lower.endsWith(".json") || lower.endsWith(".jsonl") || lower.endsWith(".ndjson")
+        ? "application/json"
+        : "text/plain; charset=utf-8";
+    return { filename, contentType, body };
+}
+/** Build attachment from an in-memory string (MCP / piped text). */
+export function attachmentFromText(body, filename = "trace.txt", contentType = "text/plain; charset=utf-8") {
+    const bytes = new TextEncoder().encode(body).byteLength;
+    if (bytes > MAX_REPORT_ATTACHMENT_BYTES) {
+        throw new Error(`attachment exceeds ${MAX_REPORT_ATTACHMENT_BYTES} bytes`);
+    }
+    if (!body.trim())
+        throw new Error("attachment is empty");
+    return {
+        filename: basename(filename) || "trace.txt",
+        contentType,
+        body,
+    };
+}
+export function buildReportPayload(message, opts = {}, deps = {}) {
+    const ctx = detectClientKind();
+    const includeAnon = deps.includeAnonId ?? isTelemetryEnabled(deps.dataDir);
+    return {
+        message,
+        type: opts.type ?? "other",
+        contact: opts.contact?.trim() || undefined,
+        surface: opts.surface ?? "cli",
+        cliVersion: deps.version ?? packageVersion(),
+        clientKind: ctx.kind,
+        agentName: ctx.agentName,
+        anonId: includeAnon ? getOrCreateAnonId(deps.dataDir) : undefined,
+        os: process.platform,
+        arch: process.arch,
+        runtime: detectRuntime(),
+        command: opts.command?.trim().slice(0, 120) || undefined,
+        errorCode: opts.errorCode?.trim().slice(0, 64) || undefined,
+        attachment: opts.attachment,
+    };
+}
+export async function submitReport(payload, opts = {}) {
+    const base = (opts.apiUrl ?? process.env.UPLOADS_API_URL ?? DEFAULT_API_URL).replace(/\/$/, "");
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), POST_TIMEOUT_MS);
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    try {
+        const res = await fetchImpl(`${base}/v1/reports`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "user-agent": `uploads-cli/${payload.cliVersion}`,
+            },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            let detail = `server returned ${res.status}`;
+            try {
+                const errBody = (await res.json());
+                if (errBody?.error?.message)
+                    detail = errBody.error.message;
+            }
+            catch {
+                // ignore
+            }
+            return { ok: false, error: detail };
+        }
+        const json = (await res.json());
+        if (!json.ok || !json.id)
+            return { ok: false, error: "unexpected response" };
+        return {
+            ok: true,
+            id: json.id,
+            hasAttachment: Boolean(json.hasAttachment),
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("abort"))
+            return { ok: false, error: "request timed out" };
+        return { ok: false, error: msg };
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+export function reportFallbackHint() {
+    return `You can open an issue instead: ${ISSUES_URL}`;
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,60 @@
+export type TelemetrySurface = "cli" | "mcp";
+export type TelemetryClientKind = "external" | "ci" | "agent";
+export interface TelemetryEventInput {
+    surface: TelemetrySurface;
+    command: string;
+    exitCode?: number;
+    durationMs?: number;
+    /** UploadsError code or USAGE — never free-form messages. */
+    errorCode?: string;
+}
+export interface RecordEventOptions {
+    /** Override data directory (tests). */
+    dataDir?: string;
+    /** Override API base URL (tests / --api-url). */
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+    now?: number;
+    version?: string;
+}
+/** XDG data dir for long-lived telemetry state (anon id, disable marker). */
+export declare function defaultTelemetryDataDir(): string;
+export declare function getOrCreateAnonId(dataDir?: string): string;
+export declare function isTelemetryEnabled(dataDir?: string): boolean;
+export declare function setTelemetryEnabled(enabled: boolean, dataDir?: string): void;
+export declare function detectClientKind(): {
+    kind: TelemetryClientKind;
+    agentName?: string;
+};
+export declare function detectRuntime(): string;
+/**
+ * Build a safe command label from argv. Only the root command (+ subcommand
+ * for known nested commands). Skips global flag/value pairs so
+ * `--token up_… put` never records the token as the command.
+ */
+export declare function telemetryCommandName(argv: string[]): string;
+/** One-time stderr notice for interactive external users. */
+export declare function maybeShowFirstRunNotice(opts?: {
+    dataDir?: string;
+    write?: (text: string) => void;
+    /** When false, skip (MCP stdio, --json, non-TTY). */
+    interactive?: boolean;
+}): void;
+/**
+ * Fire-and-forget usage ping. Never throws; delivery runs in the background
+ * so CLI exit is not delayed by the network.
+ */
+export declare function recordEvent(input: TelemetryEventInput, opts?: RecordEventOptions): void;
+export declare function telemetryStatus(opts?: {
+    dataDir?: string;
+    apiUrl?: string;
+}): {
+    enabled: boolean;
+    anonId: string;
+    clientKind: TelemetryClientKind;
+    agentName?: string;
+    endpoint: string;
+    reason?: string;
+};
+/** Map thrown CLI errors to a short, allowlisted code for telemetry. */
+export declare function errorCodeFromUnknown(err: unknown): string | undefined;