@buildinternet/uploads 0.1.0 → 0.2.0

package/dist/commands.js

@@ -5,66 +5,58 @@ 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]
-
-Upload an image for GitHub embeds. Use "-" for stdin.
-
-Options:
-  --key <key>           Object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>)
-  --prefix <path>       Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX)
-  --repo <owner/repo>   Repo segment (default: git remote, or UPLOADS_DEFAULT_REPO)
-  --ref <id>            PR/issue/branch segment (default: today, or UPLOADS_DEFAULT_REF)
-  --alt <text>          Alt text (default: filename)
-  --width <px>          <img width=…> markdown (or UPLOADS_DEFAULT_WIDTH)
-  --content-type <mime> Override Content-Type
-  --no-git              Don't derive --repo from git (or UPLOADS_NO_GIT=1)
-  --workspace, -w <name>  Override workspace (wins over UPLOADS_WORKSPACE and token inference)
-  --format human|url|markdown|json
-  --pr <num>            Attach to a pull request: key gh/<owner>/<repo>/pull/<num>/<name> (stable URL, no hash)
-  --issue <num>         Attach to an issue: key gh/<owner>/<repo>/issues/<num>/<name>
-  --comment             With --pr/--issue: create/update the attachments comment via your local gh auth
-
-Examples:
-  uploads put ./shot.png --repo myorg/myapp --ref 1722 --alt "New cards" --width 700
-  uploads --env-file .env put ./shot.png
-  uploads --env-file .env put ./after.png --pr 123 --comment
+const PUT_HELP = `uploads put <file> [options]
+
+Upload an image for GitHub embeds. Use "-" for stdin.
+
+Options:
+  --key <key>           Object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>)
+  --prefix <path>       Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX)
+  --repo <owner/repo>   Repo segment (default: git remote, or UPLOADS_DEFAULT_REPO)
+  --ref <id>            PR/issue/branch segment (default: today, or UPLOADS_DEFAULT_REF)
+  --alt <text>          Alt text (default: filename)
+  --width <px>          <img width=…> markdown (or UPLOADS_DEFAULT_WIDTH)
+  --content-type <mime> Override Content-Type
+  --no-git              Don't derive --repo from git (or UPLOADS_NO_GIT=1)
+  --workspace, -w <name>  Override workspace (wins over UPLOADS_WORKSPACE and token inference)
+  --format human|url|markdown|json
+  --pr <num>            Attach to a pull request: key gh/<owner>/<repo>/pull/<num>/<name> (stable URL, no hash)
+  --issue <num>         Attach to an issue: key gh/<owner>/<repo>/issues/<num>/<name>
+  --comment             With --pr/--issue: create/update the attachments comment via your local gh auth
+
+Examples:
+  uploads put ./shot.png --repo myorg/myapp --ref 1722 --alt "New cards" --width 700
+  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);
@@ -72,23 +64,23 @@ async function syncAttachmentsComment(ctx, target, run) {
     return { action: created ? "created" : "updated", count: items.length };
 }
 // --- attach ---
-const ATTACH_HELP = `uploads attach <file...> [options]
-
-Upload one or more stable PR/issue attachments and maintain a single GitHub
-comment. With no target, uses the pull request for the current branch.
-
-Options:
-  --pr <num>            Attach to this pull request
-  --issue <num>         Attach to this issue
-  --repo <owner/repo>   Repository (default: gh/git inference)
-  --no-comment          Upload only; don't create/update the managed comment
-  --content-type <mime> Override Content-Type (applied to every file)
-  --workspace, -w <name>  Override workspace
-
-Examples:
-  uploads attach ./before.png ./after.png
-  uploads attach ./shot.png --pr 123 --repo myorg/myapp
-  uploads attach ./artifact.zip --issue 45 --no-comment
+const ATTACH_HELP = `uploads attach <file...> [options]
+
+Upload one or more stable PR/issue attachments and maintain a single GitHub
+comment. With no target, uses the pull request for the current branch.
+
+Options:
+  --pr <num>            Attach to this pull request
+  --issue <num>         Attach to this issue
+  --repo <owner/repo>   Repository (default: gh/git inference)
+  --no-comment          Upload only; don't create/update the managed comment
+  --content-type <mime> Override Content-Type (applied to every file)
+  --workspace, -w <name>  Override workspace
+
+Examples:
+  uploads attach ./before.png ./after.png
+  uploads attach ./shot.png --pr 123 --repo myorg/myapp
+  uploads attach ./artifact.zip --issue 45 --no-comment
 `;
 export async function runAttach(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
@@ -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`);
             }
@@ -243,14 +235,14 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     return 0;
 }
 // --- list ---
-const LIST_HELP = `uploads list [--prefix <p>] [--pr <num> | --issue <num>] [--repo <owner/name>] [--limit <n>] [--cursor <c>] [--all] [--workspace <name>]
-
-Default prefix: UPLOADS_DEFAULT_PREFIX (screenshots if unset).
-
-Examples:
-  uploads list --prefix screenshots/
-  uploads list --pr 123
-  uploads list --all --json
+const LIST_HELP = `uploads list [--prefix <p>] [--pr <num> | --issue <num>] [--repo <owner/name>] [--limit <n>] [--cursor <c>] [--all] [--workspace <name>]
+
+Default prefix: UPLOADS_DEFAULT_PREFIX (screenshots if unset).
+
+Examples:
+  uploads list --prefix screenshots/
+  uploads list --pr 123
+  uploads list --all --json
 `;
 export async function runList(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
@@ -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
@@ -296,10 +283,10 @@ export async function runList(ctx, args, help = false, run = execRunner) {
     return 0;
 }
 // --- delete ---
-const DELETE_HELP = `uploads delete <key> [--dry-run] [--workspace <name>]
-
-Examples:
-  uploads delete screenshots/myapp/42/shot-a1b2c3.png
+const DELETE_HELP = `uploads delete <key> [--dry-run] [--workspace <name>]
+
+Examples:
+  uploads delete screenshots/myapp/42/shot-a1b2c3.png
 `;
 export async function runDelete(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
@@ -327,16 +314,16 @@ export async function runDelete(ctx, args, help = false) {
     return 0;
 }
 // --- comment ---
-const COMMENT_HELP = `uploads comment (--pr <num> | --issue <num>) [--repo <owner/name>] [--workspace <name>]
-
-Create or update the managed attachments comment on a GitHub PR or issue,
-listing everything uploaded for it. Uses your local gh auth. Finds its own
-prior comment via a hidden marker and edits it in place; never touches other
-comments or the description.
-
-Examples:
-  uploads --env-file .env comment --pr 123
-  uploads comment --issue 45 --repo buildinternet/uploads
+const COMMENT_HELP = `uploads comment (--pr <num> | --issue <num>) [--repo <owner/name>] [--workspace <name>]
+
+Create or update the managed attachments comment on a GitHub PR or issue,
+listing everything uploaded for it. Uses your local gh auth. Finds its own
+prior comment via a hidden marker and edits it in place; never touches other
+comments or the description.
+
+Examples:
+  uploads --env-file .env comment --pr 123
+  uploads comment --issue 45 --repo buildinternet/uploads
 `;
 export async function runComment(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
@@ -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,14 +345,91 @@ 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
-
-API liveness (no auth).
-
-Examples:
-  uploads health
-  uploads --api-url http://localhost:8787 health
+const HEALTH_HELP = `uploads health
+
+API liveness (no auth).
+
+Examples:
+  uploads health
+  uploads --api-url http://localhost:8787 health
 `;
 export async function runHealth(ctx, args, help = false) {
     if (help || parseCommandArgs(args).help) {
@@ -383,31 +447,28 @@ export async function runHealth(ctx, args, help = false) {
         await writeStdout(result.ok ? `ok (${ctx.apiUrl})\n` : `unhealthy (${ctx.apiUrl})\n`);
     return result.ok ? 0 : 1;
 }
-const DOCTOR_HELP = `uploads doctor [--workspace <name>]
-
-Checks API health, token auth, and workspace/token alignment.
-
-Examples:
-  uploads --env-file .env doctor
-  uploads --workspace acme --env-file .env doctor
+const DOCTOR_HELP = `uploads doctor [--workspace <name>]
+
+Checks API health, token auth, and workspace/token alignment.
+
+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),
+            };
+        }
+    }
+    if (!config.configExists && !config.token) {
+        hints.push(`run uploads setup to configure ${config.configPath}`);
     }
-    const report = {
+    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/config-file.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { homedir } from "node:os";
 export const UPLOADS_CONFIG_KEYS = [
@@ -162,6 +162,10 @@ const INIT_HEADER = `# uploads.sh CLI — shared buildinternet config
 /** Create or update UPLOADS_* keys in the shared config file. Preserves other keys. */
 export function writeConfigKeys(path, keys, opts) {
     const entries = Object.entries(keys).filter(([, v]) => v !== undefined && v !== "");
+    for (const [key, value] of entries) {
+        if (/[\r\n]/.test(value))
+            throw new Error(`invalid newline in ${key}`);
+    }
     if (entries.length === 0) {
         throw new Error("no config values to write");
     }
@@ -187,7 +191,15 @@ export function writeConfigKeys(path, keys, opts) {
             updated.push(key);
         }
     }
-    writeFileSync(path, lines.join("\n").replace(/\n*$/, "\n"), "utf8");
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, lines.join("\n").replace(/\n*$/, "\n"), { encoding: "utf8", mode: 0o600 });
+    renameSync(tmp, path);
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        /* Windows/filesystems may not support modes. */
+    }
     return { path, created: !existed, updated };
 }
 export function configValuesFromClient(config, defaults) {

package/dist/config.js

@@ -141,6 +141,7 @@ export function resolveConfig(flags) {
 function missingTokenMessage(configPath) {
     return [
         "UPLOADS_TOKEN is required.",
+        "  uploads login                         # exchange an admin-provided enrollment code",
         `  uploads setup --token <token>         # guided setup → ${configPath}`,
         `  uploads config init --token <token>   # writes ${configPath}`,
         "  or set UPLOADS_TOKEN in env, pass --token, or use --env-file",

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;