@buildinternet/uploads 0.11.0 → 0.12.0

package/dist/mcp/tools.js

@@ -1,24 +1,13 @@
-/**
- * MCP tool set mirroring the CLI commands (put, attach, list, delete,
- * usage, reconcile, purge_expired, comment, health, doctor). Config is
- * resolved fresh per tool call so a
- * per-call `workspace` argument behaves like the CLI's --workspace flag, and
- * a missing token surfaces as a tool error rather than a startup failure.
- */
-import { basename } from "node:path";
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, makeGhTarget, prepareImageForUpload, readFileArg, syncAttachmentsComment, } from "../commands.js";
+import { buildDoctorReport, makeGhTarget, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
-import { buildMarkdown } from "../embed.js";
-import { urlForGithubEmbed } from "../public-urls.js";
 import { resolvePutPrefix } from "../destinations.js";
-import { ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget } from "../github.js";
+import { ghKeyPrefix, ghMetadataFromTarget } from "../github.js";
 import { validateMetaMap } from "../metadata.js";
-import { rewriteKeyExtension } from "../optimize.js";
-import { buildCliProvenance } from "../provenance.js";
 import { execRunner, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
 import { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
+import { batchFailureMessage, ToolBatchError } from "./server.js";
 import { attachmentFromText, buildReportPayload, parseReportType, REPORT_TYPES, submitReport, validateReportMessage, } from "../report.js";
 import { resolveApiUrl } from "../config.js";
 function optBool(args, name) {
@@ -270,13 +259,18 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "put",
-            description: "Upload a file to uploads.sh and get a public URL plus GitHub-ready embed markdown. Returns `url` (durable CDN) and `embedUrl` (same object, freshness-oriented host for GitHub Camo — prefer this in PR/issue markdown). The returned `markdown` already uses embedUrl when available. Pass `file` or `contentBase64` + `filename`; with `pr`/`issue` the key is stable and `comment` syncs the managed attachments comment. All uploads are public; pr/issue keys are predictable, so upload only non-sensitive media.",
+            description: "Upload one or more files to uploads.sh and get public URL(s) plus GitHub-ready embed markdown. Single-file: pass `file` or `contentBase64`+`filename` (flat result with `url`/`embedUrl`/`markdown`). Multi-file: pass `files` (paths; parallel; returns `uploads`+`failures`). Prefer `embedUrl` in PR/issue markdown. With `pr`/`issue` keys are stable and `comment` syncs the managed attachments comment. All uploads are public; pr/issue keys are predictable — upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {
                     file: {
                         type: "string",
-                        description: "Path of the file to upload. Exactly one of file or contentBase64 is required.",
+                        description: "Path of a single file to upload. Exactly one of file, files, or contentBase64 is required.",
+                    },
+                    files: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Paths of multiple files to upload in parallel. Returns { uploads, failures }. Cannot combine with file, contentBase64, key, or filename.",
                     },
                     contentBase64: {
                         type: "string",
@@ -284,11 +278,11 @@ export function createUploadsMcpTools(opts) {
                     },
                     filename: {
                         type: "string",
-                        description: "Filename for contentBase64 content (drives the key and content type). With `file`, overrides the key's leaf (clean name) while keeping the pr/default path.",
+                        description: "Filename for contentBase64 content (drives the key and content type). With single `file`, overrides the key's leaf (clean name) while keeping the pr/default path.",
                     },
                     key: {
                         type: "string",
-                        description: "Explicit object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>). Cannot be combined with pr/issue.",
+                        description: "Explicit object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>). Single file only; cannot be combined with pr/issue.",
                     },
                     destination: {
                         type: "string",
@@ -308,7 +302,10 @@ export function createUploadsMcpTools(opts) {
                         type: "string",
                         description: "PR/issue/branch key segment (default: today, or UPLOADS_DEFAULT_REF). Cannot be combined with pr/issue.",
                     },
-                    alt: { type: "string", description: "Alt text for the markdown (default: filename)." },
+                    alt: {
+                        type: "string",
+                        description: "Alt text for the markdown (default: each file's name; with multiple files applies to all).",
+                    },
                     width: {
                         type: "number",
                         description: "Emit <img width=…> markdown instead of a plain image embed.",
@@ -350,14 +347,24 @@ export function createUploadsMcpTools(opts) {
             },
             async handler(args) {
                 const file = optString(args, "file");
+                const filesArg = optStringArray(args, "files");
                 const contentBase64 = optString(args, "contentBase64");
-                if ((file === undefined) === (contentBase64 === undefined)) {
-                    usage("exactly one of file or contentBase64 is required");
+                if (filesArg !== undefined && filesArg.length === 0) {
+                    usage("files must be a non-empty array of paths");
+                }
+                const multi = filesArg !== undefined;
+                const sources = [file !== undefined, multi, contentBase64 !== undefined];
+                if (sources.filter(Boolean).length !== 1) {
+                    usage("exactly one of file, files, or contentBase64 is required");
                 }
                 const filenameArg = optString(args, "filename");
                 if (contentBase64 !== undefined && !filenameArg) {
                     usage("filename is required with contentBase64");
                 }
+                if (multi && filenameArg)
+                    usage("filename cannot be combined with files");
+                if (multi && optString(args, "key"))
+                    usage("key cannot be combined with files");
                 const target = ghTargetFromArgs(args, run);
                 const wantComment = optBool(args, "comment");
                 const dryRun = optBool(args, "dryRun");
@@ -396,67 +403,357 @@ export function createUploadsMcpTools(opts) {
                     usage(err instanceof Error ? err.message : String(err));
                 }
                 const { client } = clientFor(args);
-                const bytes = file !== undefined
-                    ? readFileArg(file)
-                    : new Uint8Array(Buffer.from(contentBase64, "base64"));
-                const sourceName = file !== undefined ? (filenameArg ?? basename(file)) : filenameArg;
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
                 const frameOpts = mcpFrameOptions(args);
                 const optimizeOpts = mcpOptimizeOptions(args, defaults);
-                const prepared = await prepareImageForUpload(bytes, sourceName, {
-                    ...frameOpts,
-                    optimize: optimizeOpts,
-                });
-                const filename = prepared.filename;
-                let key = target ? ghAttachmentKey(target, filename) : keyArg;
-                if (key && prepared.optimized)
-                    key = rewriteKeyExtension(key, filename);
                 const noGit = optBool(args, "noGit") || defaults.noGit === true;
-                const result = await client.put(prepared.bytes, {
-                    filename,
-                    key,
+                const alt = optString(args, "alt");
+                const width = optPosInt(args, "width") ?? defaults.width;
+                const contentType = optString(args, "contentType");
+                const putShared = {
+                    client,
+                    ghTarget: target,
                     prefix: resolvedPrefix ?? defaults.prefix,
                     repo: optString(args, "repo") ?? defaults.repo,
                     ref: refArg ?? defaults.ref,
-                    contentType: prepared.optimized ? prepared.contentType : optString(args, "contentType"),
                     deriveRepoFromGit: !noGit,
+                    contentType,
                     dryRun,
-                    provenance: buildCliProvenance({
-                        sourceName,
-                        client: "uploads-mcp",
-                        optimized: prepared.optimized,
-                        frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
-                        keepExif: optimizeOpts.keepExif === true,
-                    }),
+                    optimize: optimizeOpts,
+                    frame: frameOpts,
                     metadata,
+                    provenanceClient: "uploads-mcp",
+                    alt,
+                    width,
+                };
+                // Multi-file path (paths only — no base64 batch).
+                if (multi) {
+                    const { uploads, failures } = await uploadPuts({
+                        ...putShared,
+                        files: filesArg,
+                    });
+                    if (uploads.length === 0 && failures.length > 0) {
+                        throw new ToolBatchError(batchFailureMessage(failures), { uploads, failures });
+                    }
+                    if (wantComment && target && uploads.length > 0) {
+                        const { comment, commentError } = await syncComment(client, target);
+                        return { uploads, failures, comment, commentError };
+                    }
+                    return { uploads, failures };
+                }
+                // Single-file: contentBase64 still supported; paths go through uploadPuts.
+                if (contentBase64 !== undefined) {
+                    const sourceName = filenameArg;
+                    const bytes = new Uint8Array(Buffer.from(contentBase64, "base64"));
+                    const { result, prepared, markdown } = await uploadPreparedImage(client, bytes, sourceName, {
+                        frame: frameOpts,
+                        optimize: optimizeOpts,
+                        ghTarget: target,
+                        key: keyArg,
+                        prefix: resolvedPrefix ?? defaults.prefix,
+                        repo: optString(args, "repo") ?? defaults.repo,
+                        ref: refArg ?? defaults.ref,
+                        contentType,
+                        deriveRepoFromGit: !noGit,
+                        dryRun,
+                        metadata,
+                        provenanceClient: "uploads-mcp",
+                        alt: () => alt ?? sourceName,
+                        width,
+                    });
+                    const optimize = {
+                        optimized: prepared.optimized,
+                        skippedReason: prepared.skippedReason,
+                        originalBytes: prepared.originalBytes,
+                        outputBytes: prepared.outputBytes,
+                        filename: prepared.filename,
+                    };
+                    if (wantComment && target) {
+                        const { comment, commentError } = await syncComment(client, target);
+                        return { ...result, markdown, optimize, frame: prepared.frame, comment, commentError };
+                    }
+                    return {
+                        ...result,
+                        markdown,
+                        optimize,
+                        frame: prepared.frame,
+                        ...(dryRun ? { dryRun: true } : {}),
+                    };
+                }
+                const { uploads, failures, firstError } = await uploadPuts({
+                    ...putShared,
+                    files: [file],
+                    nameOverride: filenameArg,
+                    explicitKey: keyArg,
                 });
-                const markdown = buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
-                    alt: optString(args, "alt") ?? sourceName,
-                    width: optPosInt(args, "width") ?? defaults.width,
-                });
-                const optimize = {
-                    optimized: prepared.optimized,
-                    skippedReason: prepared.skippedReason,
-                    originalBytes: prepared.originalBytes,
-                    outputBytes: prepared.outputBytes,
-                    filename: prepared.filename,
+                if (uploads.length === 0 && failures.length > 0) {
+                    throw firstError instanceof Error ? firstError : new Error(String(firstError));
+                }
+                const u = uploads[0];
+                const flat = {
+                    workspace: u.workspace,
+                    key: u.key,
+                    url: u.url,
+                    embedUrl: u.embedUrl,
+                    size: u.size,
+                    contentType: u.contentType,
+                    replaced: u.replaced,
+                    markdown: u.markdown,
+                    optimize: u.optimize,
+                    frame: u.frame,
+                    ...(dryRun ? { dryRun: true } : {}),
                 };
                 if (wantComment && target) {
                     const { comment, commentError } = await syncComment(client, target);
-                    return { ...result, markdown, optimize, frame: prepared.frame, comment, commentError };
+                    return { ...flat, comment, commentError };
                 }
-                return {
+                return flat;
+            },
+        },
+        {
+            name: "screenshot",
+            description: "Capture a URL or a local .html file and host it — a hosted, PR-embeddable image in one call. Backend `local` drives an already-installed Chrome/Chromium (dynamically loaded; unavailable in some runtimes); `remote` renders server-side via the workspace's render endpoint and counts against the monthly upload budget. Default via=auto prefers local when found, else remote. localhost/private-network URLs and .html files are local-only — via=remote (or auto falling back to remote) fails fast instead of a doomed request. Shares the put upload pipeline: optional frame, optimize-by-default, pr/issue attachment + comment, gallery, metadata. Uploads are public.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    target: {
+                        type: "string",
+                        description: "http(s) URL, or a path to a local .html file.",
+                    },
+                    via: {
+                        type: "string",
+                        description: "Capture backend: auto (default) | local | remote.",
+                    },
+                    browser: {
+                        type: "string",
+                        description: "Explicit local browser executable path (local backend only).",
+                    },
+                    cdp: {
+                        type: "string",
+                        description: "Attach to a running Chrome via CDP instead of launching one (local backend only).",
+                    },
+                    viewport: {
+                        type: "string",
+                        description: "WIDTHxHEIGHT[@SCALEx], e.g. 1280x800@2x (default: 1280x800@2).",
+                    },
+                    selector: { type: "string", description: "Capture one element instead of the viewport." },
+                    fullPage: { type: "boolean", description: "Capture the full scrollable page." },
+                    colorScheme: {
+                        type: "string",
+                        description: "Emulate prefers-color-scheme: dark | light. Full media-query emulation requires via: \"local\" — the remote backend only sets the CSS color-scheme property and won't flip a page's own prefers-color-scheme queries.",
+                    },
+                    wait: {
+                        type: "string",
+                        description: 'Settle strategy: load (default) | domcontentloaded | networkidle | a millisecond count (millisecond counts are local-only — via: "local").',
+                    },
+                    key: {
+                        type: "string",
+                        description: "Explicit object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.png). Cannot be combined with pr/issue.",
+                    },
+                    destination: {
+                        type: "string",
+                        description: "Typed destination root: screenshots | gh | f. With pr/issue must be gh or omitted.",
+                    },
+                    prefix: {
+                        type: "string",
+                        description: "Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX).",
+                    },
+                    ...ghTargetProps("Attach to"),
+                    repo: {
+                        type: "string",
+                        description: "owner/name repo segment (default: git remote, or UPLOADS_DEFAULT_REPO).",
+                    },
+                    ref: {
+                        type: "string",
+                        description: "PR/issue/branch key segment (default: today, or UPLOADS_DEFAULT_REF).",
+                    },
+                    alt: {
+                        type: "string",
+                        description: "Alt text for the markdown (default: derived filename).",
+                    },
+                    width: {
+                        type: "number",
+                        description: "Emit <img width=…> markdown instead of a plain embed.",
+                    },
+                    noOptimize: {
+                        type: "boolean",
+                        description: "Skip client-side image optimization (default: optimize to WebP).",
+                    },
+                    optimizeMaxEdge: {
+                        type: "number",
+                        description: "Max long edge in pixels when optimizing.",
+                    },
+                    optimizeQuality: { type: "number", description: "WebP quality 1-100 when optimizing." },
+                    keepExif: { type: "boolean", description: "Keep EXIF/XMP/ICC when optimizing." },
+                    ...frameProps,
+                    noGit: { type: "boolean", description: "Don't derive the repo segment from git." },
+                    comment: {
+                        type: "boolean",
+                        description: "With pr/issue: create/update the managed attachments comment (best-effort).",
+                    },
+                    galleryId: {
+                        type: "string",
+                        description: "Add the uploaded object to this public gallery.",
+                    },
+                    dryRun: {
+                        type: "boolean",
+                        description: "Capture + resolve key/URL without uploading. Not with comment or galleryId.",
+                    },
+                    metadata: metadataProp,
+                    workspace: workspaceProp,
+                },
+                required: ["target"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const targetArg = optString(args, "target");
+                if (!targetArg)
+                    usage("target is required");
+                const viaArg = optString(args, "via") ?? "auto";
+                if (viaArg !== "auto" && viaArg !== "local" && viaArg !== "remote") {
+                    usage("via must be auto, local, or remote");
+                }
+                const colorSchemeArg = optString(args, "colorScheme");
+                if (colorSchemeArg && colorSchemeArg !== "dark" && colorSchemeArg !== "light") {
+                    usage("colorScheme must be dark or light");
+                }
+                const target = ghTargetFromArgs(args, run);
+                const wantComment = optBool(args, "comment");
+                const dryRun = optBool(args, "dryRun");
+                const keyArg = optString(args, "key");
+                const destArg = optString(args, "destination");
+                const prefixArg = optString(args, "prefix");
+                const refArg = optString(args, "ref");
+                const galleryIdArg = optString(args, "galleryId");
+                if (wantComment && !target)
+                    usage("comment requires pr or issue");
+                if (dryRun && wantComment)
+                    usage("dryRun cannot be combined with comment");
+                if (dryRun && galleryIdArg)
+                    usage("dryRun cannot be combined with galleryId");
+                if (target) {
+                    if (keyArg)
+                        usage("key cannot be combined with pr/issue");
+                    if (refArg)
+                        usage("ref cannot be combined with pr/issue");
+                    if (prefixArg)
+                        usage("prefix cannot be combined with pr/issue");
+                }
+                const metadata = optStringRecord(args, "metadata");
+                if (metadata)
+                    validateMetaMap(metadata);
+                let resolvedPrefix;
+                try {
+                    resolvedPrefix = resolvePutPrefix({
+                        destination: destArg,
+                        prefix: prefixArg,
+                        key: keyArg,
+                        ghAttachment: Boolean(target),
+                    });
+                }
+                catch (err) {
+                    usage(err instanceof Error ? err.message : String(err));
+                }
+                const { config, client } = clientFor(args);
+                const defaults = resolvePutDefaults({ envFile: globals.envFile });
+                const frameOpts = mcpFrameOptions(args);
+                const optimizeOpts = mcpOptimizeOptions(args, defaults);
+                const noGit = optBool(args, "noGit") || defaults.noGit === true;
+                const alt = optString(args, "alt");
+                const width = optPosInt(args, "width") ?? defaults.width;
+                // Dynamic import only: keeps mcp/tools.ts (and therefore anything
+                // that statically imports it) free of a static reference to the
+                // local-backend chain. If this fails, the runtime can't do Node-side
+                // capture at all — point the caller at the remote backend instead.
+                let screenshotModule;
+                try {
+                    screenshotModule = await import("../screenshot.js");
+                }
+                catch (err) {
+                    usage(`screenshot capture is unavailable in this runtime; try via: "remote" instead (${err instanceof Error ? err.message : String(err)})`);
+                }
+                let captured;
+                try {
+                    captured = await screenshotModule.captureScreenshot({
+                        target: targetArg,
+                        via: viaArg,
+                        browserPath: optString(args, "browser"),
+                        cdp: optString(args, "cdp"),
+                        viewport: screenshotModule.parseViewport(optString(args, "viewport")),
+                        selector: optString(args, "selector"),
+                        fullPage: optBool(args, "fullPage"),
+                        colorScheme: colorSchemeArg,
+                        waitUntil: screenshotModule.parseWaitUntil(optString(args, "wait")),
+                        apiUrl: config.apiUrl,
+                        token: config.token,
+                    });
+                }
+                catch (err) {
+                    if (err instanceof Error &&
+                        "code" in err &&
+                        err.code === "BROWSER_NOT_FOUND" &&
+                        viaArg === "local") {
+                        usage(`${err.message} — try via: "remote" instead`);
+                    }
+                    throw err;
+                }
+                const { result, prepared, markdown } = await uploadPreparedImage(client, captured.png, captured.filename, {
+                    frame: frameOpts,
+                    optimize: optimizeOpts,
+                    ghTarget: target,
+                    key: keyArg,
+                    prefix: resolvedPrefix ?? defaults.prefix,
+                    repo: optString(args, "repo") ?? defaults.repo,
+                    ref: refArg ?? defaults.ref,
+                    deriveRepoFromGit: !noGit,
+                    dryRun,
+                    metadata,
+                    provenanceClient: "uploads-mcp-screenshot",
+                    alt: (p) => alt ?? p.filename,
+                    width,
+                });
+                let gallery;
+                if (galleryIdArg) {
+                    try {
+                        const current = await client.getGallery(galleryIdArg);
+                        await client.addGalleryItem(galleryIdArg, result.key, {
+                            expectedVersion: current.version,
+                            altText: alt ?? prepared.filename,
+                        });
+                        gallery = { id: galleryIdArg, url: current.url };
+                    }
+                    catch (err) {
+                        gallery = {
+                            id: galleryIdArg,
+                            error: err instanceof Error ? err.message : String(err),
+                        };
+                    }
+                }
+                const flat = {
                     ...result,
                     markdown,
-                    optimize,
+                    backend: captured.backend,
+                    optimize: {
+                        optimized: prepared.optimized,
+                        skippedReason: prepared.skippedReason,
+                        originalBytes: prepared.originalBytes,
+                        outputBytes: prepared.outputBytes,
+                        filename: prepared.filename,
+                    },
                     frame: prepared.frame,
+                    gallery,
                     ...(dryRun ? { dryRun: true } : {}),
                 };
+                if (wantComment && target) {
+                    const { comment, commentError } = await syncComment(client, target);
+                    return { ...flat, comment, commentError };
+                }
+                return flat;
             },
         },
         {
             name: "attach",
-            description: "Upload one or more files as stable PR/issue attachments and maintain a single managed GitHub comment listing them. Each upload returns `url`, `embedUrl` (when dual-host applies), and `markdown` (uses embedUrl for GitHub). With no pr/issue, targets the pull request for the current branch. Attachments are public and keys are predictable; upload only non-sensitive media.",
+            description: "Upload one or more files as stable PR/issue attachments (in parallel) and maintain a managed GitHub comment. Returns `uploads` and `failures` (one bad file does not abort the batch). Each success has `url`, `embedUrl`, and `markdown` (prefer embedUrl for GitHub). With no pr/issue, targets the current branch PR. Attachments are public and keys are predictable; upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -523,45 +820,28 @@ export function createUploadsMcpTools(opts) {
                 const metadata = { ...metaExtras, ...ghMetadataFromTarget(target) };
                 if (Object.keys(metadata).length > 0)
                     validateMetaMap(metadata);
-                const uploads = [];
-                for (const file of files) {
-                    const sourceName = basename(file);
-                    const prepared = await prepareImageForUpload(readFileArg(file), sourceName, {
-                        ...frameOpts,
-                        optimize: optimizeOpts,
-                    });
-                    const result = await client.put(prepared.bytes, {
-                        filename: prepared.filename,
-                        key: ghAttachmentKey(target, prepared.filename),
-                        contentType: prepared.optimized ? prepared.contentType : contentType,
-                        provenance: buildCliProvenance({
-                            sourceName,
-                            client: "uploads-mcp",
-                            optimized: prepared.optimized,
-                            frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
-                            keepExif: optimizeOpts.keepExif === true,
-                        }),
-                        metadata,
-                    });
-                    uploads.push({
-                        ...result,
-                        markdown: buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
-                            alt: sourceName,
-                        }),
-                        frame: prepared.frame,
-                        optimize: {
-                            optimized: prepared.optimized,
-                            skippedReason: prepared.skippedReason,
-                            originalBytes: prepared.originalBytes,
-                            outputBytes: prepared.outputBytes,
-                            filename: prepared.filename,
-                        },
+                const { uploads, failures } = await uploadAttachments({
+                    client,
+                    target,
+                    files,
+                    contentType,
+                    optimize: optimizeOpts,
+                    frame: frameOpts,
+                    metadata,
+                    provenanceClient: "uploads-mcp",
+                });
+                // Total failure → isError with full failures[] for agents.
+                if (uploads.length === 0 && failures.length > 0) {
+                    throw new ToolBatchError(batchFailureMessage(failures), {
+                        target,
+                        uploads,
+                        failures,
                     });
                 }
                 if (optBool(args, "noComment"))
-                    return { target, uploads };
+                    return { target, uploads, failures };
                 const { comment, commentError } = await syncComment(client, target);
-                return { target, uploads, comment, commentError };
+                return { target, uploads, failures, comment, commentError };
             },
         },
         {
@@ -628,9 +908,28 @@ export function createUploadsMcpTools(opts) {
                 return client.delete(key);
             },
         },
+        {
+            name: "get_metadata",
+            description: "Read an object's queryable custom metadata (D1 key-value pairs, not R2 provenance). Returns `{ metadata }` (empty when none). Object must exist. Same as `uploads meta get`.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: { type: "string", description: "Object key to inspect." },
+                    workspace: workspaceProp,
+                },
+                required: ["key"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const key = optString(args, "key");
+                if (!key)
+                    usage("key is required");
+                return clientFor(args).client.getMetadata(key);
+            },
+        },
         {
             name: "set_metadata",
-            description: "Merge-set and/or delete an object's queryable custom metadata (D1-backed key-value pairs; distinct from the R2 provenance headers put on upload). `set` pairs win over `delete` when a key appears in both. " +
+            description: "Merge-set and/or delete an object's queryable custom metadata (D1 key-value pairs, not R2 provenance). `set` wins over `delete` for the same key. " +
                 METADATA_DESCRIPTION +
                 " Requires at least one of `set` or `delete`. Same as `uploads meta set`.",
             inputSchema: {

package/dist/screenshot-local.d.ts

@@ -0,0 +1,64 @@
+export type BrowserCandidateSource = "env" | "system" | "playwright-cache" | "puppeteer-cache";
+export interface BrowserCandidate {
+    source: BrowserCandidateSource;
+    /** e.g. "chrome", "chromium", "chromium_headless_shell", "edge". */
+    kind: string;
+    executablePath: string;
+    /** Cache revision/build string, when applicable. */
+    revision?: string;
+}
+export interface DetectRoots {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    playwrightCacheDir?: string;
+    puppeteerCacheDir?: string;
+    /** Injectable for tests: overrides the fixed system-install paths. */
+    systemCandidates?: readonly {
+        kind: string;
+        path: string;
+    }[];
+    /** Injectable for tests: replaces fs.existsSync. */
+    exists?: (path: string) => boolean;
+    /** Injectable for tests: replaces fs.readdirSync. */
+    readdir?: (path: string) => string[];
+}
+export interface DetectResult {
+    /** Explicit --browser / UPLOADS_CHROME_PATH / CHROME_PATH override, if any. */
+    envOverride?: string;
+    candidates: BrowserCandidate[];
+    /** Best candidate by the documented ranking, or undefined if none found. */
+    winner?: BrowserCandidate;
+}
+/**
+ * Scan for a usable local Chromium-family executable. Pure fs/env — never
+ * launches a browser. Roots are injectable so tests can fake a cache layout.
+ */
+export declare function detectLocalBrowser(roots?: DetectRoots): DetectResult;
+export interface LocalCaptureOptions {
+    /** URL to navigate to, or a `file://` URL for local .html targets. */
+    url: string;
+    /** Explicit browser executable (--browser / UPLOADS_CHROME_PATH / CHROME_PATH). */
+    browserPath?: string;
+    /** Attach to a running Chrome instead of launching one. */
+    cdp?: string;
+    viewport: {
+        width: number;
+        height: number;
+        deviceScaleFactor: number;
+    };
+    selector?: string;
+    fullPage?: boolean;
+    colorScheme?: "dark" | "light";
+    /** "load" | "domcontentloaded" | "networkidle", or a millisecond settle delay. */
+    waitUntil: "load" | "domcontentloaded" | "networkidle" | number;
+    timeoutMs?: number;
+    detectRoots?: DetectRoots;
+    /**
+     * Pre-computed detection result from a caller that already scanned the
+     * filesystem (e.g. `auto`-routing's probe) — avoids re-running
+     * `detectLocalBrowser` a second time for the same capture.
+     */
+    detectResult?: DetectResult;
+}
+/** Capture a PNG screenshot using a local (already-installed) browser. */
+export declare function captureLocal(opts: LocalCaptureOptions): Promise<Uint8Array>;