@buildinternet/uploads 0.10.0 → 0.11.0

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.0",
+  "version": "0.11.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,