@buildinternet/uploads 0.19.0 → 0.21.0

package/dist/mcp/args.js

@@ -4,6 +4,7 @@
  * Workers as well as Node.
  */
 import { UploadsError } from "../errors.js";
+import { META_STATE_VALUES, validateStateValue } from "../metadata-vocab.js";
 export function usage(msg) {
     throw new UploadsError(msg, "USAGE");
 }
@@ -15,6 +16,15 @@ export function optString(args, name) {
         usage(`${name} must be a string`);
     return v;
 }
+/** A boolean flag argument; missing/null reads as `false`. */
+export function optBool(args, name) {
+    const v = args[name];
+    if (v === undefined || v === null)
+        return false;
+    if (typeof v !== "boolean")
+        usage(`${name} must be a boolean`);
+    return v;
+}
 export function optPosInt(args, name) {
     const v = args[name];
     if (v === undefined || v === null)
@@ -60,9 +70,59 @@ export function optStringArray(args, name) {
  * `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 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. Canonical keys, which uploads.sh derives automatically where it can: url, path, env, theme, viewport, device, software, captured. Use `path` for the route (e.g. /settings) — that is the key `find_files` searches by, so spell it `path` and not route/page/screen. `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,
 };
+export const stateProp = {
+    type: "string",
+    enum: [...META_STATE_VALUES],
+    description: "The UI state this image shows. Set it whenever the image is one side of a comparison — before/after is the most useful pair in a PR, and is what makes `find_files` with state=after work later.",
+};
+export const appProp = {
+    type: "string",
+    description: "Which surface is shown: web, ios, android, cli. Worth setting only when the same route exists on more than one surface.",
+};
+/**
+ * Canonical `state`/`app` pairs from their dedicated tool params. The schema
+ * enum already constrains `state` for well-behaved clients; re-validate here
+ * because a schema is a hint, not an enforcement boundary.
+ */
+export function canonicalMetaFromArgs(args) {
+    const meta = {};
+    const state = optString(args, "state");
+    if (state !== undefined) {
+        // Delegate rather than re-checking the enum here, so MCP callers get the
+        // same near-miss suggestions ("post" → "after") the CLI gives. Only the
+        // error channel differs.
+        try {
+            meta.state = validateStateValue(state);
+        }
+        catch (err) {
+            usage(err instanceof Error
+                ? err.message.replace(/^invalid --state: /, "invalid state: ")
+                : String(err));
+        }
+    }
+    const app = optString(args, "app");
+    if (app !== undefined) {
+        const normalized = app.trim().toLowerCase();
+        if (normalized.length > 0)
+            meta.app = normalized;
+    }
+    return meta;
+}
+/**
+ * The `metadata` tool arg merged with the canonical `state`/`app` params.
+ * `undefined` (leave stored metadata untouched) is preserved only when the
+ * caller supplied none of the three.
+ */
+export function metadataArgWithCanonical(args) {
+    const canonical = canonicalMetaFromArgs(args);
+    const metadataArg = optStringRecord(args, "metadata");
+    return metadataArg === undefined && Object.keys(canonical).length === 0
+        ? undefined
+        : { ...metadataArg, ...canonical };
+}

package/dist/mcp/server.d.ts

@@ -1,4 +1,4 @@
-export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, type ToolArgs, } from "./args.js";
+export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCanonical, metadataProp, stateProp, optBool, optPosInt, optString, optStringArray, optStringRecord, usage, type ToolArgs, } from "./args.js";
 export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
 export { mapBounded } from "../async.js";
 export interface McpTool {

package/dist/mcp/server.js

@@ -10,7 +10,7 @@
 import { UploadsError } from "../errors.js";
 import { errorCodeFromUnknown, recordEvent } from "../telemetry.js";
 import { ToolBatchError } from "./batch-error.js";
-export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
+export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCanonical, metadataProp, stateProp, optBool, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
 export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
 export { mapBounded } from "../async.js";
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(["2025-06-18", "2025-03-26", "2024-11-05"]);

package/dist/mcp/tools.js

@@ -4,20 +4,14 @@ import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
 import { ghKeyPrefix } from "../github.js";
+import { safeCaptureFacts } from "../capture-facts.js";
 import { validateMetaMap } from "../metadata.js";
+import { mergeDerivedMeta } from "../metadata-vocab.js";
 import { execRunner, ghMetadataFromTargetWithTitle, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
-import { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
+import { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCanonical, metadataProp, optBool, optPosInt, optString, optStringArray, optStringRecord, stateProp, usage, } from "./args.js";
 import { batchFailureMessage, ToolBatchError } from "./server.js";
 import { attachmentFromText, buildReportPayload, parseReportType, REPORT_TYPES, submitReport, validateReportMessage, } from "../report.js";
 import { resolveApiUrl } from "../config.js";
-function optBool(args, name) {
-    const v = args[name];
-    if (v === undefined || v === null)
-        return false;
-    if (typeof v !== "boolean")
-        usage(`${name} must be a boolean`);
-    return v;
-}
 function mcpOptimizeOptions(args, defaults) {
     const quality = optPosInt(args, "optimizeQuality");
     if (quality !== undefined && quality > 100)
@@ -338,9 +332,15 @@ export function createUploadsMcpTools(opts) {
                     },
                     dryRun: {
                         type: "boolean",
-                        description: "Resolve key + public URL without uploading. Not with comment.",
+                        description: "Resolve key + public URL without uploading (also previews a strict-key refusal via wouldRefuse). Not with comment.",
+                    },
+                    replace: {
+                        type: "boolean",
+                        description: "Allow overwriting an existing object on a strict (non-gh/) key: explicit key, or the default put path. Default false — an existing object there is refused (key_exists) unless this is true or UPLOADS_OVERWRITE=1 is set in the server's environment. No effect on pr/issue keys, which always overwrite.",
                     },
                     metadata: metadataProp,
+                    state: stateProp,
+                    app: appProp,
                     workspace: workspaceProp,
                 },
                 additionalProperties: false,
@@ -372,6 +372,11 @@ export function createUploadsMcpTools(opts) {
                 const destArg = optString(args, "destination");
                 const prefixArg = optString(args, "prefix");
                 const refArg = optString(args, "ref");
+                // Strict-overwrite gate (issue #174): defaults false; a strict-path
+                // put (explicit key or the default path) refuses an existing object
+                // unless this is true or UPLOADS_OVERWRITE=1 is set for this process.
+                // No effect on pr/issue keys — the server always overwrites those.
+                const replaceArg = optBool(args, "replace") ?? process.env.UPLOADS_OVERWRITE === "1";
                 if (wantComment && !target)
                     usage("comment requires pr or issue");
                 if (dryRun && wantComment)
@@ -387,7 +392,7 @@ export function createUploadsMcpTools(opts) {
                 // Validate up front (fail fast, before reading/optimizing the file).
                 // undefined leaves existing metadata untouched; an object (even {})
                 // fully replaces it — see metadataProp's description.
-                const metadata = optStringRecord(args, "metadata");
+                const metadata = metadataArgWithCanonical(args);
                 if (metadata)
                     validateMetaMap(metadata);
                 let resolvedPrefix;
@@ -419,9 +424,13 @@ export function createUploadsMcpTools(opts) {
                     deriveRepoFromGit: !noGit,
                     contentType,
                     dryRun,
+                    replace: replaceArg,
                     optimize: optimizeOpts,
                     frame: frameOpts,
                     metadata,
+                    // The shared metadata description promises uploads.sh derives these
+                    // "automatically where it can" — MCP has no --no-auto, so always on.
+                    deriveImageFacts: true,
                     provenanceClient: "uploads-mcp",
                     alt,
                     width,
@@ -456,6 +465,7 @@ export function createUploadsMcpTools(opts) {
                         contentType,
                         deriveRepoFromGit: !noGit,
                         dryRun,
+                        replace: replaceArg,
                         metadata,
                         provenanceClient: "uploads-mcp",
                         alt: () => alt ?? sourceName,
@@ -498,6 +508,7 @@ export function createUploadsMcpTools(opts) {
                     size: u.size,
                     contentType: u.contentType,
                     replaced: u.replaced,
+                    wouldRefuse: u.wouldRefuse,
                     markdown: u.markdown,
                     optimize: u.optimize,
                     frame: u.frame,
@@ -613,6 +624,8 @@ export function createUploadsMcpTools(opts) {
                         description: "Capture + resolve key/URL without uploading. Not with comment or galleryId.",
                     },
                     metadata: metadataProp,
+                    state: stateProp,
+                    app: appProp,
                     workspace: workspaceProp,
                 },
                 required: ["target"],
@@ -652,7 +665,7 @@ export function createUploadsMcpTools(opts) {
                     if (prefixArg)
                         usage("prefix cannot be combined with pr/issue");
                 }
-                const metadata = optStringRecord(args, "metadata");
+                const metadata = metadataArgWithCanonical(args);
                 if (metadata)
                     validateMetaMap(metadata);
                 let resolvedPrefix;
@@ -685,6 +698,14 @@ export function createUploadsMcpTools(opts) {
                 catch (err) {
                     usage(`screenshot capture is unavailable in this runtime; try via: "remote" instead (${err instanceof Error ? err.message : String(err)})`);
                 }
+                const viewport = screenshotModule.parseViewport(optString(args, "viewport"));
+                // Same derivation the CLI does — explicit args win over capture facts.
+                // Keep undefined when nothing at all was supplied or derived, so the
+                // "omit to leave stored metadata untouched" contract still holds.
+                const captureDerived = safeCaptureFacts(targetArg, viewport, colorSchemeArg);
+                const metadataWithCaptureFacts = metadata === undefined && Object.keys(captureDerived).length === 0
+                    ? undefined
+                    : mergeDerivedMeta(metadata ?? {}, captureDerived);
                 let captured;
                 try {
                     captured = await screenshotModule.captureScreenshot({
@@ -692,7 +713,7 @@ export function createUploadsMcpTools(opts) {
                         via: viaArg,
                         browserPath: optString(args, "browser"),
                         cdp: optString(args, "cdp"),
-                        viewport: screenshotModule.parseViewport(optString(args, "viewport")),
+                        viewport,
                         selector: optString(args, "selector"),
                         fullPage: optBool(args, "fullPage"),
                         colorScheme: colorSchemeArg,
@@ -723,7 +744,8 @@ export function createUploadsMcpTools(opts) {
                     ref: refArg ?? defaults.ref,
                     deriveRepoFromGit: !noGit,
                     dryRun,
-                    metadata,
+                    metadata: metadataWithCaptureFacts,
+                    deriveImageFacts: true,
                     provenanceClient: "uploads-mcp-screenshot",
                     alt: (p) => alt ?? p.filename,
                     width,
@@ -809,6 +831,8 @@ export function createUploadsMcpTools(opts) {
                         description: "Extra queryable metadata (key→value), merged with the automatic gh.repo/gh.kind/gh.number/gh.ref pairs — a gh.* pair here loses to the resolved target's own gh.* value. " +
                             METADATA_DESCRIPTION,
                     },
+                    state: stateProp,
+                    app: appProp,
                     workspace: workspaceProp,
                 },
                 required: ["files"],
@@ -832,7 +856,10 @@ export function createUploadsMcpTools(opts) {
                 // just the extras) so the 24-key/8KB caps are enforced client-side —
                 // extras alone might pass while extras + the gh.* pairs exceed the
                 // cap, which would otherwise only be caught server-side after upload.
-                const metaExtras = optStringRecord(args, "metadata") ?? {};
+                const metaExtras = {
+                    ...optStringRecord(args, "metadata"),
+                    ...canonicalMetaFromArgs(args),
+                };
                 const metadata = { ...metaExtras, ...ghMetadataFromTargetWithTitle(target, run) };
                 if (Object.keys(metadata).length > 0)
                     validateMetaMap(metadata);

package/dist/metadata-vocab.d.ts

@@ -0,0 +1,24 @@
+export declare const CANONICAL_META_KEYS: readonly ["url", "path", "env", "theme", "viewport", "device", "software", "captured", "state", "app"];
+export type CanonicalMetaKey = (typeof CANONICAL_META_KEYS)[number];
+/** Closed enum for `state` — the highest-value hand-supplied search facet. */
+export declare const META_STATE_VALUES: readonly ["before", "after", "empty", "error", "loading"];
+export type MetaStateValue = (typeof META_STATE_VALUES)[number];
+/**
+ * Validate a `--state` value. Fails fast with a suggestion when the value is a
+ * recognized near-miss, otherwise lists the valid set.
+ */
+export declare function validateStateValue(raw: string): MetaStateValue;
+/**
+ * Warning lines for supplied keys that look like misspellings of canonical
+ * ones. Callers warn and continue — we never silently rewrite a caller's key,
+ * because a wrong guess is worse than a nag.
+ */
+export declare function nearMissMetaWarnings(keys: string[]): string[];
+/** Canonical value format for the `viewport` key, e.g. `1280x800@2x`. */
+export declare function formatViewport(width: number, height: number, scale: number): string;
+/**
+ * Merge derived pairs under the explicit ones, adding derived keys only while
+ * the result still satisfies the metadata caps. Explicit keys always win and
+ * are never dropped; a full key budget must never fail an upload.
+ */
+export declare function mergeDerivedMeta(explicit: Record<string, string>, derived: Record<string, string>): Record<string, string>;

package/dist/metadata-vocab.js

@@ -0,0 +1,127 @@
+/**
+ * The canonical upload metadata vocabulary: a small closed set of keys that
+ * `uploads find` can rely on being spelled consistently. Most are derived (see
+ * capture-facts.ts / image-facts.ts); only `state` and `app` are typed by hand.
+ *
+ * Design: .context/2026-07-21-upload-metadata-vocabulary-design.md
+ */
+import { UsageError } from "./cli-args.js";
+import { validateMetaMap } from "./metadata.js";
+export const CANONICAL_META_KEYS = [
+    "url",
+    "path",
+    "env",
+    "theme",
+    "viewport",
+    "device",
+    "software",
+    "captured",
+    "state",
+    "app",
+];
+const CANONICAL_KEY_SET = new Set(CANONICAL_META_KEYS);
+/** Closed enum for `state` — the highest-value hand-supplied search facet. */
+export const META_STATE_VALUES = ["before", "after", "empty", "error", "loading"];
+const STATE_VALUE_SET = new Set(META_STATE_VALUES);
+/** Common spellings agents reach for, mapped to the canonical `state` value. */
+const STATE_ALIASES = {
+    pre: "before",
+    prior: "before",
+    old: "before",
+    previous: "before",
+    post: "after",
+    new: "after",
+    updated: "after",
+    blank: "empty",
+    none: "empty",
+    failure: "error",
+    failed: "error",
+    err: "error",
+    spinner: "loading",
+    pending: "loading",
+    busy: "loading",
+};
+/**
+ * Validate a `--state` value. Fails fast with a suggestion when the value is a
+ * recognized near-miss, otherwise lists the valid set.
+ */
+export function validateStateValue(raw) {
+    const value = raw.trim().toLowerCase();
+    if (STATE_VALUE_SET.has(value))
+        return value;
+    const suggestion = STATE_ALIASES[value];
+    if (suggestion) {
+        throw new UsageError(`invalid --state: "${raw}" — did you mean "${suggestion}"?`);
+    }
+    throw new UsageError(`invalid --state: "${raw}" (expected one of: ${META_STATE_VALUES.join(", ")})`);
+}
+/** Common misspellings of canonical keys, mapped to the canonical spelling. */
+const META_KEY_ALIASES = {
+    route: "path",
+    page: "path",
+    screen: "path",
+    pathname: "path",
+    mode: "theme",
+    appearance: "theme",
+    colorscheme: "theme",
+    environment: "env",
+    stage: "env",
+    surface: "app",
+    platform: "app",
+    status: "state",
+    variant: "state",
+    resolution: "viewport",
+    size: "viewport",
+    dimensions: "viewport",
+    link: "url",
+    href: "url",
+    source: "url",
+    model: "device",
+    hardware: "device",
+    when: "captured",
+    date: "captured",
+    timestamp: "captured",
+};
+/**
+ * Warning lines for supplied keys that look like misspellings of canonical
+ * ones. Callers warn and continue — we never silently rewrite a caller's key,
+ * because a wrong guess is worse than a nag.
+ */
+export function nearMissMetaWarnings(keys) {
+    const warnings = [];
+    for (const key of keys) {
+        if (CANONICAL_KEY_SET.has(key))
+            continue;
+        const canonical = META_KEY_ALIASES[key];
+        if (canonical) {
+            warnings.push(`metadata key "${key}" is not canonical — did you mean "${canonical}"?`);
+        }
+    }
+    return warnings;
+}
+/** Canonical value format for the `viewport` key, e.g. `1280x800@2x`. */
+export function formatViewport(width, height, scale) {
+    const trimmed = Number(scale.toFixed(2));
+    return `${Math.round(width)}x${Math.round(height)}@${trimmed}x`;
+}
+/**
+ * Merge derived pairs under the explicit ones, adding derived keys only while
+ * the result still satisfies the metadata caps. Explicit keys always win and
+ * are never dropped; a full key budget must never fail an upload.
+ */
+export function mergeDerivedMeta(explicit, derived) {
+    const out = { ...explicit };
+    for (const [key, value] of Object.entries(derived)) {
+        if (key in out)
+            continue;
+        const candidate = { ...out, [key]: value };
+        try {
+            validateMetaMap(candidate);
+        }
+        catch {
+            continue; // derived key does not fit — drop it, keep going
+        }
+        out[key] = value;
+    }
+    return out;
+}

package/dist/metadata.d.ts

@@ -16,6 +16,13 @@ export declare function validateMetaEntry(key: string, value: string): void;
  * unicode (emoji, curly quotes) that the metadata value rule disallows.
  */
 export declare function isMetaValueSafe(value: string): boolean;
+/**
+ * Drop, in place, any entry whose value breaks the metadata contract. For
+ * *derived* pairs only: a fact we inferred must never fail an upload, so an
+ * over-long URL or non-ASCII EXIF string is silently discarded rather than
+ * surfaced. Never use this on caller-supplied metadata, which should error.
+ */
+export declare function dropUnsafeMetaValues(facts: Record<string, string>): Record<string, string>;
 /**
  * Split `k=v` on the FIRST "=" (so values may themselves contain "="), then
  * validate the pair. Throws `UsageError` on malformed input.

package/dist/metadata.js

@@ -48,6 +48,19 @@ export function validateMetaEntry(key, value) {
 export function isMetaValueSafe(value) {
     return value.length >= 1 && value.length <= META_VALUE_MAX && VALUE_SAFE_RE.test(value);
 }
+/**
+ * Drop, in place, any entry whose value breaks the metadata contract. For
+ * *derived* pairs only: a fact we inferred must never fail an upload, so an
+ * over-long URL or non-ASCII EXIF string is silently discarded rather than
+ * surfaced. Never use this on caller-supplied metadata, which should error.
+ */
+export function dropUnsafeMetaValues(facts) {
+    for (const [key, value] of Object.entries(facts)) {
+        if (!isMetaValueSafe(value))
+            delete facts[key];
+    }
+    return facts;
+}
 /**
  * Split `k=v` on the FIRST "=" (so values may themselves contain "="), then
  * validate the pair. Throws `UsageError` on malformed input.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,
@@ -56,6 +56,7 @@
     "provenance": true
   },
   "dependencies": {
+    "exif-reader": "^2.0.3",
     "sharp": "^0.35.3"
   },
   "optionalDependencies": {