@buildinternet/uploads 0.48.0 → 0.49.0

package/README.md

@@ -27,6 +27,8 @@ uploads put ./ui.png --frame browser --frame-url "https://app.example"
 uploads put ./after.png --pr 123
 uploads put ./capture-2026-…Z.png --pr 123 --name hero.png   # clean leaf, stable path
 uploads put ./shot.png --pr 123 --name hero.png --dry-run --format url  # preview URL, no upload
+uploads put --url https://cdn.example/shot.png --pr 123
+uploads put --url http://localhost:4321/shot.png
 uploads gallery create --title "Release screenshots"
 uploads put ./after.png --gallery gal_example
 # custom metadata (queryable): page URL, in-app path, which surface
@@ -196,7 +198,7 @@ Config layers (first match wins): CLI flags → env vars → `--env-file` → `~
 
 ## MCP server
 
-`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows: `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`. Gallery tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `get_metadata`, `set_metadata`, `find_files`, `usage`, `reconcile`, `purge_expired`, `comment`, `health`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. `put` and `attach` accept a `metadata` param (same `gh.*` auto-injection as the CLI's `attach`); `get_metadata`, `set_metadata`, and `find_files` mirror `uploads meta get` / `meta set` / `find`. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`health` needs no auth).
+`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows: `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`. Gallery tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `get_metadata`, `set_metadata`, `find_files`, `usage`, `reconcile`, `purge_expired`, `comment`, `whoami`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. `put` and `attach` accept a `metadata` param (same `gh.*` auto-injection as the CLI's `attach`); `get_metadata`, `set_metadata`, and `find_files` mirror `uploads meta get` / `meta set` / `find`. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`whoami` needs no auth).
 
 ```json
 { "command": "uploads", "args": ["--env-file", "/path/to/.env", "mcp"] }
@@ -204,6 +206,8 @@ Config layers (first match wins): CLI flags → env vars → `--env-file` → `~
 
 Or with `UPLOADS_TOKEN`/`UPLOADS_WORKSPACE` in the environment or user config. Claude Code: `claude mcp add uploads -- uploads --env-file /path/to/.env mcp`.
 
+The MCP Registry lists this server as `sh.uploads/mcp`.
+
 For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations (including `get_metadata` / `set_metadata` / `find_files`) plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. The hosted `put` also accepts a `metadata` param. `uploads install` registers the skills + hosted MCP with whichever of Claude Code, Codex, and Grok are on PATH (a missing CLI is skipped) + Grok/Cursor hooks (short progress; `--verbose` for underlying output). Claude and Codex use their plugins for the same pre-PR screenshot reminder (`uploads hook pre-pr-screenshot`). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
 
 ## Programmatic use

package/dist/cli-help.js

@@ -106,6 +106,7 @@ ${section(style, "Examples:")}
   ${style.command("uploads whoami")}
   ${style.command("uploads put")} ./shot.png --pr 123 --name hero.png
   ${style.command("uploads put")} ./after.png --pr 123
+  ${style.command("uploads put")} --url https://cdn.example/shot.png --pr 123
   ${style.command("uploads put")} ./bug.png --issue 45
   ${style.command("uploads put")} ./shot.png --meta path=/settings --state after
   ${style.command("uploads attach")} ./before.png ./after.png
@@ -155,6 +156,7 @@ ${section(style, "Examples:")}
   ${style.command("uploads whoami")}
   ${style.command("uploads put")} ./shot.png --pr 123 --name hero.png
   ${style.command("uploads put")} ./after.png --pr 123
+  ${style.command("uploads put")} --url https://cdn.example/shot.png --pr 123
   ${style.command("uploads put")} ./bug.png --issue 45 --repo myorg/myapp
   ${style.command("uploads put")} ./shot.png --dry-run --format url
   ${style.command("uploads put")} ./shot.png --meta path=/settings --state after

package/dist/commands/completion.js

@@ -124,7 +124,10 @@ ${subMaps.join("\n")}
 
   if [[ "$cur" == -* ]]; then
     case "$cmd" in
-      put|attach)
+      put)
+        COMPREPLY=( $(compgen -W "\${put_flags[*]} --url" -- "$cur") )
+        ;;
+      attach)
         COMPREPLY=( $(compgen -W "\${put_flags[*]}" -- "$cur") )
         ;;
       screenshot)
@@ -284,6 +287,7 @@ function fishScript() {
             continue;
         lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put attach' -l ${flag.slice(2)}`);
     }
+    lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put' -l url -r`);
     for (const flag of SCREENSHOT_FLAGS) {
         if (!flag.startsWith("--"))
             continue;

package/dist/commands/mcp.js

@@ -2,7 +2,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { AjvJsonSchemaValidator } from "@modelcontextprotocol/server/validators/ajv";
 import { parseCommandArgs } from "../cli-args.js";
 import { resolveApiUrl } from "../config.js";
-import { createMcpServer } from "../mcp/server.js";
+import { createMcpServer, MCP_SERVER_ICONS } from "../mcp/server.js";
 import { createUploadsMcpTools } from "../mcp/tools.js";
 import { packageVersion } from "../package-version.js";
 import { writeCommandHelp } from "../cli-style.js";
@@ -10,7 +10,7 @@ const MCP_HELP = `uploads [globals] mcp
 
 Serve the Model Context Protocol (MCP) over stdio for agent clients. Tools
 mirror the CLI commands: put, attach, list, delete, usage, reconcile,
-purge_expired, comment, health, doctor.
+purge_expired, comment, whoami, doctor.
 Global flags before "mcp" (--api-url, --token, --workspace, --env-file)
 configure every tool call; a per-call "workspace" argument overrides
 --workspace, like the CLI's per-command flag.
@@ -35,7 +35,7 @@ export async function runMcp(args, opts, help = false) {
     // `@cfworker/json-schema` provider instead).
     const validator = new AjvJsonSchemaValidator();
     const handle = serveStdio(() => createMcpServer({
-        serverInfo: { name: "uploads", version: packageVersion() },
+        serverInfo: { name: "uploads", version: packageVersion(), icons: MCP_SERVER_ICONS },
         tools: createUploadsMcpTools({ globals: opts.globals }),
         apiUrl: resolveApiUrl(opts.globals),
         validator,

package/dist/commands.d.ts

@@ -350,7 +350,16 @@ export type PutUploadItem = PutResult & {
  */
 export declare function uploadPuts(opts: {
     client: UploadsClient;
-    files: readonly string[];
+    files?: readonly string[];
+    /**
+     * In-memory bodies (CLI `--url`, MCP `contentUrl`). Mutually exclusive
+     * with `files`. `source` is the failure/progress label (the URL).
+     */
+    byteSources?: readonly {
+        bytes: Uint8Array;
+        filename: string;
+        source: string;
+    }[];
     /** Single-file --name leaf override. */
     nameOverride?: string;
     /** Single-file --key. */

package/dist/commands.js

@@ -8,6 +8,7 @@ import { buildUploadMarkdown } from "./embed.js";
 import { readLocalRepoCommentConfig, resolveCommentOptions } from "./comment-config.js";
 import { urlForGithubEmbed } from "./public-urls.js";
 import { UploadsError } from "./errors.js";
+import { fetchUploadSource, resolveUploadFilename } from "./fetch-upload-source.js";
 import { writeJson, writeStdout } from "./io.js";
 import { imageFactsFromBytes } from "./image-facts.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
@@ -94,8 +95,12 @@ export function readFileArg(fileArg) {
 }
 // --- put ---
 const PUT_HELP = `uploads put <file...> [options]
+uploads put --url <url> [options]
 
 Upload one or more images for GitHub embeds. Use "-" for stdin (single file only).
+Pass --url (repeatable) to fetch a file instead of a local path. Public HTTPS,
+or http://localhost / 127.0.0.1 / *.localhost on this machine. Other private
+hosts are rejected. The filename comes from the URL path, or --name.
 
 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).
@@ -135,6 +140,7 @@ MARKDOWN prefers embedUrl for GitHub. Override: UPLOADS_EMBED_PUBLIC_BASE_URL.
 Options:
   --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
+  --url <url>           Fetch this URL and upload its body (repeatable). Public HTTPS, or http://localhost on the CLI. Not with file arguments
   --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)
@@ -201,6 +207,8 @@ Examples:
   uploads put ./shot.png --pr 128 --name hero.webp --dry-run --format url
   uploads put ./after.png --gallery gal_example
   uploads put ./shot.png --meta path=/settings --state after --app web
+  uploads put --url https://cdn.example/shot.png --pr 128 --name hero.png
+  uploads put --url http://localhost:4321/shot.png
 `;
 /**
  * Turns a pr/issue pair (+ optional repo) into a GhTarget; undefined when
@@ -1027,13 +1035,21 @@ function errorDetail(err) {
  * Same partial-failure shape as uploadAttachments.
  */
 export async function uploadPuts(opts) {
-    if (opts.files.length > 1 && opts.files.some((f) => f === "-")) {
+    const files = opts.files ?? [];
+    const byteSources = opts.byteSources ?? [];
+    if (files.length > 0 && byteSources.length > 0) {
+        throw new UsageError("internal: uploadPuts files and byteSources are mutually exclusive");
+    }
+    const count = files.length + byteSources.length;
+    if (count === 0)
+        throw new UsageError("put requires at least one file");
+    if (count > 1 && files.some((f) => f === "-")) {
         throw new UsageError("stdin (-) cannot be combined with multiple file arguments");
     }
-    if (opts.files.length > 1 && opts.explicitKey) {
+    if (count > 1 && opts.explicitKey) {
         throw new UsageError("--key cannot be combined with multiple files");
     }
-    if (opts.files.length > 1 && opts.nameOverride) {
+    if (count > 1 && opts.nameOverride) {
         throw new UsageError("--name cannot be combined with multiple files");
     }
     // Resolved once for the whole batch (issue #631) — never per file.
@@ -1048,18 +1064,33 @@ export async function uploadPuts(opts) {
                 branch: opts.ghBranchTarget.branch,
             })
             : undefined;
-    const slots = await mapBounded(opts.files, opts.concurrency ?? UPLOAD_BATCH_CONCURRENCY, async (file) => {
+    const items = byteSources.length > 0
+        ? byteSources.map((s) => ({
+            source: s.source,
+            filename: opts.nameOverride ?? s.filename,
+            bytes: s.bytes,
+        }))
+        : files.map((file) => ({
+            source: file,
+            path: file,
+        }));
+    const slots = await mapBounded(items, opts.concurrency ?? UPLOAD_BATCH_CONCURRENCY, async (item) => {
+        const file = item.source;
         try {
-            const sourceName = opts.nameOverride ??
+            const bytes = item.bytes ?? readFileArg(item.path ?? file);
+            const sourceName = item.filename ??
+                opts.nameOverride ??
                 (file === "-"
                     ? opts.explicitKey
                         ? basename(opts.explicitKey)
                         : "stdin.bin"
                     : basename(file));
-            const bytes = readFileArg(file);
             // Sidecar manifest from a prior `screenshot --out` of this exact file
-            // (issue #469 lever 2) — see mergeSidecarMeta. Not applicable to stdin.
-            const metadata = file !== "-" ? mergeSidecarMeta(file, bytes, opts.metadata) : opts.metadata;
+            // (issue #469 lever 2) — see mergeSidecarMeta. Not applicable to stdin
+            // or URL fetches.
+            const metadata = item.path && item.path !== "-"
+                ? mergeSidecarMeta(item.path, bytes, opts.metadata)
+                : opts.metadata;
             const { result, prepared, markdown, sentMetadata } = await uploadPreparedImage(opts.client, bytes, sourceName, {
                 frame: opts.frame,
                 optimize: opts.optimize,
@@ -1883,12 +1914,23 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         return 0;
     }
     const files = parsed.positionals;
-    if (files.length === 0) {
-        throw new UsageError("put requires at least one file", {
+    if (parsed.flags.get("--url") === true) {
+        throw new UsageError("missing value for --url", {
+            example: "uploads put --url https://cdn.example/shot.png --pr 123",
+        });
+    }
+    const urlArgs = flagValues(parsed.flags, "--url");
+    if (files.length > 0 && urlArgs.length > 0) {
+        throw new UsageError("--url cannot be combined with file arguments", {
+            example: "uploads put --url https://cdn.example/shot.png --pr 123",
+        });
+    }
+    if (files.length === 0 && urlArgs.length === 0) {
+        throw new UsageError("put requires at least one file or --url", {
             example: "uploads put ./shot.png --pr 123",
         });
     }
-    const multi = files.length > 1;
+    const multi = files.length > 1 || urlArgs.length > 1;
     // Resolved early (issue #700): both the auto-PR opt-out default and the
     // `--no-git`-gated staging/auto-PR detection below need it before the rest
     // of put's flag parsing.
@@ -2135,36 +2177,77 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const logHuman = !ctx.quiet && format === "human";
     if (logHuman) {
         if (multi) {
-            process.stderr.write(`>> ${dryRun ? "dry run for" : "uploading"} ${files.length} files\n`);
+            const n = files.length > 0 ? files.length : urlArgs.length;
+            process.stderr.write(`>> ${dryRun ? "dry run for" : "uploading"} ${n} files\n`);
         }
         else {
-            const fileArg = files[0];
+            const fileArg = files[0] ?? urlArgs[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, sentMetadata } = await uploadPuts({
-        client: ctx.client,
-        files,
-        nameOverride: nameFlag,
-        explicitKey: keyHint,
-        ghTarget: effectiveGhTarget,
-        ghBranchTarget: stagingTarget,
-        prefix: resolvedPrefix ?? defaults.prefix,
-        repo: flagString(parsed.flags, "--repo") ?? defaults.repo,
-        ref: flagString(parsed.flags, "--ref") ?? defaults.ref,
-        deriveRepoFromGit: !noGit,
-        contentType: contentTypeOverride,
-        dryRun,
-        replace: replaceFlag,
-        optimize: optimizeOpts,
-        frame: frameOpts,
-        metadata,
-        deriveImageFacts: derivedMetaEnabled(parsed.flags, defaults),
-        alt: altFlag,
-        width,
-    });
+    let byteSources;
+    const urlFetchFailures = [];
+    let urlFetchFirstError;
+    if (urlArgs.length > 0) {
+        byteSources = [];
+        for (const raw of urlArgs) {
+            try {
+                const filename = resolveUploadFilename(raw, !multi ? nameFlag : undefined, "--url", {
+                    allowLoopback: true,
+                });
+                const bytes = await fetchUploadSource(raw, {
+                    label: "--url",
+                    userAgent: "uploads.sh/cli",
+                    allowLoopback: true,
+                });
+                byteSources.push({ bytes, filename, source: raw });
+            }
+            catch (err) {
+                urlFetchFirstError ??= err;
+                urlFetchFailures.push({ file: raw, error: errorDetail(err) });
+            }
+        }
+    }
+    let uploads;
+    let failures;
+    let firstError;
+    let sentMetadata;
+    if (byteSources && byteSources.length === 0) {
+        uploads = [];
+        failures = urlFetchFailures;
+        firstError = urlFetchFirstError;
+        sentMetadata = [];
+    }
+    else {
+        const batch = await uploadPuts({
+            client: ctx.client,
+            files: byteSources ? undefined : files,
+            byteSources,
+            nameOverride: byteSources ? undefined : nameFlag,
+            explicitKey: keyHint,
+            ghTarget: effectiveGhTarget,
+            ghBranchTarget: stagingTarget,
+            prefix: resolvedPrefix ?? defaults.prefix,
+            repo: flagString(parsed.flags, "--repo") ?? defaults.repo,
+            ref: flagString(parsed.flags, "--ref") ?? defaults.ref,
+            deriveRepoFromGit: !noGit,
+            contentType: contentTypeOverride,
+            dryRun,
+            replace: replaceFlag,
+            optimize: optimizeOpts,
+            frame: frameOpts,
+            metadata,
+            deriveImageFacts: derivedMetaEnabled(parsed.flags, defaults),
+            alt: altFlag,
+            width,
+        });
+        uploads = batch.uploads;
+        failures = [...urlFetchFailures, ...batch.failures];
+        firstError = urlFetchFirstError ?? batch.firstError;
+        sentMetadata = batch.sentMetadata;
+    }
     // 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));

package/dist/fetch-upload-source.d.ts

@@ -0,0 +1,35 @@
+export declare const FETCH_UPLOAD_SOURCE_TIMEOUT_MS = 15000;
+export declare const FETCH_UPLOAD_SOURCE_MAX_REDIRECTS = 5;
+/** Client-side cap when the caller does not pass a workspace policy ceiling. */
+export declare const FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES: number;
+export interface FetchableUploadUrlOptions {
+    /**
+     * CLI / stdio MCP only. Permit loopback (`localhost`, `*.localhost`,
+     * `127.0.0.0/8`, `::1`) and `http` on those hosts. LAN, link-local, and
+     * `.internal` stay rejected. Hosted MCP must not set this.
+     */
+    allowLoopback?: boolean;
+}
+export interface FetchUploadSourceOptions extends FetchableUploadUrlOptions {
+    maxBytes?: number;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Human label in errors (`--url`, `contentUrl`). */
+    label?: string;
+    userAgent?: string;
+}
+/** Parse and reject URLs we will not fetch. Used on the original URL and every redirect. */
+export declare function assertFetchableUploadUrl(raw: string, label?: string, opts?: FetchableUploadUrlOptions): URL;
+/** Filename leaf from a URL path (`https://cdn.example/a/shot.png?x=1` → `shot.png`). */
+export declare function filenameFromUploadUrl(url: URL): string | undefined;
+/** `filename` if given, else the URL path leaf. Throws USAGE when neither works. */
+export declare function resolveUploadFilename(rawUrl: string, filename: string | undefined, label?: string, opts?: FetchableUploadUrlOptions): string;
+/**
+ * GET `url` and return the body bytes, capped at `maxBytes`.
+ *
+ * Redirects are followed manually so each hop is re-validated (scheme, no
+ * credentials, host policy). A public origin cannot redirect onto loopback
+ * even when `allowLoopback` is set. Auth headers are never forwarded.
+ */
+export declare function fetchUploadSource(raw: string, opts?: FetchUploadSourceOptions): Promise<Uint8Array>;

package/dist/fetch-upload-source.js

@@ -0,0 +1,185 @@
+/**
+ * Fetch bytes from a caller-supplied URL for `put --url` / MCP `contentUrl`.
+ *
+ * Guardrails: HTTPS only (http allowed on loopback when `allowLoopback` is
+ * set), no URL credentials, private/internal hosts rejected unless they are
+ * loopback and `allowLoopback` is set. Redirects re-checked each hop; a
+ * public origin cannot redirect onto loopback. No auth headers forwarded.
+ * The server still sniffs and size-caps after this.
+ */
+import { UploadsError } from "./errors.js";
+import { isLoopbackHost, isPrivateOrLocalHost } from "./private-host.js";
+export const FETCH_UPLOAD_SOURCE_TIMEOUT_MS = 15_000;
+export const FETCH_UPLOAD_SOURCE_MAX_REDIRECTS = 5;
+/** Client-side cap when the caller does not pass a workspace policy ceiling. */
+export const FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+function fail(label, message, code = "USAGE") {
+    throw new UploadsError(`${label} ${message}`, code);
+}
+/** Parse and reject URLs we will not fetch. Used on the original URL and every redirect. */
+export function assertFetchableUploadUrl(raw, label = "url", opts = {}) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        fail(label, "must be a valid absolute URL");
+    }
+    const loopback = isLoopbackHost(url.hostname);
+    const allowThisLoopback = Boolean(opts.allowLoopback && loopback);
+    if (url.protocol === "http:") {
+        if (!allowThisLoopback)
+            fail(label, "must be https");
+    }
+    else if (url.protocol !== "https:") {
+        fail(label, "must be https");
+    }
+    if (url.username !== "" || url.password !== "") {
+        fail(label, "must not include credentials");
+    }
+    if (isPrivateOrLocalHost(url.hostname) && !allowThisLoopback) {
+        fail(label, "targets a private or internal network");
+    }
+    return url;
+}
+/** Filename leaf from a URL path (`https://cdn.example/a/shot.png?x=1` → `shot.png`). */
+export function filenameFromUploadUrl(url) {
+    const last = url.pathname.replace(/\/+$/, "").split("/").pop();
+    if (!last)
+        return undefined;
+    let decoded = last;
+    try {
+        decoded = decodeURIComponent(last);
+    }
+    catch {
+        // Keep the raw segment.
+    }
+    const cleaned = decoded.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+    return cleaned || undefined;
+}
+/** `filename` if given, else the URL path leaf. Throws USAGE when neither works. */
+export function resolveUploadFilename(rawUrl, filename, label = "url", opts = {}) {
+    if (filename)
+        return filename;
+    const derived = filenameFromUploadUrl(assertFetchableUploadUrl(rawUrl, label, opts));
+    if (!derived) {
+        throw new UploadsError(`${label} has no filename in the path; pass a filename`, "USAGE");
+    }
+    return derived;
+}
+function timeoutError(label) {
+    fail(label, "fetch timed out", "NETWORK");
+}
+function isAbortError(err) {
+    return ((err instanceof DOMException && err.name === "AbortError") ||
+        (err instanceof Error && err.name === "AbortError"));
+}
+async function readCappedBody(res, maxBytes, label) {
+    const declared = Number(res.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        fail(label, `exceeds the upload limit (${maxBytes} bytes)`);
+    }
+    const body = res.body;
+    if (!body)
+        fail(label, "returned an empty body");
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value || value.byteLength === 0)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                fail(label, `exceeds the upload limit (${maxBytes} bytes)`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // Already locked/cancelled after a size abort.
+        }
+    }
+    if (total === 0)
+        fail(label, "returned an empty body");
+    if (chunks.length === 1)
+        return chunks[0];
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+/**
+ * GET `url` and return the body bytes, capped at `maxBytes`.
+ *
+ * Redirects are followed manually so each hop is re-validated (scheme, no
+ * credentials, host policy). A public origin cannot redirect onto loopback
+ * even when `allowLoopback` is set. Auth headers are never forwarded.
+ */
+export async function fetchUploadSource(raw, opts = {}) {
+    const label = opts.label ?? "url";
+    const timeoutMs = opts.timeoutMs ?? FETCH_UPLOAD_SOURCE_TIMEOUT_MS;
+    const maxBytes = opts.maxBytes ?? FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES;
+    const doFetch = opts.fetch ?? fetch;
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+    const urlOpts = { allowLoopback: opts.allowLoopback };
+    let url = assertFetchableUploadUrl(raw, label, urlOpts);
+    for (let hop = 0; hop <= FETCH_UPLOAD_SOURCE_MAX_REDIRECTS; hop++) {
+        let res;
+        try {
+            res = await doFetch(url, {
+                method: "GET",
+                redirect: "manual",
+                signal,
+                headers: {
+                    accept: "*/*",
+                    "user-agent": opts.userAgent ?? "uploads.sh",
+                },
+            });
+        }
+        catch (err) {
+            if (isAbortError(err) || timeout.aborted)
+                timeoutError(label);
+            throw new UploadsError(`could not fetch ${label}`, "NETWORK");
+        }
+        if (REDIRECT_STATUSES.has(res.status)) {
+            const location = res.headers.get("location");
+            if (!location)
+                fail(label, "redirect is missing a Location header");
+            if (hop === FETCH_UPLOAD_SOURCE_MAX_REDIRECTS) {
+                fail(label, "redirected too many times");
+            }
+            // Loopback is only sticky while we are already on loopback. A public
+            // CDN cannot bounce the CLI onto http://127.0.0.1.
+            url = assertFetchableUploadUrl(new URL(location, url).toString(), label, {
+                allowLoopback: urlOpts.allowLoopback && isLoopbackHost(url.hostname),
+            });
+            continue;
+        }
+        if (res.status !== 200) {
+            throw new UploadsError(`could not fetch ${label} (HTTP ${res.status})`, "NETWORK");
+        }
+        try {
+            return await readCappedBody(res, maxBytes, label);
+        }
+        catch (err) {
+            if (isAbortError(err) || timeout.aborted)
+                timeoutError(label);
+            throw err;
+        }
+    }
+    fail(label, "redirected too many times");
+}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey
 export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, resolveDestinationRoot, resolvePutPrefix, type BuiltinDestinationId, } from "./destinations.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 { assertFetchableUploadUrl, fetchUploadSource, filenameFromUploadUrl, resolveUploadFilename, FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES, FETCH_UPLOAD_SOURCE_MAX_REDIRECTS, FETCH_UPLOAD_SOURCE_TIMEOUT_MS, } from "./fetch-upload-source.js";
 export { createUploadsClient, type UploadsClient, type PutOptions, type ProvenanceInput, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type GalleryItem, type Gallery, type GallerySummary, type GalleryListOptions, type GalleryListResult, type CreateGalleryOptions, type AddGalleryItemOptions, type DeleteGalleryOptions, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, type FindFilesOptions, type FindFilesItem, type FindFilesResult, type MetadataKeysResult, type MetadataValuesResult, type GetMetadataResult, type PatchMetadataOptions, type ResolveGhPrefixOptions, type ResolveGhPrefixResult, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";

package/dist/index.js

@@ -4,6 +4,7 @@ export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey
 export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, resolveDestinationRoot, resolvePutPrefix, } from "./destinations.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, } from "./config.js";
 export { UploadsError } from "./errors.js";
+export { assertFetchableUploadUrl, fetchUploadSource, filenameFromUploadUrl, resolveUploadFilename, FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES, FETCH_UPLOAD_SOURCE_MAX_REDIRECTS, FETCH_UPLOAD_SOURCE_TIMEOUT_MS, } from "./fetch-upload-source.js";
 export { createUploadsClient, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";

package/dist/mcp/args.d.ts

@@ -10,12 +10,10 @@ export declare function optPosInt(args: ToolArgs, name: string, options?: {
 export declare function optStringRecord(args: ToolArgs, name: string): Record<string, string> | undefined;
 /** A JSON-array argument of strings (e.g. a `delete` or `files` param). */
 export declare function optStringArray(args: ToolArgs, name: string): string[] | undefined;
-/**
- * Shared tool-description text for the metadata-shaped `metadata`/`set`/
- * `filters` params across the CLI/local MCP (put/attach/set_metadata/
- * find_files) and the remote MCP worker (set_metadata/find_files).
- */
-export declare const METADATA_DESCRIPTION = "Queryable custom metadata (key\u2192value), separate from provenance. Omit to leave any metadata already stored for this key untouched; pass an object (even {}) to fully replace it. Keys: lowercase, ^[a-z][a-z0-9._-]{0,63}$. Values: 1-512 printable ASCII characters. Caps: at most 24 keys, at most 8192 total key+value bytes. Canonical keys, which uploads.sh derives automatically where it can: url, path, env, theme, viewport, device, software, captured. Use `path` for the route (e.g. /settings) \u2014 that is the key `find_files` searches by, so spell it `path` and not route/page/screen. `gh.*` is reserved by convention for GitHub PR/issue attachment context (repo/kind/number/ref).";
+/** Shared cue: `path` is the route `find_files` searches by. */
+export declare const METADATA_PATH_CUE = "Use `path` for the route (e.g. /settings), not route/page/screen.";
+/** put/screenshot/attach `metadata`. Key regex and caps stay in usage errors. */
+export declare const METADATA_DESCRIPTION: string;
 export declare const metadataProp: {
     type: string;
     additionalProperties: {
@@ -23,6 +21,8 @@ export declare const metadataProp: {
     };
     description: string;
 };
+/** 1×1 PNG, used only in MCP `inputSchema.examples` so copy-paste from Inspector works. */
+export declare const MCP_EXAMPLE_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
 export declare const stateProp: {
     type: string;
     enum: ("after" | "before" | "empty" | "error" | "loading")[];

package/dist/mcp/args.js

@@ -66,17 +66,19 @@ export function optStringArray(args, name) {
     }
     return v;
 }
-/**
- * Shared tool-description text for the metadata-shaped `metadata`/`set`/
- * `filters` params across the CLI/local MCP (put/attach/set_metadata/
- * find_files) and the remote MCP worker (set_metadata/find_files).
- */
-export const METADATA_DESCRIPTION = "Queryable custom metadata (key→value), separate from provenance. Omit to leave any metadata already stored for this key untouched; pass an object (even {}) to fully replace it. Keys: lowercase, ^[a-z][a-z0-9._-]{0,63}$. Values: 1-512 printable ASCII characters. Caps: at most 24 keys, at most 8192 total key+value bytes. Canonical keys, which uploads.sh derives automatically where it can: url, path, env, theme, viewport, device, software, captured. Use `path` for the route (e.g. /settings) — that is the key `find_files` searches by, so spell it `path` and not route/page/screen. `gh.*` is reserved by convention for GitHub PR/issue attachment context (repo/kind/number/ref).";
+/** Shared cue: `path` is the route `find_files` searches by. */
+export const METADATA_PATH_CUE = "Use `path` for the route (e.g. /settings), not route/page/screen.";
+/** put/screenshot/attach `metadata`. Key regex and caps stay in usage errors. */
+export const METADATA_DESCRIPTION = "Queryable tags for later search (key→value). " +
+    METADATA_PATH_CUE +
+    " Omit to leave existing tags; pass an object (even {}) to replace them. `state` and `app` have their own fields.";
 export const metadataProp = {
     type: "object",
     additionalProperties: { type: "string" },
     description: METADATA_DESCRIPTION,
 };
+/** 1×1 PNG, used only in MCP `inputSchema.examples` so copy-paste from Inspector works. */
+export const MCP_EXAMPLE_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
 export const stateProp = {
     type: "string",
     enum: [...META_STATE_VALUES],