@buildinternet/uploads 0.7.0 → 0.9.0

package/dist/github.d.ts

@@ -22,11 +22,25 @@ export declare function ghKeyPrefix(target: GhTarget): string;
  * (unlike buildScreenshotKey).
  */
 export declare function ghAttachmentKey(target: GhTarget, filename: string): string;
+/**
+ * The four `gh.*` queryable-metadata pairs `uploads attach` writes
+ * automatically (`.context/2026-07-13-file-metadata-design.md`). `gh.kind`
+ * uses the API's singular vocabulary (`pull`/`issue`), distinct from
+ * `GhTarget.kind`'s URL-segment spelling (`pull`/`issues`). `gh.repo` and
+ * `gh.ref` are both lowercased so exact-match metadata search has one
+ * canonical spelling regardless of source casing (`--repo`, git remote, and
+ * `gh` output vary); `gh.ref` uses the same lowercased `owner/repo#number`
+ * coordinate as gallery GitHub references, so both surfaces resolve the same
+ * lookup key.
+ */
+export declare function ghMetadataFromTarget(target: GhTarget): Record<string, string>;
 /** Hidden marker identifying the one comment this CLI manages. Never change it — existing comments are found by exact match. */
 export declare const ATTACHMENTS_MARKER = "<!-- uploads.sh:attachments -->";
 export interface AttachmentItem {
     key: string;
     url: string | null;
+    /** Prefer for `<img src>` on GitHub (Camo-friendly host). Falls back to `url`. */
+    embedUrl?: string | null;
 }
 /** A public gallery linked to the PR or issue whose managed comment is syncing. */
 export interface GalleryCommentItem {
@@ -37,6 +51,7 @@ export interface GalleryCommentItem {
     previews?: {
         url: string;
         alt: string;
+        embedUrl?: string | null;
         itemUrl?: string;
     }[];
 }

package/dist/github.js

@@ -63,6 +63,26 @@ export function ghKeyPrefix(target) {
 export function ghAttachmentKey(target, filename) {
     return `${ghKeyPrefix(target)}${sanitizeKeySegment(filename)}`;
 }
+/**
+ * The four `gh.*` queryable-metadata pairs `uploads attach` writes
+ * automatically (`.context/2026-07-13-file-metadata-design.md`). `gh.kind`
+ * uses the API's singular vocabulary (`pull`/`issue`), distinct from
+ * `GhTarget.kind`'s URL-segment spelling (`pull`/`issues`). `gh.repo` and
+ * `gh.ref` are both lowercased so exact-match metadata search has one
+ * canonical spelling regardless of source casing (`--repo`, git remote, and
+ * `gh` output vary); `gh.ref` uses the same lowercased `owner/repo#number`
+ * coordinate as gallery GitHub references, so both surfaces resolve the same
+ * lookup key.
+ */
+export function ghMetadataFromTarget(target) {
+    const repo = target.repo.toLowerCase();
+    return {
+        "gh.repo": repo,
+        "gh.kind": target.kind === "issues" ? "issue" : "pull",
+        "gh.number": String(target.num),
+        "gh.ref": `${repo}#${target.num}`,
+    };
+}
 /** 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). */
@@ -107,7 +127,8 @@ export function attachmentsCommentBody(items, galleries = []) {
             lines.push(`#### <a href="${href}">${escapeHtmlText(gallery.title)}</a>`);
             for (const preview of gallery.previews ?? []) {
                 const previewHref = preview.itemUrl ? escapeHtmlAttr(preview.itemUrl) : href;
-                lines.push(`<a href="${previewHref}"><img width="320" alt="${escapeHtmlAttr(preview.alt)}" src="${escapeHtmlAttr(preview.url)}"></a>`);
+                const previewSrc = escapeHtmlAttr(preview.embedUrl ?? preview.url);
+                lines.push(`<a href="${previewHref}"><img width="320" alt="${escapeHtmlAttr(preview.alt)}" src="${previewSrc}"></a>`);
             }
             lines.push(`<sub><a href="${href}">Open gallery</a></sub>`, "");
         }
@@ -117,17 +138,20 @@ export function attachmentsCommentBody(items, galleries = []) {
         lines.push("### 📎 Attachments", "");
     for (const item of sorted) {
         const name = item.key.slice(item.key.lastIndexOf("/") + 1);
-        if (item.url && inferContentType(name).startsWith("image/")) {
+        const stable = item.url;
+        const src = item.embedUrl ?? item.url;
+        if (src && inferContentType(name).startsWith("image/")) {
             // 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).
+            // img src uses embed host when available (Camo revalidates); click-through keeps stable URL.
             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>`);
+            const href = escapeHtmlAttr(stable ?? src);
+            const imgSrc = escapeHtmlAttr(src);
+            lines.push(`<a href="${href}"><img width="${w}" alt="${alt}" src="${imgSrc}"></a>`);
             lines.push("");
         }
-        else if (item.url) {
-            lines.push(`- [${name}](${item.url})`);
+        else if (stable) {
+            lines.push(`- [${name}](${stable})`);
         }
         else {
             lines.push(`- ${name}`);

package/dist/index.d.ts

@@ -1,11 +1,13 @@
 export { inferContentType, buildMarkdown } from "./embed.js";
+export { DEFAULT_EMBED_PUBLIC_BASE_URL, embedBaseUrlFromEnv, embedUrlFromPublic, resolveEmbedBaseUrl, resolveEmbedUrl, urlForGithubEmbed, } from "./public-urls.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 ProvenanceInput, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type GalleryItem, type Gallery, type GallerySummary, type GalleryListOptions, type GalleryListResult, type CreateGalleryOptions, type AddGalleryItemOptions, type DeleteGalleryOptions, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, } from "./client.js";
+export { createUploadsClient, type UploadsClient, type PutOptions, type ProvenanceInput, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type GalleryItem, type Gallery, type GallerySummary, type GalleryListOptions, type GalleryListResult, type CreateGalleryOptions, type AddGalleryItemOptions, type DeleteGalleryOptions, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, type FindFilesOptions, type FindFilesItem, type FindFilesResult, type GetMetadataResult, type PatchMetadataOptions, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
-export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, isValidRepo, parseRepoFromRemoteUrl, type AttachmentItem, type GhTarget, type GhTargetKind, } from "./github.js";
+export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, 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,11 +1,13 @@
 export { inferContentType, buildMarkdown } from "./embed.js";
+export { DEFAULT_EMBED_PUBLIC_BASE_URL, embedBaseUrlFromEnv, embedUrlFromPublic, resolveEmbedBaseUrl, resolveEmbedUrl, urlForGithubEmbed, } from "./public-urls.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 { buildCliProvenance } from "./provenance.js";
-export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
+export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, 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/args.d.ts

@@ -2,3 +2,20 @@ export type ToolArgs = Record<string, unknown>;
 export declare function usage(msg: string): never;
 export declare function optString(args: ToolArgs, name: string): string | undefined;
 export declare function optPosInt(args: ToolArgs, name: string): number | undefined;
+/** A JSON-object argument of string→string pairs (e.g. a `metadata` or `filters` param). */
+export declare function optStringRecord(args: ToolArgs, name: string): Record<string, string> | undefined;
+/** A JSON-array argument of strings (e.g. a `delete` or `files` param). */
+export declare function optStringArray(args: ToolArgs, name: string): string[] | undefined;
+/**
+ * Shared tool-description text for the metadata-shaped `metadata`/`set`/
+ * `filters` params across the CLI/local MCP (put/attach/set_metadata/
+ * find_files) and the remote MCP worker (set_metadata/find_files).
+ */
+export declare const METADATA_DESCRIPTION = "Queryable custom metadata (key\u2192value), separate from provenance. Omit to leave any metadata already stored for this key untouched; pass an object (even {}) to fully replace it. Keys: lowercase, ^[a-z][a-z0-9._-]{0,63}$. Values: 1-512 printable ASCII characters. Caps: at most 24 keys, at most 8192 total key+value bytes. Suggested keys: app, url, page, device, resolution, commit, branch. `gh.*` is reserved by convention for GitHub PR/issue attachment context (repo/kind/number/ref).";
+export declare const metadataProp: {
+    type: string;
+    additionalProperties: {
+        type: string;
+    };
+    description: string;
+};

package/dist/mcp/args.js

@@ -24,3 +24,45 @@ export function optPosInt(args, name) {
     }
     return v;
 }
+/** A JSON-object argument of string→string pairs (e.g. a `metadata` or `filters` param). */
+export function optStringRecord(args, name) {
+    const v = args[name];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "object" || Array.isArray(v)) {
+        usage(`${name} must be an object of string values`);
+    }
+    // Object.create(null): a plain `{}` would silently drop a `__proto__` key
+    // (it hits the inherited setter instead of becoming an own property),
+    // turning a malicious/malformed key into a no-op rather than a rejected
+    // input. A null-prototype object makes every key a real own property so
+    // downstream validation (e.g. META_KEY_RE) sees and rejects it.
+    const result = Object.create(null);
+    for (const [key, value] of Object.entries(v)) {
+        if (typeof value !== "string")
+            usage(`${name}.${key} must be a string`);
+        result[key] = value;
+    }
+    return result;
+}
+/** A JSON-array argument of strings (e.g. a `delete` or `files` param). */
+export function optStringArray(args, name) {
+    const v = args[name];
+    if (v === undefined || v === null)
+        return undefined;
+    if (!Array.isArray(v) || v.some((item) => typeof item !== "string")) {
+        usage(`${name} must be an array of strings`);
+    }
+    return v;
+}
+/**
+ * Shared tool-description text for the metadata-shaped `metadata`/`set`/
+ * `filters` params across the CLI/local MCP (put/attach/set_metadata/
+ * find_files) and the remote MCP worker (set_metadata/find_files).
+ */
+export const METADATA_DESCRIPTION = "Queryable custom metadata (key→value), separate from provenance. Omit to leave any metadata already stored for this key untouched; pass an object (even {}) to fully replace it. Keys: lowercase, ^[a-z][a-z0-9._-]{0,63}$. Values: 1-512 printable ASCII characters. Caps: at most 24 keys, at most 8192 total key+value bytes. Suggested keys: app, url, page, device, resolution, commit, branch. `gh.*` is reserved by convention for GitHub PR/issue attachment context (repo/kind/number/ref).";
+export const metadataProp = {
+    type: "object",
+    additionalProperties: { type: "string" },
+    description: METADATA_DESCRIPTION,
+};

package/dist/mcp/server.d.ts

@@ -1,4 +1,4 @@
-export { optPosInt, optString, usage, type ToolArgs } from "./args.js";
+export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, type ToolArgs, } from "./args.js";
 export interface McpTool {
     name: string;
     description: string;

package/dist/mcp/server.js

@@ -8,7 +8,7 @@
  * stdio transport lives in ./stdio.ts; logs must never go to stdout.
  */
 import { UploadsError } from "../errors.js";
-export { optPosInt, optString, usage } from "./args.js";
+export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(["2025-06-18", "2025-03-26", "2024-11-05"]);
 const LATEST_PROTOCOL_VERSION = "2025-06-18";
 function response(id, result) {

package/dist/mcp/tools.js

@@ -5,19 +5,20 @@
  * per-call `workspace` argument behaves like the CLI's --workspace flag, and
  * a missing token surfaces as a tool error rather than a startup failure.
  */
-import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, makeGhTarget, prepareImageForUpload, syncAttachmentsComment, } from "../commands.js";
+import { buildDoctorReport, makeGhTarget, prepareImageForUpload, readFileArg, syncAttachmentsComment, } from "../commands.js";
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { buildMarkdown } from "../embed.js";
+import { urlForGithubEmbed } from "../public-urls.js";
 import { resolvePutPrefix } from "../destinations.js";
-import { ghAttachmentKey, ghKeyPrefix } from "../github.js";
+import { ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget } from "../github.js";
+import { validateMetaMap } from "../metadata.js";
 import { rewriteKeyExtension } from "../optimize.js";
 import { buildCliProvenance } from "../provenance.js";
 import { execRunner, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
-import { optPosInt, optString, usage } from "./args.js";
+import { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
 function optBool(args, name) {
     const v = args[name];
     if (v === undefined || v === null)
@@ -26,15 +27,6 @@ function optBool(args, name) {
         usage(`${name} must be a boolean`);
     return v;
 }
-function optStringArray(args, name) {
-    const v = args[name];
-    if (v === undefined || v === null)
-        return undefined;
-    if (!Array.isArray(v) || v.some((item) => typeof item !== "string")) {
-        usage(`${name} must be an array of strings`);
-    }
-    return v;
-}
 function mcpOptimizeOptions(args, defaults) {
     const quality = optPosInt(args, "optimizeQuality");
     if (quality !== undefined && quality > 100)
@@ -276,7 +268,7 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "put",
-            description: "Upload a file to uploads.sh and get a public URL plus GitHub-ready embed markdown (the returned `markdown` is ready to paste into a PR or issue). Pass `file` (a local path) or `contentBase64` + `filename` for in-memory content; with `pr`/`issue` the key is stable (same filename → same URL) and `comment` syncs the managed attachments comment. All uploads are public; pr/issue keys are predictable and remain public for private/internal GitHub repositories, so upload only non-sensitive media.",
+            description: "Upload a file to uploads.sh and get a public URL plus GitHub-ready embed markdown. Returns `url` (durable CDN) and `embedUrl` (same object, freshness-oriented host for GitHub Camo — prefer this in PR/issue markdown). The returned `markdown` already uses embedUrl when available. Pass `file` or `contentBase64` + `filename`; with `pr`/`issue` the key is stable and `comment` syncs the managed attachments comment. All uploads are public; pr/issue keys are predictable, so upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -290,7 +282,7 @@ export function createUploadsMcpTools(opts) {
                     },
                     filename: {
                         type: "string",
-                        description: "Filename for contentBase64 content (drives the key and content type).",
+                        description: "Filename for contentBase64 content (drives the key and content type). With `file`, overrides the key's leaf (clean name) while keeping the pr/default path.",
                     },
                     key: {
                         type: "string",
@@ -345,6 +337,11 @@ export function createUploadsMcpTools(opts) {
                         type: "boolean",
                         description: "With pr/issue: create or update the managed attachments comment via local gh auth (best-effort).",
                     },
+                    dryRun: {
+                        type: "boolean",
+                        description: "Resolve key + public URL without uploading. Not with comment.",
+                    },
+                    metadata: metadataProp,
                     workspace: workspaceProp,
                 },
                 additionalProperties: false,
@@ -361,12 +358,15 @@ export function createUploadsMcpTools(opts) {
                 }
                 const target = ghTargetFromArgs(args, run);
                 const wantComment = optBool(args, "comment");
+                const dryRun = optBool(args, "dryRun");
                 const keyArg = optString(args, "key");
                 const destArg = optString(args, "destination");
                 const prefixArg = optString(args, "prefix");
                 const refArg = optString(args, "ref");
                 if (wantComment && !target)
                     usage("comment requires pr or issue");
+                if (dryRun && wantComment)
+                    usage("dryRun cannot be combined with comment");
                 if (target) {
                     if (keyArg)
                         usage("key cannot be combined with pr/issue");
@@ -375,6 +375,12 @@ export function createUploadsMcpTools(opts) {
                     if (prefixArg)
                         usage("prefix cannot be combined with pr/issue");
                 }
+                // Validate up front (fail fast, before reading/optimizing the file).
+                // undefined leaves existing metadata untouched; an object (even {})
+                // fully replaces it — see metadataProp's description.
+                const metadata = optStringRecord(args, "metadata");
+                if (metadata)
+                    validateMetaMap(metadata);
                 let resolvedPrefix;
                 try {
                     resolvedPrefix = resolvePutPrefix({
@@ -389,7 +395,7 @@ export function createUploadsMcpTools(opts) {
                 }
                 const { client } = clientFor(args);
                 const bytes = file !== undefined
-                    ? new Uint8Array(readFileSync(file))
+                    ? readFileArg(file)
                     : new Uint8Array(Buffer.from(contentBase64, "base64"));
                 const sourceName = file !== undefined ? (filenameArg ?? basename(file)) : filenameArg;
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
@@ -412,6 +418,7 @@ export function createUploadsMcpTools(opts) {
                     ref: refArg ?? defaults.ref,
                     contentType: prepared.optimized ? prepared.contentType : optString(args, "contentType"),
                     deriveRepoFromGit: !noGit,
+                    dryRun,
                     provenance: buildCliProvenance({
                         sourceName,
                         client: "uploads-mcp",
@@ -419,8 +426,9 @@ export function createUploadsMcpTools(opts) {
                         frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
                         keepExif: optimizeOpts.keepExif === true,
                     }),
+                    metadata,
                 });
-                const markdown = buildMarkdown(result.url, {
+                const markdown = buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
                     alt: optString(args, "alt") ?? sourceName,
                     width: optPosInt(args, "width") ?? defaults.width,
                 });
@@ -435,12 +443,18 @@ export function createUploadsMcpTools(opts) {
                     const { comment, commentError } = await syncComment(client, target);
                     return { ...result, markdown, optimize, frame: prepared.frame, comment, commentError };
                 }
-                return { ...result, markdown, optimize, frame: prepared.frame };
+                return {
+                    ...result,
+                    markdown,
+                    optimize,
+                    frame: prepared.frame,
+                    ...(dryRun ? { dryRun: true } : {}),
+                };
             },
         },
         {
             name: "attach",
-            description: "Upload one or more files as stable PR/issue attachments and maintain a single managed GitHub comment listing them (each upload's `markdown` is ready to paste into GitHub). With no pr/issue, targets the pull request for the current branch. Attachments are public and their repo/number/filename keys are predictable even for private/internal GitHub repositories; upload only non-sensitive media.",
+            description: "Upload one or more files as stable PR/issue attachments and maintain a single managed GitHub comment listing them. Each upload returns `url`, `embedUrl` (when dual-host applies), and `markdown` (uses embedUrl for GitHub). With no pr/issue, targets the pull request for the current branch. Attachments are public and keys are predictable; upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -475,6 +489,11 @@ export function createUploadsMcpTools(opts) {
                         description: "Keep EXIF/XMP/ICC when optimizing (default: strip for privacy on public embeds).",
                     },
                     ...frameProps,
+                    metadata: {
+                        ...metadataProp,
+                        description: "Extra queryable metadata (key→value), merged with the automatic gh.repo/gh.kind/gh.number/gh.ref pairs — a gh.* pair here loses to the resolved target's own gh.* value. " +
+                            METADATA_DESCRIPTION,
+                    },
                     workspace: workspaceProp,
                 },
                 required: ["files"],
@@ -492,10 +511,23 @@ export function createUploadsMcpTools(opts) {
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
                 const frameOpts = mcpFrameOptions(args);
                 const optimizeOpts = mcpOptimizeOptions(args, defaults);
+                // User-supplied extras first, then the resolved target's gh.* —
+                // explicit target pairs always win over a same-named metadata extra
+                // (mirrors runAttach in ../commands.js). Validate the merged map (not
+                // just the extras) so the 24-key/8KB caps are enforced client-side —
+                // extras alone might pass while extras + the 4 gh.* pairs exceed the
+                // cap, which would otherwise only be caught server-side after upload.
+                const metaExtras = optStringRecord(args, "metadata") ?? {};
+                const metadata = { ...metaExtras, ...ghMetadataFromTarget(target) };
+                if (Object.keys(metadata).length > 0)
+                    validateMetaMap(metadata);
                 const uploads = [];
                 for (const file of files) {
                     const sourceName = basename(file);
-                    const prepared = await prepareImageForUpload(new Uint8Array(readFileSync(file)), sourceName, { ...frameOpts, optimize: optimizeOpts });
+                    const prepared = await prepareImageForUpload(readFileArg(file), sourceName, {
+                        ...frameOpts,
+                        optimize: optimizeOpts,
+                    });
                     const result = await client.put(prepared.bytes, {
                         filename: prepared.filename,
                         key: ghAttachmentKey(target, prepared.filename),
@@ -507,10 +539,13 @@ export function createUploadsMcpTools(opts) {
                             frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
                             keepExif: optimizeOpts.keepExif === true,
                         }),
+                        metadata,
                     });
                     uploads.push({
                         ...result,
-                        markdown: buildMarkdown(result.url, { alt: sourceName }),
+                        markdown: buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
+                            alt: sourceName,
+                        }),
                         frame: prepared.frame,
                         optimize: {
                             optimized: prepared.optimized,
@@ -591,6 +626,71 @@ export function createUploadsMcpTools(opts) {
                 return client.delete(key);
             },
         },
+        {
+            name: "set_metadata",
+            description: "Merge-set and/or delete an object's queryable custom metadata (D1-backed key-value pairs; distinct from the R2 provenance headers put on upload). `set` pairs win over `delete` when a key appears in both. " +
+                METADATA_DESCRIPTION +
+                " Requires at least one of `set` or `delete`. Same as `uploads meta set`.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: { type: "string", description: "Object key to update." },
+                    set: { ...metadataProp, description: "Keys to set/overwrite. " + METADATA_DESCRIPTION },
+                    delete: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Keys to remove.",
+                    },
+                    workspace: workspaceProp,
+                },
+                required: ["key"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const key = optString(args, "key");
+                if (!key)
+                    usage("key is required");
+                const set = optStringRecord(args, "set");
+                const del = optStringArray(args, "delete");
+                if ((!set || Object.keys(set).length === 0) && (!del || del.length === 0)) {
+                    usage("set_metadata requires set and/or delete");
+                }
+                if (set)
+                    validateMetaMap(set);
+                const { client } = clientFor(args);
+                return client.patchMetadata(key, { set, delete: del });
+            },
+        },
+        {
+            name: "find_files",
+            description: "Find objects in the workspace whose queryable custom metadata matches ALL of `filters` (ANDed equality). Returns each match's key, public URL, and full metadata map. Same as `uploads find k=v...` / `uploads list --meta k=v`.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    filters: {
+                        ...metadataProp,
+                        description: "Metadata equality filters (at least one pair). " + METADATA_DESCRIPTION,
+                    },
+                    prefix: { type: "string", description: "Key prefix filter, combinable with filters." },
+                    limit: { type: "number", description: "Page size (default 50, max 500)." },
+                    workspace: workspaceProp,
+                },
+                required: ["filters"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const filters = optStringRecord(args, "filters");
+                if (!filters || Object.keys(filters).length === 0) {
+                    usage("filters must have at least one key");
+                }
+                validateMetaMap(filters);
+                const { client } = clientFor(args);
+                return client.findFiles(filters, {
+                    prefix: optString(args, "prefix"),
+                    limit: optPosInt(args, "limit"),
+                });
+            },
+        },
         {
             name: "usage",
             description: "Workspace storage and monthly upload counters (and remaining headroom when budgets are configured). Same as `uploads usage`.",

package/dist/metadata.d.ts

@@ -0,0 +1,32 @@
+/** Lowercase key, optionally dot-namespaced (e.g. `gh.repo`). Mirrors META_KEY_RE server-side. */
+export declare const META_KEY_RE: RegExp;
+/** Max value length in characters (mirrors META_VALUE_MAX server-side). */
+export declare const META_VALUE_MAX = 512;
+/** Cap on keys per request (mirrors META_MAX_KEYS server-side). */
+export declare const META_MAX_KEYS = 24;
+/** Cap on total UTF-8 key+value bytes per request (mirrors META_MAX_TOTAL_BYTES server-side). */
+export declare const META_MAX_TOTAL_BYTES = 8192;
+/** Throws `UsageError` with a readable message if `key`/`value` violate the metadata rules. */
+export declare function validateMetaEntry(key: string, value: string): void;
+/**
+ * Split `k=v` on the FIRST "=" (so values may themselves contain "="), then
+ * validate the pair. Throws `UsageError` on malformed input.
+ */
+export declare function parseMetaPair(raw: string): [string, string];
+/**
+ * Parse and validate a batch of `k=v` pairs (e.g. every `--meta` occurrence,
+ * or `meta set`'s positional pairs) into a map. Fails fast on the first
+ * invalid pair or when the batch exceeds `META_MAX_KEYS` or
+ * `META_MAX_TOTAL_BYTES`. Later duplicate keys in the same batch win
+ * (last write).
+ */
+export declare function parseMetaFlags(pairs: string[]): Record<string, string>;
+/**
+ * Validates a pre-parsed key→value metadata map (e.g. an MCP tool's object
+ * argument) against the same rules as {@link parseMetaFlags} — the same
+ * per-entry validation (`validateMetaEntry`, which `parseMetaPair` also
+ * uses), the same key-count cap, and the same aggregate byte cap — without
+ * round-tripping through "k=v" string reconstruction and re-parsing first.
+ * Throws `UsageError`.
+ */
+export declare function validateMetaMap(meta: Record<string, string>): void;

package/dist/metadata.js

@@ -0,0 +1,102 @@
+/**
+ * Client-side validation for `--meta k=v` / `meta set` pairs, mirroring the
+ * server rules in `apps/api/src/file-metadata.ts` (`.context/2026-07-13-file-metadata-design.md`).
+ * Validating here lets the CLI fail fast with a readable message instead of a
+ * round-trip 400 — the server remains the source of truth and re-validates on
+ * every write.
+ */
+import { UsageError } from "./cli-args.js";
+/** Lowercase key, optionally dot-namespaced (e.g. `gh.repo`). Mirrors META_KEY_RE server-side. */
+export const META_KEY_RE = /^[a-z][a-z0-9._-]{0,63}$/;
+/** Max value length in characters (mirrors META_VALUE_MAX server-side). */
+export const META_VALUE_MAX = 512;
+/** Cap on keys per request (mirrors META_MAX_KEYS server-side). */
+export const META_MAX_KEYS = 24;
+/** Cap on total UTF-8 key+value bytes per request (mirrors META_MAX_TOTAL_BYTES server-side). */
+export const META_MAX_TOTAL_BYTES = 8192;
+// Printable ASCII only — same rule as the server's file-metadata.ts.
+const VALUE_SAFE_RE = /^[\x20-\x7E]+$/;
+const encoder = new TextEncoder();
+/**
+ * Server-computed/server-reserved keys the API rejects as custom metadata:
+ * `content-sha256` (server-computed provenance) and `visibility` (names the
+ * R2-backed public/private gate, not a piece of D1 custom metadata — mirrors
+ * apps/api/src/file-metadata.ts's RESERVED_META_KEYS). `gh.*` is NOT reserved
+ * here: it's system-managed by convention (attach flow), not blocked — the
+ * server happily accepts user-supplied `gh.*` extras via `--meta`.
+ */
+const RESERVED_META_KEYS = new Set(["content-sha256", "visibility"]);
+/** Throws `UsageError` with a readable message if `key`/`value` violate the metadata rules. */
+export function validateMetaEntry(key, value) {
+    if (!META_KEY_RE.test(key)) {
+        throw new UsageError(`invalid metadata key: "${key}" (must match ^[a-z][a-z0-9._-]{0,63}$)`);
+    }
+    if (RESERVED_META_KEYS.has(key)) {
+        throw new UsageError(`invalid metadata key: "${key}" is reserved (server-computed)`);
+    }
+    if (value.length < 1 || value.length > META_VALUE_MAX || !VALUE_SAFE_RE.test(value)) {
+        throw new UsageError(`invalid metadata value for key "${key}": must be 1-${META_VALUE_MAX} printable ASCII characters`);
+    }
+}
+/**
+ * Split `k=v` on the FIRST "=" (so values may themselves contain "="), then
+ * validate the pair. Throws `UsageError` on malformed input.
+ */
+export function parseMetaPair(raw) {
+    const eq = raw.indexOf("=");
+    if (eq === -1) {
+        throw new UsageError(`invalid --meta value: "${raw}" (expected key=value)`);
+    }
+    const key = raw.slice(0, eq);
+    const value = raw.slice(eq + 1);
+    validateMetaEntry(key, value);
+    return [key, value];
+}
+/** Throws `UsageError` if the aggregate UTF-8 key+value bytes of `entries` exceed `META_MAX_TOTAL_BYTES`. */
+function enforceMetaByteCap(entries) {
+    let totalBytes = 0;
+    for (const [key, value] of entries) {
+        totalBytes += encoder.encode(key).byteLength + encoder.encode(value).byteLength;
+    }
+    if (totalBytes > META_MAX_TOTAL_BYTES) {
+        throw new UsageError(`metadata too large: ${totalBytes} bytes of keys+values exceeds the ${META_MAX_TOTAL_BYTES}-byte limit per request`);
+    }
+}
+/**
+ * Parse and validate a batch of `k=v` pairs (e.g. every `--meta` occurrence,
+ * or `meta set`'s positional pairs) into a map. Fails fast on the first
+ * invalid pair or when the batch exceeds `META_MAX_KEYS` or
+ * `META_MAX_TOTAL_BYTES`. Later duplicate keys in the same batch win
+ * (last write).
+ */
+export function parseMetaFlags(pairs) {
+    if (pairs.length > META_MAX_KEYS) {
+        throw new UsageError(`too many --meta pairs: at most ${META_MAX_KEYS} per request`);
+    }
+    const result = {};
+    for (const pair of pairs) {
+        const [key, value] = parseMetaPair(pair);
+        result[key] = value;
+    }
+    // Aggregate byte cap over the deduplicated map — same accounting as the
+    // server (sum of UTF-8 key+value bytes, META_MAX_TOTAL_BYTES).
+    enforceMetaByteCap(Object.entries(result));
+    return result;
+}
+/**
+ * Validates a pre-parsed key→value metadata map (e.g. an MCP tool's object
+ * argument) against the same rules as {@link parseMetaFlags} — the same
+ * per-entry validation (`validateMetaEntry`, which `parseMetaPair` also
+ * uses), the same key-count cap, and the same aggregate byte cap — without
+ * round-tripping through "k=v" string reconstruction and re-parsing first.
+ * Throws `UsageError`.
+ */
+export function validateMetaMap(meta) {
+    const entries = Object.entries(meta);
+    if (entries.length > META_MAX_KEYS) {
+        throw new UsageError(`too many --meta pairs: at most ${META_MAX_KEYS} per request`);
+    }
+    for (const [key, value] of entries)
+        validateMetaEntry(key, value);
+    enforceMetaByteCap(entries);
+}

package/dist/public-urls.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Client-side dual-host helpers (published package; no @uploads/storage dep).
+ * Keep behavior aligned with packages/storage.
+ *
+ * `UPLOADS_EMBED_PUBLIC_BASE_URL`: unset = default twin; empty = disable; URL = override.
+ */
+export declare const DEFAULT_EMBED_PUBLIC_BASE_URL = "https://embed.uploads.sh";
+export type ClientEmbedUrlOptions = {
+    embedBaseUrl?: string | null;
+    publicBaseUrl?: string | null;
+};
+export declare function embedBaseUrlFromEnv(env?: NodeJS.ProcessEnv): string | null | undefined;
+export declare function resolveEmbedBaseUrl(publicBaseUrl?: string | null, embedBaseUrl?: string | null): string | null;
+export declare function embedUrlFromPublic(publicObjectUrl: string | null | undefined, opts?: ClientEmbedUrlOptions): string | null;
+/** Prefer API `embedUrl`; otherwise derive (incl. env override). */
+export declare function resolveEmbedUrl(publicObjectUrl: string | null | undefined, apiEmbedUrl?: string | null, opts?: ClientEmbedUrlOptions): string | null;
+/** Prefer embed host for GitHub markdown; fall back to stable public URL. */
+export declare function urlForGithubEmbed(publicObjectUrl: string | null | undefined, apiEmbedUrl?: string | null, opts?: ClientEmbedUrlOptions): string | null;