@buildinternet/uploads 0.36.0 → 0.37.0

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

@@ -2134,31 +2134,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 +2182,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 +2193,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 +2236,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>]
 
-Human-friendly alias for \`uploads list --meta k=v...\` — same metadata filter
-(ANDed equality), same output; pairs are positional, or spelled --meta k=v.
+Find objects by queryable metadata (ANDed equality) and/or a case-insensitive
+filename substring. Same output as \`uploads list --meta\` / \`--name\`.
+
+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 +2260,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 +2306,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 +2317,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 +2374,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",
             });
     }

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.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,