@buildinternet/uploads 0.2.0 → 0.4.0

package/dist/mcp/tools.js

@@ -8,10 +8,14 @@
 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 { buildCliProvenance } from "../provenance.js";
 import { execRunner, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
 import { optPosInt, optString, usage } from "./args.js";
 function optBool(args, name) {
@@ -31,6 +35,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 +158,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 +181,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 +223,81 @@ 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 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(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,
+                    provenance: buildCliProvenance({
+                        sourceName,
+                        client: "uploads-mcp",
+                        optimized: prepared.optimized,
+                        frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
+                        keepExif: optimizeOpts.keepExif === true,
+                    }),
                 });
                 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 +318,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 +351,37 @@ 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,
+                        provenance: buildCliProvenance({
+                            sourceName,
+                            client: "uploads-mcp",
+                            optimized: prepared.optimized,
+                            frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
+                            keepExif: optimizeOpts.keepExif === true,
+                        }),
+                    });
+                    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;

package/dist/optimize.js

@@ -0,0 +1,177 @@
+/**
+ * Client-side still-image optimization for put/attach.
+ *
+ * Default path for GitHub embeds: re-encode PNG/JPEG (and similar) to WebP,
+ * cap the long edge, keep the smaller of original vs optimized. Animated GIF,
+ * SVG, video, and non-images are left unchanged.
+ */
+import sharp from "sharp";
+/** Longest edge in pixels (screenshots beyond this rarely help PR review). */
+export const DEFAULT_OPTIMIZE_MAX_EDGE = 2400;
+/** WebP quality tuned for UI screenshots (text/chrome stay sharp enough). */
+export const DEFAULT_OPTIMIZE_QUALITY = 85;
+const IMAGE_EXT = new Set([
+    "png",
+    "jpg",
+    "jpeg",
+    "webp",
+    "gif",
+    "tif",
+    "tiff",
+    "avif",
+    "heic",
+    "heif",
+]);
+function extensionOf(name) {
+    const base = name.includes("/") ? name.slice(name.lastIndexOf("/") + 1) : name;
+    const dot = base.lastIndexOf(".");
+    return dot >= 0 ? base.slice(dot + 1).toLowerCase() : "";
+}
+/** Replace a trailing image-looking extension, or append when missing. */
+export function withImageExtension(name, ext) {
+    const clean = ext.replace(/^\./, "").toLowerCase();
+    const slash = name.lastIndexOf("/");
+    const dir = slash >= 0 ? name.slice(0, slash + 1) : "";
+    const base = slash >= 0 ? name.slice(slash + 1) : name;
+    const dot = base.lastIndexOf(".");
+    if (dot >= 0 && IMAGE_EXT.has(base.slice(dot + 1).toLowerCase())) {
+        return `${dir}${base.slice(0, dot)}.${clean}`;
+    }
+    return `${dir}${base}.${clean}`;
+}
+function contentTypeForFormat(format) {
+    return format === "jpeg" ? "image/jpeg" : "image/webp";
+}
+function looksLikeSvg(bytes, filename) {
+    if (extensionOf(filename) === "svg")
+        return true;
+    const head = new TextDecoder("utf-8", { fatal: false })
+        .decode(bytes.subarray(0, Math.min(bytes.length, 256)))
+        .trimStart()
+        .toLowerCase();
+    return head.startsWith("<?xml") || head.startsWith("<svg");
+}
+function passthrough(bytes, filename, contentType, skippedReason) {
+    return {
+        bytes,
+        filename,
+        contentType,
+        optimized: false,
+        skippedReason,
+        originalBytes: bytes.byteLength,
+        outputBytes: bytes.byteLength,
+    };
+}
+/**
+ * Optimize still images for public embeds. Safe to call on any payload:
+ * non-images and unsupported types pass through.
+ */
+export async function optimizeImageForUpload(bytes, filename, opts = {}) {
+    const originalBytes = bytes.byteLength;
+    if (opts.enabled === false) {
+        return passthrough(bytes, filename, guessContentType(filename), "disabled");
+    }
+    if (originalBytes === 0) {
+        return passthrough(bytes, filename, guessContentType(filename), "empty");
+    }
+    if (looksLikeSvg(bytes, filename)) {
+        return passthrough(bytes, filename, "image/svg+xml", "svg");
+    }
+    const format = opts.format ?? "webp";
+    const maxEdge = opts.maxEdge ?? DEFAULT_OPTIMIZE_MAX_EDGE;
+    const quality = opts.quality ?? DEFAULT_OPTIMIZE_QUALITY;
+    if (!Number.isFinite(maxEdge) || maxEdge < 1) {
+        throw new Error(`optimize maxEdge must be a positive number (got ${maxEdge})`);
+    }
+    if (!Number.isFinite(quality) || quality < 1 || quality > 100) {
+        throw new Error(`optimize quality must be 1–100 (got ${quality})`);
+    }
+    let image = sharp(bytes, { animated: true, failOn: "none" });
+    let meta;
+    try {
+        meta = await image.metadata();
+    }
+    catch {
+        return passthrough(bytes, filename, guessContentType(filename), "not_image");
+    }
+    if (!meta.format) {
+        return passthrough(bytes, filename, guessContentType(filename), "not_image");
+    }
+    // Animated GIF/WebP: keep as-is (re-encoding often breaks or balloons size).
+    if ((meta.pages ?? 1) > 1) {
+        return passthrough(bytes, filename, meta.format === "gif" ? "image/gif" : guessContentType(filename), "animated");
+    }
+    if (meta.format === "gif") {
+        // Single-frame GIF can convert; multi-page already returned above.
+    }
+    const width = meta.width ?? 0;
+    const height = meta.height ?? 0;
+    if (width > 0 && height > 0) {
+        const longEdge = Math.max(width, height);
+        if (longEdge > maxEdge) {
+            image = image.resize({
+                width: width >= height ? maxEdge : undefined,
+                height: height > width ? maxEdge : undefined,
+                fit: "inside",
+                withoutEnlargement: true,
+            });
+        }
+    }
+    // Apply EXIF orientation so stored pixels match what users saw.
+    image = image.rotate();
+    // Default: strip metadata (privacy + size). Opt in to keep EXIF/etc. for
+    // cases where image metadata is part of the discussion (e.g. photo forensics).
+    if (opts.keepExif) {
+        image = image.withMetadata();
+    }
+    let encoded;
+    try {
+        if (format === "jpeg") {
+            encoded = await image.jpeg({ quality, mozjpeg: true }).toBuffer();
+        }
+        else {
+            encoded = await image.webp({ quality, effort: 4 }).toBuffer();
+        }
+    }
+    catch {
+        return passthrough(bytes, filename, guessContentType(filename), "encode_failed");
+    }
+    if (encoded.byteLength >= originalBytes) {
+        return passthrough(bytes, filename, guessContentType(filename), "not_smaller");
+    }
+    const outFilename = withImageExtension(filename, format === "jpeg" ? "jpg" : "webp");
+    return {
+        bytes: new Uint8Array(encoded),
+        filename: outFilename,
+        contentType: contentTypeForFormat(format),
+        optimized: true,
+        originalBytes,
+        outputBytes: encoded.byteLength,
+    };
+}
+function guessContentType(filename) {
+    switch (extensionOf(filename)) {
+        case "png":
+            return "image/png";
+        case "jpg":
+        case "jpeg":
+            return "image/jpeg";
+        case "gif":
+            return "image/gif";
+        case "webp":
+            return "image/webp";
+        case "avif":
+            return "image/avif";
+        case "svg":
+            return "image/svg+xml";
+        default:
+            return "application/octet-stream";
+    }
+}
+/** Rewrite an object key's trailing image extension to match optimized output. */
+export function rewriteKeyExtension(key, filename) {
+    const ext = extensionOf(filename);
+    if (!ext || !IMAGE_EXT.has(ext))
+        return key;
+    return withImageExtension(key, ext);
+}

package/dist/provenance.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Client-side provenance headers for put (X-Uploads-Meta-*).
+ * API allowlists keys; secrets never go here.
+ */
+import type { ProvenanceInput } from "./client.js";
+export declare function buildCliProvenance(opts: {
+    sourceName: string;
+    optimized?: boolean;
+    frameId?: string;
+    keepExif?: boolean;
+    client?: string;
+}): ProvenanceInput;

package/dist/provenance.js

@@ -0,0 +1,29 @@
+import { createRequire } from "node:module";
+let cachedVersion;
+function packageVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require("../package.json");
+        cachedVersion = pkg.version ?? "0.0.0";
+    }
+    catch {
+        cachedVersion = "0.0.0";
+    }
+    return cachedVersion;
+}
+export function buildCliProvenance(opts) {
+    const provenance = {
+        client: opts.client ?? "uploads-cli",
+        "client-version": packageVersion(),
+        "source-name": opts.sourceName.slice(0, 128),
+    };
+    if (opts.optimized)
+        provenance.optimized = "1";
+    if (opts.frameId)
+        provenance.frame = opts.frameId.slice(0, 64);
+    if (opts.keepExif)
+        provenance["keep-exif"] = "1";
+    return provenance;
+}

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
+  "sideEffects": false,
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -54,6 +55,9 @@
     "access": "public",
     "provenance": true
   },
+  "dependencies": {
+    "sharp": "^0.35.3"
+  },
   "scripts": {
     "test": "vitest run",
     "typecheck": "tsc --noEmit && tsc --noEmit -p test",