@buildinternet/uploads 0.10.1 → 0.11.1

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/batch-error.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tool handler failure that still carries structuredContent (e.g. multi-file
+ * total failure with a `failures` array). The MCP server maps this to
+ * isError: true while preserving structuredContent for agents.
+ */
+export declare class ToolBatchError extends Error {
+    readonly structuredContent: unknown;
+    constructor(message: string, structuredContent: unknown);
+}
+/** One-line summary of a multi-file failure list. */
+export declare function batchFailureMessage(failures: readonly {
+    file: string;
+    error: {
+        message: string;
+    };
+}[]): string;

package/dist/mcp/batch-error.js

@@ -0,0 +1,24 @@
+/**
+ * Tool handler failure that still carries structuredContent (e.g. multi-file
+ * total failure with a `failures` array). The MCP server maps this to
+ * isError: true while preserving structuredContent for agents.
+ */
+export class ToolBatchError extends Error {
+    structuredContent;
+    constructor(message, structuredContent) {
+        super(message);
+        this.name = "ToolBatchError";
+        this.structuredContent = structuredContent;
+    }
+}
+/** One-line summary of a multi-file failure list. */
+export function batchFailureMessage(failures) {
+    if (failures.length === 0)
+        return "upload failed";
+    if (failures.length === 1) {
+        const f = failures[0];
+        return `${f.file}: ${f.error.message}`;
+    }
+    const lines = failures.map((f) => `  ${f.file}: ${f.error.message}`);
+    return `${failures.length} uploads failed:\n${lines.join("\n")}`;
+}

package/dist/mcp/server.d.ts

@@ -1,4 +1,5 @@
 export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, type ToolArgs, } from "./args.js";
+export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
 export interface McpTool {
     name: string;
     description: string;
@@ -16,4 +17,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,7 +8,10 @@
  * stdio transport lives in ./stdio.ts; logs must never go to stdout.
  */
 import { UploadsError } from "../errors.js";
+import { errorCodeFromUnknown, recordEvent } from "../telemetry.js";
+import { ToolBatchError } from "./batch-error.js";
 export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
+export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(["2025-06-18", "2025-03-26", "2024-11-05"]);
 const LATEST_PROTOCOL_VERSION = "2025-06-18";
 function response(id, result) {
@@ -24,7 +27,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 +37,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 +54,27 @@ export function createMcpServer(opts) {
             });
         }
         catch (err) {
+            recordEvent({
+                surface: "mcp",
+                command,
+                exitCode: 1,
+                durationMs: Date.now() - start,
+                errorCode: errorCodeFromUnknown(err),
+            }, { apiUrl });
+            // Multi-file total failure: keep structuredContent so agents see every
+            // per-file error, not only the first message string.
+            if (err instanceof ToolBatchError) {
+                return response(id, {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(err.structuredContent, null, 2),
+                        },
+                    ],
+                    structuredContent: err.structuredContent,
+                    isError: true,
+                });
+            }
             return response(id, {
                 content: [{ type: "text", text: toolErrorText(err) }],
                 isError: true,

package/dist/mcp/tools.d.ts

@@ -2,7 +2,7 @@ import type { GlobalFlags } from "../cli-args.js";
 import { type UploadsClient } from "../client.js";
 import { type UploadsClientConfig } from "../config.js";
 import { type CommandRunner } from "../github-gh.js";
-import type { McpTool } from "./server.js";
+import { type McpTool } from "./server.js";
 export declare function createUploadsMcpTools(opts: {
     globals: GlobalFlags;
     runner?: CommandRunner;