@buildinternet/uploads 0.36.0 → 0.37.1

package/dist/cli-catalog.js

@@ -173,15 +173,17 @@ export const ROOT_COMMANDS = [
     },
     {
         name: "find",
-        usage: "find k=v...",
-        summary: "List objects matching metadata (alias for list --meta)",
+        usage: "find [k=v...] [--name <term>]",
+        summary: "Find objects by metadata and/or filename substring",
     },
     {
         name: "meta",
-        summary: "Get/set an object's queryable metadata",
+        summary: "Get/set object metadata; discover workspace keys/values",
         subcommands: [
             { name: "get", summary: "Show metadata for an object" },
             { name: "set", summary: "Merge-set and/or delete metadata pairs" },
+            { name: "keys", summary: "List distinct metadata keys in the workspace" },
+            { name: "values", summary: "List distinct values for one metadata key" },
         ],
     },
     {

package/dist/client.d.ts

@@ -47,6 +47,11 @@ export interface ListOptions {
 export interface FindFilesOptions {
     prefix?: string;
     limit?: number;
+    /**
+     * Case-insensitive substring match on object keys (`?name=`).
+     * At least one of non-empty `filters` or `name` is required.
+     */
+    name?: string;
 }
 export interface FindFilesItem {
     key: string;
@@ -56,6 +61,24 @@ export interface FindFilesItem {
 export interface FindFilesResult {
     items: FindFilesItem[];
     cursor: string | null;
+    /** Present when a `name` term was used — true if the underlying query hit its cap. */
+    truncated?: boolean;
+}
+export interface MetadataKeysResult {
+    keys: Array<{
+        key: string;
+        count: number;
+        distinctValues: number;
+    }>;
+    truncated: boolean;
+}
+export interface MetadataValuesResult {
+    key: string;
+    values: Array<{
+        value: string;
+        count: number;
+    }>;
+    truncated: boolean;
 }
 export interface GetMetadataResult {
     metadata: Record<string, string>;
@@ -220,7 +243,7 @@ export interface FindGalleriesByReferenceOptions {
  * anyway, defeating the point of the server-side gate, so the CLI surfaces
  * the decline instead.
  */
-export type GithubCommentDeclineReason = "app_unconfigured" | "not_installed" | "forbidden" | "not_authorized" | "unavailable";
+export type GithubCommentDeclineReason = "app_unconfigured" | "not_installed" | "forbidden" | "not_authorized" | "actor_not_authorized" | "unavailable";
 export type GithubCommentResult = {
     posted: true;
     action: "created" | "updated" | "skipped";
@@ -523,10 +546,16 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
     /** `PATCH /v1/:workspace/files/:key` — merge `set`/`delete`; returns the merged map. */
     patchMetadata(key: string, opts: PatchMetadataOptions): Promise<GetMetadataResult>;
     /**
-     * `GET /v1/:workspace/files?meta.<k>=<v>&…` — ANDed equality filter over
-     * queryable metadata. `filters` must be pre-validated (see `metadata.ts`).
+     * `GET /v1/:workspace/files?meta.<k>=<v>&…&name=…` — ANDed equality filter
+     * over queryable metadata and/or a case-insensitive filename substring.
+     * At least one of non-empty `filters` or `opts.name` is required.
+     * `filters` must be pre-validated when present (see `metadata.ts`).
      */
-    findFiles(filters: Record<string, string>, opts?: FindFilesOptions): Promise<FindFilesResult>;
+    findFiles(filters?: Record<string, string>, opts?: FindFilesOptions): Promise<FindFilesResult>;
+    /** `GET /v1/:workspace/files/facets` — workspace metadata key vocabulary. */
+    listMetadataKeys(): Promise<MetadataKeysResult>;
+    /** `GET /v1/:workspace/files/facets?key=` — distinct values for one key. */
+    listMetadataValues(key: string): Promise<MetadataValuesResult>;
     head(key: string): Promise<HeadResult>;
     createGallery(opts: CreateGalleryOptions): Promise<Gallery>;
     getGallery(id: string): Promise<Gallery>;

package/dist/client.js

@@ -405,19 +405,31 @@ export function createUploadsClient(config) {
             });
         },
         /**
-         * `GET /v1/:workspace/files?meta.<k>=<v>&…` — ANDed equality filter over
-         * queryable metadata. `filters` must be pre-validated (see `metadata.ts`).
+         * `GET /v1/:workspace/files?meta.<k>=<v>&…&name=…` — ANDed equality filter
+         * over queryable metadata and/or a case-insensitive filename substring.
+         * At least one of non-empty `filters` or `opts.name` is required.
+         * `filters` must be pre-validated when present (see `metadata.ts`).
          */
-        async findFiles(filters, opts = {}) {
+        async findFiles(filters = {}, opts = {}) {
             const params = new URLSearchParams();
             for (const [k, v] of Object.entries(filters))
                 params.append(`meta.${k}`, v);
+            if (opts.name)
+                params.set("name", opts.name);
             if (opts.prefix)
                 params.set("prefix", opts.prefix);
             if (opts.limit != null)
                 params.set("limit", String(opts.limit));
             return request("GET", `${filesBase(config)}?${params.toString()}`);
         },
+        /** `GET /v1/:workspace/files/facets` — workspace metadata key vocabulary. */
+        async listMetadataKeys() {
+            return request("GET", `${filesBase(config)}/facets`);
+        },
+        /** `GET /v1/:workspace/files/facets?key=` — distinct values for one key. */
+        async listMetadataValues(key) {
+            return request("GET", `${filesBase(config)}/facets?${new URLSearchParams({ key })}`);
+        },
         async head(key) {
             const result = await request("GET", `${filesBase(config)}/${encodeKeyPath(key)}`);
             return { ...result, embedUrl: resolveEmbedUrl(result.url, result.embedUrl) };

package/dist/commands.d.ts

@@ -165,8 +165,10 @@ export interface AttachmentsCommentResult {
 export declare function commentViaSuffix(via: AttachmentsCommentResult["via"]): string;
 /**
  * Thrown by `syncAttachmentsComment` when the server declines with
- * `not_authorized` (issue #297 baseline control) — this repo is bound to a
- * different workspace. Deliberately not caught by the generic "bot endpoint
+ * `not_authorized` (issue #297 baseline control — this repo is bound to a
+ * different workspace) or `actor_not_authorized` (issue #297 control 2 — the
+ * workspace requires the caller to be on the target PR/issue thread).
+ * Deliberately not caught by the generic "bot endpoint
  * unreachable" fallback below: falling back to gh here would let the
  * human's own credentials post anyway, defeating the point of the
  * server-side gate.
@@ -490,6 +492,19 @@ export interface DoctorReport {
     scopes?: string[];
     /** Workspace/token mismatch warning (also present in hints). */
     warning?: string;
+    /**
+     * Bring-your-own-bucket storage status (issue #583 Phase 3). `GET
+     * /me/workspaces/:name/storage` is session-gated (Better Auth cookie or
+     * bearer via the AUTH service — see `session-auth.ts`); the CLI only ever
+     * holds a minted `up_<workspace>_…` workspace token, never a session
+     * bearer, so doctor cannot reach that route today. Until a token-authed
+     * read path exists, this is an honest "can't check from here" rather than
+     * a fabricated mode.
+     */
+    storage: {
+        checked: false;
+        note: string;
+    };
     hints: string[];
     /** `screenshot`'s local-browser detection (fs scans only — never launches a browser). */
     browser: {

package/dist/commands.js

@@ -447,8 +447,10 @@ export function commentViaSuffix(via) {
 }
 /**
  * Thrown by `syncAttachmentsComment` when the server declines with
- * `not_authorized` (issue #297 baseline control) — this repo is bound to a
- * different workspace. Deliberately not caught by the generic "bot endpoint
+ * `not_authorized` (issue #297 baseline control — this repo is bound to a
+ * different workspace) or `actor_not_authorized` (issue #297 control 2 — the
+ * workspace requires the caller to be on the target PR/issue thread).
+ * Deliberately not caught by the generic "bot endpoint
  * unreachable" fallback below: falling back to gh here would let the
  * human's own credentials post anyway, defeating the point of the
  * server-side gate.
@@ -485,6 +487,14 @@ export async function syncAttachmentsComment(client, target, run, workspace, opt
                 `Run \`uploads github link --status --repo ${target.repo}\` to see who owns the ` +
                 `binding, use that workspace instead, or post the comment manually with gh.`);
         }
+        // Actor-on-PR gate (issue #297 control 2, workspace opt-in): same
+        // no-gh-fallback rule as not_authorized — the workspace explicitly asked
+        // the server to hold this line, so the CLI shouldn't route around it.
+        if (bot.reason === "actor_not_authorized") {
+            throw new GithubCommentAuthorizationError(`${bot.message ?? `You are not an actor on ${target.repo}#${target.num}.`}\n` +
+                `Ask an authorized thread participant to run this, or post the ` +
+                `comment manually with gh.`);
+        }
         // Installed-but-unapproved is a fixable misconfiguration, not a silent
         // degrade: tell the user (and how to fix it) before falling back to gh.
         if (bot.reason === "forbidden" && bot.message) {
@@ -1384,7 +1394,7 @@ export function mergeStagingMeta(base, target) {
  * for both the human-mode stderr line and the JSON `hint` field.
  */
 export function putStagingNoteText(branch) {
-    return (`note: staged for branch ${branch} — auto-attaches to this branch's PR when it opens ` +
+    return (`note: staged for branch ${branch} — auto-comments to pull request when opened ` +
         `(or run: uploads attach --promote once it exists). Use --ref/--prefix for a plain dated upload.`);
 }
 /**
@@ -2134,31 +2144,45 @@ 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] [--meta <k=v>]... [--workspace <name>]
+const LIST_HELP = `uploads list [--prefix <p>] [--pr <num> | --issue <num>] [--repo <owner/name>] [--limit <n>] [--cursor <c>] [--all] [--meta <k=v>]... [--name <term>] [--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).
+--meta <k=v> (repeatable, ANDed) and/or --name <term> switch to the search
+endpoint — returned items include their matched metadata. Combines with
+--prefix, not with --pr/--issue/--all. --name is a case-insensitive
+substring match on object keys. See also: uploads find.
 
 Examples:
   uploads list --prefix screenshots/
   uploads list --pr 123
   uploads list --all --json
   uploads list --meta gh.repo=buildinternet/uploads --meta gh.number=123
+  uploads list --name hero --meta app=web
 `;
-/** `--meta k=v` (repeatable) filter path, shared by `runList` and `runFind`. */
-async function runFindFiles(ctx, filters, flags) {
+/** Human-mode stderr note when a paged API response was capped server-side. */
+function writeTruncatedNotice(truncated, quiet, detail) {
+    if (truncated && !quiet) {
+        process.stderr.write(`truncated: true (${detail})\n`);
+    }
+}
+/** `--meta` / `--name` search path, shared by `runList` and `runFind`. */
+async function runFindFiles(ctx, filters, flags, name) {
     if (flagString(flags, "--cursor") !== undefined) {
-        throw new UsageError("--cursor is not supported with metadata filters");
+        throw new UsageError("--cursor is not supported with metadata or name filters");
     }
     const prefix = flagString(flags, "--prefix");
     const limit = flagInt(flags, "--limit", "--limit");
-    const result = await ctx.client.findFiles(filters, { prefix, limit });
+    const nameTerm = name ?? flagString(flags, "--name");
+    if (Object.keys(filters).length === 0 && !nameTerm) {
+        throw new UsageError("find requires at least one k=v pair, --meta k=v, or --name <term>", {
+            example: "uploads find path=/settings state=after",
+        });
+    }
+    const result = await ctx.client.findFiles(filters, { prefix, limit, name: nameTerm });
     if (ctx.json)
         await writeJson(result);
-    else
+    else {
         for (const item of result.items) {
             // LIST_HELP promises matched metadata in the output; render it inline
             // (sorted for stable output) so human mode honors that, not just --json.
@@ -2168,6 +2192,8 @@ async function runFindFiles(ctx, filters, flags) {
                 .join(" ");
             await writeStdout(`${item.key}${item.url ? `  ${item.url}` : ""}${meta ? `  ${meta}` : ""}\n`);
         }
+        writeTruncatedNotice(result.truncated, ctx.quiet, "more matches may exist beyond this page");
+    }
     return 0;
 }
 export async function runList(ctx, args, help = false, run = execRunner) {
@@ -2177,14 +2203,15 @@ export async function runList(ctx, args, help = false, run = execRunner) {
         return 0;
     }
     const metaPairs = flagValues(parsed.flags, "--meta");
-    if (metaPairs.length > 0) {
+    const nameFlag = flagString(parsed.flags, "--name");
+    if (metaPairs.length > 0 || nameFlag !== undefined) {
         if (ghTargetFromFlags(parsed.flags, run)) {
-            throw new UsageError("--meta cannot be combined with --pr/--issue");
+            throw new UsageError("--meta/--name cannot be combined with --pr/--issue");
         }
         if (flagBool(parsed.flags, "--all")) {
-            throw new UsageError("--meta cannot be combined with --all");
+            throw new UsageError("--meta/--name cannot be combined with --all");
         }
-        return runFindFiles(ctx, parseMetaFlags(metaPairs), parsed.flags);
+        return runFindFiles(ctx, metaPairs.length > 0 ? parseMetaFlags(metaPairs) : {}, parsed.flags, nameFlag);
     }
     const defaults = resolvePutDefaults({ envFile: ctx.envFile });
     const prefixFlag = flagString(parsed.flags, "--prefix");
@@ -2219,15 +2246,21 @@ 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>]
+const FIND_HELP = `uploads find [k=v...] [--meta k=v]... [--name <term>] [--prefix <p>] [--limit <n>] [--workspace <name>]
+
+Find objects by queryable metadata (ANDed equality) and/or a case-insensitive
+filename substring. Same output as \`uploads list --meta\` / \`--name\`.
 
-Human-friendly alias for \`uploads list --meta k=v...\` — same metadata filter
-(ANDed equality), same output; pairs are positional, or spelled --meta k=v.
+Pairs are positional k=v, or spelled --meta k=v. A bare positional without
+\`=\` is treated as --name (e.g. \`uploads find hero\`). At least one of a
+meta pair or a name term is required.
 
 Examples:
   uploads find gh.repo=buildinternet/uploads gh.number=123
   uploads find path=/settings state=after --prefix screenshots/
   uploads find --meta path=/settings
+  uploads find hero
+  uploads find --name hero --meta app=web
 `;
 export async function runFind(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
@@ -2237,24 +2270,43 @@ export async function runFind(ctx, args, help = false) {
     }
     // Same flag/positional symmetry as `meta set` (issue #545): `find` is the
     // alias for `list --meta`, so `find --meta k=v` must not dead-end.
-    const pairs = [...parsed.positionals, ...flagValues(parsed.flags, "--meta")];
-    if (pairs.length === 0) {
-        throw new UsageError("find requires at least one k=v pair (or --meta k=v)", {
-            example: "uploads find path=/settings state=after",
+    // Bare positionals without `=` are the filename term (issue #528) so
+    // `uploads find hero` works without a flag. Empty input is rejected inside
+    // `runFindFiles` (shared with `list --name` / `--meta`).
+    const nameFlag = flagString(parsed.flags, "--name");
+    const kvPositionals = [];
+    const bareNames = [];
+    for (const pos of parsed.positionals) {
+        if (pos.includes("="))
+            kvPositionals.push(pos);
+        else
+            bareNames.push(pos);
+    }
+    if (bareNames.length > 1) {
+        throw new UsageError("find accepts at most one bare name term (or use --name)", {
+            example: "uploads find hero --meta app=web",
+        });
+    }
+    if (bareNames.length === 1 && nameFlag !== undefined) {
+        throw new UsageError("pass the name term either as a bare positional or --name, not both", {
+            example: "uploads find hero",
         });
     }
-    const filters = parseMetaFlags(pairs);
-    return runFindFiles(ctx, filters, parsed.flags);
+    const pairs = [...kvPositionals, ...flagValues(parsed.flags, "--meta")];
+    return runFindFiles(ctx, pairs.length > 0 ? parseMetaFlags(pairs) : {}, parsed.flags, nameFlag ?? bareNames[0]);
 }
 // --- 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).
+distinct from the R2 provenance headers put on upload). Discover which keys
+and values exist in the workspace before filtering with find/list.
 
 Commands:
   get <key>                            Show metadata for an object
   set <key> k=v [k=v...] [--delete k]...   Merge-set and/or delete pairs
+  keys                                 List distinct metadata keys (with counts)
+  values <meta-key>                    List distinct values for one key
 
 Pairs take either form: positional k=v, or --meta k=v (same spelling as
 put/screenshot/list). Both can appear in one call.
@@ -2264,6 +2316,8 @@ Examples:
   uploads meta set screenshots/myapp/42/shot.png path=/settings state=after
   uploads meta set screenshots/myapp/42/shot.png --meta path=/settings
   uploads meta set screenshots/myapp/42/shot.png --delete path --delete state
+  uploads meta keys
+  uploads meta values app
 `;
 export async function runMeta(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
@@ -2273,7 +2327,7 @@ export async function runMeta(ctx, args, help = false) {
         return 0;
     }
     if (!action) {
-        throw new UsageError("meta requires a subcommand: get or set", {
+        throw new UsageError("meta requires a subcommand: get, set, keys, or values", {
             example: "uploads meta set screenshots/myapp/42/shot.png --meta path=/settings",
         });
     }
@@ -2330,8 +2384,40 @@ export async function runMeta(ctx, args, help = false) {
             await resyncCommentAfterMetaSet(ctx, key, [...Object.keys(set ?? {}), ...del]);
             return 0;
         }
+        case "keys": {
+            // Workspace vocabulary discovery (issue #528) — which meta keys exist
+            // and how common they are, before agents guess at find filters.
+            const result = await ctx.client.listMetadataKeys();
+            if (ctx.json)
+                await writeJson(result);
+            else {
+                for (const row of result.keys) {
+                    await writeStdout(`${row.key}  count=${row.count}  distinct=${row.distinctValues}\n`);
+                }
+                writeTruncatedNotice(result.truncated, ctx.quiet, "more keys may exist beyond this page");
+            }
+            return 0;
+        }
+        case "values": {
+            const key = parsed.positionals[1];
+            if (!key) {
+                throw new UsageError("meta values requires a metadata key", {
+                    example: "uploads meta values app",
+                });
+            }
+            const result = await ctx.client.listMetadataValues(key);
+            if (ctx.json)
+                await writeJson(result);
+            else {
+                for (const row of result.values) {
+                    await writeStdout(`${row.value}  count=${row.count}\n`);
+                }
+                writeTruncatedNotice(result.truncated, ctx.quiet, "more values may exist beyond this page");
+            }
+            return 0;
+        }
         default:
-            throw new UsageError(`unknown meta command: ${action} (expected get or set)`, {
+            throw new UsageError(`unknown meta command: ${action} (expected get, set, keys, or values)`, {
                 example: "uploads meta get screenshots/myapp/42/shot.png",
             });
     }
@@ -2845,6 +2931,10 @@ export async function buildDoctorReport(config, client, detectRoots) {
         usage,
         scopes,
         warning: mismatch,
+        storage: {
+            checked: false,
+            note: "not checked from the CLI — storage settings (shared vs. bring-your-own-bucket) live behind a signed-in session; sign in on the web (Account → workspace → Settings) to view mode and verification status",
+        },
         hints,
         browser,
     };
@@ -2881,6 +2971,7 @@ export async function runDoctor(ctx, args, help = false) {
     else {
         lines.push(`browser:   ${report.browser.note ?? "not supported in this runtime"}`);
     }
+    lines.push(`storage:   ${report.storage.note}`);
     if (report.warning)
         lines.push(`warning:   ${report.warning}`);
     for (const h of report.hints)

package/dist/github.d.ts

@@ -76,8 +76,8 @@ export declare function attachmentsMarker(workspace?: string): string;
 export declare const MAX_INLINE_ATTACHMENT_IMAGES = 16;
 /**
  * Per-render knobs for the managed comment (issue #307), sourced from repo
- * comment config. `imageWidth: "auto"` preserves today's per-item width
- * heuristics (`attachmentImageWidth`/`posterImageWidth`/pair cap); `"full"`
+ * comment config. `imageWidth: "auto"` uses per-item filename heuristics plus
+ * density-aware sizing (solo/sparse/dense from the inlined count); `"full"`
  * omits the `width` attribute entirely; a number overrides every width site.
  */
 export interface CommentRenderOptions {
@@ -134,21 +134,29 @@ export interface GalleryCommentItem {
         itemUrl?: string;
     }[];
 }
-/** Default max width for images in the managed attachments comment (HTML img). */
+/**
+ * How crowded the managed comment is. Sparse comments (one shot, a single
+ * before/after) get larger embeds; dense comments keep compact historical sizes.
+ */
+export type AttachmentDensity = "solo" | "sparse" | "dense";
+/** Dense (historical) default max width for images in the managed comment. */
 export declare const ATTACHMENT_IMAGE_WIDTH_DEFAULT = 400;
 /** Portrait / device mockups — keep phones readable, not full-column. */
 export declare const ATTACHMENT_IMAGE_WIDTH_PORTRAIT = 280;
 /** Wide UI / browser chrome. */
 export declare const ATTACHMENT_IMAGE_WIDTH_WIDE = 640;
+/** Dense pair-cell cap (side-by-side before/after). */
+export declare const ATTACHMENT_IMAGE_WIDTH_PAIR = 320;
+/** Map an inlined-media count onto a density tier. */
+export declare function attachmentDensityForCount(inlinedCount: number): AttachmentDensity;
+/** Pair-cell cap for the given density. */
+export declare function attachmentPairWidth(density?: AttachmentDensity): number;
 /**
- * Pick a display width for GitHub comment embeds. Filenames are a weak but
- * practical signal (we don't re-fetch dimensions when rebuilding the comment).
+ * Display width for a GitHub comment embed. Filenames are a weak but practical
+ * signal (we don't re-fetch dimensions when rebuilding the comment). `density`
+ * only affects managed-comment auto layout; other callers leave it `"dense"`.
  */
-export declare function attachmentImageWidth(filename: string): number;
-/** Max display width for one image inside a before/after pair row — smaller
- * than a standalone image so two side by side stay under GitHub's comment
- * column width (and don't overflow on mobile). */
-export declare const ATTACHMENT_IMAGE_WIDTH_PAIR = 320;
+export declare function attachmentImageWidth(filename: string, density?: AttachmentDensity): number;
 /**
  * Render the one marker-owned GitHub comment. When there are no galleries this
  * intentionally preserves the legacy attachment-only body byte-for-byte.

package/dist/github.js

@@ -171,26 +171,52 @@ export const AUTO_RENDER_OPTIONS = {
     metaState: true,
     note: null,
 };
-/** Default max width for images in the managed attachments comment (HTML img). */
+/** Dense (historical) default max width for images in the managed comment. */
 export const ATTACHMENT_IMAGE_WIDTH_DEFAULT = 400;
 /** Portrait / device mockups — keep phones readable, not full-column. */
 export const ATTACHMENT_IMAGE_WIDTH_PORTRAIT = 280;
 /** Wide UI / browser chrome. */
 export const ATTACHMENT_IMAGE_WIDTH_WIDE = 640;
+/** Dense pair-cell cap (side-by-side before/after). */
+export const ATTACHMENT_IMAGE_WIDTH_PAIR = 320;
+/** Per-density widths for `imageWidth: "auto"`. Dense reuses the exports above. */
+const WIDTH_BY_DENSITY = {
+    solo: { default: 720, portrait: 360, wide: 800, pair: 400 },
+    sparse: { default: 560, portrait: 300, wide: 720, pair: 380 },
+    dense: {
+        default: ATTACHMENT_IMAGE_WIDTH_DEFAULT,
+        portrait: ATTACHMENT_IMAGE_WIDTH_PORTRAIT,
+        wide: ATTACHMENT_IMAGE_WIDTH_WIDE,
+        pair: ATTACHMENT_IMAGE_WIDTH_PAIR,
+    },
+};
+/** Map an inlined-media count onto a density tier. */
+export function attachmentDensityForCount(inlinedCount) {
+    if (inlinedCount <= 1)
+        return "solo";
+    if (inlinedCount <= 3)
+        return "sparse";
+    return "dense";
+}
+/** Pair-cell cap for the given density. */
+export function attachmentPairWidth(density = "dense") {
+    return WIDTH_BY_DENSITY[density].pair;
+}
 /**
- * Pick a display width for GitHub comment embeds. Filenames are a weak but
- * practical signal (we don't re-fetch dimensions when rebuilding the comment).
+ * Display width for a GitHub comment embed. Filenames are a weak but practical
+ * signal (we don't re-fetch dimensions when rebuilding the comment). `density`
+ * only affects managed-comment auto layout; other callers leave it `"dense"`.
  */
-export function attachmentImageWidth(filename) {
+export function attachmentImageWidth(filename, density = "dense") {
+    const table = WIDTH_BY_DENSITY[density];
     const n = filename.toLowerCase();
-    if (/(?:^|[-_.])(browser|desktop|dashboard|wide)(?:[-_.]|$)/.test(n)) {
-        return ATTACHMENT_IMAGE_WIDTH_WIDE;
-    }
+    if (/(?:^|[-_.])(browser|desktop|dashboard|wide)(?:[-_.]|$)/.test(n))
+        return table.wide;
     if (/(?:^|[-_.])(phone|iphone|ipad|pixel|android|mobile|device)(?:[-_.]|$)/.test(n) ||
         /iphone|pixel-?\d/.test(n)) {
-        return ATTACHMENT_IMAGE_WIDTH_PORTRAIT;
+        return table.portrait;
     }
-    return ATTACHMENT_IMAGE_WIDTH_DEFAULT;
+    return table.default;
 }
 /** `m:ss` under an hour, `h:mm:ss` at or above one. */
 function formatDuration(seconds) {
@@ -205,19 +231,16 @@ function formatDuration(seconds) {
 }
 /**
  * Display width for a video poster. Real dimensions only *select* among the
- * width constants — a raw 1920 would blow out the comment column — and the
- * result is capped at the real width so a small clip is never upscaled.
+ * density table's tiers — a raw 1920 would blow out the comment column — and
+ * the result is capped at the real width so a small clip is never upscaled.
  */
-function posterImageWidth(videoMeta, filename) {
+function posterImageWidth(videoMeta, filename, density = "dense") {
     const w = videoMeta?.width ?? 0;
     const h = videoMeta?.height ?? 0;
     if (w <= 0 || h <= 0)
-        return attachmentImageWidth(filename);
-    const chosen = h > w
-        ? ATTACHMENT_IMAGE_WIDTH_PORTRAIT
-        : w / h >= 16 / 9
-            ? ATTACHMENT_IMAGE_WIDTH_WIDE
-            : ATTACHMENT_IMAGE_WIDTH_DEFAULT;
+        return attachmentImageWidth(filename, density);
+    const table = WIDTH_BY_DENSITY[density];
+    const chosen = h > w ? table.portrait : w / h >= 16 / 9 ? table.wide : table.default;
     return Math.min(chosen, w);
 }
 function escapeHtmlAttr(s) {
@@ -236,45 +259,37 @@ function escapeMarkdownText(s) {
     return s.replace(/([\\`*_[\]~])/g, "\\$1");
 }
 /**
- * An attachment's caption parts — `path`, then `state` (issue #365). Empty
- * when neither is usable, so callers emit nothing at all and a body with no
- * metadata stays byte-identical to the pre-#365 render.
- *
- * Neither value is pre-sanitized: metadata values are printable ASCII up to
- * 512 chars, and while the CLI validates `--state` against a closed enum,
- * `PATCH /v1/:workspace/files/:key` can set any valid metadata value. A
- * whitespace-only value passes that validation (length-1 printable ASCII), so
- * treat it as absent rather than rendering a dangling separator.
- *
- * Bare `/` is stored/searchable but omitted from captions (issue #375) —
- * alone it is a stray character, and as a prefix next to `state` it is
- * noise. Only exact `/` after trim is suppressed.
+ * Collect path then state for a caption (issue #365). Bare `/` and
+ * whitespace-only values are omitted (issue #375). Empty when nothing usable.
  */
-function metaCaptionParts(meta, options) {
-    const parts = [];
+function metaCaptionValues(meta, options) {
+    const values = [];
     const path = meta?.path?.trim();
     if (options.metaPath && path && path !== "/")
-        parts.push(path);
+        values.push(path);
     const state = meta?.state?.trim();
     if (options.metaState && state)
-        parts.push(state);
-    return parts;
-}
-/** `<sub>` caption body for an inline image, or null when there is nothing to say. */
-function metaCaptionHtml(meta, options) {
-    const parts = metaCaptionParts(meta, options);
-    return parts.length > 0 ? parts.map(escapeHtmlText).join(" · ") : null;
+        values.push(state);
+    return values;
 }
 /**
- * ` · …` suffix for a markdown list row, or `""` when there is nothing to add.
- * HTML-escapes first, then markdown-escapes: HTML escaping introduces no
- * backslashes or brackets, so the markdown pass cannot corrupt its entities.
+ * Format path/state as code tokens. HTML → `<code>…</code>`; markdown →
+ * `` `…` `` (backslash-escape if the value itself contains a backtick).
+ * Returns `""` when there is nothing to say.
  */
-function metaCaptionMarkdown(meta, options) {
-    const parts = metaCaptionParts(meta, options);
-    if (parts.length === 0)
+function formatMetaCaption(meta, options, mode) {
+    const values = metaCaptionValues(meta, options);
+    if (values.length === 0)
         return "";
-    return ` · ${parts.map((p) => escapeMarkdownText(escapeHtmlText(p))).join(" · ")}`;
+    if (mode === "html") {
+        return values.map((v) => `<code>${escapeHtmlText(v)}</code>`).join(" · ");
+    }
+    return values
+        .map((v) => {
+        const esc = escapeHtmlText(v);
+        return esc.includes("`") ? escapeMarkdownText(esc) : `\`${esc}\``;
+    })
+        .join(" · ");
 }
 /** Resolved pixel width for an image site, or `null` meaning "omit the width
  * attribute". `"auto"` defers to the caller's per-item heuristic (`autoPx`);
@@ -388,28 +403,37 @@ function pairAttachments(items, isImageAt) {
     }
     return { partnerOf, roleOf };
 }
-/** Max display width for one image inside a before/after pair row — smaller
- * than a standalone image so two side by side stay under GitHub's comment
- * column width (and don't overflow on mobile). */
-export const ATTACHMENT_IMAGE_WIDTH_PAIR = 320;
-function renderPairCell(item, label, options) {
+function renderPairCell(item, label, options, density) {
     const name = item.key.slice(item.key.lastIndexOf("/") + 1);
     const src = item.embedUrl ?? item.url;
     const link = item.pageUrl ?? item.url;
-    const autoPx = Math.min(attachmentImageWidth(name), ATTACHMENT_IMAGE_WIDTH_PAIR);
+    const autoPx = Math.min(attachmentImageWidth(name, density), attachmentPairWidth(density));
     const w = resolvedWidth(autoPx, options);
     const alt = escapeHtmlAttr(name);
     const href = escapeHtmlAttr((link ?? src));
     const imgSrc = escapeHtmlAttr(src);
-    const caption = metaCaptionHtml(item.meta, options);
+    const caption = formatMetaCaption(item.meta, options, "html");
     const captionHtml = caption ? `<br><sub>${caption}</sub>` : "";
     return `<td align="center"><sub><strong>${label}</strong></sub><br><a href="${href}">${imgTag(w, alt, imgSrc)}</a>${captionHtml}</td>`;
 }
-/** One side-by-side before/after row (issue #419): a single HTML table so
- * GitHub renders both images on one line, with `Before`/`After` labels and
- * each side's usual path/state caption preserved underneath. */
-function renderPairRow(beforeItem, afterItem, options) {
-    return `<table><tr>${renderPairCell(beforeItem, "Before", options)}${renderPairCell(afterItem, "After", options)}</tr></table>`;
+/** One side-by-side before/after row (issue #419). */
+function renderPairRow(beforeItem, afterItem, options, density) {
+    return `<table><tr>${renderPairCell(beforeItem, "Before", options, density)}${renderPairCell(afterItem, "After", options, density)}</tr></table>`;
+}
+/** How many image/poster items will fit under `maxInlineImages` (for density). */
+function countInlinableMedia(sorted, maxInlineImages) {
+    let count = 0;
+    for (const item of sorted) {
+        if (count >= maxInlineImages)
+            break;
+        const name = item.key.slice(item.key.lastIndexOf("/") + 1);
+        const src = item.embedUrl ?? item.url;
+        const isImage = Boolean(src) && inferContentType(name).startsWith("image/");
+        const isPoster = Boolean(item.posterUrl) && inferContentType(name).startsWith("video/");
+        if (isImage || isPoster)
+            count++;
+    }
+    return count;
 }
 /**
  * Render the one marker-owned GitHub comment. When there are no galleries this
@@ -444,6 +468,10 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
         return Boolean(src) && inferContentType(name).startsWith("image/");
     });
     const { partnerOf, roleOf } = pairAttachments(sorted, isImageAt);
+    // One screenshot → large; a wall of shots → compact historical sizes.
+    const density = options.imageWidth === "auto"
+        ? attachmentDensityForCount(countInlinableMedia(sorted, options.maxInlineImages))
+        : "dense";
     const consumedByPair = new Set();
     let inlinedImages = 0;
     const overflowImages = [];
@@ -459,7 +487,7 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
                 consumedByPair.add(partnerIdx);
                 const beforeItem = roleOf.get(idx) === "before" ? item : partner;
                 const afterItem = roleOf.get(idx) === "before" ? partner : item;
-                lines.push(renderPairRow(beforeItem, afterItem, options), "");
+                lines.push(renderPairRow(beforeItem, afterItem, options, density), "");
                 continue;
             }
             // Cap already full for a two-image row — degrade this pair to two
@@ -483,7 +511,7 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
         }
         if (isPosterVideo) {
             inlinedImages++;
-            const autoPx = posterImageWidth(item.videoMeta, name);
+            const autoPx = posterImageWidth(item.videoMeta, name, density);
             const w = resolvedWidth(autoPx, options);
             const href = escapeHtmlAttr(link ?? item.posterUrl);
             lines.push(`<a href="${href}">${imgTag(w, escapeHtmlAttr(name), escapeHtmlAttr(item.posterUrl))}</a>`);
@@ -493,29 +521,33 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
             if (item.videoMeta?.durationSeconds != null) {
                 parts.push(formatDuration(item.videoMeta.durationSeconds));
             }
-            parts.push(...metaCaptionParts(item.meta, options).map(escapeHtmlText));
+            const metaCap = formatMetaCaption(item.meta, options, "html");
+            if (metaCap)
+                parts.push(metaCap);
             lines.push(`<sub>${parts.join(" · ")}</sub>`, "");
         }
         else if (isImage) {
             inlinedImages++;
             // Markdown ![]() has no width control — phone frames become full-column giants.
             // img src uses embed host when available (Camo revalidates); click-through prefers the file page.
-            const autoPx = attachmentImageWidth(name);
+            const autoPx = attachmentImageWidth(name, density);
             const w = resolvedWidth(autoPx, options);
             const alt = escapeHtmlAttr(name);
             const href = escapeHtmlAttr(link ?? src);
             const imgSrc = escapeHtmlAttr(src);
             lines.push(`<a href="${href}">${imgTag(w, alt, imgSrc)}</a>`);
-            const caption = metaCaptionHtml(item.meta, options);
+            const caption = formatMetaCaption(item.meta, options, "html");
             if (caption)
                 lines.push(`<sub>${caption}</sub>`);
             lines.push("");
         }
         else if (link) {
-            lines.push(`- [${name}](${link})${metaCaptionMarkdown(item.meta, options)}`);
+            const cap = formatMetaCaption(item.meta, options, "markdown");
+            lines.push(`- [${name}](${link})${cap ? ` · ${cap}` : ""}`);
         }
         else {
-            lines.push(`- ${name}${metaCaptionMarkdown(item.meta, options)}`);
+            const cap = formatMetaCaption(item.meta, options, "markdown");
+            lines.push(`- ${name}${cap ? ` · ${cap}` : ""}`);
         }
     }
     if (overflowImages.length > 0) {
@@ -524,7 +556,8 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
         for (const item of overflowImages) {
             const name = item.key.slice(item.key.lastIndexOf("/") + 1);
             const link = item.pageUrl ?? item.url;
-            const suffix = metaCaptionMarkdown(item.meta, options);
+            const cap = formatMetaCaption(item.meta, options, "markdown");
+            const suffix = cap ? ` · ${cap}` : "";
             lines.push(link ? `- [${name}](${link})${suffix}` : `- ${name}${suffix}`);
         }
         lines.push("", "</details>", "");

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey
 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, type FindFilesOptions, type FindFilesItem, type FindFilesResult, type GetMetadataResult, type PatchMetadataOptions, } 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 MetadataKeysResult, type MetadataValuesResult, type GetMetadataResult, type PatchMetadataOptions, } from "./client.js";
 export { buildCliProvenance } from "./provenance.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, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, type AttachmentItem, type GhTarget, type GhTargetKind, } from "./github.js";

package/dist/mcp/tools.js

@@ -1075,34 +1075,64 @@ export function createUploadsMcpTools(opts) {
         },
         {
             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`.",
+            description: "Find objects whose queryable custom metadata matches ALL of `filters` (ANDed equality) and/or whose key contains `name` (case-insensitive substring). At least one of `filters` or `name` is required. Returns each match's key, public URL, full metadata map, and optional `truncated`. Same as `uploads find k=v...` / `uploads find --name <term>`.",
             inputSchema: {
                 type: "object",
                 properties: {
                     filters: {
                         ...metadataProp,
-                        description: "Metadata equality filters (at least one pair). " + METADATA_DESCRIPTION,
+                        description: "Metadata equality filters (optional when `name` is set). " + METADATA_DESCRIPTION,
+                    },
+                    name: {
+                        type: "string",
+                        description: "Case-insensitive substring match on object keys (1–128 chars). Optional when `filters` is non-empty.",
+                    },
+                    prefix: {
+                        type: "string",
+                        description: "Key prefix filter, combinable with filters/name.",
                     },
-                    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");
+                const filters = optStringRecord(args, "filters") ?? {};
+                const name = optString(args, "name");
+                const hasMeta = Object.keys(filters).length > 0;
+                if (!hasMeta && !name) {
+                    usage("find_files requires filters and/or name");
                 }
-                validateMetaMap(filters);
+                if (hasMeta)
+                    validateMetaMap(filters);
                 const { client } = clientFor(args);
                 return client.findFiles(filters, {
+                    name,
                     prefix: optString(args, "prefix"),
                     limit: optPosInt(args, "limit"),
                 });
             },
         },
+        {
+            name: "list_metadata_keys",
+            description: "List the distinct queryable metadata keys present in the workspace, with file counts and distinct-value counts. Use this to discover what is filterable before calling find_files — keys are user/agent-defined, not a fixed schema. Same as `uploads meta keys`. Pass optional `key` to list that key's values instead (`uploads meta values <key>`).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: {
+                        type: "string",
+                        description: "When set, return distinct values for this metadata key (with counts) instead of the key list.",
+                    },
+                    workspace: workspaceProp,
+                },
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const { client } = clientFor(args);
+                const key = optString(args, "key");
+                return key ? client.listMetadataValues(key) : client.listMetadataKeys();
+            },
+        },
         {
             name: "usage",
             description: "Workspace storage and monthly upload counters (and remaining headroom when budgets are configured). Same as `uploads usage`.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.36.0",
+  "version": "0.37.1",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,