@buildinternet/uploads 0.19.0 → 0.22.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,11 +28,21 @@ 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;
     limit?: number;
     cursor?: string;
+    /** Hydrate each row's queryable D1 metadata (`?metadata=1`). */
+    metadata?: boolean;
 }
 export interface FindFilesOptions {
     prefix?: string;
@@ -67,6 +77,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 {
@@ -77,6 +92,8 @@ export interface ListItem {
     pageUrl?: string;
     size?: number;
     uploaded?: string;
+    /** Present only when listed with `metadata: true`, and only for keys that have rows. */
+    metadata?: Record<string, string>;
 }
 export interface ListResult {
     items: ListItem[];
@@ -175,8 +192,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 +235,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 {
@@ -332,7 +355,14 @@ export interface DeviceCodeResponse {
     interval: number;
 }
 /** POST /api/auth/device/code — start a device flow. Throws on a non-2xx. */
-export declare function requestDeviceCode(authUrl: string, clientId?: string): Promise<DeviceCodeResponse>;
+export declare function requestDeviceCode(authUrl: string, clientId?: string, 
+/**
+ * RFC 8628 `scope`. Carries the requested workspace (`workspace:<slug>`,
+ * plus `create`) so the approval page can validate it before approving —
+ * issue #362. Stored on the device-code row and echoed back at token
+ * exchange, possibly rewritten by the page.
+ */
+scope?: string): Promise<DeviceCodeResponse>;
 /**
  * One poll of POST /api/auth/device/token. Unlike most calls, the "not ready
  * yet" outcomes (`authorization_pending`, `slow_down`) are EXPECTED 400s, so
@@ -430,12 +460,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

@@ -56,14 +56,21 @@ export function cliUserAgent(purpose = "device-login") {
     return `@buildinternet/uploads/${packageVersion()} (${purpose})`;
 }
 /** POST /api/auth/device/code — start a device flow. Throws on a non-2xx. */
-export function requestDeviceCode(authUrl, clientId = DEVICE_CLIENT_ID) {
+export function requestDeviceCode(authUrl, clientId = DEVICE_CLIENT_ID, 
+/**
+ * RFC 8628 `scope`. Carries the requested workspace (`workspace:<slug>`,
+ * plus `create`) so the approval page can validate it before approving —
+ * issue #362. Stored on the device-code row and echoed back at token
+ * exchange, possibly rewritten by the page.
+ */
+scope) {
     return jsonRequest(`${authUrl.replace(/\/$/, "")}/api/auth/device/code`, {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
             "User-Agent": cliUserAgent("device-code"),
         },
-        body: JSON.stringify({ client_id: clientId }),
+        body: JSON.stringify({ client_id: clientId, ...(scope ? { scope } : {}) }),
     });
 }
 export async function requestDeviceToken(authUrl, input) {
@@ -188,7 +195,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 +225,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 +249,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 +267,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) {
@@ -292,6 +303,8 @@ export function createUploadsClient(config) {
             params.set("limit", String(opts.limit));
         if (opts.cursor)
             params.set("cursor", opts.cursor);
+        if (opts.metadata)
+            params.set("metadata", "1");
         const qs = params.toString();
         const page = await request("GET", `${filesBase(config)}${qs ? `?${qs}` : ""}`);
         return {
@@ -318,7 +331,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 +344,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/login.d.ts

@@ -1,5 +1,16 @@
 import { parseCommandArgs } from "../cli-args.js";
 export declare function validateEnrollmentCode(raw: string): string;
+/** The scope the CLI sends with its device-code request. No workspace requested → no scope. */
+export declare function formatDeviceScope(workspace: string | undefined, create: boolean): string | undefined;
+/**
+ * Read back what the approval page decided. A surviving `create` token means
+ * the page left the scope alone and deferred provisioning to the CLI; a bare
+ * `workspace:<slug>` means the browser recorded a choice and wins.
+ */
+export declare function parseDeviceScope(scope: string | undefined): {
+    workspace: string | undefined;
+    create: boolean;
+};
 export declare function resolveEnrollmentCode(parsed: ReturnType<typeof parseCommandArgs>, io?: {
     isTTY: boolean;
     readLine: () => Promise<string>;
@@ -23,10 +34,21 @@ export interface DeviceLoginIo {
     promptWorkspaceName: () => Promise<string>;
 }
 export declare const defaultDeviceIo: DeviceLoginIo;
+/** A completed device authorization: the session bearer plus the (possibly rewritten) scope. */
+export interface DeviceSession {
+    accessToken: string;
+    scope: string;
+}
 /**
  * Browser device-authorization session only (no workspace token mint).
  * Shared by `uploads login` and `uploads invite create`.
  */
+export declare function obtainDeviceSession(authUrl: string, opts?: {
+    noOpen?: boolean;
+    prompt?: string;
+    scope?: string;
+}, io?: DeviceLoginIo): Promise<DeviceSession>;
+/** Session bearer only — `invite create` has no workspace to resolve. */
 export declare function obtainDeviceAccessToken(authUrl: string, opts?: {
     noOpen?: boolean;
     prompt?: string;
@@ -36,7 +58,7 @@ export declare function pollForDeviceToken(authUrl: string, code: {
     device_code: string;
     interval: number;
     expires_in: number;
-}, io: DeviceLoginIo): Promise<string>;
+}, io: DeviceLoginIo): Promise<DeviceSession>;
 export declare function runLogin(args: string[], opts: {
     json?: boolean;
     apiUrl?: string;

package/dist/commands/login.js

@@ -7,15 +7,17 @@ import { createUploadsClient, createWorkspaceRequest, exchangeEnrollment, listMi
 import { flagBool, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
 import { parseScopes } from "./admin-enrollment.js";
 import { writeCommandHelp } from "../cli-style.js";
+import { UploadsError } from "../errors.js";
 const HELP = `uploads login [options]
 
 Sign in and save workspace credentials. With no flags, opens a browser to
-authorize this device — the recommended way to sign in. Pass an enrollment
-code only if you were given one from before device login (fallback path).
+authorize this device — the recommended way to sign in. The browser asks which
+workspace to sign in to, so --workspace is optional. Pass an enrollment code
+only if you were given one from before device login (fallback path).
 
 Options:
-  --workspace <name>  Workspace to mint a token for (device flow; required if
-                      your account can access more than one)
+  --workspace <name>  Preselect this workspace in the browser (device flow);
+                      you can still change it there
   --create            With --workspace: create the workspace first if your
                       account doesn't have it yet (device flow only) — lets
                       scripted/agent logins provision without a prompt
@@ -46,6 +48,34 @@ export function validateEnrollmentCode(raw) {
         throw new UsageError("invalid enrollment code");
     return code;
 }
+/**
+ * Device-code scope vocabulary (issue #362). Mirrors `parseDeviceScope` /
+ * `workspaceScopeValue` in apps/auth/src/device-workspace.ts — this package
+ * ships with no workspace dependencies, so the two copies are deliberately
+ * independent. Keep the vocabulary in sync.
+ */
+const WORKSPACE_SCOPE_PREFIX = "workspace:";
+const CREATE_SCOPE_TOKEN = "create";
+/** The scope the CLI sends with its device-code request. No workspace requested → no scope. */
+export function formatDeviceScope(workspace, create) {
+    if (!workspace)
+        return undefined;
+    return create
+        ? `${WORKSPACE_SCOPE_PREFIX}${workspace} ${CREATE_SCOPE_TOKEN}`
+        : `${WORKSPACE_SCOPE_PREFIX}${workspace}`;
+}
+/**
+ * Read back what the approval page decided. A surviving `create` token means
+ * the page left the scope alone and deferred provisioning to the CLI; a bare
+ * `workspace:<slug>` means the browser recorded a choice and wins.
+ */
+export function parseDeviceScope(scope) {
+    const tokens = (scope ?? "").split(/\s+/).filter(Boolean);
+    const slug = tokens
+        .find((t) => t.startsWith(WORKSPACE_SCOPE_PREFIX))
+        ?.slice(WORKSPACE_SCOPE_PREFIX.length) ?? "";
+    return { workspace: slug || undefined, create: tokens.includes(CREATE_SCOPE_TOKEN) };
+}
 async function readLine() {
     let out = "";
     for await (const chunk of stdin) {
@@ -187,8 +217,8 @@ export const defaultDeviceIo = {
  * Browser device-authorization session only (no workspace token mint).
  * Shared by `uploads login` and `uploads invite create`.
  */
-export async function obtainDeviceAccessToken(authUrl, opts = {}, io = defaultDeviceIo) {
-    const code = await requestDeviceCode(authUrl);
+export async function obtainDeviceSession(authUrl, opts = {}, io = defaultDeviceIo) {
+    const code = await requestDeviceCode(authUrl, undefined, opts.scope);
     const verifyUrl = code.verification_uri_complete ?? code.verification_uri;
     const prompt = opts.prompt ?? "To sign in, open:";
     io.write(`${prompt}\n\n  ${verifyUrl}\n\nand confirm this code:\n\n  ${code.user_code}\n\n`);
@@ -197,6 +227,31 @@ export async function obtainDeviceAccessToken(authUrl, opts = {}, io = defaultDe
     io.write("Waiting for approval…\n");
     return pollForDeviceToken(authUrl, code, io);
 }
+/** Session bearer only — `invite create` has no workspace to resolve. */
+export async function obtainDeviceAccessToken(authUrl, opts = {}, io = defaultDeviceIo) {
+    return (await obtainDeviceSession(authUrl, opts, io)).accessToken;
+}
+/**
+ * Turn the API's deliberately opaque 403 (`no access to this workspace` — it
+ * refuses to distinguish "doesn't exist" from "you're not a member", see
+ * apps/api/src/routes/tokens.ts) into something the user can act on, by
+ * listing the workspaces their own account CAN reach. Backstop only: since
+ * #362 the approval page catches this before approving.
+ */
+async function describeMintFailure(apiUrl, accessToken, workspace, err) {
+    if (!(err instanceof UploadsError) || err.status !== 403)
+        throw err;
+    let names = [];
+    try {
+        names = (await listMintWorkspaces(apiUrl, accessToken)).workspaces.map((w) => w.workspace);
+    }
+    catch {
+        // Listing is best-effort — fall through to the generic hint below.
+    }
+    throw new UsageError(names.length
+        ? `no access to workspace "${workspace}" — this account can use: ${names.join(", ")}`
+        : `no access to workspace "${workspace}" — this account has no workspaces yet; pass --workspace <name> --create to provision one`);
+}
 /**
  * Device-authorization login (RFC 8628): request a code, have the user approve
  * it in a browser, poll for the session token, then mint a workspace token.
@@ -217,9 +272,22 @@ async function runDeviceLogin(parsed, opts, io) {
     // Make the target explicit: a bare `uploads login` on a self-hosted install
     // would otherwise silently sign in to the cloud service.
     io.write(`signing in to ${opts.authUrl} (self-hosted? pass --api-url or set UPLOADS_API_URL)\n\n`);
-    const accessToken = await obtainDeviceAccessToken(opts.authUrl, { noOpen: opts.noOpen }, io);
-    const workspace = await resolveMintWorkspace(opts.apiUrl, accessToken, requestedWorkspace, io, flagBool(parsed.flags, "--create"));
-    const minted = await mintWorkspaceToken(opts.apiUrl, accessToken, { workspace, scopes, label });
+    const create = flagBool(parsed.flags, "--create");
+    const session = await obtainDeviceSession(opts.authUrl, { noOpen: opts.noOpen, scope: formatDeviceScope(requestedWorkspace, create) }, io);
+    // The approval page is authoritative: it validated the workspace against the
+    // signed-in account's memberships (and may have created a new one) before
+    // approving. A scope that still carries `create` means the page deferred to
+    // the CLI, and an empty one means an older server that doesn't echo a
+    // choice — both fall back to the local resolution below.
+    const chosen = parseDeviceScope(session.scope);
+    const workspace = chosen.workspace && !chosen.create
+        ? chosen.workspace
+        : await resolveMintWorkspace(opts.apiUrl, session.accessToken, requestedWorkspace, io, create);
+    const minted = await mintWorkspaceToken(opts.apiUrl, session.accessToken, {
+        workspace,
+        scopes,
+        label,
+    }).catch((err) => describeMintFailure(opts.apiUrl, session.accessToken, workspace, err));
     return { workspace: minted.workspace, token: minted.token, apiUrl: opts.apiUrl };
 }
 function safeHostname() {
@@ -247,7 +315,7 @@ export async function pollForDeviceToken(authUrl, code, io) {
         }
         switch (result.status) {
             case "ok":
-                return result.accessToken;
+                return { accessToken: result.accessToken, scope: result.scope };
             case "pending":
                 continue;
             case "slow_down":

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;