@buildinternet/uploads 0.2.0 → 0.3.0

package/README.md

@@ -4,9 +4,7 @@ CLI and client for **uploads.sh** — upload files, get public URLs, and produce
 
 ## 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

@@ -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.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);

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,38 @@ 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";
 // --- 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 +49,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 +70,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 +165,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 +205,44 @@ 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,
+        });
+        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 +283,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 +298,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 +326,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 +345,39 @@ 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,
     });
     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;

package/dist/destinations.js

@@ -0,0 +1,47 @@
+/**
+ * Typed destination roots for put/attach. Matches the API allowlist defaults
+ * (`f/`, `screenshots/`, `gh/`) — see apps/api `key-policy.ts`.
+ */
+export const BUILTIN_DESTINATIONS = {
+    f: "f",
+    screenshots: "screenshots",
+    gh: "gh",
+};
+export function isBuiltinDestination(id) {
+    return Object.hasOwn(BUILTIN_DESTINATIONS, id);
+}
+/** Root segment for a known destination, or throws with a usage-friendly message. */
+export function resolveDestinationRoot(id) {
+    if (!isBuiltinDestination(id)) {
+        const known = Object.keys(BUILTIN_DESTINATIONS).join(", ");
+        throw new Error(`unknown destination: ${id} (known: ${known})`);
+    }
+    return BUILTIN_DESTINATIONS[id];
+}
+/** True when `key` is under the destination root. */
+export function keyMatchesDestination(key, destinationId) {
+    if (!isBuiltinDestination(destinationId))
+        return false;
+    const root = BUILTIN_DESTINATIONS[destinationId];
+    return key === root || key.startsWith(`${root}/`);
+}
+/**
+ * Resolve CLI/MCP destination flags into a put `prefix`. Throws plain Errors
+ * (callers wrap as UsageError / MCP usage errors).
+ */
+export function resolvePutPrefix(opts) {
+    const { destination, prefix, key, ghAttachment } = opts;
+    if (!destination)
+        return prefix;
+    const root = resolveDestinationRoot(destination);
+    if (ghAttachment && destination !== "gh") {
+        throw new Error("destination with pr/issue must be gh (or omit it)");
+    }
+    if (key && !keyMatchesDestination(key, destination)) {
+        throw new Error(`key must start with destination root "${root}/"`);
+    }
+    if (prefix && prefix.replace(/\/+$/, "") !== root) {
+        throw new Error(`prefix (${prefix}) conflicts with destination ${destination} (root ${root})`);
+    }
+    return root;
+}

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_KEY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "API_ERROR" | "NETWORK" | "USAGE";
+export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_KEY" | "KEY_POLICY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "API_ERROR" | "NETWORK" | "USAGE";
 export declare class UploadsError extends Error {
     readonly code: UploadsErrorCode;
     readonly status?: number;

package/dist/frame.d.ts

@@ -0,0 +1,36 @@
+export type FrameFit = "cover" | "contain";
+export interface FrameOptions {
+    id: string;
+    fit?: FrameFit;
+    /** Address bar text for procedural `browser`. */
+    browserUrl?: string;
+    fetchImpl?: typeof fetch;
+    cacheDir?: string;
+}
+export interface FrameResult {
+    bytes: Uint8Array;
+    filename: string;
+    contentType: string;
+    framed: boolean;
+    frameId: string;
+    skippedReason?: string;
+}
+type FramePreset = {
+    kind: "procedural";
+    label: string;
+} | {
+    kind: "remote";
+    label: string;
+    /** Directory URL with frame.png, mask.png, template.json */
+    assetBase: string;
+};
+export declare const FRAME_PRESETS: Record<string, FramePreset>;
+export declare function listFramePresets(): Array<{
+    id: string;
+    label: string;
+    kind: string;
+}>;
+export declare function resolveFrameId(raw: string | undefined): string | undefined;
+/** Apply a named frame. Non-images pass through. Output PNG for the optimize step. */
+export declare function applyFrame(bytes: Uint8Array, filename: string, opts: FrameOptions): Promise<FrameResult>;
+export {};