@buildinternet/uploads 0.1.1 → 0.2.0

package/dist/commands.js

@@ -5,16 +5,9 @@ import { parseCommandArgs, flagString, flagBool, flagInt, UsageError, } from "./
 import { resolvePutDefaults, workspaceMismatch, workspaceFromToken, } from "./config.js";
 import { buildMarkdown } from "./embed.js";
 import { UploadsError } from "./errors.js";
+import { writeJson, writeStdout } from "./io.js";
 import { ghAttachmentKey, ghKeyPrefix, attachmentsCommentBody, } from "./github.js";
 import { resolveRepo, resolveCurrentPullRequest, execRunner, upsertAttachmentsComment, } from "./github-gh.js";
-async function writeStdout(text) {
-    if (!process.stdout.write(text)) {
-        await new Promise((resolve) => process.stdout.once("drain", resolve));
-    }
-}
-async function writeJson(value) {
-    await writeStdout(JSON.stringify(value, null, 2) + "\n");
-}
 // --- put ---
 const PUT_HELP = `uploads put <file> [options]
 
@@ -40,31 +33,30 @@ Examples:
   uploads --env-file .env put ./shot.png
   uploads --env-file .env put ./after.png --pr 123 --comment
 `;
-/** Reads --pr/--issue (+ --repo) into a GhTarget; undefined when neither flag is present. */
-function ghTargetFromFlags(flags, run) {
-    const pr = flagInt(flags, "--pr", "--pr");
-    const issue = flagInt(flags, "--issue", "--issue");
+/**
+ * Turns a pr/issue pair (+ optional repo) into a GhTarget; undefined when
+ * neither is present. Shared by the CLI flags and the MCP tool arguments.
+ */
+export function makeGhTarget(pr, issue, repoArg, run) {
     if (pr === undefined && issue === undefined)
         return undefined;
     if (pr !== undefined && issue !== undefined) {
         throw new UsageError("--pr and --issue are mutually exclusive");
     }
-    const repo = resolveRepo(flagString(flags, "--repo"), run);
+    const repo = resolveRepo(repoArg, run);
     return { repo, kind: pr !== undefined ? "pull" : "issues", num: (pr ?? issue) };
 }
+/** Reads --pr/--issue (+ --repo) into a GhTarget; undefined when neither flag is present. */
+function ghTargetFromFlags(flags, run) {
+    return makeGhTarget(flagInt(flags, "--pr", "--pr"), flagInt(flags, "--issue", "--issue"), flagString(flags, "--repo"), run);
+}
 /**
  * List every attachment under the target's prefix and create/update the
  * managed comment. Throws on gh failure — callers decide whether that is
  * fatal (`comment` command) or a warning (`put --comment`).
  */
-async function syncAttachmentsComment(ctx, target, run) {
-    const items = [];
-    let cursor;
-    do {
-        const page = await ctx.client.list({ prefix: ghKeyPrefix(target), cursor });
-        items.push(...page.items.map(({ key, url }) => ({ key, url })));
-        cursor = page.cursor ?? undefined;
-    } while (cursor);
+export async function syncAttachmentsComment(client, target, run) {
+    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url }) => ({ key, url }));
     if (items.length === 0)
         return { action: "skipped", count: 0 };
     const body = attachmentsCommentBody(items);
@@ -124,7 +116,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     let commentError;
     if (!parsed.flags.has("--no-comment")) {
         try {
-            comment = await syncAttachmentsComment(ctx, target, run);
+            comment = await syncAttachmentsComment(ctx.client, target, run);
         }
         catch (err) {
             commentError = err instanceof Error ? err.message : String(err);
@@ -230,7 +222,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     }
     if (wantComment && ghTarget) {
         try {
-            const sync = await syncAttachmentsComment(ctx, ghTarget, run);
+            const sync = await syncAttachmentsComment(ctx.client, ghTarget, run);
             if (!ctx.quiet && format === "human") {
                 process.stderr.write(`>> attachments comment ${sync.action}\n`);
             }
@@ -270,13 +262,8 @@ export async function runList(ctx, args, help = false, run = execRunner) {
     const limit = flagInt(parsed.flags, "--limit", "--limit");
     const cursor = flagString(parsed.flags, "--cursor");
     if (flagBool(parsed.flags, "--all")) {
-        const items = [];
-        let next = cursor;
-        do {
-            const page = await ctx.client.list({ prefix, limit, cursor: next ?? undefined });
-            items.push(...page.items);
-            next = page.cursor;
-        } while (next);
+        // --all may start from a caller-provided --cursor and drains from there.
+        const items = await ctx.client.listAll({ prefix, limit, cursor });
         if (ctx.json)
             await writeJson({ items, cursor: null });
         else
@@ -347,7 +334,7 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
     const target = ghTargetFromFlags(parsed.flags, run);
     if (!target)
         throw new UsageError("comment requires --pr or --issue");
-    const result = await syncAttachmentsComment(ctx, target, run);
+    const result = await syncAttachmentsComment(ctx.client, target, run);
     if (ctx.json) {
         await writeJson({ ...target, ...result });
     }
@@ -358,6 +345,83 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
     }
     return 0;
 }
+// --- usage / reconcile / purge ---
+const USAGE_HELP = `uploads usage [--workspace <name>]
+
+Show workspace storage and monthly upload counters (and limits when set).
+
+Examples:
+  uploads --env-file .env usage
+  uploads usage --json
+`;
+export async function runUsage(ctx, args, help = false) {
+    if (help || parseCommandArgs(args).help) {
+        process.stderr.write(USAGE_HELP);
+        return 0;
+    }
+    const result = await ctx.client.usage();
+    if (ctx.json) {
+        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");
+    return 0;
+}
+const RECONCILE_HELP = `uploads reconcile [--workspace <name>]
+
+Rebuild ledger bytes/objects from storage (source of truth). Preserves the
+monthly upload counter. Requires files:write.
+
+Examples:
+  uploads --env-file .env reconcile
+`;
+export async function runReconcile(ctx, args, help = false) {
+    if (help || parseCommandArgs(args).help) {
+        process.stderr.write(RECONCILE_HELP);
+        return 0;
+    }
+    const result = await ctx.client.reconcile();
+    if (ctx.json) {
+        await writeJson(result);
+        return 0;
+    }
+    await writeStdout(result.changed
+        ? `reconciled ${result.workspace}: ${result.previous.bytes}→${result.bytes} bytes, ${result.previous.objects}→${result.objects} objects\n`
+        : `reconciled ${result.workspace}: unchanged (${result.bytes} bytes, ${result.objects} objects)\n`);
+    return 0;
+}
+const PURGE_HELP = `uploads purge-expired [--workspace <name>]
+
+Delete objects older than the workspace retentionDays setting, then reconcile.
+Skips if retention is unset. Requires files:delete.
+
+Examples:
+  uploads --env-file .env purge-expired
+`;
+export async function runPurgeExpired(ctx, args, help = false) {
+    if (help || parseCommandArgs(args).help) {
+        process.stderr.write(PURGE_HELP);
+        return 0;
+    }
+    const result = await ctx.client.purgeExpired();
+    if (ctx.json) {
+        await writeJson(result);
+        return 0;
+    }
+    if ("skipped" in result) {
+        await writeStdout(`skipped: ${result.reason}\n`);
+        return 0;
+    }
+    await writeStdout(`purged ${result.deleted} object(s), freed ${result.freedBytes} bytes (retention ${result.retentionDays}d)\n`);
+    return 0;
+}
 // --- health & doctor ---
 const HEALTH_HELP = `uploads health
 
@@ -391,23 +455,20 @@ Examples:
   uploads --env-file .env doctor
   uploads --workspace acme --env-file .env doctor
 `;
-export async function runDoctor(ctx, args, help = false) {
-    if (help || parseCommandArgs(args).help) {
-        process.stderr.write(DOCTOR_HELP);
-        return 0;
-    }
-    const mismatch = workspaceMismatch(ctx.config);
+/** Doctor's health + auth + workspace checks, shared by the CLI and the MCP tool. */
+export async function buildDoctorReport(config, client) {
+    const mismatch = workspaceMismatch(config);
     const hints = [];
     if (mismatch)
         hints.push(mismatch);
-    if (ctx.config.apiUrl.includes("localhost") || ctx.config.apiUrl.includes("127.0.0.1")) {
+    if (config.apiUrl.includes("localhost") || config.apiUrl.includes("127.0.0.1")) {
         hints.push("local API uses dev KV — prod tokens won't work unless minted with --local");
     }
-    const health = await ctx.client.health();
+    const health = await client.health();
     let authOk = false;
     let authError;
     try {
-        await ctx.client.list({ limit: 1 });
+        await client.list({ limit: 1 });
         authOk = true;
     }
     catch (err) {
@@ -416,35 +477,67 @@ export async function runDoctor(ctx, args, help = false) {
             hints.push("if this token works on api.uploads.sh, set UPLOADS_API_URL=https://api.uploads.sh");
         }
     }
-    if (!ctx.config.configExists && !ctx.config.token) {
-        hints.push(`run uploads setup to configure ${ctx.config.configPath}`);
+    let usage;
+    if (authOk) {
+        try {
+            const snap = await client.usage();
+            usage = {
+                ok: true,
+                bytes: snap.bytes,
+                objects: snap.objects,
+                uploadsInPeriod: snap.uploadsInPeriod,
+            };
+        }
+        catch (err) {
+            usage = {
+                ok: false,
+                error: err instanceof UploadsError ? err.message : String(err),
+            };
+        }
     }
-    const report = {
+    if (!config.configExists && !config.token) {
+        hints.push(`run uploads setup to configure ${config.configPath}`);
+    }
+    return {
         ok: health.ok && authOk,
-        apiUrl: ctx.config.apiUrl,
-        workspace: ctx.config.workspace,
-        workspaceSource: ctx.config.workspaceSource,
-        workspaceFromToken: workspaceFromToken(ctx.config.token),
-        configPath: ctx.config.configPath,
-        configExists: ctx.config.configExists,
+        apiUrl: config.apiUrl,
+        workspace: config.workspace,
+        workspaceSource: config.workspaceSource,
+        workspaceFromToken: workspaceFromToken(config.token),
+        configPath: config.configPath,
+        configExists: config.configExists,
         health,
         auth: { ok: authOk, error: authError },
+        usage,
+        warning: mismatch,
         hints,
     };
+}
+export async function runDoctor(ctx, args, help = false) {
+    if (help || parseCommandArgs(args).help) {
+        process.stderr.write(DOCTOR_HELP);
+        return 0;
+    }
+    const report = await buildDoctorReport(ctx.config, ctx.client);
     if (ctx.json) {
         await writeJson(report);
         return report.ok ? 0 : 1;
     }
     const lines = [
-        `config:    ${ctx.config.configPath}${ctx.config.configExists ? "" : " (missing)"}`,
-        `api:       ${ctx.config.apiUrl} (${health.ok ? "ok" : "failed"})`,
-        `workspace: ${ctx.config.workspace}`,
-        `auth:      ${authOk ? "ok" : `failed — ${authError ?? "no token"}`}`,
+        `config:    ${report.configPath}${report.configExists ? "" : " (missing)"}`,
+        `api:       ${report.apiUrl} (${report.health.ok ? "ok" : "failed"})`,
+        `workspace: ${report.workspace}`,
+        `auth:      ${report.auth.ok ? "ok" : `failed — ${report.auth.error ?? "no token"}`}`,
     ];
-    if (mismatch)
-        lines.push(`warning:   ${mismatch}`);
-    for (const h of hints)
-        if (h !== mismatch)
+    if (report.usage) {
+        lines.push(report.usage.ok
+            ? `usage:     ${report.usage.bytes} bytes, ${report.usage.objects} objects, ${report.usage.uploadsInPeriod} uploads this period`
+            : `usage:     failed — ${report.usage.error ?? "unknown"}`);
+    }
+    if (report.warning)
+        lines.push(`warning:   ${report.warning}`);
+    for (const h of report.hints)
+        if (h !== report.warning)
             lines.push(`hint:      ${h}`);
     await writeStdout(lines.join("\n") + "\n");
     return report.ok ? 0 : 1;

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_KEY" | "API_ERROR" | "NETWORK" | "USAGE";
+export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_KEY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "API_ERROR" | "NETWORK" | "USAGE";
 export declare class UploadsError extends Error {
     readonly code: UploadsErrorCode;
     readonly status?: number;

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { inferContentType, buildMarkdown } from "./embed.js";
 export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey } from "./keys.js";
 export { DEFAULT_API_URL, DEFAULT_WORKSPACE, UPLOADS_CONFIG_KEYS, defaultConfigPath, resolveConfigPath, loadConfigFile, loadEnvFile, resolveApiUrl, resolveConfig, describeConfigSources, redactToken, writeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, workspaceFromToken, workspaceMismatch, type UploadsClientConfig, type ResolvedConfig, type WorkspaceSource, type ConfigValueSource, type ConfigSources, type UploadsConfigKey, type UploadsConfigValues, type PutDefaults, } from "./config.js";
 export { UploadsError, type UploadsErrorCode } from "./errors.js";
-export { createUploadsClient, type UploadsClient, type PutOptions, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type HealthResult, } from "./client.js";
+export { createUploadsClient, type UploadsClient, type PutOptions, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, } from "./client.js";
 export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, isValidRepo, parseRepoFromRemoteUrl, type AttachmentItem, type GhTarget, type GhTargetKind, } from "./github.js";
 export { execRunner, resolveRepo, upsertAttachmentsComment, type CommandRunner, } from "./github-gh.js";

package/dist/io.d.ts

@@ -0,0 +1,3 @@
+/** Backpressure-aware stdout helpers shared by the CLI commands and the stdio MCP transport. */
+export declare function writeStdout(text: string): Promise<void>;
+export declare function writeJson(value: unknown): Promise<void>;

package/dist/io.js

@@ -0,0 +1,9 @@
+/** Backpressure-aware stdout helpers shared by the CLI commands and the stdio MCP transport. */
+export async function writeStdout(text) {
+    if (!process.stdout.write(text)) {
+        await new Promise((resolve) => process.stdout.once("drain", resolve));
+    }
+}
+export async function writeJson(value) {
+    await writeStdout(JSON.stringify(value, null, 2) + "\n");
+}

package/dist/mcp/args.d.ts

@@ -0,0 +1,4 @@
+export type ToolArgs = Record<string, unknown>;
+export declare function usage(msg: string): never;
+export declare function optString(args: ToolArgs, name: string): string | undefined;
+export declare function optPosInt(args: ToolArgs, name: string): number | undefined;

package/dist/mcp/args.js

@@ -0,0 +1,26 @@
+/**
+ * Argument helpers shared by the stdio MCP tool set (./tools.ts) and the
+ * remote worker's tool set (apps/mcp). Runtime-agnostic — usable from
+ * Workers as well as Node.
+ */
+import { UploadsError } from "../errors.js";
+export function usage(msg) {
+    throw new UploadsError(msg, "USAGE");
+}
+export function optString(args, name) {
+    const v = args[name];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "string")
+        usage(`${name} must be a string`);
+    return v;
+}
+export function optPosInt(args, name) {
+    const v = args[name];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "number" || !Number.isInteger(v) || v <= 0) {
+        usage(`${name} must be a positive integer`);
+    }
+    return v;
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,19 @@
+export { optPosInt, optString, usage, type ToolArgs } from "./args.js";
+export interface McpTool {
+    name: string;
+    description: string;
+    /** Hand-written JSON Schema for the tool's arguments. */
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+}
+export interface McpServer {
+    /** Handle one JSON-RPC line. Undefined for notifications / client responses. */
+    handleLine(line: string): Promise<string | undefined>;
+}
+export declare function createMcpServer(opts: {
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    tools: McpTool[];
+}): McpServer;

package/dist/mcp/server.js

@@ -0,0 +1,109 @@
+/**
+ * Minimal, dependency-free MCP (Model Context Protocol) server core.
+ *
+ * Transport is one JSON-RPC 2.0 message per line/request. This module is
+ * transport- and runtime-agnostic (usable from Workers as well as Node) —
+ * `handleLine` takes a raw message string and returns the serialized response
+ * (or undefined when no response is due), so it is directly testable. The
+ * stdio transport lives in ./stdio.ts; logs must never go to stdout.
+ */
+import { UploadsError } from "../errors.js";
+export { optPosInt, optString, 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";
+function response(id, result) {
+    return JSON.stringify({ jsonrpc: "2.0", id, result });
+}
+function errorResponse(id, code, message) {
+    return JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } });
+}
+/** Tool failures become tool results (isError), never JSON-RPC errors. */
+function toolErrorText(err) {
+    if (err instanceof UploadsError)
+        return `${err.message} (${err.code})`;
+    return err instanceof Error ? err.message : String(err);
+}
+export function createMcpServer(opts) {
+    const { serverInfo, tools } = opts;
+    async function callTool(id, params) {
+        const name = params.name;
+        const tool = typeof name === "string" ? tools.find((t) => t.name === name) : undefined;
+        if (!tool)
+            return errorResponse(id, -32602, `unknown tool: ${String(name ?? "(missing)")}`);
+        const args = params.arguments ?? {};
+        if (typeof args !== "object" || args === null || Array.isArray(args)) {
+            return errorResponse(id, -32602, "tool arguments must be an object");
+        }
+        try {
+            const result = await tool.handler(args);
+            return response(id, {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+                isError: false,
+            });
+        }
+        catch (err) {
+            return response(id, {
+                content: [{ type: "text", text: toolErrorText(err) }],
+                isError: true,
+            });
+        }
+    }
+    return {
+        async handleLine(line) {
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                return errorResponse(null, -32700, "Parse error");
+            }
+            // JSON-RPC batching was removed from MCP: arrays are invalid requests.
+            if (typeof msg !== "object" || msg === null || Array.isArray(msg)) {
+                return errorResponse(null, -32600, "Invalid Request");
+            }
+            const record = msg;
+            const { method, params } = record;
+            // A response from the client (has result/error, no method): ignore.
+            if (method === undefined && ("result" in record || "error" in record))
+                return undefined;
+            const id = typeof record.id === "string" || typeof record.id === "number" ? record.id : null;
+            if (typeof method !== "string")
+                return errorResponse(id, -32600, "Invalid Request");
+            if (method.startsWith("notifications/"))
+                return undefined;
+            // A request without an id is a notification — never respond.
+            if (!("id" in record))
+                return undefined;
+            const p = (typeof params === "object" && params !== null && !Array.isArray(params) ? params : {});
+            try {
+                switch (method) {
+                    case "initialize": {
+                        const requested = typeof p.protocolVersion === "string" ? p.protocolVersion : "";
+                        const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.has(requested)
+                            ? requested
+                            : LATEST_PROTOCOL_VERSION;
+                        return response(id, { protocolVersion, capabilities: { tools: {} }, serverInfo });
+                    }
+                    case "ping":
+                        return response(id, {});
+                    case "tools/list":
+                        return response(id, {
+                            tools: tools.map(({ name, description, inputSchema }) => ({
+                                name,
+                                description,
+                                inputSchema,
+                            })),
+                        });
+                    case "tools/call":
+                        return await callTool(id, p);
+                    default:
+                        return errorResponse(id, -32601, `method not found: ${method}`);
+                }
+            }
+            catch (err) {
+                return errorResponse(id, -32603, err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+}

package/dist/mcp/stdio.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "./server.js";
+/** Serve the MCP protocol on stdin/stdout; resolves when stdin ends. */
+export declare function serveStdio(server: McpServer): Promise<void>;

package/dist/mcp/stdio.js

@@ -0,0 +1,14 @@
+/** Stdio transport for the MCP server core (Node-only; the core itself is runtime-agnostic). */
+import { createInterface } from "node:readline";
+import { writeStdout } from "../io.js";
+/** Serve the MCP protocol on stdin/stdout; resolves when stdin ends. */
+export async function serveStdio(server) {
+    const rl = createInterface({ input: process.stdin, crlfDelay: Infinity, terminal: false });
+    for await (const line of rl) {
+        if (!line.trim())
+            continue;
+        const out = await server.handleLine(line);
+        if (out !== undefined)
+            await writeStdout(out + "\n");
+    }
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,10 @@
+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";
+export declare function createUploadsMcpTools(opts: {
+    globals: GlobalFlags;
+    runner?: CommandRunner;
+    clientFactory?: (config: UploadsClientConfig) => UploadsClient;
+}): McpTool[];