@buildinternet/uploads 0.10.1 → 0.11.1

package/dist/commands.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
-import { createUploadsClient } from "./client.js";
+import { mapBounded } from "./async.js";
+import { createUploadsClient, } from "./client.js";
 import { parseCommandArgs, flagString, flagBool, flagInt, flagValues, UsageError, } from "./cli-args.js";
 import { resolvePutDefaults, workspaceMismatch, workspaceFromToken, } from "./config.js";
 import { buildMarkdown } from "./embed.js";
@@ -15,8 +16,14 @@ import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
 import { applyFrame, resolveFrameId } from "./frame.js";
 import { buildCliProvenance } from "./provenance.js";
 import { formatByteSize } from "./format-bytes.js";
+import { formatUsageHuman } from "./format-usage.js";
 import { packageVersion } from "./package-version.js";
-import { writeCommandHelp } from "./cli-style.js";
+import { colorEnabled, writeCommandHelp } from "./cli-style.js";
+/** Parallel fan-out for multi-file put/attach (matches files-sdk bulk default). */
+export const UPLOAD_BATCH_CONCURRENCY = 8;
+/** @deprecated Use UPLOAD_BATCH_CONCURRENCY. */
+export const ATTACH_CONCURRENCY = UPLOAD_BATCH_CONCURRENCY;
+export { formatUsageHuman } from "./format-usage.js";
 /** Read a local file (or `-` for stdin). Missing path → FILE_NOT_FOUND (exit 2). */
 export function readFileArg(fileArg) {
     try {
@@ -30,9 +37,13 @@ export function readFileArg(fileArg) {
     }
 }
 // --- put ---
-const PUT_HELP = `uploads put <file> [options]
+const PUT_HELP = `uploads put <file...> [options]
 
-Upload an image for GitHub embeds. Use "-" for stdin.
+Upload one or more images for GitHub embeds. Use "-" for stdin (single file only).
+
+Multiple files upload in parallel (bounded concurrency). One bad file does not
+block the rest; multi-file JSON is { uploads, failures } (exit 1 when any failed).
+Single-file JSON stays a flat object (back-compat).
 
 Still images (PNG/JPEG/…) are optimized to WebP by default (long edge capped,
 high quality; EXIF stripped) so GitHub embeds stay lean. Original bytes are kept
@@ -55,13 +66,13 @@ Human/json output includes durable url and (when dual-host applies) embedUrl.
 MARKDOWN prefers embedUrl for GitHub. Override: UPLOADS_EMBED_PUBLIC_BASE_URL.
 
 Options:
-  --key <key>           Object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>)
-  --name <leaf>         Clean key leaf + default alt (no '/'); keeps --pr/default path. Not with --key
+  --key <key>           Object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>). Single file only
+  --name <leaf>         Clean key leaf + default alt (no '/'); keeps --pr/default path. Single file only. Not with --key
   --destination <id>    Typed root: screenshots | gh | f (sets --prefix)
   --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)
+  --alt <text>          Alt text (default: each file's name; with multiple files applies to all)
   --width <px>          <img width=…> markdown (or UPLOADS_DEFAULT_WIDTH)
   --content-type <mime> Override Content-Type (ignored when optimize rewrites the body)
   --frame <id>          Device/browser frame before optimize (phone|browser|iphone-16-pro)
@@ -79,18 +90,19 @@ Options:
   --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: update one managed comment with attachments and linked galleries via local gh auth
-  --gallery <id>         Add the uploaded object to this public gallery
+  --gallery <id>         Add the uploaded object(s) to this public gallery
   --meta <k=v>          Queryable custom metadata (repeatable; value may contain "="): key ^[a-z][a-z0-9._-]{0,63}$, value 1-512 printable ASCII, max 24 pairs
                         Re-uploading to an existing key WITH --meta replaces that file's
                         entire metadata set; without --meta the existing metadata is
                         preserved. Use "uploads meta set" to edit individual keys.
   --dry-run             Print key + public URL without uploading; reports if the key would replace an existing object. Not with --comment/--gallery
 
-Exit codes: 0 ok · 2 usage/token/file · 3 auth/policy · 4 network · 1 other.
+Exit codes: 0 ok · 2 usage/token/file · 3 auth/policy · 4 network · 1 other (incl. partial multi-file failure).
 Scripted formats (json|url|markdown) also print failures on stdout.
 
 Examples:
   uploads put ./shot.png --repo myorg/myapp --ref 1722 --alt "New cards" --width 700
+  uploads put ./before.png ./after.png
   uploads put ./mobile.png --frame phone
   uploads put ./ui.png --frame browser --frame-url "https://app.example/settings"
   uploads put ./shot.png --destination screenshots
@@ -269,6 +281,9 @@ 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.
 
+Multiple files upload in parallel (bounded concurrency). One bad file does not
+block the rest; JSON includes uploads + failures (exit 1 when any failed).
+
 Attachments are public and their repo/number/filename keys are predictable.
 Private/internal GitHub repository visibility does not restrict access; upload
 only media that is safe at a public URL.
@@ -308,6 +323,163 @@ Examples:
   uploads attach ./artifact.zip --issue 45 --no-comment
   uploads attach ./shot.png --meta app=myapp --meta page=settings
 `;
+/**
+ * Prepare + put each path as a PR/issue attachment with bounded concurrency.
+ * Per-file errors collect in `failures` (does not throw). `firstError` is the
+ * original cause of the first failure — for rethrowing single-file CLI paths.
+ */
+export async function uploadAttachments(opts) {
+    if (opts.files.some((f) => f === "-")) {
+        throw new UsageError("attach does not support stdin; pass one or more file paths");
+    }
+    const slots = await mapBounded(opts.files, opts.concurrency ?? UPLOAD_BATCH_CONCURRENCY, async (file) => {
+        try {
+            const sourceName = basename(file);
+            const prepared = await prepareImageForUpload(readFileArg(file), sourceName, {
+                ...opts.frame,
+                optimize: opts.optimize,
+            });
+            const result = await opts.client.put(prepared.bytes, {
+                filename: prepared.filename,
+                key: ghAttachmentKey(opts.target, prepared.filename),
+                contentType: prepared.optimized ? prepared.contentType : opts.contentType,
+                provenance: buildCliProvenance({
+                    sourceName,
+                    client: opts.provenanceClient,
+                    optimized: prepared.optimized,
+                    frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
+                    keepExif: opts.optimize.keepExif === true,
+                }),
+                metadata: opts.metadata,
+            });
+            return {
+                ok: true,
+                upload: {
+                    ...result,
+                    file,
+                    markdown: buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
+                        alt: sourceName,
+                    }),
+                    optimize: {
+                        optimized: prepared.optimized,
+                        skippedReason: prepared.skippedReason,
+                        originalBytes: prepared.originalBytes,
+                        outputBytes: prepared.outputBytes,
+                        filename: prepared.filename,
+                    },
+                    frame: prepared.frame,
+                },
+            };
+        }
+        catch (err) {
+            return { ok: false, file, err };
+        }
+    });
+    const uploads = [];
+    const failures = [];
+    let firstError;
+    for (const slot of slots) {
+        if (slot.ok)
+            uploads.push(slot.upload);
+        else {
+            firstError ??= slot.err;
+            failures.push({ file: slot.file, error: errorDetail(slot.err) });
+        }
+    }
+    return { uploads, failures, firstError };
+}
+function errorDetail(err) {
+    if (err instanceof UploadsError)
+        return { message: err.message, code: err.code, status: err.status };
+    return { message: err instanceof Error ? err.message : String(err) };
+}
+/**
+ * Prepare + put each path with put-style key resolution and bounded concurrency.
+ * Same partial-failure shape as uploadAttachments.
+ */
+export async function uploadPuts(opts) {
+    if (opts.files.length > 1 && opts.files.some((f) => f === "-")) {
+        throw new UsageError("stdin (-) cannot be combined with multiple file arguments");
+    }
+    if (opts.files.length > 1 && opts.explicitKey) {
+        throw new UsageError("--key cannot be combined with multiple files");
+    }
+    if (opts.files.length > 1 && opts.nameOverride) {
+        throw new UsageError("--name cannot be combined with multiple files");
+    }
+    const slots = await mapBounded(opts.files, opts.concurrency ?? UPLOAD_BATCH_CONCURRENCY, async (file) => {
+        try {
+            const sourceName = opts.nameOverride ??
+                (file === "-"
+                    ? opts.explicitKey
+                        ? basename(opts.explicitKey)
+                        : "stdin.bin"
+                    : basename(file));
+            const prepared = await prepareImageForUpload(readFileArg(file), sourceName, {
+                ...opts.frame,
+                optimize: opts.optimize,
+            });
+            let key = opts.ghTarget
+                ? ghAttachmentKey(opts.ghTarget, prepared.filename)
+                : opts.explicitKey;
+            if (key && prepared.optimized)
+                key = rewriteKeyExtension(key, prepared.filename);
+            const result = await opts.client.put(prepared.bytes, {
+                filename: prepared.filename,
+                key,
+                prefix: opts.prefix,
+                repo: opts.repo,
+                ref: opts.ref,
+                contentType: prepared.optimized ? prepared.contentType : opts.contentType,
+                deriveRepoFromGit: opts.deriveRepoFromGit,
+                dryRun: opts.dryRun,
+                provenance: buildCliProvenance({
+                    sourceName,
+                    client: opts.provenanceClient,
+                    optimized: prepared.optimized,
+                    frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
+                    keepExif: opts.optimize.keepExif === true,
+                }),
+                metadata: opts.metadata,
+            });
+            const alt = opts.alt ?? basename(sourceName);
+            return {
+                ok: true,
+                upload: {
+                    ...result,
+                    file,
+                    markdown: buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
+                        alt,
+                        width: opts.width,
+                    }),
+                    optimize: {
+                        optimized: prepared.optimized,
+                        skippedReason: prepared.skippedReason,
+                        originalBytes: prepared.originalBytes,
+                        outputBytes: prepared.outputBytes,
+                        filename: prepared.filename,
+                    },
+                    frame: prepared.frame,
+                },
+            };
+        }
+        catch (err) {
+            return { ok: false, file, err };
+        }
+    });
+    const uploads = [];
+    const failures = [];
+    let firstError;
+    for (const slot of slots) {
+        if (slot.ok)
+            uploads.push(slot.upload);
+        else {
+            firstError ??= slot.err;
+            failures.push({ file: slot.file, error: errorDetail(slot.err) });
+        }
+    }
+    return { uploads, failures, firstError };
+}
 export async function runAttach(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
@@ -337,53 +509,28 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     const metadata = { ...metaExtras, ...ghMetadataFromTarget(target) };
     if (Object.keys(metadata).length > 0)
         validateMetaMap(metadata);
-    const results = [];
-    for (const file of parsed.positionals) {
-        if (file === "-")
-            throw new UsageError("attach does not support stdin; pass one or more file paths");
-        const sourceName = basename(file);
-        if (!ctx.quiet && !ctx.json)
-            process.stderr.write(`>> uploading ${file}\n`);
-        const prepared = await prepareImageForUpload(readFileArg(file), sourceName, {
-            ...frameOpts,
-            optimize: optimizeOpts,
-        });
-        if (prepared.frame?.framed && !ctx.quiet && !ctx.json) {
-            process.stderr.write(`>> framed with ${prepared.frame.frameId}\n`);
-        }
-        const note = formatOptimizeNote(prepared);
-        if (note && !ctx.quiet && !ctx.json)
-            process.stderr.write(`>> ${note}\n`);
-        const result = await ctx.client.put(prepared.bytes, {
-            filename: prepared.filename,
-            key: ghAttachmentKey(target, prepared.filename),
-            contentType: prepared.optimized ? prepared.contentType : contentTypeOverride,
-            provenance: buildCliProvenance({
-                sourceName,
-                optimized: prepared.optimized,
-                frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
-                keepExif: optimizeOpts.keepExif === true,
-            }),
-            metadata,
-        });
-        writeReplacedNote(result.replaced, ctx.quiet || ctx.json);
-        const embedSrc = urlForGithubEmbed(result.url, result.embedUrl);
-        results.push({
-            ...result,
-            markdown: buildMarkdown(embedSrc, { alt: sourceName }),
-            optimize: {
-                optimized: prepared.optimized,
-                skippedReason: prepared.skippedReason,
-                originalBytes: prepared.originalBytes,
-                outputBytes: prepared.outputBytes,
-                filename: prepared.filename,
-            },
-            frame: prepared.frame,
-        });
+    const logHuman = !ctx.quiet && !ctx.json;
+    if (logHuman) {
+        const n = parsed.positionals.length;
+        process.stderr.write(`>> uploading ${n} file${n === 1 ? "" : "s"}\n`);
+    }
+    const { uploads, failures, firstError } = await uploadAttachments({
+        client: ctx.client,
+        target,
+        files: parsed.positionals,
+        contentType: contentTypeOverride,
+        optimize: optimizeOpts,
+        frame: frameOpts,
+        metadata,
+    });
+    // Single-file total failure: rethrow so CLI exit codes stay auth/network-aware.
+    if (uploads.length === 0 && failures.length === 1 && parsed.positionals.length === 1) {
+        throw firstError instanceof Error ? firstError : new Error(String(firstError));
     }
     let comment;
     let commentError;
-    if (!parsed.flags.has("--no-comment")) {
+    // Skip comment refresh when every upload failed — nothing new from this batch.
+    if (!parsed.flags.has("--no-comment") && uploads.length > 0) {
         try {
             comment = await syncAttachmentsComment(ctx.client, target, run);
         }
@@ -393,22 +540,33 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         }
     }
     if (ctx.json) {
-        await writeJson({ target, uploads: results, comment, commentError });
+        await writeJson({ target, uploads, failures, comment, commentError });
     }
     else {
-        for (const result of results) {
+        for (const result of uploads) {
+            if (logHuman) {
+                if (result.frame?.framed) {
+                    process.stderr.write(`>> ${basename(result.file)}: framed with ${result.frame.frameId}\n`);
+                }
+                const note = formatOptimizeNote(result.optimize);
+                if (note)
+                    process.stderr.write(`>> ${basename(result.file)}: ${note}\n`);
+                writeReplacedNote(result.replaced, false);
+            }
             const embedLine = result.embedUrl ? `EMBED: ${result.embedUrl}\n` : "";
             await writeStdout(`URL: ${result.url}\n${embedLine}MARKDOWN: ${result.markdown}\n`);
         }
+        for (const failure of failures) {
+            process.stderr.write(`warning: could not upload ${failure.file}: ${failure.error.message}\n`);
+        }
         if (!ctx.quiet && comment)
             process.stderr.write(`>> attachments comment ${comment.action}\n`);
-        // attach auto-writes gh.* metadata; point the user at how to find it later.
-        if (!ctx.quiet) {
+        if (!ctx.quiet && uploads.length > 0) {
             const ref = ghMetadataFromTarget(target)["gh.ref"];
             process.stderr.write(`>> find these later: uploads find gh.ref=${ref}\n`);
         }
     }
-    return 0;
+    return failures.length === 0 ? 0 : 1;
 }
 export async function runPut(ctx, args, help = false, run = execRunner) {
     if (help) {
@@ -420,11 +578,12 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         writeCommandHelp(PUT_HELP);
         return 0;
     }
-    const fileArg = parsed.positionals[0];
-    if (!fileArg) {
+    const files = parsed.positionals;
+    if (files.length === 0) {
         writeCommandHelp(PUT_HELP);
         return 2;
     }
+    const multi = files.length > 1;
     const keyHint = flagString(parsed.flags, "--key");
     const destFlag = flagString(parsed.flags, "--destination");
     const prefixFlag = flagString(parsed.flags, "--prefix");
@@ -449,6 +608,15 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     }
     if (wantComment && !ghTarget)
         throw new UsageError("--comment requires --pr or --issue");
+    if (multi) {
+        if (keyHint)
+            throw new UsageError("--key cannot be combined with multiple files");
+        if (nameFlag !== undefined)
+            throw new UsageError("--name cannot be combined with multiple files");
+        if (files.some((f) => f === "-")) {
+            throw new UsageError("stdin (-) cannot be combined with multiple file arguments");
+        }
+    }
     if (ghTarget) {
         if (keyHint) {
             throw new UsageError("--key cannot be combined with --pr/--issue; use --name <leaf> to set a clean filename on the stable path");
@@ -484,8 +652,6 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     catch (err) {
         throw new UsageError(err instanceof Error ? err.message : String(err));
     }
-    const bytes = readFileArg(fileArg);
-    const sourceName = nameFlag ?? (fileArg === "-" ? (keyHint ? basename(keyHint) : "stdin.bin") : basename(fileArg));
     const format = ctx.json
         ? "json"
         : (() => {
@@ -499,14 +665,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const defaults = resolvePutDefaults({ envFile: ctx.envFile });
     const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
     const frameOpts = frameOptionsFromFlags(parsed.flags);
-    // Optimize even on --dry-run so the preview key extension/hash match a real put.
-    const prepared = await prepareImageForUpload(bytes, sourceName, {
-        ...frameOpts,
-        optimize: optimizeOpts,
-    });
-    const filename = prepared.filename;
     const contentTypeOverride = flagString(parsed.flags, "--content-type");
-    const alt = flagString(parsed.flags, "--alt") ?? basename(sourceName);
+    const altFlag = flagString(parsed.flags, "--alt");
     const widthRaw = flagString(parsed.flags, "--width");
     const width = widthRaw && /^\d+$/.test(widthRaw) && Number(widthRaw) > 0
         ? Number.parseInt(widthRaw, 10)
@@ -515,14 +675,6 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 throw new UsageError(`invalid --width: ${widthRaw}`);
             })()
             : defaults.width;
-    if (!ctx.quiet && format === "human") {
-        process.stderr.write(`>> ${dryRun ? "dry run" : "uploading"} ${fileArg === "-" ? "stdin" : fileArg}\n`);
-        if (prepared.frame?.framed)
-            process.stderr.write(`>> framed with ${prepared.frame.frameId}\n`);
-        const note = formatOptimizeNote(prepared);
-        if (note)
-            process.stderr.write(`>> ${note}\n`);
-    }
     const noGit = flagBool(parsed.flags, "--no-git") || defaults.noGit === true;
     // gh.* metadata: explicit --pr/--issue target wins over --meta; otherwise
     // best-effort auto resolution (on by default) where --meta wins. --no-git,
@@ -558,66 +710,144 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             }
         }
     }
-    if (attachedRef && !ctx.quiet && format === "human") {
-        process.stderr.write(`>> attached to ${attachedRef}\n`);
-    }
-    let key = ghTarget ? ghAttachmentKey(ghTarget, filename) : keyHint;
-    if (key && prepared.optimized)
-        key = rewriteKeyExtension(key, filename);
-    const result = await ctx.client.put(prepared.bytes, {
-        filename,
-        key,
+    const logHuman = !ctx.quiet && format === "human";
+    if (logHuman) {
+        if (multi) {
+            process.stderr.write(`>> ${dryRun ? "dry run for" : "uploading"} ${files.length} files\n`);
+        }
+        else {
+            const fileArg = files[0];
+            process.stderr.write(`>> ${dryRun ? "dry run" : "uploading"} ${fileArg === "-" ? "stdin" : fileArg}\n`);
+        }
+        if (attachedRef)
+            process.stderr.write(`>> attached to ${attachedRef}\n`);
+    }
+    const { uploads, failures, firstError } = await uploadPuts({
+        client: ctx.client,
+        files,
+        nameOverride: nameFlag,
+        explicitKey: keyHint,
+        ghTarget,
         prefix: resolvedPrefix ?? defaults.prefix,
         repo: flagString(parsed.flags, "--repo") ?? defaults.repo,
         ref: flagString(parsed.flags, "--ref") ?? defaults.ref,
-        contentType: prepared.optimized ? prepared.contentType : contentTypeOverride,
         deriveRepoFromGit: !noGit,
+        contentType: contentTypeOverride,
         dryRun,
-        provenance: buildCliProvenance({
-            sourceName,
-            optimized: prepared.optimized,
-            frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
-            keepExif: optimizeOpts.keepExif === true,
-        }),
+        optimize: optimizeOpts,
+        frame: frameOpts,
         metadata,
+        alt: altFlag,
+        width,
     });
-    if (format === "human")
-        writeReplacedNote(result.replaced, ctx.quiet, dryRun);
-    const embedSrc = urlForGithubEmbed(result.url, result.embedUrl);
-    const markdown = buildMarkdown(embedSrc, { alt, width });
-    let gallery;
-    if (galleryId) {
+    // Single-file total failure: rethrow so CLI exit codes stay auth/network-aware.
+    if (uploads.length === 0 && failures.length > 0 && !multi) {
+        throw firstError instanceof Error ? firstError : new Error(String(firstError));
+    }
+    const galleriesByKey = new Map();
+    let galleryHadError = false;
+    if (galleryId && uploads.length > 0) {
+        for (const upload of uploads) {
+            const alt = altFlag ?? basename(upload.file === "-" ? upload.optimize.filename : upload.file);
+            try {
+                // Gallery mutations use optimistic versions. Re-fetch before each add.
+                const current = await ctx.client.getGallery(galleryId);
+                const item = await ctx.client.addGalleryItem(galleryId, upload.key, {
+                    expectedVersion: current.version,
+                    altText: alt,
+                });
+                galleriesByKey.set(upload.key, { id: galleryId, url: current.url, item });
+            }
+            catch (err) {
+                galleryHadError = true;
+                galleriesByKey.set(upload.key, { id: galleryId, error: errorDetail(err) });
+            }
+        }
+    }
+    let comment;
+    let commentError;
+    if (wantComment && ghTarget && uploads.length > 0) {
         try {
-            // Gallery mutations use optimistic versions. Fetch immediately before this
-            // mutation so `put --gallery` composes safely with other CLI writers.
-            const current = await ctx.client.getGallery(galleryId);
-            const item = await ctx.client.addGalleryItem(galleryId, result.key, {
-                expectedVersion: current.version,
-                altText: alt,
-            });
-            gallery = { id: galleryId, url: current.url, item };
+            comment = await syncAttachmentsComment(ctx.client, ghTarget, run);
+            if (logHuman)
+                process.stderr.write(`>> attachments comment ${comment.action}\n`);
         }
         catch (err) {
-            gallery = { id: galleryId, error: galleryError(err) };
+            commentError = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`warning: upload succeeded but the GitHub comment failed (is gh installed and authenticated?): ${commentError}\n`);
         }
     }
-    const optimizeMeta = {
-        optimized: prepared.optimized,
-        skippedReason: prepared.skippedReason,
-        originalBytes: prepared.originalBytes,
-        outputBytes: prepared.outputBytes,
-        filename: prepared.filename,
-    };
-    if (!ctx.quiet && format === "human") {
+    // --- multi-file output ---
+    if (multi) {
+        if (format === "json") {
+            await writeJson({
+                uploads: uploads.map((u) => ({
+                    ...u,
+                    gallery: galleriesByKey.get(u.key),
+                    ...(dryRun ? { dryRun: true } : {}),
+                })),
+                failures,
+                comment,
+                commentError,
+            });
+        }
+        else {
+            for (const result of uploads) {
+                if (logHuman) {
+                    if (result.frame?.framed) {
+                        process.stderr.write(`>> ${basename(result.file)}: framed with ${result.frame.frameId}\n`);
+                    }
+                    const note = formatOptimizeNote(result.optimize);
+                    if (note)
+                        process.stderr.write(`>> ${basename(result.file)}: ${note}\n`);
+                    writeReplacedNote(result.replaced, false, dryRun);
+                    process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n`);
+                }
+                const gallery = galleriesByKey.get(result.key);
+                if (format === "url")
+                    await writeStdout(`${result.url}\n`);
+                else if (format === "markdown")
+                    await writeStdout(`${result.markdown}\n`);
+                else {
+                    const embedLine = result.embedUrl ? `EMBED: ${result.embedUrl}\n` : "";
+                    await writeStdout(`URL: ${result.url}\n${embedLine}MARKDOWN: ${result.markdown}${gallery?.url ? `\nGALLERY: ${gallery.url}` : ""}\n`);
+                }
+                if (gallery?.error) {
+                    process.stderr.write(`warning: upload succeeded but adding ${result.key} to gallery ${gallery.id} failed: ${gallery.error.message}\n`);
+                }
+            }
+            for (const failure of failures) {
+                process.stderr.write(`warning: could not upload ${failure.file}: ${failure.error.message}\n`);
+            }
+        }
+        return failures.length === 0 && !galleryHadError ? 0 : 1;
+    }
+    // --- single-file output (flat JSON shape, back-compat) ---
+    const result = uploads[0];
+    const gallery = galleriesByKey.get(result.key);
+    if (logHuman) {
+        if (result.frame?.framed) {
+            process.stderr.write(`>> framed with ${result.frame.frameId}\n`);
+        }
+        const note = formatOptimizeNote(result.optimize);
+        if (note)
+            process.stderr.write(`>> ${note}\n`);
+        writeReplacedNote(result.replaced, ctx.quiet, dryRun);
         process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n\n`);
     }
     switch (format) {
         case "json":
             await writeJson({
-                ...result,
-                markdown,
-                optimize: optimizeMeta,
-                frame: prepared.frame,
+                workspace: result.workspace,
+                key: result.key,
+                url: result.url,
+                embedUrl: result.embedUrl,
+                size: result.size,
+                contentType: result.contentType,
+                replaced: result.replaced,
+                markdown: result.markdown,
+                optimize: result.optimize,
+                frame: result.frame,
                 gallery,
                 ...(dryRun ? { dryRun: true } : {}),
             });
@@ -626,11 +856,11 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             await writeStdout(`${result.url}\n`);
             break;
         case "markdown":
-            await writeStdout(`${markdown}\n`);
+            await writeStdout(`${result.markdown}\n`);
             break;
         default: {
             const embedLine = result.embedUrl ? `EMBED: ${result.embedUrl}\n` : "";
-            await writeStdout(`URL: ${result.url}\n${embedLine}MARKDOWN: ${markdown}${gallery?.url ? `\nGALLERY: ${gallery.url}` : ""}\n`);
+            await writeStdout(`URL: ${result.url}\n${embedLine}MARKDOWN: ${result.markdown}${gallery?.url ? `\nGALLERY: ${gallery.url}` : ""}\n`);
         }
     }
     if (gallery?.url && format !== "human") {
@@ -639,25 +869,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     if (gallery?.error) {
         process.stderr.write(`warning: upload succeeded but adding it to gallery ${gallery.id} failed: ${gallery.error.message}\n`);
     }
-    if (wantComment && ghTarget) {
-        try {
-            const sync = await syncAttachmentsComment(ctx.client, ghTarget, run);
-            if (!ctx.quiet && format === "human") {
-                process.stderr.write(`>> attachments comment ${sync.action}\n`);
-            }
-        }
-        catch (err) {
-            // Upload already succeeded; the comment is best-effort by design.
-            process.stderr.write(`warning: upload succeeded but the GitHub comment failed (is gh installed and authenticated?): ${err instanceof Error ? err.message : String(err)}\n`);
-        }
-    }
     return gallery?.error ? 1 : 0;
 }
-function galleryError(err) {
-    if (err instanceof UploadsError)
-        return { message: err.message, code: err.code, status: err.status };
-    return { message: err instanceof Error ? err.message : String(err) };
-}
 // --- galleries ---
 const GALLERY_HELP = `uploads gallery <command> [args]
 
@@ -848,7 +1061,7 @@ export async function runGallery(ctx, args, help = false) {
                     }));
                 }
                 catch (err) {
-                    failures.push({ objectKey, error: galleryError(err) });
+                    failures.push({ objectKey, error: errorDetail(err) });
                 }
             }
             const output = { galleryId: id, galleryUrl: galleryUrl ?? null, added, failures };
@@ -1112,12 +1325,20 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
 // --- usage / reconcile / purge ---
 const USAGE_HELP = `uploads usage [--workspace <name>]
 
-Show workspace storage and monthly upload counters (and limits when set).
+Show workspace storage and monthly upload counters.
+
+When the API reports workspace quotas (typical on uploads.sh cloud /
+self-serve plans), human output includes progress bars toward those caps.
+Self-hosted or unlimited operator workspaces get usage totals only, plus a
+short unmetered note — no invented limits.
 
 Examples:
   uploads --env-file .env usage
   uploads usage --json
 `;
+function formatCount(n) {
+    return Number.isFinite(n) ? Math.trunc(n).toLocaleString("en-US") : String(n);
+}
 export async function runUsage(ctx, args, help = false) {
     if (help || parseCommandArgs(args).help) {
         writeCommandHelp(USAGE_HELP);
@@ -1128,14 +1349,7 @@ export async function runUsage(ctx, args, help = false) {
         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");
+    await writeStdout(formatUsageHuman(result, { color: colorEnabled(process.stdout) }).join("\n") + "\n");
     return 0;
 }
 const RECONCILE_HELP = `uploads reconcile [--workspace <name>]
@@ -1298,7 +1512,7 @@ export async function runDoctor(ctx, args, help = false) {
     ];
     if (report.usage) {
         lines.push(report.usage.ok
-            ? `usage:     ${report.usage.bytes} bytes, ${report.usage.objects} objects, ${report.usage.uploadsInPeriod} uploads this period`
+            ? `usage:     ${formatByteSize(report.usage.bytes ?? 0)}, ${formatCount(report.usage.objects ?? 0)} objects, ${formatCount(report.usage.uploadsInPeriod ?? 0)} uploads this period`
             : `usage:     failed — ${report.usage.error ?? "unknown"}`);
     }
     if (report.warning)