@buildinternet/uploads 0.7.0 → 0.8.0

package/dist/commands.js

@@ -1,18 +1,32 @@
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { createUploadsClient } from "./client.js";
-import { parseCommandArgs, flagString, flagBool, flagInt, UsageError, } from "./cli-args.js";
+import { parseCommandArgs, flagString, flagBool, flagInt, flagValues, UsageError, } from "./cli-args.js";
 import { resolvePutDefaults, workspaceMismatch, workspaceFromToken, } from "./config.js";
 import { buildMarkdown } from "./embed.js";
+import { urlForGithubEmbed } from "./public-urls.js";
 import { UploadsError } from "./errors.js";
 import { writeJson, writeStdout } from "./io.js";
-import { ghAttachmentKey, ghKeyPrefix, attachmentsCommentBody, normalizeGithubCoordinate, } from "./github.js";
+import { parseMetaFlags, validateMetaMap } from "./metadata.js";
+import { ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, attachmentsCommentBody, normalizeGithubCoordinate, } 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";
 import { packageVersion } from "./package-version.js";
+/** Read a local file (or `-` for stdin). Missing path → FILE_NOT_FOUND (exit 2). */
+export function readFileArg(fileArg) {
+    try {
+        return new Uint8Array(readFileSync(fileArg === "-" ? 0 : fileArg));
+    }
+    catch (err) {
+        if (err?.code === "ENOENT") {
+            throw new UploadsError(`file not found: ${fileArg}`, "FILE_NOT_FOUND");
+        }
+        throw err;
+    }
+}
 // --- put ---
 const PUT_HELP = `uploads put <file> [options]
 
@@ -30,8 +44,12 @@ Uploads are public. --pr/--issue keys include the repo, number, and filename and
 remain public even for private/internal GitHub repositories. Upload only media
 that is safe at a predictable public URL.
 
+Human/json output includes durable url and (when dual-host applies) embedUrl.
+MARKDOWN prefers embedUrl for GitHub. Override: UPLOADS_EMBED_PUBLIC_BASE_URL.
+
 Options:
   --key <key>           Object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>)
+  --name <leaf>         Clean key leaf + default alt (no '/'); keeps --pr/default path. Not with --key
   --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)
@@ -53,13 +71,24 @@ Options:
   --issue <num>         Attach to an issue: key gh/<owner>/<repo>/issues/<num>/<name>
   --comment             With --pr/--issue: update one managed comment with attachments and linked galleries via local gh auth
   --gallery <id>         Add the uploaded object to this public gallery
+  --meta <k=v>          Queryable custom metadata (repeatable; value may contain "="): key ^[a-z][a-z0-9._-]{0,63}$, value 1-512 printable ASCII, max 24 pairs
+                        Re-uploading to an existing key WITH --meta replaces that file's
+                        entire metadata set; without --meta the existing metadata is
+                        preserved. Use "uploads meta set" to edit individual keys.
+  --dry-run             Print key + public URL without uploading. Not with --comment/--gallery
+
+Exit codes: 0 ok · 2 usage/token/file · 3 auth/policy · 4 network · 1 other.
+Scripted formats (json|url|markdown) also print failures on stdout.
 
 Examples:
   uploads put ./shot.png --repo myorg/myapp --ref 1722 --alt "New cards" --width 700
   uploads put ./mobile.png --frame phone
   uploads put ./ui.png --frame browser --frame-url "https://app.example/settings"
   uploads put ./shot.png --destination screenshots
+  uploads put ./capture-….webp --pr 128 --name hero.webp
+  uploads put ./shot.png --pr 128 --name hero.webp --dry-run --format url
   uploads put ./after.png --gallery gal_example
+  uploads put ./shot.png --meta app=myapp --meta page=settings
 `;
 /**
  * Turns a pr/issue pair (+ optional repo) into a GhTarget; undefined when
@@ -160,7 +189,7 @@ function frameOptionsFromFlags(flags) {
  * fatal (`comment` command) or a warning (`put --comment`).
  */
 export async function syncAttachmentsComment(client, target, run) {
-    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url }) => ({ key, url }));
+    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url, embedUrl }) => ({ key, url, embedUrl }));
     const galleries = [];
     let cursor;
     do {
@@ -183,6 +212,7 @@ export async function syncAttachmentsComment(client, target, run) {
                     .slice(0, 3)
                     .map((item) => ({
                     url: item.url,
+                    embedUrl: item.embedUrl,
                     alt: item.altText ?? item.objectKey,
                     itemUrl: item.pageUrl,
                 })),
@@ -226,12 +256,19 @@ Options:
   --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
+  --meta <k=v>          Extra queryable metadata (repeatable; value may contain "=").
+                        gh.repo/gh.kind/gh.number/gh.ref are always set from the resolved
+                        target — a --meta pair with the same key is overridden by it.
+                        Because attach always sends its own gh.* pairs, re-attaching to
+                        the same key always replaces that file's entire metadata set
+                        (never preserves) — use "uploads meta set" to add to it instead.
 
 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
+  uploads attach ./shot.png --meta app=myapp --meta page=settings
 `;
 export async function runAttach(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
@@ -253,6 +290,15 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
     const frameOpts = frameOptionsFromFlags(parsed.flags);
     const contentTypeOverride = flagString(parsed.flags, "--content-type");
+    // User-supplied extras first, then the resolved target's gh.* — explicit
+    // target pairs always win over a same-named --meta extra (documented above).
+    // Validate the merged map (not just the extras) so the 24-key/8KB caps are
+    // enforced client-side even when extras alone are under the cap but extras
+    // + the 4 gh.* pairs push the merged map over it.
+    const metaExtras = parseMetaFlags(flagValues(parsed.flags, "--meta"));
+    const metadata = { ...metaExtras, ...ghMetadataFromTarget(target) };
+    if (Object.keys(metadata).length > 0)
+        validateMetaMap(metadata);
     const results = [];
     for (const file of parsed.positionals) {
         if (file === "-")
@@ -260,7 +306,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         const sourceName = basename(file);
         if (!ctx.quiet && !ctx.json)
             process.stderr.write(`>> uploading ${file}\n`);
-        const prepared = await prepareImageForUpload(new Uint8Array(readFileSync(file)), sourceName, {
+        const prepared = await prepareImageForUpload(readFileArg(file), sourceName, {
             ...frameOpts,
             optimize: optimizeOpts,
         });
@@ -280,10 +326,12 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
                 frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
                 keepExif: optimizeOpts.keepExif === true,
             }),
+            metadata,
         });
+        const embedSrc = urlForGithubEmbed(result.url, result.embedUrl);
         results.push({
             ...result,
-            markdown: buildMarkdown(result.url, { alt: sourceName }),
+            markdown: buildMarkdown(embedSrc, { alt: sourceName }),
             optimize: {
                 optimized: prepared.optimized,
                 skippedReason: prepared.skippedReason,
@@ -310,7 +358,8 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     }
     else {
         for (const result of results) {
-            await writeStdout(`URL: ${result.url}\nMARKDOWN: ${result.markdown}\n`);
+            const embedLine = result.embedUrl ? `EMBED: ${result.embedUrl}\n` : "";
+            await writeStdout(`URL: ${result.url}\n${embedLine}MARKDOWN: ${result.markdown}\n`);
         }
         if (!ctx.quiet && comment)
             process.stderr.write(`>> attachments comment ${comment.action}\n`);
@@ -338,20 +387,41 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const ghTarget = ghTargetFromFlags(parsed.flags, run);
     const wantComment = parsed.flags.has("--comment");
     const galleryId = flagString(parsed.flags, "--gallery");
+    const nameFlag = flagString(parsed.flags, "--name");
+    const dryRun = flagBool(parsed.flags, "--dry-run");
+    // Validate --meta up front (fail fast, before reading/optimizing the file).
+    const metadata = (() => {
+        const pairs = flagValues(parsed.flags, "--meta");
+        return pairs.length > 0 ? parseMetaFlags(pairs) : undefined;
+    })();
     if (wantComment && typeof parsed.flags.get("--comment") === "string") {
         throw new UsageError("--comment takes no value — place it after the file argument");
     }
     if (wantComment && !ghTarget)
         throw new UsageError("--comment requires --pr or --issue");
     if (ghTarget) {
-        if (keyHint)
-            throw new UsageError("--key cannot be combined with --pr/--issue");
+        if (keyHint) {
+            throw new UsageError("--key cannot be combined with --pr/--issue; use --name <leaf> to set a clean filename on the stable path");
+        }
         if (flagString(parsed.flags, "--ref")) {
             throw new UsageError("--ref cannot be combined with --pr/--issue");
         }
         if (prefixFlag)
             throw new UsageError("--prefix cannot be combined with --pr/--issue");
     }
+    if (nameFlag !== undefined) {
+        if (nameFlag === "" || nameFlag.includes("/")) {
+            throw new UsageError("--name must be a bare filename with no '/'");
+        }
+        if (keyHint)
+            throw new UsageError("--name cannot be combined with --key");
+    }
+    if (dryRun) {
+        if (wantComment)
+            throw new UsageError("--dry-run cannot be combined with --comment");
+        if (galleryId)
+            throw new UsageError("--dry-run cannot be combined with --gallery");
+    }
     let resolvedPrefix;
     try {
         resolvedPrefix = resolvePutPrefix({
@@ -364,8 +434,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     catch (err) {
         throw new UsageError(err instanceof Error ? err.message : String(err));
     }
-    const bytes = fileArg === "-" ? new Uint8Array(readFileSync(0)) : new Uint8Array(readFileSync(fileArg));
-    const sourceName = fileArg === "-" ? (keyHint ? basename(keyHint) : "stdin.bin") : basename(fileArg);
+    const bytes = readFileArg(fileArg);
+    const sourceName = nameFlag ?? (fileArg === "-" ? (keyHint ? basename(keyHint) : "stdin.bin") : basename(fileArg));
     const format = ctx.json
         ? "json"
         : (() => {
@@ -379,6 +449,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const defaults = resolvePutDefaults({ envFile: ctx.envFile });
     const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
     const frameOpts = frameOptionsFromFlags(parsed.flags);
+    // Optimize even on --dry-run so the preview key extension/hash match a real put.
     const prepared = await prepareImageForUpload(bytes, sourceName, {
         ...frameOpts,
         optimize: optimizeOpts,
@@ -395,7 +466,7 @@ 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`);
+        process.stderr.write(`>> ${dryRun ? "dry run" : "uploading"} ${fileArg === "-" ? "stdin" : fileArg}\n`);
         if (prepared.frame?.framed)
             process.stderr.write(`>> framed with ${prepared.frame.frameId}\n`);
         const note = formatOptimizeNote(prepared);
@@ -414,14 +485,17 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         ref: flagString(parsed.flags, "--ref") ?? defaults.ref,
         contentType: prepared.optimized ? prepared.contentType : contentTypeOverride,
         deriveRepoFromGit: !noGit,
+        dryRun,
         provenance: buildCliProvenance({
             sourceName,
             optimized: prepared.optimized,
             frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
             keepExif: optimizeOpts.keepExif === true,
         }),
+        metadata,
     });
-    const markdown = buildMarkdown(result.url, { alt, width });
+    const embedSrc = urlForGithubEmbed(result.url, result.embedUrl);
+    const markdown = buildMarkdown(embedSrc, { alt, width });
     let gallery;
     if (galleryId) {
         try {
@@ -446,7 +520,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         filename: prepared.filename,
     };
     if (!ctx.quiet && format === "human") {
-        process.stderr.write(`>> key: ${result.key}\n\n`);
+        process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n\n`);
     }
     switch (format) {
         case "json":
@@ -456,6 +530,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 optimize: optimizeMeta,
                 frame: prepared.frame,
                 gallery,
+                ...(dryRun ? { dryRun: true } : {}),
             });
             break;
         case "url":
@@ -464,8 +539,10 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         case "markdown":
             await writeStdout(`${markdown}\n`);
             break;
-        default:
-            await writeStdout(`URL: ${result.url}\nMARKDOWN: ${markdown}${gallery?.url ? `\nGALLERY: ${gallery.url}` : ""}\n`);
+        default: {
+            const embedLine = result.embedUrl ? `EMBED: ${result.embedUrl}\n` : "";
+            await writeStdout(`URL: ${result.url}\n${embedLine}MARKDOWN: ${markdown}${gallery?.url ? `\nGALLERY: ${gallery.url}` : ""}\n`);
+        }
     }
     if (gallery?.url && format !== "human") {
         process.stderr.write(`gallery: ${gallery.url}\n`);
@@ -703,21 +780,51 @@ export async function runGallery(ctx, args, help = false) {
     }
 }
 // --- list ---
-const LIST_HELP = `uploads list [--prefix <p>] [--pr <num> | --issue <num>] [--repo <owner/name>] [--limit <n>] [--cursor <c>] [--all] [--workspace <name>]
+const LIST_HELP = `uploads list [--prefix <p>] [--pr <num> | --issue <num>] [--repo <owner/name>] [--limit <n>] [--cursor <c>] [--all] [--meta <k=v>]... [--workspace <name>]
 
 Default prefix: UPLOADS_DEFAULT_PREFIX (screenshots if unset).
 
+--meta <k=v> (repeatable, ANDed) switches to the metadata filter endpoint —
+returned items include their matched metadata. Combines with --prefix, not
+with --pr/--issue/--all. See also: uploads find (positional-pair alias).
+
 Examples:
   uploads list --prefix screenshots/
   uploads list --pr 123
   uploads list --all --json
+  uploads list --meta gh.repo=buildinternet/uploads --meta gh.number=123
 `;
+/** `--meta k=v` (repeatable) filter path, shared by `runList` and `runFind`. */
+async function runFindFiles(ctx, filters, flags) {
+    if (flagString(flags, "--cursor") !== undefined) {
+        throw new UsageError("--cursor is not supported with metadata filters");
+    }
+    const prefix = flagString(flags, "--prefix");
+    const limit = flagInt(flags, "--limit", "--limit");
+    const result = await ctx.client.findFiles(filters, { prefix, limit });
+    if (ctx.json)
+        await writeJson(result);
+    else
+        for (const item of result.items)
+            await writeStdout(`${item.key}${item.url ? `  ${item.url}` : ""}\n`);
+    return 0;
+}
 export async function runList(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
         process.stderr.write(LIST_HELP);
         return 0;
     }
+    const metaPairs = flagValues(parsed.flags, "--meta");
+    if (metaPairs.length > 0) {
+        if (ghTargetFromFlags(parsed.flags, run)) {
+            throw new UsageError("--meta cannot be combined with --pr/--issue");
+        }
+        if (flagBool(parsed.flags, "--all")) {
+            throw new UsageError("--meta cannot be combined with --all");
+        }
+        return runFindFiles(ctx, parseMetaFlags(metaPairs), parsed.flags);
+    }
     const defaults = resolvePutDefaults({ envFile: ctx.envFile });
     const prefixFlag = flagString(parsed.flags, "--prefix");
     let prefix = prefixFlag ?? (defaults.prefix ? `${defaults.prefix}/` : undefined);
@@ -750,6 +857,89 @@ export async function runList(ctx, args, help = false, run = execRunner) {
     }
     return 0;
 }
+// --- find ---
+const FIND_HELP = `uploads find k=v [k=v...] [--prefix <p>] [--limit <n>] [--workspace <name>]
+
+Human-friendly alias for \`uploads list --meta k=v...\` — same metadata filter
+(ANDed equality), same output; pairs are positional instead of repeated flags.
+
+Examples:
+  uploads find gh.repo=buildinternet/uploads gh.number=123
+  uploads find app=myapp page=settings --prefix screenshots/
+`;
+export async function runFind(ctx, args, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        process.stderr.write(FIND_HELP);
+        return 0;
+    }
+    if (parsed.positionals.length === 0) {
+        process.stderr.write(FIND_HELP);
+        return 2;
+    }
+    const filters = parseMetaFlags(parsed.positionals);
+    return runFindFiles(ctx, filters, parsed.flags);
+}
+// --- meta ---
+const META_HELP = `uploads meta <command> [args]
+
+Read/write an object's queryable custom metadata (D1-backed key-value pairs;
+distinct from the R2 provenance headers put on upload).
+
+Commands:
+  get <key>                            Show metadata for an object
+  set <key> k=v [k=v...] [--delete k]...   Merge-set and/or delete pairs
+
+Examples:
+  uploads meta get screenshots/myapp/42/shot.png
+  uploads meta set screenshots/myapp/42/shot.png app=myapp page=settings
+  uploads meta set screenshots/myapp/42/shot.png --delete app --delete page
+`;
+export async function runMeta(ctx, args, help = false) {
+    const parsed = parseCommandArgs(args);
+    const action = parsed.positionals[0];
+    if (help || parsed.help || !action) {
+        process.stderr.write(META_HELP);
+        return help || parsed.help ? 0 : 2;
+    }
+    switch (action) {
+        case "get": {
+            const key = parsed.positionals[1];
+            if (!key)
+                throw new UsageError("meta get requires an object key");
+            const result = await ctx.client.getMetadata(key);
+            if (ctx.json)
+                await writeJson(result);
+            else
+                for (const [k, v] of Object.entries(result.metadata))
+                    await writeStdout(`${k}=${v}\n`);
+            return 0;
+        }
+        case "set": {
+            const key = parsed.positionals[1];
+            if (!key)
+                throw new UsageError("meta set requires an object key");
+            const pairs = parsed.positionals.slice(2);
+            const del = flagValues(parsed.flags, "--delete");
+            if (pairs.length === 0 && del.length === 0) {
+                throw new UsageError("meta set requires k=v pairs and/or --delete <key>");
+            }
+            const set = pairs.length > 0 ? parseMetaFlags(pairs) : undefined;
+            const result = await ctx.client.patchMetadata(key, {
+                set,
+                delete: del.length > 0 ? del : undefined,
+            });
+            if (ctx.json)
+                await writeJson(result);
+            else
+                for (const [k, v] of Object.entries(result.metadata))
+                    await writeStdout(`${k}=${v}\n`);
+            return 0;
+        }
+        default:
+            throw new UsageError(`unknown meta command: ${action}`);
+    }
+}
 // --- delete ---
 const DELETE_HELP = `uploads delete <key> [--dry-run] [--workspace <name>]
 

package/dist/config.js

@@ -140,11 +140,14 @@ export function resolveConfig(flags) {
 }
 function missingTokenMessage(configPath) {
     return [
-        "UPLOADS_TOKEN is required.",
-        "  uploads login                         # exchange an admin-provided enrollment code",
+        "You're not signed in yet — one quick step and you're set:",
+        "",
+        "  uploads login                         # open a browser and authorize this device",
+        "",
+        "Already have a token?",
         `  uploads setup --token <token>         # guided setup → ${configPath}`,
         `  uploads config init --token <token>   # writes ${configPath}`,
-        "  or set UPLOADS_TOKEN in env, pass --token, or use --env-file",
+        "  or set UPLOADS_TOKEN / pass --token / use --env-file",
     ].join("\n");
 }
 /** Warn when an explicit workspace override may not match the token's embedded workspace. */

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_KEY" | "KEY_POLICY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "API_ERROR" | "NETWORK" | "USAGE";
+export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "FILE_NOT_FOUND" | "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/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,
+};