@buildinternet/uploads 0.10.1 → 0.11.1

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;

package/dist/telemetry.js

@@ -0,0 +1,290 @@
+/**
+ * Anonymous, opt-out usage telemetry for the CLI and MCP server.
+ *
+ * Sends command names, timing, exit codes, and optional error codes only —
+ * never arguments, paths, tokens, workspace names, or content.
+ *
+ * Opt out:
+ *   UPLOADS_TELEMETRY_DISABLED=1
+ *   DO_NOT_TRACK=1
+ *   uploads telemetry disable
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { DEFAULT_API_URL } from "./config.js";
+import { packageVersion } from "./package-version.js";
+const ANON_ID_FILE = "telemetry-id";
+const DISABLE_FILE = "telemetry-disabled";
+const NOTICE_FILE = "telemetry-notice-shown";
+const POST_TIMEOUT_MS = 1500;
+const MAX_COMMAND = 120;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Known root commands that take a subcommand as the second positional. */
+const NESTED_COMMANDS = new Set([
+    "admin",
+    "completion",
+    "completions",
+    "config",
+    "gallery",
+    "install",
+    "meta",
+    "telemetry",
+]);
+/** Global flags that consume a following value (must not become command names). */
+const VALUE_GLOBALS = new Set(["--api-url", "--workspace", "-w", "--token", "--env-file"]);
+/** Allowlisted error codes sent to telemetry (mirror server ERROR_CODES). */
+const TELEMETRY_ERROR_CODES = new Set([
+    "MISSING_TOKEN",
+    "NO_PUBLIC_URL",
+    "FILE_NOT_FOUND",
+    "NOT_FOUND",
+    "UNAUTHORIZED",
+    "INVALID_KEY",
+    "KEY_POLICY",
+    "STORAGE_QUOTA",
+    "UPLOAD_BUDGET",
+    "GITHUB_REQUIRED",
+    "API_ERROR",
+    "NETWORK",
+    "USAGE",
+]);
+function truthyEnv(name) {
+    const v = process.env[name];
+    if (!v)
+        return false;
+    const lower = v.toLowerCase();
+    return lower !== "0" && lower !== "false" && lower !== "no";
+}
+/** XDG data dir for long-lived telemetry state (anon id, disable marker). */
+export function defaultTelemetryDataDir() {
+    const base = process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
+    return join(base, "uploads");
+}
+function filePath(name, dataDir) {
+    return join(dataDir ?? defaultTelemetryDataDir(), name);
+}
+function safeRead(path) {
+    try {
+        return readFileSync(path, "utf8").trim();
+    }
+    catch {
+        return null;
+    }
+}
+function safeWrite(path, content, mode) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, content, "utf8");
+        if (mode !== undefined)
+            chmodSync(path, mode);
+    }
+    catch {
+        // Telemetry must never throw or break the CLI.
+    }
+}
+export function getOrCreateAnonId(dataDir) {
+    const path = filePath(ANON_ID_FILE, dataDir);
+    const existing = safeRead(path);
+    if (existing && UUID_RE.test(existing))
+        return existing;
+    const id = randomUUID();
+    safeWrite(path, id, 0o600);
+    return id;
+}
+export function isTelemetryEnabled(dataDir) {
+    if (truthyEnv("UPLOADS_TELEMETRY_DISABLED"))
+        return false;
+    if (process.env.DO_NOT_TRACK === "1")
+        return false;
+    // Vitest sets VITEST=true — never open a network connection from other suites.
+    // Opt in for this package's own telemetry tests with UPLOADS_TELEMETRY_TEST=1.
+    if (process.env.VITEST && process.env.UPLOADS_TELEMETRY_TEST !== "1")
+        return false;
+    if (existsSync(filePath(DISABLE_FILE, dataDir)))
+        return false;
+    return true;
+}
+export function setTelemetryEnabled(enabled, dataDir) {
+    const path = filePath(DISABLE_FILE, dataDir);
+    if (enabled) {
+        try {
+            if (existsSync(path))
+                unlinkSync(path);
+        }
+        catch {
+            // ignore
+        }
+    }
+    else {
+        safeWrite(path, "disabled\n");
+    }
+}
+export function detectClientKind() {
+    const envKind = process.env.UPLOADS_CLIENT_KIND;
+    if (envKind === "external" || envKind === "ci" || envKind === "agent") {
+        return { kind: envKind, agentName: process.env.UPLOADS_CLIENT_AGENT };
+    }
+    if (process.env.CI === "true" || process.env.GITHUB_ACTIONS === "true") {
+        return { kind: "ci" };
+    }
+    // Coarse agent-host markers only (no PII).
+    if (process.env.CLAUDECODE || process.env.CLAUDE_CODE) {
+        return { kind: "agent", agentName: process.env.UPLOADS_CLIENT_AGENT ?? "claude" };
+    }
+    if (process.env.CURSOR_AGENT || process.env.CURSOR_TRACE_ID) {
+        return { kind: "agent", agentName: process.env.UPLOADS_CLIENT_AGENT ?? "cursor" };
+    }
+    return { kind: "external" };
+}
+export function detectRuntime() {
+    const bun = globalThis.Bun;
+    if (bun?.version)
+        return `bun-${bun.version}`;
+    if (typeof process !== "undefined" && process.versions?.node) {
+        return `node-${process.versions.node}`;
+    }
+    return "unknown";
+}
+function endpoint(apiUrl) {
+    const base = (apiUrl ?? process.env.UPLOADS_API_URL ?? DEFAULT_API_URL).replace(/\/$/, "");
+    return base;
+}
+/**
+ * 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 function telemetryCommandName(argv) {
+    const args = argv.slice(2);
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--") {
+            positional.push(...args.slice(i + 1).filter((a) => !a.startsWith("-")));
+            break;
+        }
+        if (VALUE_GLOBALS.has(arg)) {
+            i += 1; // skip value
+            continue;
+        }
+        if (arg.startsWith("--") && arg.includes("="))
+            continue;
+        if (arg.startsWith("-"))
+            continue;
+        positional.push(arg);
+    }
+    const root = positional[0];
+    if (!root)
+        return "(root)";
+    if (!NESTED_COMMANDS.has(root))
+        return root.slice(0, MAX_COMMAND);
+    const sub = positional[1];
+    if (!sub)
+        return root.slice(0, MAX_COMMAND);
+    return `${root} ${sub}`.slice(0, MAX_COMMAND);
+}
+/** One-time stderr notice for interactive external users. */
+export function maybeShowFirstRunNotice(opts = {}) {
+    if (!isTelemetryEnabled(opts.dataDir))
+        return;
+    if (opts.interactive === false)
+        return;
+    if (detectClientKind().kind !== "external")
+        return;
+    // Default: only when stderr looks interactive.
+    if (opts.interactive === undefined && !process.stderr.isTTY)
+        return;
+    const marker = filePath(NOTICE_FILE, opts.dataDir);
+    if (existsSync(marker))
+        return;
+    const write = opts.write ?? ((t) => process.stderr.write(t));
+    write("\n" +
+        "Note: uploads collects anonymous non-PII usage data. " +
+        "Opt out with `uploads telemetry disable` or UPLOADS_TELEMETRY_DISABLED=1.\n\n");
+    safeWrite(marker, new Date().toISOString());
+}
+/**
+ * Fire-and-forget usage ping. Never throws; delivery runs in the background
+ * so CLI exit is not delayed by the network.
+ */
+export function recordEvent(input, opts = {}) {
+    if (!isTelemetryEnabled(opts.dataDir))
+        return;
+    const command = input.command.trim().slice(0, MAX_COMMAND);
+    if (!command)
+        return;
+    const ctx = detectClientKind();
+    const body = {
+        anonId: getOrCreateAnonId(opts.dataDir),
+        timestamp: opts.now ?? Date.now(),
+        surface: input.surface,
+        clientKind: ctx.kind,
+        agentName: ctx.agentName ?? null,
+        command,
+        exitCode: input.exitCode ?? null,
+        durationMs: input.durationMs ?? null,
+        errorCode: input.errorCode ?? null,
+        cliVersion: opts.version ?? packageVersion(),
+        os: process.platform,
+        arch: process.arch,
+        runtime: detectRuntime(),
+    };
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), POST_TIMEOUT_MS);
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    void fetchImpl(`${endpoint(opts.apiUrl)}/v1/telemetry`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "user-agent": `uploads-cli/${body.cliVersion}`,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+    })
+        .catch(() => {
+        // fire-and-forget
+    })
+        .finally(() => {
+        clearTimeout(t);
+    });
+}
+export function telemetryStatus(opts = {}) {
+    const dataDir = opts.dataDir;
+    const enabled = isTelemetryEnabled(dataDir);
+    let reason;
+    if (truthyEnv("UPLOADS_TELEMETRY_DISABLED"))
+        reason = "UPLOADS_TELEMETRY_DISABLED=1";
+    else if (process.env.DO_NOT_TRACK === "1")
+        reason = "DO_NOT_TRACK=1";
+    else if (existsSync(filePath(DISABLE_FILE, dataDir))) {
+        reason = `${filePath(DISABLE_FILE, dataDir)} present`;
+    }
+    const ctx = detectClientKind();
+    return {
+        enabled,
+        anonId: getOrCreateAnonId(dataDir),
+        clientKind: ctx.kind,
+        agentName: ctx.agentName,
+        endpoint: `${endpoint(opts.apiUrl)}/v1/telemetry`,
+        reason,
+    };
+}
+/** Map thrown CLI errors to a short, allowlisted code for telemetry. */
+export function errorCodeFromUnknown(err) {
+    if (err &&
+        typeof err === "object" &&
+        "name" in err &&
+        err.name === "UsageError") {
+        return "USAGE";
+    }
+    if (err &&
+        typeof err === "object" &&
+        "code" in err &&
+        typeof err.code === "string") {
+        const code = err.code.slice(0, 64);
+        return TELEMETRY_ERROR_CODES.has(code) ? code : undefined;
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,