@buildinternet/uploads 0.19.0 → 0.21.0

package/dist/capture-facts.d.ts

@@ -0,0 +1,19 @@
+import { type ScreenshotTarget, type ScreenshotViewport } from "./screenshot.js";
+export interface CaptureFactsInput {
+    target: ScreenshotTarget;
+    viewport: ScreenshotViewport;
+    /** Only set when the caller forced a scheme (`--dark` / `--light`). */
+    colorScheme?: "dark" | "light";
+}
+/**
+ * Derive `url`/`path`/`env`/`theme`/`viewport` from a capture. `env` is only
+ * ever `local`: inferring `prod` from "not localhost" would mislabel every
+ * staging and preview URL, and wrong metadata is worse than absent metadata.
+ */
+export declare function captureFacts(input: CaptureFactsInput): Record<string, string>;
+/**
+ * `captureFacts` for a raw target string, never at the cost of the capture
+ * itself: an unclassifiable target yields no facts rather than an error.
+ * Shared by the CLI and MCP screenshot paths.
+ */
+export declare function safeCaptureFacts(target: string, viewport: ScreenshotViewport, colorScheme: "dark" | "light" | undefined): Record<string, string>;

package/dist/capture-facts.js

@@ -0,0 +1,49 @@
+/**
+ * Canonical metadata derived from a screenshot capture, where the CLI knows
+ * the inputs exactly. Pure: no I/O, no throwing — an unparseable URL simply
+ * yields fewer keys.
+ *
+ * Design: .context/2026-07-21-upload-metadata-vocabulary-design.md
+ */
+import { dropUnsafeMetaValues } from "./metadata.js";
+import { formatViewport } from "./metadata-vocab.js";
+import { classifyTarget } from "./screenshot.js";
+/**
+ * Derive `url`/`path`/`env`/`theme`/`viewport` from a capture. `env` is only
+ * ever `local`: inferring `prod` from "not localhost" would mislabel every
+ * staging and preview URL, and wrong metadata is worse than absent metadata.
+ */
+export function captureFacts(input) {
+    const facts = {};
+    facts.viewport = formatViewport(input.viewport.width, input.viewport.height, input.viewport.deviceScaleFactor);
+    if (input.colorScheme)
+        facts.theme = input.colorScheme;
+    if (input.target.kind === "url") {
+        facts.url = input.target.url;
+        try {
+            facts.path = new URL(input.target.url).pathname || "/";
+        }
+        catch {
+            // classifyTarget already validated this, but never let a URL parse
+            // failure cost us the other facts.
+        }
+        if (input.target.localOnly)
+            facts.env = "local";
+    }
+    // A long query string can exceed the 512-char value cap; drop rather than
+    // let a derived value fail the upload.
+    return dropUnsafeMetaValues(facts);
+}
+/**
+ * `captureFacts` for a raw target string, never at the cost of the capture
+ * itself: an unclassifiable target yields no facts rather than an error.
+ * Shared by the CLI and MCP screenshot paths.
+ */
+export function safeCaptureFacts(target, viewport, colorScheme) {
+    try {
+        return captureFacts({ target: classifyTarget(target), viewport, colorScheme });
+    }
+    catch {
+        return {}; // derived metadata must never fail a capture
+    }
+}

package/dist/cli-catalog.js

@@ -36,6 +36,8 @@ export const PUT_LIKE_FLAGS = [
     "--frame-url",
     "--gallery",
     "--meta",
+    "--state",
+    "--app",
     "--workspace",
     "-w",
     "--help",
@@ -80,6 +82,8 @@ export const SCREENSHOT_FLAGS = [
     "--comment",
     "--gallery",
     "--meta",
+    "--state",
+    "--app",
     "--dry-run",
     "--format",
     "--workspace",

package/dist/cli-help.js

@@ -87,10 +87,10 @@ ${section(style, "Examples:")}
   ${style.command("uploads put")} ./shot.png --pr 123 --name hero.png
   ${style.command("uploads put")} ./after.png --pr 123 --comment
   ${style.command("uploads put")} ./bug.png --issue 45
-  ${style.command("uploads put")} ./shot.png --meta app=myapp --meta page=settings
+  ${style.command("uploads put")} ./shot.png --meta path=/settings --state after
   ${style.command("uploads attach")} ./before.png ./after.png
   ${style.command("uploads attach")} ./shot.png --pr 123 --repo myorg/myapp
-  ${style.command("uploads attach")} ./shot.png --meta app=myapp --meta page=settings
+  ${style.command("uploads attach")} ./shot.png --meta path=/settings --state after
   ${style.command("uploads doctor")}
   ${style.command("uploads install")}
   ${style.command("uploads logout")}
@@ -137,11 +137,11 @@ ${section(style, "Examples:")}
   ${style.command("uploads put")} ./after.png --pr 123 --comment
   ${style.command("uploads put")} ./bug.png --issue 45 --repo myorg/myapp
   ${style.command("uploads put")} ./shot.png --dry-run --format url
-  ${style.command("uploads put")} ./shot.png --meta app=myapp --meta page=settings
+  ${style.command("uploads put")} ./shot.png --meta path=/settings --state after
   ${style.command("uploads attach")} ./before.png ./after.png
   ${style.command("uploads attach")} ./shot.png --pr 123 --repo myorg/myapp
   ${style.command("uploads attach")} ./artifact.zip --issue 45 --no-comment
-  ${style.command("uploads attach")} ./shot.png --meta app=myapp --meta page=settings
+  ${style.command("uploads attach")} ./shot.png --meta path=/settings --state after
   ${style.command("uploads gallery")} create --title "Release screenshots"
   ${style.command("uploads doctor")}
   ${style.command("uploads logout")}

package/dist/client.d.ts

@@ -28,6 +28,14 @@ export interface PutOptions {
     metadata?: Record<string, string>;
     /** Validate key + resolve public URL without writing. `size` is local bytes only. */
     dryRun?: boolean;
+    /**
+     * Opt in to overwriting an existing object on a "strict" (non-`gh/`) key —
+     * see issue #174. Ignored (always allowed) on managed `gh/` paths
+     * (`attach`, `put --pr`/`--issue`), which stay silent hot-swap. Omit/false
+     * on a strict path with an existing key throws `UploadsError` with code
+     * `KEY_EXISTS`.
+     */
+    replace?: boolean;
 }
 export interface ListOptions {
     prefix?: string;
@@ -67,6 +75,11 @@ export interface PutResult {
      * at this key would overwrite. Always set by the API for put/dry-run.
      */
     replaced?: boolean;
+    /**
+     * dryRun only: true when a real put at this key would be refused (strict
+     * non-`gh/` key, existing object, no `replace`) instead of overwriting.
+     */
+    wouldRefuse?: boolean;
     metadata?: Record<string, string>;
 }
 export interface ListItem {
@@ -175,8 +188,7 @@ export interface FindGalleriesByReferenceOptions {
 /**
  * Reasons the bot did not post. The CLI falls back to the local `gh` path
  * for all of these except `not_authorized` (issue #297 baseline control):
- * the target repo is bound to a different workspace (or is unbound and the
- * caller is the communal `default` workspace, which can't claim new repos).
+ * the target repo is bound to a different workspace.
  * Falling back to `gh` there would let the human's own credentials post
  * anyway, defeating the point of the server-side gate, so the CLI surfaces
  * the decline instead.
@@ -219,6 +231,13 @@ export interface GithubLinkResult {
 /** POST-only: whether THIS call's workspace ended up owning the binding. */
 export interface GithubLinkClaimResult extends GithubLinkResult {
     claimed: boolean;
+    /**
+     * Present (only) when `claimed` is false because the repo is unbound and
+     * this workspace couldn't be verified as entitled to claim it — issue
+     * #297's cross-tenant authorization gate. Distinct from the "someone else
+     * already owns it" case, which instead reports a non-null `workspace`.
+     */
+    reason?: "not_authorized";
 }
 /** `DELETE /v1/:workspace/github/link` result (issue #318, self-serve unlink). */
 export interface GithubLinkUnlinkResult {
@@ -430,12 +449,14 @@ export declare function extractErrorFields(body: unknown, fallback?: string): {
     message: string;
     code?: string;
     requiredScope?: string;
+    existingUrl?: string;
 };
 /** Fetch + parse an error-response body via {@link extractErrorFields}. */
 export declare function parseErrorEnvelope(res: Response, fallback?: string): Promise<{
     message: string;
     code?: string;
     requiredScope?: string;
+    existingUrl?: string;
 }>;
 export declare function createUploadsClient(config: UploadsClientConfig): {
     put(body: Uint8Array, opts: PutOptions & {

package/dist/client.js

@@ -188,7 +188,7 @@ function usageBase(config) {
 function galleriesBase(config) {
     return `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/galleries`;
 }
-function mapApiError(status, error, code, requiredScope) {
+function mapApiError(status, error, code, requiredScope, existingUrl) {
     const normalized = error.toLowerCase();
     if (status === 401 || code === "unauthorized" || normalized === "unauthorized") {
         return new UploadsError(error, "UNAUTHORIZED", status);
@@ -218,6 +218,9 @@ function mapApiError(status, error, code, requiredScope) {
     if (code === "github_required") {
         return new UploadsError(error, "GITHUB_REQUIRED", status);
     }
+    if (code === "key_exists") {
+        return new UploadsError(error, "KEY_EXISTS", status, { existingUrl });
+    }
     return new UploadsError(error, "API_ERROR", status);
 }
 /**
@@ -239,6 +242,7 @@ export function extractErrorFields(body, fallback = "request failed") {
                 ...(typeof details?.required_scope === "string"
                     ? { requiredScope: details.required_scope }
                     : {}),
+                ...(typeof details?.url === "string" ? { existingUrl: details.url } : {}),
             };
         }
         if (typeof err === "string") {
@@ -256,8 +260,8 @@ export async function parseErrorEnvelope(res, fallback = "request failed") {
     return extractErrorFields(body, fallback);
 }
 async function parseErrorResponse(res) {
-    const { message, code, requiredScope } = await parseErrorEnvelope(res, res.statusText || "request failed");
-    return mapApiError(res.status, message, code, requiredScope);
+    const { message, code, requiredScope, existingUrl } = await parseErrorEnvelope(res, res.statusText || "request failed");
+    return mapApiError(res.status, message, code, requiredScope, existingUrl);
 }
 export function createUploadsClient(config) {
     async function request(method, path, opts) {
@@ -318,7 +322,8 @@ export function createUploadsClient(config) {
                 }));
             const contentType = opts.contentType ?? inferContentType(opts.filename);
             if (opts.dryRun) {
-                const preview = await request("PUT", `${filesBase(config)}/${encodeKeyPath(key)}?dryRun=1`);
+                const qs = opts.replace ? "dryRun=1&replace=1" : "dryRun=1";
+                const preview = await request("PUT", `${filesBase(config)}/${encodeKeyPath(key)}?${qs}`);
                 if (preview.url == null) {
                     throw new UploadsError("workspace has no publicBaseUrl (cannot resolve a public URL)", "NO_PUBLIC_URL");
                 }
@@ -330,9 +335,12 @@ export function createUploadsClient(config) {
                     size: body.byteLength,
                     contentType,
                     replaced: preview.replaced === true,
+                    wouldRefuse: preview.wouldRefuse === true,
                 };
             }
             const headers = { "Content-Type": contentType };
+            if (opts.replace)
+                headers["X-Uploads-Replace"] = "1";
             if (opts.provenance) {
                 for (const [k, v] of Object.entries(opts.provenance)) {
                     if (v !== undefined && v !== "")

package/dist/commands/screenshot.js

@@ -2,13 +2,15 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { writeCommandHelp } from "../cli-style.js";
-import { branchFromFlags, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, } from "../commands.js";
+import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, } from "../commands.js";
 import { resolvePutDefaults } from "../config.js";
 import { loadDefaultsRaw, resolveScreenshotDefaults } from "../config-file.js";
 import { resolvePutPrefix } from "../destinations.js";
 import { execRunner, ghMetadataFromTargetWithTitle, resolveRepo, } from "../github-gh.js";
 import { ghBranchAttachmentKey, ghMetadataForBranch } from "../github.js";
+import { safeCaptureFacts } from "../capture-facts.js";
 import { parseMetaFlags, validateMetaMap } from "../metadata.js";
+import { mergeDerivedMeta } from "../metadata-vocab.js";
 import { writeJson, writeStdout } from "../io.js";
 import { assertHideSelector, captureScreenshot, parseViewport, parseWaitUntil, } from "../screenshot.js";
 const SCREENSHOT_HELP = `uploads screenshot <target> [options]
@@ -77,6 +79,8 @@ Options:
                              otherwise via local gh.
   --gallery <id>            Add the uploaded object to this public gallery
   --meta <k=v>              Queryable custom metadata (repeatable)
+  --state <s>               before|after|empty|error|loading — the UI state shown
+  --app <name>              Surface shown: web, ios, android, cli
   --workspace, -w <name>    Override workspace
   --dry-run                 Capture + resolve key/URL without uploading
   --format human|url|markdown|json
@@ -234,18 +238,22 @@ captureImpl = captureScreenshot) {
     const frameOpts = frameOptionsFromFlags(parsed.flags);
     const altFlag = flagString(parsed.flags, "--alt");
     const width = flagInt(parsed.flags, "--width", "--width") ?? putDefaults.width;
-    const metaExtras = parseMetaFlags(flagValues(parsed.flags, "--meta"));
-    let metadata = metaExtras;
+    const metaExtras = warnNearMissMeta(ctx, parseMetaFlags(flagValues(parsed.flags, "--meta")));
+    // Explicit input (--meta plus the dedicated flags) wins over capture facts.
+    const explicitMeta = { ...metaExtras, ...stateAppMetaFromFlags(parsed.flags) };
+    const deriveMeta = derivedMetaEnabled(parsed.flags, putDefaults);
+    const withFacts = mergeDerivedMeta(explicitMeta, deriveMeta ? safeCaptureFacts(target, viewport, colorScheme) : {});
+    let metadata = withFacts;
     if (ghTarget) {
-        metadata = { ...metaExtras, ...ghMetadataFromTargetWithTitle(ghTarget, run) };
+        metadata = { ...withFacts, ...ghMetadataFromTargetWithTitle(ghTarget, run) };
         validateMetaMap(metadata);
     }
     else if (branchArg !== undefined) {
-        metadata = { ...metaExtras, ...ghMetadataForBranch(branchRepo, branchArg) };
+        metadata = { ...withFacts, ...ghMetadataForBranch(branchRepo, branchArg) };
         validateMetaMap(metadata);
     }
-    else if (Object.keys(metaExtras).length > 0) {
-        validateMetaMap(metaExtras);
+    else if (Object.keys(withFacts).length > 0) {
+        validateMetaMap(withFacts);
     }
     const logHuman = !ctx.quiet && format === "human";
     if (logHuman)

package/dist/commands.d.ts

@@ -41,6 +41,28 @@ export declare function ghTargetFromFlags(flags: CommandFlags["flags"], run: Com
 export declare function branchFromFlags(flags: CommandFlags["flags"], run: CommandRunner): string | undefined;
 /** Shared put/attach optimize flags + UPLOADS_NO_OPTIMIZE default. */
 export declare function optimizeOptionsFromFlags(flags: CommandFlags["flags"], defaults: PutDefaults): OptimizeImageOptions;
+/**
+ * Whether the derived-metadata tier is on — screenshot capture facts and EXIF
+ * promotion. `--no-auto` and `UPLOADS_NO_AUTO_META=1` turn it off; `--auto`
+ * forces past the config default.
+ *
+ * Deliberately *not* gated on `--no-git`. That flag means "don't shell out to
+ * git", which says nothing about a viewport or a URL path — a capture of a
+ * local .html file outside any repo should still record what it captured.
+ * `--no-git` still disables gh.* below, which genuinely needs a repo.
+ */
+export declare function derivedMetaEnabled(flags: CommandFlags["flags"], defaults: Pick<PutDefaults, "noAutoMeta">): boolean;
+/**
+ * Warn about metadata keys that look like misspellings of canonical ones, then
+ * return the map unchanged — we nag, we never rewrite a caller's key.
+ */
+export declare function warnNearMissMeta(ctx: CliContext, meta: Record<string, string>): Record<string, string>;
+/**
+ * Canonical `state`/`app` pairs from their dedicated flags. Shared by put,
+ * attach and screenshot. These are sugar for the matching `--meta` keys; the
+ * point is `--help` discoverability and `--state` validation.
+ */
+export declare function stateAppMetaFromFlags(flags: CommandFlags["flags"]): Record<string, string>;
 export type PreparedUpload = OptimizeImageResult & {
     frame?: Pick<FrameResult, "framed" | "frameId" | "skippedReason">;
 };
@@ -67,7 +89,19 @@ export interface UploadPreparedImageOptions {
     deriveRepoFromGit?: boolean;
     contentType?: string;
     dryRun?: boolean;
+    /**
+     * Opt in to overwriting an existing object on a strict (non-`gh/`) key —
+     * see issue #174. Ignored server-side on managed `gh/` paths (`ghTarget`
+     * set), which always hot-swap.
+     */
+    replace?: boolean;
     metadata?: Record<string, string>;
+    /**
+     * Promote this image's own EXIF allowlist into its metadata (see
+     * image-facts.ts). Lives here, on the shared bytes tail, so every upload
+     * surface — CLI put/screenshot, MCP put/screenshot — derives alike.
+     */
+    deriveImageFacts?: boolean;
     provenanceClient?: string;
     /**
      * Alt text for the markdown. Takes the prepared result so callers whose
@@ -118,8 +152,7 @@ export declare function commentViaSuffix(via: AttachmentsCommentResult["via"]):
 /**
  * Thrown by `syncAttachmentsComment` when the server declines with
  * `not_authorized` (issue #297 baseline control) — this repo is bound to a
- * different workspace, or unbound and unclaimable by the communal `default`
- * workspace. Deliberately not caught by the generic "bot endpoint
+ * different workspace. 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.
@@ -164,6 +197,8 @@ export declare function uploadAttachments(opts: {
         frameFit?: "cover" | "contain";
     };
     metadata?: Record<string, string>;
+    /** Forwarded per file — see image-facts.ts. */
+    deriveImageFacts?: boolean;
     /** Provenance `client` field (default uploads-cli). */
     provenanceClient?: string;
     concurrency?: number;
@@ -196,6 +231,8 @@ export declare function uploadBranchAttachments(opts: {
         frameFit?: "cover" | "contain";
     };
     metadata?: Record<string, string>;
+    /** Forwarded per file — see image-facts.ts. */
+    deriveImageFacts?: boolean;
     provenanceClient?: string;
     concurrency?: number;
 }): Promise<{
@@ -227,6 +264,12 @@ export declare function uploadPuts(opts: {
     deriveRepoFromGit?: boolean;
     contentType?: string;
     dryRun?: boolean;
+    /**
+     * Opt in to overwriting an existing object on a strict (non-`gh/`) key —
+     * see issue #174. Ignored server-side when `ghTarget` targets a managed
+     * `gh/` path, which always hot-swaps.
+     */
+    replace?: boolean;
     optimize: OptimizeImageOptions;
     frame: {
         frameId?: string;
@@ -234,6 +277,8 @@ export declare function uploadPuts(opts: {
         frameFit?: "cover" | "contain";
     };
     metadata?: Record<string, string>;
+    /** Forwarded per file to `uploadPreparedImage` — see image-facts.ts. */
+    deriveImageFacts?: boolean;
     provenanceClient?: string;
     /** When set, used as alt for every file; else each file's basename. */
     alt?: string;