@buildinternet/uploads 0.11.1 → 0.12.1

package/README.md

@@ -15,6 +15,8 @@ npx @buildinternet/uploads --help
 uploads setup
 uploads --version
 uploads attach ./before.png ./after.png
+uploads screenshot https://app.example --pr 123 --comment   # capture + host in one step
+uploads screenshot ./report.html --dark --selector "main"
 uploads put ./shot.png
 uploads put ./shot.png --destination screenshots
 uploads put ./shot.png --no-optimize
@@ -37,7 +39,7 @@ Inside this monorepo only, `pnpm uploads …` builds the package first so you pi
 up local source; product docs and PR “how to try it” examples should use the
 global `uploads` form above.
 
-Commands: `attach`, `put`, `gallery`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
+Commands: `attach`, `put`, `screenshot`, `gallery`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
 `reconcile`, `purge-expired`, `setup`, `install`, `login`, `whoami` (alias `status`),
 `logout`, `invite`, `admin`, `config`, `telemetry`, `report`, `doctor`, `health`, `mcp`,
 `completion`.
@@ -81,6 +83,15 @@ infers the pull request for the current branch via `gh`, uploads stable URLs, an
 or updates one marker-owned GitHub comment. It keeps loose `gh/...` attachments and linked public galleries in distinct sections, shows up to three available gallery images inline, and updates that same comment in place on every sync. Use `--pr`, `--issue`, and `--repo` to select
 the target explicitly, or `--no-comment` to upload without changing GitHub comments.
 
+**Screenshot capture:** `uploads screenshot <url|file.html>` renders a page to a
+hosted image in one step — no separate browser tooling needed. `--via auto`
+(default) drives a Chrome/Chromium already on the machine (`playwright-core`
+ships no browser; `--browser <path>`, `--cdp <endpoint>`, or the Playwright/
+Puppeteer caches all work), and falls back to server-side rendering when none
+is found. localhost/private URLs are local-only; `.html` files work on both
+backends. After capture it joins the same pipeline as `put` (optimize, frames,
+`--pr`/`--issue` comments, galleries). See `uploads screenshot --help`.
+
 **Keys / destinations:** default put uses the `screenshots` layout. Typed destinations
 (`--destination screenshots|gh|f`, MCP `destination`) set the root; `--pr`/`--issue`
 use `gh/…`. Workspaces may restrict put/sign to those roots via

package/dist/cli-catalog.d.ts

@@ -22,6 +22,13 @@ export declare const GLOBAL_FLAGS: readonly {
 }[];
 /** Common flags for put/attach (file-oriented commands). */
 export declare const PUT_LIKE_FLAGS: readonly string[];
+/**
+ * All flags `uploads screenshot` actually reads (verified against
+ * commands/screenshot.ts) — kept as its own explicit list rather than
+ * spreading PUT_LIKE_FLAGS, which includes `--name`/`--no-comment` that
+ * screenshot never parses.
+ */
+export declare const SCREENSHOT_FLAGS: readonly string[];
 export declare const LIST_LIKE_FLAGS: readonly string[];
 export declare const ROOT_COMMANDS: readonly CatalogCommand[];
 export declare const COMPLETION_SHELLS: readonly ["bash", "zsh", "fish"];

package/dist/cli-catalog.js

@@ -40,6 +40,51 @@ export const PUT_LIKE_FLAGS = [
     "--help",
     "-h",
 ];
+/**
+ * All flags `uploads screenshot` actually reads (verified against
+ * commands/screenshot.ts) — kept as its own explicit list rather than
+ * spreading PUT_LIKE_FLAGS, which includes `--name`/`--no-comment` that
+ * screenshot never parses.
+ */
+export const SCREENSHOT_FLAGS = [
+    "--via",
+    "--browser",
+    "--cdp",
+    "--viewport",
+    "--selector",
+    "--full-page",
+    "--dark",
+    "--light",
+    "--wait",
+    "--out",
+    "--no-upload",
+    "--destination",
+    "--prefix",
+    "--repo",
+    "--ref",
+    "--key",
+    "--alt",
+    "--width",
+    "--frame",
+    "--frame-url",
+    "--frame-fit",
+    "--no-optimize",
+    "--optimize-max-edge",
+    "--optimize-quality",
+    "--keep-exif",
+    "--no-git",
+    "--pr",
+    "--issue",
+    "--comment",
+    "--gallery",
+    "--meta",
+    "--dry-run",
+    "--format",
+    "--workspace",
+    "-w",
+    "--help",
+    "-h",
+];
 export const LIST_LIKE_FLAGS = [
     "--prefix",
     "--limit",
@@ -63,6 +108,12 @@ export const ROOT_COMMANDS = [
         summary: "Upload (+ URL + markdown for GitHub)",
         essential: true,
     },
+    {
+        name: "screenshot",
+        usage: "screenshot <target>",
+        summary: "Capture a URL or .html file and host it (local browser or remote render)",
+        essential: true,
+    },
     {
         name: "gallery",
         summary: "Create and organize public media galleries",

package/dist/cli.js

@@ -16,6 +16,7 @@ import { runCompletion } from "./commands/completion.js";
 import { runLogout, runWhoami } from "./commands/session.js";
 import { runTelemetry } from "./commands/telemetry.js";
 import { runReport } from "./commands/report.js";
+import { runScreenshot } from "./commands/screenshot.js";
 import { packageVersion } from "./package-version.js";
 import { checkForUpdate, maybeHintUpdate } from "./update-check.js";
 import { errorCodeFromUnknown, maybeShowFirstRunNotice, recordEvent, telemetryCommandName, } from "./telemetry.js";
@@ -75,7 +76,12 @@ function exitCode(err) {
             case "STORAGE_QUOTA":
             case "UPLOAD_BUDGET":
                 return 3;
+            case "BROWSER_NOT_FOUND":
+                return 2;
             case "NETWORK":
+            // Transient — same "retry, don't reconfigure" family as a network
+            // hiccup, not an auth/policy/budget denial (those are exit 3).
+            case "RATE_LIMITED":
                 return 4;
             default:
                 return 1;
@@ -99,6 +105,8 @@ const ERROR_HINTS = {
     UPLOAD_BUDGET: QUOTA_HINT,
     KEY_POLICY: "hint: use a typed destination (`--destination screenshots|gh`) or an allowed prefix; operators set allowlists with `pnpm workspace:limits --allowed-prefixes`\n",
     UNAUTHORIZED: "hint: token rejected — run `uploads login` to sign in again, or check UPLOADS_TOKEN / --token\n",
+    BROWSER_NOT_FOUND: "hint: no local browser found; try --via remote, or install Chrome / npx playwright install chromium\n",
+    RATE_LIMITED: "hint: transient rate limit — wait ~60s and retry\n",
 };
 function errorOut(err, format) {
     const payload = err instanceof UploadsError
@@ -260,6 +268,7 @@ export async function runCli(argv) {
                 break;
             case "attach":
             case "put":
+            case "screenshot":
             case "gallery":
             case "list":
             case "find":
@@ -278,6 +287,9 @@ export async function runCli(argv) {
                     case "put":
                         code = await runPut(ctx, cmdArgs, showHelp);
                         break;
+                    case "screenshot":
+                        code = await runScreenshot(ctx, cmdArgs, showHelp);
+                        break;
                     case "gallery":
                         code = await runGallery(ctx, cmdArgs, showHelp);
                         break;

package/dist/client.d.ts

@@ -336,6 +336,22 @@ export declare function mintWorkspaceToken(apiUrl: string, accessToken: string,
     label?: string;
     ttlSeconds?: number;
 }): Promise<MintTokenResult>;
+/**
+ * Parse API error bodies. Prefers the nested envelope
+ * `{ error: { code, type, message, details? } }`; still accepts the legacy
+ * flat `{ error: string, code?: string }` shape. Exported so other backends
+ * (e.g. the screenshot render endpoint) share this parsing instead of
+ * duplicating it — each caller supplies its own `fallback` message.
+ */
+export declare function extractErrorFields(body: unknown, fallback?: string): {
+    message: string;
+    code?: string;
+};
+/** Fetch + parse an error-response body via {@link extractErrorFields}. */
+export declare function parseErrorEnvelope(res: Response, fallback?: string): Promise<{
+    message: string;
+    code?: string;
+}>;
 export declare function createUploadsClient(config: UploadsClientConfig): {
     put(body: Uint8Array, opts: PutOptions & {
         filename: string;

package/dist/client.js

@@ -210,15 +210,17 @@ function mapApiError(status, error, code) {
 /**
  * Parse API error bodies. Prefers the nested envelope
  * `{ error: { code, type, message, details? } }`; still accepts the legacy
- * flat `{ error: string, code?: string }` shape.
+ * flat `{ error: string, code?: string }` shape. Exported so other backends
+ * (e.g. the screenshot render endpoint) share this parsing instead of
+ * duplicating it — each caller supplies its own `fallback` message.
  */
-function extractErrorFields(body) {
+export function extractErrorFields(body, fallback = "request failed") {
     if (typeof body === "object" && body && "error" in body) {
         const err = body.error;
         if (typeof err === "object" && err && "message" in err) {
             const nested = err;
             return {
-                message: typeof nested.message === "string" ? nested.message : "request failed",
+                message: typeof nested.message === "string" ? nested.message : fallback,
                 code: typeof nested.code === "string" ? nested.code : undefined,
             };
         }
@@ -229,12 +231,16 @@ function extractErrorFields(body) {
             return { message: err, code };
         }
     }
-    return { message: "request failed" };
+    return { message: fallback };
 }
-async function parseErrorResponse(res) {
+/** Fetch + parse an error-response body via {@link extractErrorFields}. */
+export async function parseErrorEnvelope(res, fallback = "request failed") {
     const body = await res.json().catch(() => ({}));
-    const { message, code } = extractErrorFields(body);
-    return mapApiError(res.status, message || res.statusText || "request failed", code);
+    return extractErrorFields(body, fallback);
+}
+async function parseErrorResponse(res) {
+    const { message, code } = await parseErrorEnvelope(res, res.statusText || "request failed");
+    return mapApiError(res.status, message, code);
 }
 export function createUploadsClient(config) {
     async function request(method, path, opts) {

package/dist/commands/completion.js

@@ -1,5 +1,5 @@
 import { parseCommandArgs, UsageError } from "../cli-args.js";
-import { COMPLETION_SHELLS, GLOBAL_FLAGS, LIST_LIKE_FLAGS, PUT_LIKE_FLAGS, ROOT_COMMANDS, isCompletionShell, } from "../cli-catalog.js";
+import { COMPLETION_SHELLS, GLOBAL_FLAGS, LIST_LIKE_FLAGS, PUT_LIKE_FLAGS, SCREENSHOT_FLAGS, ROOT_COMMANDS, isCompletionShell, } from "../cli-catalog.js";
 import { writeCommandHelp } from "../cli-style.js";
 const HELP = `uploads completion <shell>
 
@@ -28,6 +28,7 @@ function bashScript() {
     const globals = GLOBAL_FLAGS.map((g) => g.flag).join(" ");
     const putFlags = PUT_LIKE_FLAGS.join(" ");
     const listFlags = LIST_LIKE_FLAGS.join(" ");
+    const screenshotFlags = SCREENSHOT_FLAGS.join(" ");
     const subMaps = ROOT_COMMANDS.filter((c) => c.subcommands?.length).map((c) => {
         const names = c.subcommands.map((s) => s.name).join(" ");
         return `    ${c.name}) subs="${names}" ;;`;
@@ -52,6 +53,7 @@ _uploads() {
   local -a globals=(${globals})
   local -a put_flags=(${putFlags})
   local -a list_flags=(${listFlags})
+  local -a screenshot_flags=(${screenshotFlags})
 
   # Find the first non-global positional (the subcommand).
   local cmd="" i=1
@@ -102,6 +104,9 @@ ${subMaps.join("\n")}
       put|attach)
         COMPREPLY=( $(compgen -W "\${put_flags[*]}" -- "$cur") )
         ;;
+      screenshot)
+        COMPREPLY=( $(compgen -W "\${screenshot_flags[*]}" -- "$cur") )
+        ;;
       list|find)
         COMPREPLY=( $(compgen -W "\${list_flags[*]}" -- "$cur") )
         ;;
@@ -114,7 +119,7 @@ ${subMaps.join("\n")}
 
   # File paths for upload-style commands.
   case "$cmd" in
-    put|attach)
+    put|attach|screenshot)
       COMPREPLY=( $(compgen -f -- "$cur") )
       ;;
   esac
@@ -194,7 +199,7 @@ ${globalArgs} \\
     args)
       case $line[1] in
 ${subCases}
-      put|attach)
+      put|attach|screenshot)
         _files
         ;;
       esac
@@ -250,13 +255,18 @@ function fishScript() {
             continue;
         lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put attach' -l ${flag.slice(2)}`);
     }
+    for (const flag of SCREENSHOT_FLAGS) {
+        if (!flag.startsWith("--"))
+            continue;
+        lines.push(`complete -c uploads -n '__fish_seen_subcommand_from screenshot' -l ${flag.slice(2)}`);
+    }
     for (const flag of LIST_LIKE_FLAGS) {
         if (!flag.startsWith("--"))
             continue;
         lines.push(`complete -c uploads -n '__fish_seen_subcommand_from list find' -l ${flag.slice(2)}`);
     }
-    // File completion for put/attach
-    lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put attach' -F`);
+    // File completion for put/attach/screenshot
+    lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put attach screenshot' -F`);
     return lines.join("\n") + "\n";
 }
 export function generateCompletionScript(shell) {

package/dist/commands/screenshot.d.ts

@@ -0,0 +1,6 @@
+import { type CliContext } from "../commands.js";
+import { type CommandRunner } from "../github-gh.js";
+import { captureScreenshot } from "../screenshot.js";
+export declare function runScreenshot(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner, 
+/** Injectable for tests — avoids launching a real browser or hitting the network. */
+captureImpl?: typeof captureScreenshot): Promise<number>;

package/dist/commands/screenshot.js

@@ -0,0 +1,317 @@
+import { writeFileSync } from "node:fs";
+import { basename } from "node:path";
+import { flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
+import { writeCommandHelp } from "../cli-style.js";
+import { frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, syncAttachmentsComment, uploadPreparedImage, } from "../commands.js";
+import { resolvePutDefaults } from "../config.js";
+import { loadDefaultsRaw, resolveScreenshotDefaults } from "../config-file.js";
+import { resolvePutPrefix } from "../destinations.js";
+import { ghMetadataFromTarget } from "../github.js";
+import { execRunner } from "../github-gh.js";
+import { parseMetaFlags, validateMetaMap } from "../metadata.js";
+import { writeJson, writeStdout } from "../io.js";
+import { captureScreenshot, parseViewport, parseWaitUntil, } from "../screenshot.js";
+const SCREENSHOT_HELP = `uploads screenshot <target> [options]
+
+Capture a URL or a local .html file and host it — a hosted, PR-embeddable
+image in one step. target is an http(s) URL or a path to an .html file.
+
+Two capture backends: "local" drives an already-installed Chrome/Chromium via
+playwright-core (no browser download); "remote" renders server-side via the
+uploads.sh render endpoint (no local browser needed, counts against the
+workspace's monthly upload budget). Default --via auto prefers local when a
+browser is found, else remote.
+
+.html files work on both backends (sent inline to remote, ≤ 2 MiB; anything
+they reference via file:// or relative paths only resolves with --via local).
+localhost/private-network URLs are reachable only by the
+local backend — with --via remote (or auto falling back to remote) these
+fail fast with a clear error instead of sending a doomed request.
+
+After capture, screenshots share the put upload pipeline: optional --frame,
+optimize-by-default, --pr/--issue attachment + --comment, --gallery, --meta.
+
+Options:
+  --via auto|local|remote   Capture backend (default: auto, or UPLOADS_SCREENSHOT_VIA)
+  --browser <path>          Explicit local browser executable (or UPLOADS_CHROME_PATH / CHROME_PATH)
+  --cdp <endpoint>          Attach to a running Chrome via CDP (http://host:port or ws://…)
+  --viewport <WxH[@Sx]>     Size + device scale factor (default: 1280x800@2)
+  --selector <css>          Capture one element instead of the viewport
+  --full-page               Capture the full scrollable page
+  --dark / --light          Emulate prefers-color-scheme (full media-query emulation on --via local
+                            only; --via remote just sets the CSS color-scheme property, so a page's
+                            own prefers-color-scheme queries won't flip)
+  --wait <load|domcontentloaded|networkidle|ms>  Settle strategy (default: load); a millisecond
+                            count is local-only — use --via local
+  --out <file>              Also write the PNG to a local file
+  --no-upload                Skip hosting; requires --out (local file only)
+  --destination <id>        Typed root: screenshots | gh | f
+  --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)
+  --key <key>               Explicit object key; cannot combine with --pr/--issue
+  --alt <text>              Alt text (default: derived filename)
+  --width <px>              <img width=…> markdown
+  --frame <id>              Device/browser frame before optimize (phone|browser|iphone-16-pro)
+  --frame-url <url>         Address bar text for --frame browser
+  --frame-fit cover|contain How the shot fills the screen (default: cover)
+  --no-optimize             Skip client-side image optimization
+  --optimize-max-edge <px>  Max long edge when optimizing (default: 2400)
+  --optimize-quality <1-100> WebP quality (default: 85)
+  --keep-exif               Keep EXIF/XMP/ICC when optimizing
+  --pr <num>                Attach to a pull request (stable URL, no hash)
+  --issue <num>             Attach to an issue
+  --comment                 With --pr/--issue: update the managed attachments comment
+  --gallery <id>            Add the uploaded object to this public gallery
+  --meta <k=v>              Queryable custom metadata (repeatable)
+  --workspace, -w <name>    Override workspace
+  --dry-run                 Capture + resolve key/URL without uploading
+  --format human|url|markdown|json
+
+Exit codes: 0 ok · 2 usage/no browser found/file · 3 auth/policy/budget · 4 network · 1 other.
+
+Examples:
+  uploads screenshot https://uploads.sh
+  uploads screenshot ./card.html --out ./card.png
+  uploads screenshot https://app.example/settings --selector main --dark
+  uploads screenshot http://localhost:3000 --via local --full-page
+  uploads screenshot https://uploads.sh --pr 128 --comment
+  uploads screenshot ./card.html --no-upload --out ./card.png
+`;
+function colorSchemeFromFlags(flags) {
+    const dark = flagBool(flags, "--dark");
+    const light = flagBool(flags, "--light");
+    if (dark && light)
+        throw new UsageError("--dark and --light are mutually exclusive");
+    if (dark)
+        return "dark";
+    if (light)
+        return "light";
+    return undefined;
+}
+function viaFromFlags(flags, fallback) {
+    const raw = flagString(flags, "--via");
+    if (!raw)
+        return fallback;
+    if (raw === "auto" || raw === "local" || raw === "remote")
+        return raw;
+    throw new UsageError(`invalid --via: ${raw} (use auto, local, or remote)`);
+}
+export async function runScreenshot(ctx, args, help = false, run = execRunner, 
+/** Injectable for tests — avoids launching a real browser or hitting the network. */
+captureImpl = captureScreenshot) {
+    if (help) {
+        writeCommandHelp(SCREENSHOT_HELP);
+        return 0;
+    }
+    const parsed = parseCommandArgs(args);
+    if (parsed.help) {
+        writeCommandHelp(SCREENSHOT_HELP);
+        return 0;
+    }
+    const target = parsed.positionals[0];
+    if (!target) {
+        writeCommandHelp(SCREENSHOT_HELP);
+        return 2;
+    }
+    if (parsed.positionals.length > 1) {
+        throw new UsageError("screenshot takes exactly one target");
+    }
+    // Read the on-disk config once and share it between the screenshot and
+    // put-style default resolvers (both would otherwise read the same file).
+    const rawDefaults = loadDefaultsRaw({ envFile: ctx.envFile });
+    const screenshotDefaults = resolveScreenshotDefaults({ envFile: ctx.envFile }, rawDefaults);
+    const via = viaFromFlags(parsed.flags, screenshotDefaults.via ?? "auto");
+    const browserPath = flagString(parsed.flags, "--browser");
+    const cdp = flagString(parsed.flags, "--cdp");
+    const viewport = parseViewport(flagString(parsed.flags, "--viewport"));
+    const selector = flagString(parsed.flags, "--selector");
+    const fullPage = flagBool(parsed.flags, "--full-page");
+    const colorScheme = colorSchemeFromFlags(parsed.flags);
+    const waitUntil = parseWaitUntil(flagString(parsed.flags, "--wait"));
+    const outFile = flagString(parsed.flags, "--out");
+    const noUpload = flagBool(parsed.flags, "--no-upload");
+    if (noUpload && !outFile)
+        throw new UsageError("--no-upload requires --out");
+    const keyHint = flagString(parsed.flags, "--key");
+    const destFlag = flagString(parsed.flags, "--destination");
+    const prefixFlag = flagString(parsed.flags, "--prefix");
+    const ghTarget = ghTargetFromFlags(parsed.flags, run);
+    const wantComment = parsed.flags.has("--comment");
+    const galleryId = flagString(parsed.flags, "--gallery");
+    const dryRun = flagBool(parsed.flags, "--dry-run");
+    if (wantComment && !ghTarget)
+        throw new UsageError("--comment requires --pr or --issue");
+    if (ghTarget) {
+        if (keyHint)
+            throw new UsageError("--key cannot be combined with --pr/--issue");
+        if (flagString(parsed.flags, "--ref"))
+            throw new UsageError("--ref cannot be combined with --pr/--issue");
+        if (prefixFlag)
+            throw new UsageError("--prefix cannot be combined with --pr/--issue");
+    }
+    if (dryRun) {
+        if (wantComment)
+            throw new UsageError("--dry-run cannot be combined with --comment");
+        if (galleryId)
+            throw new UsageError("--dry-run cannot be combined with --gallery");
+        if (noUpload)
+            throw new UsageError("--dry-run cannot be combined with --no-upload");
+    }
+    let resolvedPrefix;
+    try {
+        resolvedPrefix = resolvePutPrefix({
+            destination: destFlag,
+            prefix: prefixFlag,
+            key: keyHint,
+            ghAttachment: Boolean(ghTarget),
+        });
+    }
+    catch (err) {
+        throw new UsageError(err instanceof Error ? err.message : String(err));
+    }
+    const format = ctx.json
+        ? "json"
+        : (() => {
+            const raw = flagString(parsed.flags, "--format");
+            if (!raw || raw === "human")
+                return "human";
+            if (raw === "url" || raw === "markdown" || raw === "json")
+                return raw;
+            throw new UsageError(`invalid --format: ${raw}`);
+        })();
+    const putDefaults = resolvePutDefaults({ envFile: ctx.envFile }, rawDefaults);
+    const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, putDefaults);
+    const frameOpts = frameOptionsFromFlags(parsed.flags);
+    const altFlag = flagString(parsed.flags, "--alt");
+    const width = flagInt(parsed.flags, "--width", "--width") ?? putDefaults.width;
+    const metaExtras = parseMetaFlags(flagValues(parsed.flags, "--meta"));
+    let metadata = metaExtras;
+    if (ghTarget) {
+        metadata = { ...metaExtras, ...ghMetadataFromTarget(ghTarget) };
+        validateMetaMap(metadata);
+    }
+    else if (Object.keys(metaExtras).length > 0) {
+        validateMetaMap(metaExtras);
+    }
+    const logHuman = !ctx.quiet && format === "human";
+    if (logHuman)
+        process.stderr.write(`>> capturing ${target}\n`);
+    const captured = await captureImpl({
+        target,
+        via,
+        browserPath,
+        cdp,
+        viewport,
+        selector,
+        fullPage,
+        colorScheme,
+        waitUntil,
+        apiUrl: ctx.config.apiUrl,
+        token: ctx.config.token,
+    });
+    if (logHuman)
+        process.stderr.write(`>> captured via ${captured.backend} backend\n`);
+    if (outFile) {
+        writeFileSync(outFile, captured.png);
+        if (logHuman)
+            process.stderr.write(`>> wrote ${outFile}\n`);
+    }
+    if (noUpload) {
+        if (ctx.json) {
+            await writeJson({ file: outFile, backend: captured.backend, size: captured.png.byteLength });
+        }
+        else {
+            await writeStdout(`FILE: ${outFile}\n`);
+        }
+        return 0;
+    }
+    const repo = flagString(parsed.flags, "--repo") ?? putDefaults.repo;
+    const ref = flagString(parsed.flags, "--ref") ?? putDefaults.ref;
+    const alt = altFlag ?? basename(captured.filename);
+    const { result, prepared, markdown } = await uploadPreparedImage(ctx.client, captured.png, captured.filename, {
+        frame: frameOpts,
+        optimize: optimizeOpts,
+        ghTarget,
+        key: keyHint,
+        prefix: resolvedPrefix ?? putDefaults.prefix,
+        repo,
+        ref,
+        deriveRepoFromGit: !(flagBool(parsed.flags, "--no-git") || putDefaults.noGit === true),
+        dryRun,
+        metadata,
+        provenanceClient: "uploads-cli-screenshot",
+        alt: () => alt,
+        width,
+    });
+    let gallery;
+    if (galleryId) {
+        try {
+            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 };
+            void item;
+        }
+        catch (err) {
+            gallery = { id: galleryId, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    let comment;
+    let commentError;
+    if (wantComment && ghTarget) {
+        try {
+            comment = await syncAttachmentsComment(ctx.client, ghTarget, run);
+            if (logHuman)
+                process.stderr.write(`>> attachments comment ${comment.action}\n`);
+        }
+        catch (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`);
+        }
+    }
+    if (logHuman) {
+        if (prepared.frame?.framed)
+            process.stderr.write(`>> framed with ${prepared.frame.frameId}\n`);
+        if (prepared.optimized) {
+            process.stderr.write(`>> optimized ${prepared.originalBytes} → ${prepared.outputBytes} bytes\n`);
+        }
+        process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n\n`);
+    }
+    switch (format) {
+        case "json":
+            await writeJson({
+                workspace: result.workspace,
+                key: result.key,
+                url: result.url,
+                embedUrl: result.embedUrl,
+                size: result.size,
+                contentType: result.contentType,
+                replaced: result.replaced,
+                markdown,
+                backend: captured.backend,
+                gallery,
+                ...(dryRun ? { dryRun: true } : {}),
+            });
+            break;
+        case "url":
+            await writeStdout(`${result.url}\n`);
+            break;
+        case "markdown":
+            await writeStdout(`${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`);
+        }
+    }
+    if (gallery?.error) {
+        process.stderr.write(`warning: upload succeeded but adding it to gallery ${gallery.id} failed: ${gallery.error}\n`);
+    }
+    if (commentError && ctx.json) {
+        // already reported to stderr above; json output stays upload-focused.
+    }
+    return gallery?.error ? 1 : 0;
+}