@buildinternet/uploads 0.2.0 → 0.3.0

package/dist/frame.js

@@ -0,0 +1,245 @@
+/**
+ * Optional device/browser frames for put/attach (default off).
+ *
+ * - `phone` / `browser` — procedural (no third-party assets)
+ * - `iphone-16-pro` — fetches frame+mask from device-frames-media once,
+ *   cached under ~/.cache/uploads/frames (not bundled in the npm package)
+ *
+ * @see https://github.com/jonnyjackson26/device-frames-media
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import sharp from "sharp";
+const DEVICE_FRAMES_BASE = "https://raw.githubusercontent.com/jonnyjackson26/device-frames-media/main/device-frames-output";
+export const FRAME_PRESETS = {
+    phone: { kind: "procedural", label: "Generic phone bezel" },
+    browser: { kind: "procedural", label: "Generic browser chrome" },
+    "iphone-16-pro": {
+        kind: "remote",
+        label: "iPhone 16 Pro (community frame art)",
+        assetBase: `${DEVICE_FRAMES_BASE}/Apple%20iPhone/16%20Pro/Black%20Titanium`,
+    },
+};
+export function listFramePresets() {
+    return Object.entries(FRAME_PRESETS).map(([id, p]) => ({
+        id,
+        label: p.label,
+        kind: p.kind,
+    }));
+}
+export function resolveFrameId(raw) {
+    if (!raw?.trim())
+        return undefined;
+    const id = raw.trim().toLowerCase();
+    if (!(id in FRAME_PRESETS)) {
+        throw new Error(`unknown frame "${raw}" (known: ${Object.keys(FRAME_PRESETS).join(", ")})`);
+    }
+    return id;
+}
+function cacheDirDefault() {
+    return join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "uploads", "frames");
+}
+async function cachedFetch(url, cacheDir, fetchImpl) {
+    const name = `${createHash("sha256").update(url).digest("hex").slice(0, 16)}-${url.split("/").pop() ?? "bin"}`;
+    const path = join(cacheDir, name);
+    if (existsSync(path))
+        return readFileSync(path);
+    mkdirSync(cacheDir, { recursive: true });
+    const res = await fetchImpl(url);
+    if (!res.ok)
+        throw new Error(`frame download failed (${res.status}): ${url}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    writeFileSync(path, buf);
+    return buf;
+}
+function scaleRect(r, s) {
+    return {
+        x: Math.round(r.x * s),
+        y: Math.round(r.y * s),
+        width: Math.round(r.width * s),
+        height: Math.round(r.height * s),
+    };
+}
+async function compositeDevice(screenshot, framePng, maskPng, screen, frameSize, fit) {
+    const fitted = await sharp(screenshot)
+        .rotate()
+        .resize(screen.width, screen.height, {
+        fit,
+        position: "centre",
+        background: { r: 0, g: 0, b: 0, alpha: 1 },
+    })
+        .ensureAlpha()
+        .png()
+        .toBuffer();
+    let layer = await sharp({
+        create: {
+            width: frameSize.width,
+            height: frameSize.height,
+            channels: 4,
+            background: { r: 0, g: 0, b: 0, alpha: 0 },
+        },
+    })
+        .composite([{ input: fitted, left: screen.x, top: screen.y }])
+        .png()
+        .toBuffer();
+    if (maskPng) {
+        layer = await sharp(layer)
+            .composite([{ input: maskPng, blend: "dest-in" }])
+            .png()
+            .toBuffer();
+    }
+    return sharp(layer)
+        .composite([{ input: framePng, left: 0, top: 0 }])
+        .png()
+        .toBuffer();
+}
+async function proceduralPhone(screenshot, fit) {
+    const screenW = 390;
+    const screenH = 844;
+    const bezel = 14;
+    const top = 36;
+    const bottom = 18;
+    const outerW = screenW + bezel * 2;
+    const outerH = screenH + top + bottom;
+    const fitted = await sharp(screenshot)
+        .rotate()
+        .resize(screenW, screenH, {
+        fit,
+        position: "centre",
+        background: { r: 0, g: 0, b: 0, alpha: 1 },
+    })
+        .png()
+        .toBuffer();
+    const roundMask = await sharp(Buffer.from(`<svg width="${screenW}" height="${screenH}" xmlns="http://www.w3.org/2000/svg"><rect width="${screenW}" height="${screenH}" rx="36" fill="white"/></svg>`))
+        .png()
+        .toBuffer();
+    const screen = await sharp(fitted)
+        .ensureAlpha()
+        .composite([{ input: roundMask, blend: "dest-in" }])
+        .png()
+        .toBuffer();
+    const shell = await sharp(Buffer.from(`<svg width="${outerW}" height="${outerH}" xmlns="http://www.w3.org/2000/svg">
+        <rect x="1" y="1" width="${outerW - 2}" height="${outerH - 2}" rx="48" fill="#1c1c1e" stroke="#3a3a3c" stroke-width="2"/>
+        <rect x="${bezel + 70}" y="12" width="${screenW - 140}" height="22" rx="11" fill="#0a0a0a"/>
+        <circle cx="${outerW / 2}" cy="${outerH - 10}" r="4" fill="#3a3a3c"/>
+      </svg>`))
+        .png()
+        .toBuffer();
+    return sharp(shell)
+        .composite([{ input: screen, left: bezel, top }])
+        .png()
+        .toBuffer();
+}
+async function proceduralBrowser(screenshot, fit, url) {
+    const chromeH = 72;
+    const pad = 12;
+    const meta = await sharp(screenshot).rotate().metadata();
+    const srcW = meta.width ?? 800;
+    const srcH = meta.height ?? 600;
+    const scale = Math.min(1, 1200 / srcW, 800 / srcH);
+    const contentW = Math.max(320, Math.round(srcW * scale));
+    const contentH = Math.max(200, Math.round(srcH * scale));
+    const outerW = contentW + pad * 2;
+    const outerH = contentH + chromeH + pad;
+    const fitted = await sharp(screenshot)
+        .rotate()
+        .resize(contentW, contentH, {
+        fit,
+        position: "centre",
+        background: { r: 255, g: 255, b: 255, alpha: 1 },
+    })
+        .png()
+        .toBuffer();
+    const safe = url
+        .slice(0, 80)
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+    const chrome = await sharp(Buffer.from(`<svg width="${outerW}" height="${outerH}" xmlns="http://www.w3.org/2000/svg">
+        <rect x="0.5" y="0.5" width="${outerW - 1}" height="${outerH - 1}" rx="12" fill="#f0f0f2" stroke="#c7c7cc"/>
+        <circle cx="22" cy="22" r="6" fill="#ff5f57"/>
+        <circle cx="42" cy="22" r="6" fill="#febc2e"/>
+        <circle cx="62" cy="22" r="6" fill="#28c840"/>
+        <rect x="84" y="12" width="${Math.max(120, outerW - 100)}" height="28" rx="8" fill="#fff" stroke="#d1d1d6"/>
+        <text x="96" y="31" font-family="system-ui,sans-serif" font-size="12" fill="#6e6e73">${safe}</text>
+        <rect x="${pad}" y="${chromeH}" width="${contentW}" height="${contentH}" fill="#fff"/>
+      </svg>`))
+        .png()
+        .toBuffer();
+    return sharp(chrome)
+        .composite([{ input: fitted, left: pad, top: chromeH }])
+        .png()
+        .toBuffer();
+}
+function asPngName(filename) {
+    const base = filename.includes("/") ? filename.slice(filename.lastIndexOf("/") + 1) : filename;
+    const dot = base.lastIndexOf(".");
+    return `${dot >= 0 ? base.slice(0, dot) : base}.png`;
+}
+function skip(bytes, filename, frameId, reason, contentType = "application/octet-stream") {
+    return { bytes, filename, contentType, framed: false, frameId, skippedReason: reason };
+}
+/** Apply a named frame. Non-images pass through. Output PNG for the optimize step. */
+export async function applyFrame(bytes, filename, opts) {
+    const id = opts.id.toLowerCase();
+    const preset = FRAME_PRESETS[id];
+    if (!preset)
+        throw new Error(`unknown frame "${opts.id}"`);
+    try {
+        const meta = await sharp(bytes, { failOn: "none" }).metadata();
+        if (!meta.format || meta.format === "svg")
+            return skip(bytes, filename, id, "not_image");
+        if ((meta.pages ?? 1) > 1) {
+            return skip(bytes, filename, id, "animated", meta.format === "gif" ? "image/gif" : "image/webp");
+        }
+    }
+    catch {
+        return skip(bytes, filename, id, "not_image");
+    }
+    const fit = opts.fit ?? "cover";
+    let out;
+    if (preset.kind === "procedural") {
+        out =
+            id === "browser"
+                ? await proceduralBrowser(bytes, fit, opts.browserUrl ?? "https://app.example")
+                : await proceduralPhone(bytes, fit);
+    }
+    else {
+        const fetchImpl = opts.fetchImpl ?? fetch;
+        const cacheDir = opts.cacheDir ?? cacheDirDefault();
+        const tpl = JSON.parse((await cachedFetch(`${preset.assetBase}/template.json`, cacheDir, fetchImpl)).toString("utf8"));
+        const framePng = await cachedFetch(`${preset.assetBase}/frame.png`, cacheDir, fetchImpl);
+        let maskPng;
+        try {
+            maskPng = await cachedFetch(`${preset.assetBase}/mask.png`, cacheDir, fetchImpl);
+        }
+        catch {
+            /* optional */
+        }
+        // Keep remote frames light for PR embeds (display width is capped separately).
+        const maxEdge = 1000;
+        const s = Math.min(1, maxEdge / Math.max(tpl.frameSize.width, tpl.frameSize.height));
+        const frameSize = {
+            width: Math.round(tpl.frameSize.width * s),
+            height: Math.round(tpl.frameSize.height * s),
+        };
+        const screen = scaleRect(tpl.screen, s);
+        const frame = s < 1
+            ? await sharp(framePng).resize(frameSize.width, frameSize.height).png().toBuffer()
+            : framePng;
+        const mask = maskPng && s < 1
+            ? await sharp(maskPng).resize(frameSize.width, frameSize.height).png().toBuffer()
+            : maskPng;
+        out = await compositeDevice(bytes, frame, mask, screen, frameSize, fit);
+    }
+    return {
+        bytes: new Uint8Array(out),
+        filename: asPngName(filename),
+        contentType: "image/png",
+        framed: true,
+        frameId: id,
+    };
+}

package/dist/github.d.ts

@@ -21,4 +21,15 @@ export interface AttachmentItem {
     key: string;
     url: string | null;
 }
+/** Default max width for images in the managed attachments comment (HTML img). */
+export declare const ATTACHMENT_IMAGE_WIDTH_DEFAULT = 400;
+/** Portrait / device mockups — keep phones readable, not full-column. */
+export declare const ATTACHMENT_IMAGE_WIDTH_PORTRAIT = 280;
+/** Wide UI / browser chrome. */
+export declare const ATTACHMENT_IMAGE_WIDTH_WIDE = 640;
+/**
+ * Pick a display width for GitHub comment embeds. Filenames are a weak but
+ * practical signal (we don't re-fetch dimensions when rebuilding the comment).
+ */
+export declare function attachmentImageWidth(filename: string): number;
 export declare function attachmentsCommentBody(items: AttachmentItem[]): string;

package/dist/github.js

@@ -24,13 +24,43 @@ export function ghAttachmentKey(target, filename) {
 }
 /** Hidden marker identifying the one comment this CLI manages. Never change it — existing comments are found by exact match. */
 export const ATTACHMENTS_MARKER = "<!-- uploads.sh:attachments -->";
+/** Default max width for images in the managed attachments comment (HTML img). */
+export const ATTACHMENT_IMAGE_WIDTH_DEFAULT = 400;
+/** Portrait / device mockups — keep phones readable, not full-column. */
+export const ATTACHMENT_IMAGE_WIDTH_PORTRAIT = 280;
+/** Wide UI / browser chrome. */
+export const ATTACHMENT_IMAGE_WIDTH_WIDE = 640;
+/**
+ * Pick a display width for GitHub comment embeds. Filenames are a weak but
+ * practical signal (we don't re-fetch dimensions when rebuilding the comment).
+ */
+export function attachmentImageWidth(filename) {
+    const n = filename.toLowerCase();
+    if (/(?:^|[-_.])(browser|desktop|dashboard|wide)(?:[-_.]|$)/.test(n)) {
+        return ATTACHMENT_IMAGE_WIDTH_WIDE;
+    }
+    if (/(?:^|[-_.])(phone|iphone|ipad|pixel|android|mobile|device)(?:[-_.]|$)/.test(n) ||
+        /iphone|pixel-?\d/.test(n)) {
+        return ATTACHMENT_IMAGE_WIDTH_PORTRAIT;
+    }
+    return ATTACHMENT_IMAGE_WIDTH_DEFAULT;
+}
+function escapeHtmlAttr(s) {
+    return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
 export function attachmentsCommentBody(items) {
     const sorted = items.toSorted((a, b) => a.key.localeCompare(b.key));
     const lines = [ATTACHMENTS_MARKER, "### 📎 Attachments", ""];
     for (const item of sorted) {
         const name = item.key.slice(item.key.lastIndexOf("/") + 1);
         if (item.url && inferContentType(name).startsWith("image/")) {
-            lines.push(`![${name}](${item.url})`);
+            // Markdown ![]() has no width control — phone frames become full-column giants.
+            // Link to the asset so a click opens the full image (no "open in new tab" hunt).
+            const w = attachmentImageWidth(name);
+            const alt = escapeHtmlAttr(name);
+            const href = escapeHtmlAttr(item.url);
+            lines.push(`<a href="${href}"><img width="${w}" alt="${alt}" src="${href}"></a>`);
+            lines.push("");
         }
         else if (item.url) {
             lines.push(`- [${name}](${item.url})`);
@@ -39,6 +69,6 @@ export function attachmentsCommentBody(items) {
             lines.push(`- ${name}`);
         }
     }
-    lines.push("", "<sub>Maintained by uploads.sh — re-uploading a file with the same name updates it everywhere it is embedded.</sub>");
+    lines.push('<sub>Maintained by <a href="https://uploads.sh">uploads.sh</a> — re-uploading a file with the same name updates it everywhere it is embedded.</sub>');
     return lines.join("\n");
 }

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 export { inferContentType, buildMarkdown } from "./embed.js";
 export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey } from "./keys.js";
+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 { createUploadsClient, type UploadsClient, type PutOptions, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, } from "./client.js";
 export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, isValidRepo, parseRepoFromRemoteUrl, type AttachmentItem, type GhTarget, type GhTargetKind, } from "./github.js";
+export { DEFAULT_OPTIMIZE_MAX_EDGE, DEFAULT_OPTIMIZE_QUALITY, optimizeImageForUpload, rewriteKeyExtension, withImageExtension, type OptimizeImageOptions, type OptimizeImageResult, type OptimizeOutputFormat, } from "./optimize.js";
+export { FRAME_PRESETS, applyFrame, listFramePresets, resolveFrameId, type FrameFit, type FrameOptions, type FrameResult, } from "./frame.js";
 export { execRunner, resolveRepo, upsertAttachmentsComment, type CommandRunner, } from "./github-gh.js";

package/dist/index.js

@@ -1,7 +1,10 @@
 export { inferContentType, buildMarkdown } from "./embed.js";
 export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey } from "./keys.js";
+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 { createUploadsClient, } from "./client.js";
 export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
+export { DEFAULT_OPTIMIZE_MAX_EDGE, DEFAULT_OPTIMIZE_QUALITY, optimizeImageForUpload, rewriteKeyExtension, withImageExtension, } from "./optimize.js";
+export { FRAME_PRESETS, applyFrame, listFramePresets, resolveFrameId, } from "./frame.js";
 export { execRunner, resolveRepo, upsertAttachmentsComment, } from "./github-gh.js";

package/dist/mcp/tools.js

@@ -8,10 +8,13 @@
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, makeGhTarget, syncAttachmentsComment } from "../commands.js";
+import { buildDoctorReport, makeGhTarget, prepareImageForUpload, syncAttachmentsComment, } from "../commands.js";
+import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { buildMarkdown } from "../embed.js";
+import { resolvePutPrefix } from "../destinations.js";
 import { ghAttachmentKey, ghKeyPrefix } from "../github.js";
+import { rewriteKeyExtension } from "../optimize.js";
 import { execRunner, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
 import { optPosInt, optString, usage } from "./args.js";
 function optBool(args, name) {
@@ -31,6 +34,55 @@ function optStringArray(args, name) {
     }
     return v;
 }
+function mcpOptimizeOptions(args, defaults) {
+    const quality = optPosInt(args, "optimizeQuality");
+    if (quality !== undefined && quality > 100)
+        usage("optimizeQuality must be 1–100");
+    return {
+        enabled: !(optBool(args, "noOptimize") || defaults.noOptimize === true),
+        maxEdge: optPosInt(args, "optimizeMaxEdge"),
+        quality,
+        keepExif: optBool(args, "keepExif") || defaults.keepExif === true,
+    };
+}
+function mcpFrameOptions(args) {
+    const raw = optString(args, "frame");
+    let frameId;
+    try {
+        frameId = resolveFrameId(raw);
+    }
+    catch (err) {
+        usage(err instanceof Error ? err.message : String(err));
+    }
+    const fitRaw = optString(args, "frameFit");
+    let frameFit;
+    if (fitRaw) {
+        if (fitRaw !== "cover" && fitRaw !== "contain") {
+            usage("frameFit must be cover or contain");
+        }
+        frameFit = fitRaw;
+    }
+    if (frameFit && !frameId)
+        usage("frameFit requires frame");
+    const frameUrl = optString(args, "frameUrl");
+    if (frameUrl && !frameId)
+        usage("frameUrl requires frame");
+    return { frameId, frameUrl, frameFit };
+}
+const frameProps = {
+    frame: {
+        type: "string",
+        description: "Optional frame before optimize: phone | browser | iphone-16-pro.",
+    },
+    frameUrl: {
+        type: "string",
+        description: "Address bar text for frame=browser.",
+    },
+    frameFit: {
+        type: "string",
+        description: "cover (default) or contain.",
+    },
+};
 /** Reads pr/issue (+ repo) into a GhTarget; undefined when neither is present. */
 function ghTargetFromArgs(args, run) {
     return makeGhTarget(optPosInt(args, "pr"), optPosInt(args, "issue"), optString(args, "repo"), run);
@@ -105,6 +157,10 @@ export function createUploadsMcpTools(opts) {
                         type: "string",
                         description: "Explicit object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>). Cannot be combined with pr/issue.",
                     },
+                    destination: {
+                        type: "string",
+                        description: "Typed destination root: screenshots | gh | f. Sets the key prefix; first-class alternative to prefix. With pr/issue must be gh or omitted.",
+                    },
                     prefix: {
                         type: "string",
                         description: "Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX). Cannot be combined with pr/issue.",
@@ -124,7 +180,27 @@ export function createUploadsMcpTools(opts) {
                         type: "number",
                         description: "Emit <img width=…> markdown instead of a plain image embed.",
                     },
-                    contentType: { type: "string", description: "Override the Content-Type." },
+                    contentType: {
+                        type: "string",
+                        description: "Override the Content-Type (ignored when optimize rewrites the body).",
+                    },
+                    noOptimize: {
+                        type: "boolean",
+                        description: "Skip client-side image optimization (default: optimize still images to WebP).",
+                    },
+                    optimizeMaxEdge: {
+                        type: "number",
+                        description: "Max long edge in pixels when optimizing (default: 2400).",
+                    },
+                    optimizeQuality: {
+                        type: "number",
+                        description: "WebP quality 1–100 when optimizing (default: 85).",
+                    },
+                    keepExif: {
+                        type: "boolean",
+                        description: "Keep EXIF/XMP/ICC when optimizing (default: strip for privacy on public embeds).",
+                    },
+                    ...frameProps,
                     noGit: { type: "boolean", description: "Don't derive the repo segment from git." },
                     comment: {
                         type: "boolean",
@@ -146,44 +222,72 @@ export function createUploadsMcpTools(opts) {
                 }
                 const target = ghTargetFromArgs(args, run);
                 const wantComment = optBool(args, "comment");
-                const key = optString(args, "key");
+                const keyArg = optString(args, "key");
+                const destArg = optString(args, "destination");
                 const prefixArg = optString(args, "prefix");
                 const refArg = optString(args, "ref");
                 if (wantComment && !target)
                     usage("comment requires pr or issue");
                 if (target) {
-                    if (key)
+                    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");
                 }
+                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 { client } = clientFor(args);
                 const bytes = file !== undefined
                     ? new Uint8Array(readFileSync(file))
                     : new Uint8Array(Buffer.from(contentBase64, "base64"));
-                const filename = file !== undefined ? (filenameArg ?? basename(file)) : filenameArg;
+                const sourceName = file !== undefined ? (filenameArg ?? basename(file)) : filenameArg;
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
+                const prepared = await prepareImageForUpload(bytes, sourceName, {
+                    ...mcpFrameOptions(args),
+                    optimize: mcpOptimizeOptions(args, defaults),
+                });
+                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(bytes, {
+                const result = await client.put(prepared.bytes, {
                     filename,
-                    key: target ? ghAttachmentKey(target, filename) : key,
-                    prefix: prefixArg ?? defaults.prefix,
+                    key,
+                    prefix: resolvedPrefix ?? defaults.prefix,
                     repo: optString(args, "repo") ?? defaults.repo,
                     ref: refArg ?? defaults.ref,
-                    contentType: optString(args, "contentType"),
+                    contentType: prepared.optimized ? prepared.contentType : optString(args, "contentType"),
                     deriveRepoFromGit: !noGit,
                 });
                 const markdown = buildMarkdown(result.url, {
-                    alt: optString(args, "alt") ?? filename,
+                    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 (wantComment && target) {
                     const { comment, commentError } = await syncComment(client, target);
-                    return { ...result, markdown, comment, commentError };
+                    return { ...result, markdown, optimize, frame: prepared.frame, comment, commentError };
                 }
-                return { ...result, markdown };
+                return { ...result, markdown, optimize, frame: prepared.frame };
             },
         },
         {
@@ -204,8 +308,25 @@ export function createUploadsMcpTools(opts) {
                     },
                     contentType: {
                         type: "string",
-                        description: "Override the Content-Type (applied to every file).",
+                        description: "Override the Content-Type (applied to every file; ignored when optimize rewrites).",
+                    },
+                    noOptimize: {
+                        type: "boolean",
+                        description: "Skip client-side image optimization (default: optimize still images to WebP).",
+                    },
+                    optimizeMaxEdge: {
+                        type: "number",
+                        description: "Max long edge in pixels when optimizing (default: 2400).",
+                    },
+                    optimizeQuality: {
+                        type: "number",
+                        description: "WebP quality 1–100 when optimizing (default: 85).",
                     },
+                    keepExif: {
+                        type: "boolean",
+                        description: "Keep EXIF/XMP/ICC when optimizing (default: strip for privacy on public embeds).",
+                    },
+                    ...frameProps,
                     workspace: workspaceProp,
                 },
                 required: ["files"],
@@ -220,15 +341,30 @@ export function createUploadsMcpTools(opts) {
                     resolveCurrentPullRequest(resolveRepo(optString(args, "repo"), run), run);
                 const { client } = clientFor(args);
                 const contentType = optString(args, "contentType");
+                const defaults = resolvePutDefaults({ envFile: globals.envFile });
+                const frameOpts = mcpFrameOptions(args);
+                const optimizeOpts = mcpOptimizeOptions(args, defaults);
                 const uploads = [];
                 for (const file of files) {
-                    const filename = basename(file);
-                    const result = await client.put(new Uint8Array(readFileSync(file)), {
-                        filename,
-                        key: ghAttachmentKey(target, filename),
-                        contentType,
+                    const sourceName = basename(file);
+                    const prepared = await prepareImageForUpload(new Uint8Array(readFileSync(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,
+                    });
+                    uploads.push({
+                        ...result,
+                        markdown: buildMarkdown(result.url, { alt: sourceName }),
+                        frame: prepared.frame,
+                        optimize: {
+                            optimized: prepared.optimized,
+                            skippedReason: prepared.skippedReason,
+                            originalBytes: prepared.originalBytes,
+                            outputBytes: prepared.outputBytes,
+                            filename: prepared.filename,
+                        },
                     });
-                    uploads.push({ ...result, markdown: buildMarkdown(result.url, { alt: filename }) });
                 }
                 if (optBool(args, "noComment"))
                     return { target, uploads };

package/dist/optimize.d.ts

@@ -0,0 +1,38 @@
+/** Longest edge in pixels (screenshots beyond this rarely help PR review). */
+export declare const DEFAULT_OPTIMIZE_MAX_EDGE = 2400;
+/** WebP quality tuned for UI screenshots (text/chrome stay sharp enough). */
+export declare const DEFAULT_OPTIMIZE_QUALITY = 85;
+export type OptimizeOutputFormat = "webp" | "jpeg";
+export interface OptimizeImageOptions {
+    /** When false, returns the input unchanged. Default true. */
+    enabled?: boolean;
+    format?: OptimizeOutputFormat;
+    maxEdge?: number;
+    quality?: number;
+    /**
+     * When true, preserve EXIF/XMP/ICC (and related) from the input via sharp
+     * `withMetadata()`. Default false — strip for privacy and smaller embeds.
+     * Orientation is still applied so pixels match what the user saw.
+     */
+    keepExif?: boolean;
+}
+export interface OptimizeImageResult {
+    bytes: Uint8Array;
+    filename: string;
+    /** Suggested Content-Type for the body (API still sniffs magic bytes). */
+    contentType: string;
+    optimized: boolean;
+    /** Why bytes were left as-is when optimized is false. */
+    skippedReason?: string;
+    originalBytes: number;
+    outputBytes: number;
+}
+/** Replace a trailing image-looking extension, or append when missing. */
+export declare function withImageExtension(name: string, ext: string): string;
+/**
+ * Optimize still images for public embeds. Safe to call on any payload:
+ * non-images and unsupported types pass through.
+ */
+export declare function optimizeImageForUpload(bytes: Uint8Array, filename: string, opts?: OptimizeImageOptions): Promise<OptimizeImageResult>;
+/** Rewrite an object key's trailing image extension to match optimized output. */
+export declare function rewriteKeyExtension(key: string, filename: string): string;