@buildinternet/uploads 0.2.0 → 0.4.0

package/README.md

@@ -1,12 +1,10 @@
 # @buildinternet/uploads
 
-CLI and client for **uploads.sh** — upload files, get public URLs, and produce GitHub-ready markdown. Successor to the R2 scripts in `buildinternet-skills/github-screenshots`.
+CLI and client for **uploads.sh** — upload files, get public URLs, and produce GitHub-ready markdown.
 
 ## CLI
 
-Binary: `uploads` (also `pnpm uploads` from repo root after `pnpm install`).
-
-Install globally or run a pinned version without installing:
+Binary: **`uploads`**. Install globally (or use a pinned `npx` one-shot):
 
 ```bash
 npm install --global @buildinternet/uploads
@@ -14,13 +12,21 @@ npx @buildinternet/uploads@0.1.0 --help
 ```
 
 ```bash
-pnpm uploads setup --env-file .env
-pnpm uploads attach ./before.png ./after.png --env-file .env
-pnpm uploads put ./shot.png --env-file .env
-pnpm uploads put ./after.png --pr 123 --comment --env-file .env
-pnpm uploads doctor --env-file .env
+uploads setup
+uploads attach ./before.png ./after.png
+uploads put ./shot.png
+uploads put ./shot.png --destination screenshots
+uploads put ./shot.png --no-optimize
+uploads put ./mobile.png --frame phone
+uploads put ./ui.png --frame browser --frame-url "https://app.example"
+uploads put ./after.png --pr 123 --comment
+uploads doctor
 ```
 
+Inside this monorepo only, `pnpm uploads …` builds the package first so you pick
+up local source; product docs and PR “how to try it” examples should use the
+global `uploads` form above.
+
 Commands: `attach`, `put`, `comment`, `list`, `delete`, `usage`, `reconcile`,
 `purge-expired`, `setup`, `install`, `config`, `doctor`, `health`, `mcp`.
 
@@ -29,6 +35,21 @@ infers the pull request for the current branch via `gh`, uploads stable URLs, an
 or updates one managed attachments comment. Use `--pr`, `--issue`, and `--repo` to select
 the target explicitly, or `--no-comment` to upload without changing GitHub comments.
 
+**Keys / destinations:** default put uses the `screenshots` layout. Typed destinations
+(`--destination screenshots|gh|f`, MCP `destination`) set the root; `--pr`/`--issue`
+use `gh/…`. Workspaces may restrict put/sign to those roots via
+`allowedKeyPrefixes` (see [workspaces](../../docs/workspaces.md)).
+
+**Image optimization:** by default, still images are re-encoded to WebP (long edge
+capped, high quality) before upload so GitHub embeds stay small, and **EXIF is
+stripped**. Pass `--keep-exif` / `UPLOADS_KEEP_EXIF=1` to preserve image metadata, or
+`--no-optimize` / `UPLOADS_NO_OPTIMIZE=1` to upload originals unchanged.
+
+**Frames (opt-in):** `--frame phone|browser|iphone-16-pro` composites chrome
+**before** optimize. `phone`/`browser` are procedural; `iphone-16-pro` fetches
+community art from [device-frames-media](https://github.com/jonnyjackson26/device-frames-media)
+into `~/.cache/uploads/frames` (not bundled).
+
 Config layers (first match wins): CLI flags → env vars → `--env-file` → `~/.config/buildinternet/config`. See `config.example` for keys.
 
 ## MCP server

package/dist/cli.js

@@ -19,7 +19,7 @@ Config (first match wins, per key):
   environment         UPLOADS_API_URL, UPLOADS_TOKEN, UPLOADS_WORKSPACE
   --env-file <path>
   $BUILDINTERNET_CONFIG
-  ~/.config/buildinternet/config   (shared with github-screenshots)
+  ~/.config/buildinternet/config
 
 Workspace (within config layers):
   --workspace, -w     override — global (before command) or per-command (after)
@@ -94,6 +94,7 @@ function exitCode(err) {
                 return 2;
             case "UNAUTHORIZED":
             case "NOT_FOUND":
+            case "KEY_POLICY":
             case "STORAGE_QUOTA":
             case "UPLOAD_BUDGET":
                 return 3;
@@ -119,6 +120,17 @@ function errorOut(err, json) {
             process.stderr.write(`${msg}\n`);
         else
             process.stderr.write(`error: ${msg}\n`);
+        if (err instanceof UploadsError) {
+            if (err.code === "STORAGE_QUOTA" || err.code === "UPLOAD_BUDGET") {
+                process.stderr.write("hint: run `uploads usage` then delete objects or raise limits (`pnpm workspace:limits`)\n");
+            }
+            else if (err.code === "KEY_POLICY") {
+                process.stderr.write("hint: use a typed destination (`--destination screenshots|gh`) or an allowed prefix; operators set allowlists with `pnpm workspace:limits --allowed-prefixes`\n");
+            }
+            else if (err.status === 413 || err.message.toLowerCase().includes("too large")) {
+                process.stderr.write("hint: file exceeds workspace size policy (images vs video may differ); compress or raise --max-upload-bytes / --max-video-bytes\n");
+            }
+        }
     }
 }
 export async function runCli(argv) {

package/dist/client.d.ts

@@ -1,4 +1,13 @@
 import type { UploadsClientConfig } from "./config.js";
+/** Allowlisted object provenance (maps to X-Uploads-Meta-* on put). */
+export type ProvenanceInput = {
+    client?: string;
+    "client-version"?: string;
+    "source-name"?: string;
+    optimized?: "0" | "1";
+    frame?: string;
+    "keep-exif"?: "0" | "1";
+};
 export interface PutOptions {
     key?: string;
     contentType?: string;
@@ -6,6 +15,8 @@ export interface PutOptions {
     repo?: string;
     ref?: string;
     deriveRepoFromGit?: boolean;
+    /** Stored as R2 custom metadata; echoed on put/head. */
+    provenance?: ProvenanceInput;
 }
 export interface ListOptions {
     prefix?: string;
@@ -18,6 +29,7 @@ export interface PutResult {
     url: string;
     size: number;
     contentType: string;
+    metadata?: Record<string, string>;
 }
 export interface ListItem {
     key: string;
@@ -35,6 +47,7 @@ export interface HeadResult {
     size: number;
     contentType: string;
     uploaded?: string;
+    metadata?: Record<string, string>;
 }
 export interface DeleteResult {
     key: string;

package/dist/client.js

@@ -47,6 +47,9 @@ function mapApiError(status, error, code) {
     if (status === 400 && normalized === "invalid key") {
         return new UploadsError(error, "INVALID_KEY", status);
     }
+    if (code === "key_prefix_not_allowed" || code === "key_too_deep") {
+        return new UploadsError(error, "KEY_POLICY", status);
+    }
     // Prefer stable body.code — bare 429 is also used for write rate limits.
     if (status === 507 || code === "storage_quota_exceeded") {
         return new UploadsError(error, "STORAGE_QUOTA", status);
@@ -114,9 +117,16 @@ export function createUploadsClient(config) {
                     deriveRepoFromGit: opts.deriveRepoFromGit,
                 }));
             const contentType = opts.contentType ?? inferContentType(opts.filename);
+            const headers = { "Content-Type": contentType };
+            if (opts.provenance) {
+                for (const [k, v] of Object.entries(opts.provenance)) {
+                    if (v !== undefined && v !== "")
+                        headers[`X-Uploads-Meta-${k}`] = v;
+                }
+            }
             const result = await request("PUT", `${filesBase(config)}/${encodeKeyPath(key)}`, {
                 body,
-                headers: { "Content-Type": contentType },
+                headers,
             });
             if (result.url == null) {
                 throw new UploadsError("upload succeeded but workspace has no publicBaseUrl", "NO_PUBLIC_URL", 201);

package/dist/commands.d.ts

@@ -1,7 +1,11 @@
 import { type UploadsClient } from "./client.js";
+import { type CommandFlags } from "./cli-args.js";
 import { type ResolvedConfig } from "./config.js";
 import { type GhTarget } from "./github.js";
 import { type CommandRunner } from "./github-gh.js";
+import { type OptimizeImageOptions, type OptimizeImageResult } from "./optimize.js";
+import { type FrameResult } from "./frame.js";
+import type { PutDefaults } from "./config-file.js";
 export interface CliContext {
     config: ResolvedConfig;
     client: UploadsClient;
@@ -14,6 +18,18 @@ export interface CliContext {
  * neither is present. Shared by the CLI flags and the MCP tool arguments.
  */
 export declare function makeGhTarget(pr: number | undefined, issue: number | undefined, repoArg: string | undefined, run: CommandRunner): GhTarget | undefined;
+/** Shared put/attach optimize flags + UPLOADS_NO_OPTIMIZE default. */
+export declare function optimizeOptionsFromFlags(flags: CommandFlags["flags"], defaults: PutDefaults): OptimizeImageOptions;
+export type PreparedUpload = OptimizeImageResult & {
+    frame?: Pick<FrameResult, "framed" | "frameId" | "skippedReason">;
+};
+/** Frame (optional) then optimize — shared by put/attach/MCP. */
+export declare function prepareImageForUpload(bytes: Uint8Array, filename: string, opts: {
+    frameId?: string;
+    frameUrl?: string;
+    frameFit?: "cover" | "contain";
+    optimize: OptimizeImageOptions;
+}): Promise<PreparedUpload>;
 /**
  * List every attachment under the target's prefix and create/update the
  * managed comment. Throws on gh failure — callers decide whether that is

package/dist/commands.js

@@ -8,19 +8,39 @@ import { UploadsError } from "./errors.js";
 import { writeJson, writeStdout } from "./io.js";
 import { ghAttachmentKey, ghKeyPrefix, attachmentsCommentBody, } from "./github.js";
 import { resolveRepo, resolveCurrentPullRequest, execRunner, upsertAttachmentsComment, } from "./github-gh.js";
+import { resolvePutPrefix } from "./destinations.js";
+import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
+import { applyFrame, resolveFrameId } from "./frame.js";
+import { buildCliProvenance } from "./provenance.js";
 // --- put ---
 const PUT_HELP = `uploads put <file> [options]
 
 Upload an image for GitHub embeds. Use "-" for stdin.
 
+Still images (PNG/JPEG/…) are optimized to WebP by default (long edge capped,
+high quality; EXIF stripped) so GitHub embeds stay lean. Original bytes are kept
+when they are already smaller, animated, or not an image. Use --no-optimize to
+upload as-is, or --keep-exif when image metadata matters for the discussion.
+
+Optional --frame wraps the image in a device/browser chrome before optimize
+(default off). See: uploads put --help frames
+
 Options:
   --key <key>           Object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>)
+  --destination <id>    Typed root: screenshots | gh | f (sets --prefix)
   --prefix <path>       Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX)
   --repo <owner/repo>   Repo segment (default: git remote, or UPLOADS_DEFAULT_REPO)
   --ref <id>            PR/issue/branch segment (default: today, or UPLOADS_DEFAULT_REF)
   --alt <text>          Alt text (default: filename)
   --width <px>          <img width=…> markdown (or UPLOADS_DEFAULT_WIDTH)
-  --content-type <mime> Override Content-Type
+  --content-type <mime> Override Content-Type (ignored when optimize rewrites the body)
+  --frame <id>          Device/browser frame before optimize (phone|browser|iphone-16-pro)
+  --frame-url <url>     Address bar text for --frame browser
+  --frame-fit cover|contain  How the shot fills the screen (default: cover)
+  --no-optimize         Skip client-side image optimization (or UPLOADS_NO_OPTIMIZE=1)
+  --optimize-max-edge <px>  Max long edge when optimizing (default: 2400)
+  --optimize-quality <1-100>  WebP quality (default: 85)
+  --keep-exif           Keep EXIF/XMP/ICC when optimizing (default: strip for privacy)
   --no-git              Don't derive --repo from git (or UPLOADS_NO_GIT=1)
   --workspace, -w <name>  Override workspace (wins over UPLOADS_WORKSPACE and token inference)
   --format human|url|markdown|json
@@ -30,8 +50,9 @@ Options:
 
 Examples:
   uploads put ./shot.png --repo myorg/myapp --ref 1722 --alt "New cards" --width 700
-  uploads --env-file .env put ./shot.png
-  uploads --env-file .env put ./after.png --pr 123 --comment
+  uploads put ./mobile.png --frame phone
+  uploads put ./ui.png --frame browser --frame-url "https://app.example/settings"
+  uploads put ./shot.png --destination screenshots
 `;
 /**
  * Turns a pr/issue pair (+ optional repo) into a GhTarget; undefined when
@@ -50,6 +71,82 @@ export function makeGhTarget(pr, issue, repoArg, run) {
 function ghTargetFromFlags(flags, run) {
     return makeGhTarget(flagInt(flags, "--pr", "--pr"), flagInt(flags, "--issue", "--issue"), flagString(flags, "--repo"), run);
 }
+/** Shared put/attach optimize flags + UPLOADS_NO_OPTIMIZE default. */
+export function optimizeOptionsFromFlags(flags, defaults) {
+    if (flags.has("--no-optimize") && typeof flags.get("--no-optimize") === "string") {
+        throw new UsageError("--no-optimize takes no value");
+    }
+    if (flags.has("--keep-exif") && typeof flags.get("--keep-exif") === "string") {
+        throw new UsageError("--keep-exif takes no value");
+    }
+    const quality = flagInt(flags, "--optimize-quality", "--optimize-quality");
+    if (quality !== undefined && quality > 100) {
+        throw new UsageError("invalid --optimize-quality: must be 1–100");
+    }
+    return {
+        enabled: !(flagBool(flags, "--no-optimize") || defaults.noOptimize === true),
+        maxEdge: flagInt(flags, "--optimize-max-edge", "--optimize-max-edge"),
+        quality,
+        keepExif: flagBool(flags, "--keep-exif") || defaults.keepExif === true,
+    };
+}
+function formatOptimizeNote(opt) {
+    if (opt.optimized) {
+        return `optimized ${opt.originalBytes} → ${opt.outputBytes} bytes (${opt.filename})`;
+    }
+    if (opt.skippedReason && opt.skippedReason !== "disabled") {
+        return `optimize skipped (${opt.skippedReason})`;
+    }
+    return undefined;
+}
+/** Frame (optional) then optimize — shared by put/attach/MCP. */
+export async function prepareImageForUpload(bytes, filename, opts) {
+    let currentBytes = bytes;
+    let currentName = filename;
+    let frameMeta;
+    if (opts.frameId) {
+        const framed = await applyFrame(currentBytes, currentName, {
+            id: opts.frameId,
+            browserUrl: opts.frameUrl,
+            fit: opts.frameFit,
+        });
+        frameMeta = {
+            framed: framed.framed,
+            frameId: framed.frameId,
+            skippedReason: framed.skippedReason,
+        };
+        if (framed.framed) {
+            currentBytes = framed.bytes;
+            currentName = framed.filename;
+        }
+    }
+    const optimized = await optimizeImageForUpload(currentBytes, currentName, opts.optimize);
+    return { ...optimized, frame: frameMeta };
+}
+function frameOptionsFromFlags(flags) {
+    const raw = flagString(flags, "--frame");
+    let frameId;
+    try {
+        frameId = resolveFrameId(raw);
+    }
+    catch (err) {
+        throw new UsageError(err instanceof Error ? err.message : String(err));
+    }
+    const fitRaw = flagString(flags, "--frame-fit");
+    let frameFit;
+    if (fitRaw) {
+        if (fitRaw !== "cover" && fitRaw !== "contain") {
+            throw new UsageError(`invalid --frame-fit: ${fitRaw} (use cover or contain)`);
+        }
+        frameFit = fitRaw;
+    }
+    if (frameFit && !frameId)
+        throw new UsageError("--frame-fit requires --frame");
+    const frameUrl = flagString(flags, "--frame-url");
+    if (frameUrl && !frameId)
+        throw new UsageError("--frame-url requires --frame");
+    return { frameId, frameUrl, frameFit };
+}
 /**
  * List every attachment under the target's prefix and create/update the
  * managed comment. Throws on gh failure — callers decide whether that is
@@ -69,16 +166,27 @@ const ATTACH_HELP = `uploads attach <file...> [options]
 Upload one or more stable PR/issue attachments and maintain a single GitHub
 comment. With no target, uses the pull request for the current branch.
 
+Still images are optimized to WebP by default (same as put). Use --no-optimize
+to upload originals. Optional --frame wraps images in device/browser chrome.
+
 Options:
   --pr <num>            Attach to this pull request
   --issue <num>         Attach to this issue
   --repo <owner/repo>   Repository (default: gh/git inference)
   --no-comment          Upload only; don't create/update the managed comment
-  --content-type <mime> Override Content-Type (applied to every file)
+  --content-type <mime> Override Content-Type (applied to every file; ignored when optimize rewrites)
+  --frame <id>          Device/browser frame before optimize (phone|browser|iphone-16-pro)
+  --frame-url <url>     Address bar text for --frame browser
+  --frame-fit cover|contain  How the shot fills the screen (default: cover)
+  --no-optimize         Skip client-side image optimization (or UPLOADS_NO_OPTIMIZE=1)
+  --optimize-max-edge <px>  Max long edge when optimizing (default: 2400)
+  --optimize-quality <1-100>  WebP quality (default: 85)
+  --keep-exif           Keep EXIF/XMP/ICC when optimizing (default: strip for privacy)
   --workspace, -w <name>  Override workspace
 
 Examples:
   uploads attach ./before.png ./after.png
+  uploads attach ./mobile.png --frame phone
   uploads attach ./shot.png --pr 123 --repo myorg/myapp
   uploads attach ./artifact.zip --issue 45 --no-comment
 `;
@@ -98,19 +206,50 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     const explicitTarget = ghTargetFromFlags(parsed.flags, run);
     const target = explicitTarget ??
         resolveCurrentPullRequest(resolveRepo(flagString(parsed.flags, "--repo"), run), run);
+    const defaults = resolvePutDefaults({ envFile: ctx.envFile });
+    const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
+    const frameOpts = frameOptionsFromFlags(parsed.flags);
+    const contentTypeOverride = flagString(parsed.flags, "--content-type");
     const results = [];
     for (const file of parsed.positionals) {
         if (file === "-")
             throw new UsageError("attach does not support stdin; pass one or more file paths");
-        const filename = basename(file);
+        const sourceName = basename(file);
         if (!ctx.quiet && !ctx.json)
             process.stderr.write(`>> uploading ${file}\n`);
-        const result = await ctx.client.put(new Uint8Array(readFileSync(file)), {
-            filename,
-            key: ghAttachmentKey(target, filename),
-            contentType: flagString(parsed.flags, "--content-type"),
+        const prepared = await prepareImageForUpload(new Uint8Array(readFileSync(file)), sourceName, {
+            ...frameOpts,
+            optimize: optimizeOpts,
+        });
+        if (prepared.frame?.framed && !ctx.quiet && !ctx.json) {
+            process.stderr.write(`>> framed with ${prepared.frame.frameId}\n`);
+        }
+        const note = formatOptimizeNote(prepared);
+        if (note && !ctx.quiet && !ctx.json)
+            process.stderr.write(`>> ${note}\n`);
+        const result = await ctx.client.put(prepared.bytes, {
+            filename: prepared.filename,
+            key: ghAttachmentKey(target, prepared.filename),
+            contentType: prepared.optimized ? prepared.contentType : contentTypeOverride,
+            provenance: buildCliProvenance({
+                sourceName,
+                optimized: prepared.optimized,
+                frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
+                keepExif: optimizeOpts.keepExif === true,
+            }),
+        });
+        results.push({
+            ...result,
+            markdown: buildMarkdown(result.url, { alt: sourceName }),
+            optimize: {
+                optimized: prepared.optimized,
+                skippedReason: prepared.skippedReason,
+                originalBytes: prepared.originalBytes,
+                outputBytes: prepared.outputBytes,
+                filename: prepared.filename,
+            },
+            frame: prepared.frame,
         });
-        results.push({ ...result, markdown: buildMarkdown(result.url, { alt: filename }) });
     }
     let comment;
     let commentError;
@@ -151,6 +290,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         return 2;
     }
     const keyHint = flagString(parsed.flags, "--key");
+    const destFlag = flagString(parsed.flags, "--destination");
+    const prefixFlag = flagString(parsed.flags, "--prefix");
     const ghTarget = ghTargetFromFlags(parsed.flags, run);
     const wantComment = parsed.flags.has("--comment");
     if (wantComment && typeof parsed.flags.get("--comment") === "string") {
@@ -164,12 +305,23 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         if (flagString(parsed.flags, "--ref")) {
             throw new UsageError("--ref cannot be combined with --pr/--issue");
         }
-        if (flagString(parsed.flags, "--prefix")) {
+        if (prefixFlag)
             throw new UsageError("--prefix cannot be combined with --pr/--issue");
-        }
+    }
+    let resolvedPrefix;
+    try {
+        resolvedPrefix = resolvePutPrefix({
+            destination: destFlag,
+            prefix: prefixFlag,
+            key: keyHint,
+            ghAttachment: Boolean(ghTarget),
+        });
+    }
+    catch (err) {
+        throw new UsageError(err instanceof Error ? err.message : String(err));
     }
     const bytes = fileArg === "-" ? new Uint8Array(readFileSync(0)) : new Uint8Array(readFileSync(fileArg));
-    const filename = fileArg === "-" ? (keyHint ? basename(keyHint) : "stdin.bin") : basename(fileArg);
+    const sourceName = fileArg === "-" ? (keyHint ? basename(keyHint) : "stdin.bin") : basename(fileArg);
     const format = ctx.json
         ? "json"
         : (() => {
@@ -181,7 +333,15 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             throw new UsageError(`invalid --format: ${raw}`);
         })();
     const defaults = resolvePutDefaults({ envFile: ctx.envFile });
-    const alt = flagString(parsed.flags, "--alt") ?? basename(filename);
+    const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
+    const frameOpts = frameOptionsFromFlags(parsed.flags);
+    const prepared = await prepareImageForUpload(bytes, sourceName, {
+        ...frameOpts,
+        optimize: optimizeOpts,
+    });
+    const filename = prepared.filename;
+    const contentTypeOverride = flagString(parsed.flags, "--content-type");
+    const alt = flagString(parsed.flags, "--alt") ?? basename(sourceName);
     const widthRaw = flagString(parsed.flags, "--width");
     const width = widthRaw && /^\d+$/.test(widthRaw) && Number(widthRaw) > 0
         ? Number.parseInt(widthRaw, 10)
@@ -192,24 +352,45 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             : defaults.width;
     if (!ctx.quiet && format === "human") {
         process.stderr.write(`>> uploading ${fileArg === "-" ? "stdin" : fileArg}\n`);
+        if (prepared.frame?.framed)
+            process.stderr.write(`>> framed with ${prepared.frame.frameId}\n`);
+        const note = formatOptimizeNote(prepared);
+        if (note)
+            process.stderr.write(`>> ${note}\n`);
     }
     const noGit = flagBool(parsed.flags, "--no-git") || defaults.noGit === true;
-    const result = await ctx.client.put(bytes, {
+    let key = ghTarget ? ghAttachmentKey(ghTarget, filename) : keyHint;
+    if (key && prepared.optimized)
+        key = rewriteKeyExtension(key, filename);
+    const result = await ctx.client.put(prepared.bytes, {
         filename,
-        key: ghTarget ? ghAttachmentKey(ghTarget, filename) : keyHint,
-        prefix: flagString(parsed.flags, "--prefix") ?? defaults.prefix,
+        key,
+        prefix: resolvedPrefix ?? defaults.prefix,
         repo: flagString(parsed.flags, "--repo") ?? defaults.repo,
         ref: flagString(parsed.flags, "--ref") ?? defaults.ref,
-        contentType: flagString(parsed.flags, "--content-type"),
+        contentType: prepared.optimized ? prepared.contentType : contentTypeOverride,
         deriveRepoFromGit: !noGit,
+        provenance: buildCliProvenance({
+            sourceName,
+            optimized: prepared.optimized,
+            frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
+            keepExif: optimizeOpts.keepExif === true,
+        }),
     });
     const markdown = buildMarkdown(result.url, { alt, width });
+    const optimizeMeta = {
+        optimized: prepared.optimized,
+        skippedReason: prepared.skippedReason,
+        originalBytes: prepared.originalBytes,
+        outputBytes: prepared.outputBytes,
+        filename: prepared.filename,
+    };
     if (!ctx.quiet && format === "human") {
         process.stderr.write(`>> key: ${result.key}\n\n`);
     }
     switch (format) {
         case "json":
-            await writeJson({ ...result, markdown });
+            await writeJson({ ...result, markdown, optimize: optimizeMeta, frame: prepared.frame });
             break;
         case "url":
             await writeStdout(`${result.url}\n`);

package/dist/config-file.d.ts

@@ -1,5 +1,5 @@
 import type { UploadsClientConfig } from "./config.js";
-export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", "UPLOADS_DEFAULT_PREFIX", "UPLOADS_DEFAULT_REPO", "UPLOADS_DEFAULT_REF", "UPLOADS_DEFAULT_WIDTH", "UPLOADS_NO_GIT"];
+export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", "UPLOADS_DEFAULT_PREFIX", "UPLOADS_DEFAULT_REPO", "UPLOADS_DEFAULT_REF", "UPLOADS_DEFAULT_WIDTH", "UPLOADS_NO_GIT", "UPLOADS_NO_OPTIMIZE", "UPLOADS_KEEP_EXIF"];
 export type UploadsConfigKey = (typeof UPLOADS_CONFIG_KEYS)[number];
 export type UploadsConfigValues = Partial<Record<UploadsConfigKey, string>>;
 export interface PutDefaults {
@@ -8,6 +8,10 @@ export interface PutDefaults {
     ref?: string;
     width?: number;
     noGit?: boolean;
+    /** When true, put/attach skip client-side image optimization. */
+    noOptimize?: boolean;
+    /** When true, optimize keeps EXIF/XMP/ICC (default strips). */
+    keepExif?: boolean;
 }
 declare const PUT_DEFAULT_KEY_MAP: Record<keyof PutDefaults, UploadsConfigKey>;
 export declare function putDefaultsToConfigValues(defaults: PutDefaults): UploadsConfigValues;

package/dist/config-file.js

@@ -10,6 +10,8 @@ export const UPLOADS_CONFIG_KEYS = [
     "UPLOADS_DEFAULT_REF",
     "UPLOADS_DEFAULT_WIDTH",
     "UPLOADS_NO_GIT",
+    "UPLOADS_NO_OPTIMIZE",
+    "UPLOADS_KEEP_EXIF",
 ];
 const PUT_DEFAULT_KEY_MAP = {
     prefix: "UPLOADS_DEFAULT_PREFIX",
@@ -17,7 +19,15 @@ const PUT_DEFAULT_KEY_MAP = {
     ref: "UPLOADS_DEFAULT_REF",
     width: "UPLOADS_DEFAULT_WIDTH",
     noGit: "UPLOADS_NO_GIT",
+    noOptimize: "UPLOADS_NO_OPTIMIZE",
+    keepExif: "UPLOADS_KEEP_EXIF",
 };
+function isTruthyConfigFlag(value) {
+    if (!value)
+        return false;
+    const v = value.toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
 export function putDefaultsToConfigValues(defaults) {
     const out = {};
     if (defaults.prefix)
@@ -30,6 +40,10 @@ export function putDefaultsToConfigValues(defaults) {
         out.UPLOADS_DEFAULT_WIDTH = String(defaults.width);
     if (defaults.noGit)
         out.UPLOADS_NO_GIT = "1";
+    if (defaults.noOptimize)
+        out.UPLOADS_NO_OPTIMIZE = "1";
+    if (defaults.keepExif)
+        out.UPLOADS_KEEP_EXIF = "1";
     return out;
 }
 function parsePutDefaultsFromRaw(raw) {
@@ -45,9 +59,12 @@ function parsePutDefaultsFromRaw(raw) {
         if (Number.isFinite(n) && n > 0)
             out.width = n;
     }
-    if (raw.UPLOADS_NO_GIT === "1" || raw.UPLOADS_NO_GIT?.toLowerCase() === "true") {
+    if (isTruthyConfigFlag(raw.UPLOADS_NO_GIT))
         out.noGit = true;
-    }
+    if (isTruthyConfigFlag(raw.UPLOADS_NO_OPTIMIZE))
+        out.noOptimize = true;
+    if (isTruthyConfigFlag(raw.UPLOADS_KEEP_EXIF))
+        out.keepExif = true;
     return out;
 }
 function parsePutDefaultsFromEnv() {
@@ -62,6 +79,10 @@ function parsePutDefaultsFromEnv() {
         raw.UPLOADS_DEFAULT_WIDTH = process.env.UPLOADS_DEFAULT_WIDTH;
     if (process.env.UPLOADS_NO_GIT)
         raw.UPLOADS_NO_GIT = process.env.UPLOADS_NO_GIT;
+    if (process.env.UPLOADS_NO_OPTIMIZE)
+        raw.UPLOADS_NO_OPTIMIZE = process.env.UPLOADS_NO_OPTIMIZE;
+    if (process.env.UPLOADS_KEEP_EXIF)
+        raw.UPLOADS_KEEP_EXIF = process.env.UPLOADS_KEEP_EXIF;
     return parsePutDefaultsFromRaw(raw);
 }
 /** XDG default shared across buildinternet skills (github-screenshots, uploads, …). */
@@ -127,6 +148,10 @@ export function mergePutDefaults(...layers) {
             out.width = layer.width;
         if (layer.noGit != null)
             out.noGit = layer.noGit;
+        if (layer.noOptimize != null)
+            out.noOptimize = layer.noOptimize;
+        if (layer.keepExif != null)
+            out.keepExif = layer.keepExif;
     }
     return out;
 }

package/dist/destinations.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Typed destination roots for put/attach. Matches the API allowlist defaults
+ * (`f/`, `screenshots/`, `gh/`) — see apps/api `key-policy.ts`.
+ */
+export declare const BUILTIN_DESTINATIONS: {
+    readonly f: "f";
+    readonly screenshots: "screenshots";
+    readonly gh: "gh";
+};
+export type BuiltinDestinationId = keyof typeof BUILTIN_DESTINATIONS;
+export declare function isBuiltinDestination(id: string): id is BuiltinDestinationId;
+/** Root segment for a known destination, or throws with a usage-friendly message. */
+export declare function resolveDestinationRoot(id: string): string;
+/** True when `key` is under the destination root. */
+export declare function keyMatchesDestination(key: string, destinationId: string): boolean;
+/**
+ * Resolve CLI/MCP destination flags into a put `prefix`. Throws plain Errors
+ * (callers wrap as UsageError / MCP usage errors).
+ */
+export declare function resolvePutPrefix(opts: {
+    destination?: string;
+    prefix?: string;
+    key?: string;
+    /** When true (PR/issue attach), destination must be `gh` or omitted. */
+    ghAttachment?: boolean;
+}): string | undefined;