@buildinternet/uploads 0.19.0 → 0.21.0

package/dist/commands.js

@@ -8,7 +8,9 @@ import { buildMarkdown } from "./embed.js";
 import { urlForGithubEmbed } from "./public-urls.js";
 import { UploadsError } from "./errors.js";
 import { writeJson, writeStdout } from "./io.js";
+import { imageFactsFromBytes } from "./image-facts.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
+import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./metadata-vocab.js";
 import { ghAttachmentKey, ghBranchAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, normalizeGithubCoordinate, } from "./github.js";
 import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, classifyGhNumber, execRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
 import { resolvePutPrefix } from "./destinations.js";
@@ -57,10 +59,15 @@ Uploads are public. --pr/--issue keys include the repo, number, and filename and
 remain public even for private/internal GitHub repositories. Upload only media
 that is safe at a predictable public URL.
 
-Re-uploading the same key overwrites in place (no prompt) so embeds hot-swap;
-human mode prints ">> replaced existing object (same URL)" after a real put,
-or ">> would replace existing object (same URL)" on --dry-run when the key
-already exists.
+Overwrite semantics depend on the key (issue #174): --pr/--issue always
+hot-swap in place (no prompt) so embeds stay stable — human mode prints
+">> replaced existing object (same URL)" after a real put, or ">> would
+replace existing object (same URL)" on --dry-run. Every other key (--key, or
+the default put path) is strict: re-uploading to an existing key REFUSES with
+a "key_exists" error (JSON includes the existing object's url) unless you
+pass --replace, or set UPLOADS_OVERWRITE=1 to restore old always-overwrite
+behavior for those paths. --dry-run reports ">> would refuse: key already
+exists" instead of writing.
 
 Human/json output includes durable url and (when dual-host applies) embedUrl.
 MARKDOWN prefers embedUrl for GitHub. Override: UPLOADS_EMBED_PUBLIC_BASE_URL.
@@ -97,7 +104,12 @@ Options:
                         Re-uploading to an existing key WITH --meta replaces that file's
                         entire metadata set; without --meta the existing metadata is
                         preserved. Use "uploads meta set" to edit individual keys.
-  --dry-run             Print key + public URL without uploading; reports if the key would replace an existing object. Not with --comment/--gallery
+  --state <s>           before|after|empty|error|loading — the UI state shown (sets meta state=)
+  --app <name>          Surface shown: web, ios, android, cli (sets meta app=)
+  --replace             Allow overwriting an existing object on a strict (--key/default) key
+                        (or UPLOADS_OVERWRITE=1). No effect on --pr/--issue, which always overwrite.
+  --dry-run             Print key + public URL without uploading; reports if the key would replace
+                        (or, on a strict key, be refused). Not with --comment/--gallery
 
 Exit codes: 0 ok · 2 usage/token/file · 3 auth/policy · 4 network · 1 other (incl. partial multi-file failure).
 Scripted formats (json|url|markdown) also print failures on stdout.
@@ -111,7 +123,7 @@ Examples:
   uploads put ./capture-….webp --pr 128 --name hero.webp
   uploads put ./shot.png --pr 128 --name hero.webp --dry-run --format url
   uploads put ./after.png --gallery gal_example
-  uploads put ./shot.png --meta app=myapp --meta page=settings
+  uploads put ./shot.png --meta path=/settings --state after --app web
 `;
 /**
  * Turns a pr/issue pair (+ optional repo) into a GhTarget; undefined when
@@ -233,6 +245,50 @@ export function optimizeOptionsFromFlags(flags, defaults) {
         keepExif: flagBool(flags, "--keep-exif") || defaults.keepExif === true,
     };
 }
+/**
+ * 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 function derivedMetaEnabled(flags, defaults) {
+    return (!flagBool(flags, "--no-auto") && (flagBool(flags, "--auto") || defaults.noAutoMeta !== true));
+}
+/**
+ * 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 function warnNearMissMeta(ctx, meta) {
+    if (!ctx.quiet) {
+        for (const warning of nearMissMetaWarnings(Object.keys(meta))) {
+            process.stderr.write(`!! ${warning}\n`);
+        }
+    }
+    return meta;
+}
+/**
+ * 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 function stateAppMetaFromFlags(flags) {
+    const meta = {};
+    const state = flagString(flags, "--state");
+    if (state !== undefined)
+        meta.state = validateStateValue(state);
+    const app = flagString(flags, "--app");
+    if (app !== undefined) {
+        const normalized = app.trim().toLowerCase();
+        if (normalized.length === 0)
+            throw new UsageError("--app requires a value");
+        meta.app = normalized;
+    }
+    return meta;
+}
 function formatOptimizeNote(opt) {
     if (opt.optimized) {
         return `optimized ${formatByteSize(opt.originalBytes)} → ${formatByteSize(opt.outputBytes)} (${opt.filename})`;
@@ -242,8 +298,14 @@ function formatOptimizeNote(opt) {
     }
     return undefined;
 }
-function writeReplacedNote(replaced, quiet, dryRun = false) {
-    if (!quiet && replaced) {
+function writeReplacedNote(replaced, quiet, dryRun = false, wouldRefuse = false) {
+    if (quiet)
+        return;
+    if (dryRun && wouldRefuse) {
+        process.stderr.write(`>> would refuse: key already exists (pass --replace to overwrite; or set UPLOADS_OVERWRITE=1)\n`);
+        return;
+    }
+    if (replaced) {
         process.stderr.write(dryRun
             ? `>> would replace existing object (same URL)\n`
             : `>> replaced existing object (same URL)\n`);
@@ -273,6 +335,19 @@ export async function prepareImageForUpload(bytes, filename, opts) {
     const optimized = await optimizeImageForUpload(currentBytes, currentName, opts.optimize);
     return { ...optimized, frame: frameMeta };
 }
+/**
+ * Merge an image's own EXIF-derived facts under any explicit metadata.
+ * Best-effort by contract: `imageFactsFromBytes` never rejects, and a full key
+ * budget drops the derived pairs rather than failing the upload. Returns the
+ * input untouched (including `undefined`) when there is nothing to add, so a
+ * metadata-free upload stays metadata-free.
+ */
+async function mergeImageFacts(bytes, metadata) {
+    const facts = await imageFactsFromBytes(bytes);
+    if (Object.keys(facts).length === 0)
+        return metadata;
+    return mergeDerivedMeta(metadata ?? {}, facts);
+}
 /**
  * Shared bytes-oriented upload tail: frame + optimize the bytes, resolve the
  * object key (gh attachment key wins over an explicit key; extension
@@ -283,6 +358,10 @@ export async function prepareImageForUpload(bytes, filename, opts) {
  * concurrency and delegate here per item.
  */
 export async function uploadPreparedImage(client, bytes, sourceName, opts) {
+    // Read EXIF from the original bytes before the optimizer strips it.
+    const metadata = opts.deriveImageFacts
+        ? await mergeImageFacts(bytes, opts.metadata)
+        : opts.metadata;
     const prepared = await prepareImageForUpload(bytes, sourceName, {
         frameId: opts.frame.frameId,
         frameUrl: opts.frame.frameUrl,
@@ -301,6 +380,7 @@ export async function uploadPreparedImage(client, bytes, sourceName, opts) {
         contentType: prepared.optimized ? prepared.contentType : opts.contentType,
         deriveRepoFromGit: opts.deriveRepoFromGit,
         dryRun: opts.dryRun,
+        replace: opts.replace,
         provenance: buildCliProvenance({
             sourceName,
             client: opts.provenanceClient,
@@ -308,7 +388,7 @@ export async function uploadPreparedImage(client, bytes, sourceName, opts) {
             frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
             keepExif: opts.optimize.keepExif === true,
         }),
-        metadata: opts.metadata,
+        metadata,
     });
     const markdown = buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
         alt: opts.alt(prepared),
@@ -347,8 +427,7 @@ export function commentViaSuffix(via) {
 /**
  * Thrown by `syncAttachmentsComment` when the server declines with
  * `not_authorized` (issue #297 baseline control) — this repo is bound to a
- * different workspace, 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.
@@ -504,13 +583,15 @@ Options:
                         Because attach always sends its own gh.* pairs, re-attaching to
                         the same key always replaces that file's entire metadata set
                         (never preserves) — use "uploads meta set" to add to it instead.
+  --state <s>           before|after|empty|error|loading — the UI state shown (sets meta state=)
+  --app <name>          Surface shown: web, ios, android, cli (sets meta app=)
 
 Examples:
   uploads attach ./before.png ./after.png
   uploads attach ./mobile.png --frame phone
   uploads attach ./shot.png --pr 123 --repo myorg/myapp
   uploads attach ./artifact.zip --issue 45 --no-comment
-  uploads attach ./shot.png --meta app=myapp --meta page=settings
+  uploads attach ./shot.png --meta path=/settings --state after
   uploads attach ./shot.png --branch
   uploads attach ./shot.png --branch feature/new-settings
   uploads attach --promote
@@ -528,7 +609,13 @@ async function uploadAttachmentBatch(opts) {
     const slots = await mapBounded(opts.files, opts.concurrency ?? UPLOAD_BATCH_CONCURRENCY, async (file) => {
         try {
             const sourceName = basename(file);
-            const prepared = await prepareImageForUpload(readFileArg(file), sourceName, {
+            const bytes = readFileArg(file);
+            // Same EXIF promotion uploadPreparedImage does; attach keeps its own
+            // per-file tail (it builds keys differently), so it opts in here too.
+            const metadata = opts.deriveImageFacts
+                ? await mergeImageFacts(bytes, opts.metadata)
+                : opts.metadata;
+            const prepared = await prepareImageForUpload(bytes, sourceName, {
                 ...opts.frame,
                 optimize: opts.optimize,
             });
@@ -543,7 +630,7 @@ async function uploadAttachmentBatch(opts) {
                     frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
                     keepExif: opts.optimize.keepExif === true,
                 }),
-                metadata: opts.metadata,
+                metadata,
             });
             return {
                 ok: true,
@@ -643,7 +730,9 @@ export async function uploadPuts(opts) {
                 deriveRepoFromGit: opts.deriveRepoFromGit,
                 contentType: opts.contentType,
                 dryRun: opts.dryRun,
+                replace: opts.replace,
                 metadata: opts.metadata,
+                deriveImageFacts: opts.deriveImageFacts,
                 provenanceClient: opts.provenanceClient,
                 alt: () => opts.alt ?? basename(sourceName),
                 width: opts.width,
@@ -761,8 +850,12 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     // Validate the merged map (not just the extras) so the 24-key/8KB caps are
     // enforced client-side even when extras alone are under the cap but extras
     // + the gh.* pairs push the merged map over it.
-    const metaExtras = parseMetaFlags(flagValues(parsed.flags, "--meta"));
-    const metadata = { ...metaExtras, ...ghMetadataFromTargetWithTitle(target, run) };
+    const metaExtras = warnNearMissMeta(ctx, parseMetaFlags(flagValues(parsed.flags, "--meta")));
+    const metadata = {
+        ...metaExtras,
+        ...stateAppMetaFromFlags(parsed.flags),
+        ...ghMetadataFromTargetWithTitle(target, run),
+    };
     if (Object.keys(metadata).length > 0)
         validateMetaMap(metadata);
     const logHuman = !ctx.quiet && !ctx.json;
@@ -778,6 +871,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         optimize: optimizeOpts,
         frame: frameOpts,
         metadata,
+        deriveImageFacts: derivedMetaEnabled(parsed.flags, defaults),
     });
     // Single-file total failure: rethrow so CLI exit codes stay auth/network-aware.
     if (uploads.length === 0 && failures.length === 1 && parsed.positionals.length === 1) {
@@ -868,8 +962,12 @@ async function runAttachBranch(ctx, parsed, branch, run) {
     const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
     const frameOpts = frameOptionsFromFlags(parsed.flags);
     const contentTypeOverride = flagString(parsed.flags, "--content-type");
-    const metaExtras = parseMetaFlags(flagValues(parsed.flags, "--meta"));
-    const metadata = { ...metaExtras, ...ghMetadataForBranch(repo, branch) };
+    const metaExtras = warnNearMissMeta(ctx, parseMetaFlags(flagValues(parsed.flags, "--meta")));
+    const metadata = {
+        ...metaExtras,
+        ...stateAppMetaFromFlags(parsed.flags),
+        ...ghMetadataForBranch(repo, branch),
+    };
     validateMetaMap(metadata);
     const logHuman = !ctx.quiet && !ctx.json;
     if (logHuman) {
@@ -885,6 +983,7 @@ async function runAttachBranch(ctx, parsed, branch, run) {
         optimize: optimizeOpts,
         frame: frameOpts,
         metadata,
+        deriveImageFacts: derivedMetaEnabled(parsed.flags, defaults),
     });
     // Single-file total failure: rethrow so CLI exit codes stay auth/network-aware.
     if (uploads.length === 0 && failures.length === 1 && parsed.positionals.length === 1) {
@@ -987,10 +1086,20 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const galleryId = flagString(parsed.flags, "--gallery");
     const nameFlag = flagString(parsed.flags, "--name");
     const dryRun = flagBool(parsed.flags, "--dry-run");
+    // Strict-overwrite escape hatch (issue #174): only matters on non-gh/ keys
+    // (--key or the default put path) — the server ignores `replace` on
+    // managed gh/ paths (--pr/--issue), which always hot-swap regardless.
+    const replaceFlag = flagBool(parsed.flags, "--replace") || process.env.UPLOADS_OVERWRITE === "1";
     // Validate --meta up front (fail fast, before reading/optimizing the file).
     const userMeta = (() => {
         const pairs = flagValues(parsed.flags, "--meta");
-        return pairs.length > 0 ? parseMetaFlags(pairs) : undefined;
+        const fromMeta = warnNearMissMeta(ctx, pairs.length > 0 ? parseMetaFlags(pairs) : {});
+        // Dedicated flags are explicit input and win over a same-named --meta pair.
+        const merged = { ...fromMeta, ...stateAppMetaFromFlags(parsed.flags) };
+        if (Object.keys(merged).length === 0)
+            return undefined;
+        validateMetaMap(merged);
+        return merged;
     })();
     if (wantComment && typeof parsed.flags.get("--comment") === "string") {
         throw new UsageError("--comment takes no value — place it after the file argument");
@@ -1084,10 +1193,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         attachedRef = merged["gh.ref"];
     }
     else {
-        const autoEnabled = !noGit &&
-            !flagBool(parsed.flags, "--no-auto") &&
-            (flagBool(parsed.flags, "--auto") || defaults.noAutoMeta !== true);
-        if (autoEnabled) {
+        // gh.* additionally needs git, which the shared derived gate ignores.
+        if (!noGit && derivedMetaEnabled(parsed.flags, defaults)) {
             const autoTarget = resolveAutoGhTarget(flagString(parsed.flags, "--repo") ?? defaults.repo, flagString(parsed.flags, "--ref") ?? defaults.ref, run);
             if (autoTarget) {
                 const autoMeta = ghMetadataFromTargetWithTitle(autoTarget, run);
@@ -1129,9 +1236,11 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         deriveRepoFromGit: !noGit,
         contentType: contentTypeOverride,
         dryRun,
+        replace: replaceFlag,
         optimize: optimizeOpts,
         frame: frameOpts,
         metadata,
+        deriveImageFacts: derivedMetaEnabled(parsed.flags, defaults),
         alt: altFlag,
         width,
     });
@@ -1195,7 +1304,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                     const note = formatOptimizeNote(result.optimize);
                     if (note)
                         process.stderr.write(`>> ${basename(result.file)}: ${note}\n`);
-                    writeReplacedNote(result.replaced, false, dryRun);
+                    writeReplacedNote(result.replaced, false, dryRun, result.wouldRefuse);
                     process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n`);
                 }
                 const gallery = galleriesByKey.get(result.key);
@@ -1227,7 +1336,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         const note = formatOptimizeNote(result.optimize);
         if (note)
             process.stderr.write(`>> ${note}\n`);
-        writeReplacedNote(result.replaced, ctx.quiet, dryRun);
+        writeReplacedNote(result.replaced, ctx.quiet, dryRun, result.wouldRefuse);
         process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n\n`);
     }
     switch (format) {
@@ -1569,7 +1678,7 @@ Human-friendly alias for \`uploads list --meta k=v...\` — same metadata filter
 
 Examples:
   uploads find gh.repo=buildinternet/uploads gh.number=123
-  uploads find app=myapp page=settings --prefix screenshots/
+  uploads find path=/settings state=after --prefix screenshots/
 `;
 export async function runFind(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
@@ -1596,8 +1705,8 @@ Commands:
 
 Examples:
   uploads meta get screenshots/myapp/42/shot.png
-  uploads meta set screenshots/myapp/42/shot.png app=myapp page=settings
-  uploads meta set screenshots/myapp/42/shot.png --delete app --delete page
+  uploads meta set screenshots/myapp/42/shot.png path=/settings state=after
+  uploads meta set screenshots/myapp/42/shot.png --delete path --delete state
 `;
 export async function runMeta(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
@@ -1694,10 +1803,9 @@ App is installed on the repo; otherwise via your local gh auth. Finds its own
 prior comment via a hidden marker and edits it in place; never touches other
 comments or the description.
 
-If this repo is bound to a different workspace (or unbound and you're on the
-communal "default" workspace), the bot post is declined and this command
-fails rather than silently falling back to gh — see \`uploads github link
---status\`.
+If this repo is bound to a different workspace, the bot post is declined and
+this command fails rather than silently falling back to gh — see
+\`uploads github link --status\`.
 
 Examples:
   uploads --env-file .env comment --pr 123
@@ -1822,7 +1930,19 @@ async function runGithubLink(ctx, repo, statusOnly) {
         return 0;
     }
     if (!statusOnly && result.claimed === false) {
-        process.stderr.write(`note: ${repo} is already bound to a different workspace ("${result.workspace}") — first-claim-wins, not overwritten. Run "uploads github unlink --repo ${repo}" from that workspace, or ask an operator to reassign it.\n`);
+        // Cross-tenant authorization (issue #297): `reason: "not_authorized"`
+        // means the repo is unbound but this workspace couldn't be verified as
+        // entitled to claim it (no linked GitHub account, or that account lacks
+        // push access) — distinct from the older "someone else already owns it"
+        // case, which still reports `result.workspace`.
+        if (result.reason === "not_authorized") {
+            process.stderr.write(`note: ${repo} isn't linked to any workspace yet, and this workspace couldn't be ` +
+                `verified as entitled to claim it. Link a GitHub account with push access to ` +
+                `${repo}, or ask an operator to bind it explicitly.\n`);
+        }
+        else {
+            process.stderr.write(`note: ${repo} is already bound to a different workspace ("${result.workspace}") — first-claim-wins, not overwritten. Run "uploads github unlink --repo ${repo}" from that workspace, or ask an operator to reassign it.\n`);
+        }
     }
     await writeStdout(formatGithubLink(repo, result));
     return 0;

package/dist/errors.d.ts

@@ -1,6 +1,14 @@
-export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "FILE_NOT_FOUND" | "NOT_FOUND" | "UNAUTHORIZED" | "INSUFFICIENT_SCOPE" | "INVALID_KEY" | "KEY_POLICY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "GITHUB_REQUIRED" | "API_ERROR" | "NETWORK" | "USAGE" | "BROWSER_NOT_FOUND" | "RENDER_FAILED" | "RATE_LIMITED";
+export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "FILE_NOT_FOUND" | "NOT_FOUND" | "UNAUTHORIZED" | "INSUFFICIENT_SCOPE" | "INVALID_KEY" | "KEY_POLICY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "GITHUB_REQUIRED" | "KEY_EXISTS" | "API_ERROR" | "NETWORK" | "USAGE" | "BROWSER_NOT_FOUND" | "RENDER_FAILED" | "RATE_LIMITED";
 export declare class UploadsError extends Error {
     readonly code: UploadsErrorCode;
     readonly status?: number;
-    constructor(message: string, code: UploadsErrorCode, status?: number);
+    /**
+     * The existing object's public URL, set only for `KEY_EXISTS` (strict
+     * overwrite refusal, issue #174) — lets a catch site point the caller at
+     * what's already there without a follow-up lookup.
+     */
+    readonly existingUrl?: string;
+    constructor(message: string, code: UploadsErrorCode, status?: number, opts?: {
+        existingUrl?: string;
+    });
 }

package/dist/errors.js

@@ -1,10 +1,17 @@
 export class UploadsError extends Error {
     code;
     status;
-    constructor(message, code, status) {
+    /**
+     * The existing object's public URL, set only for `KEY_EXISTS` (strict
+     * overwrite refusal, issue #174) — lets a catch site point the caller at
+     * what's already there without a follow-up lookup.
+     */
+    existingUrl;
+    constructor(message, code, status, opts) {
         super(message);
         this.name = "UploadsError";
         this.code = code;
         this.status = status;
+        this.existingUrl = opts?.existingUrl;
     }
 }

package/dist/image-facts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Map exif-reader's parsed tags onto canonical keys. Pure and total: junk
+ * input yields `{}`. Only `device`, `software` and `captured` are ever read —
+ * every other tag, including all of GPSInfo, is ignored by construction.
+ */
+export declare function factsFromExifTags(tags: unknown): Record<string, string>;
+/**
+ * Read canonical facts from image bytes. Best-effort by contract: any failure
+ * (not an image, corrupt EXIF, unsupported format) yields `{}` and must never
+ * fail the upload.
+ */
+export declare function imageFactsFromBytes(bytes: Uint8Array): Promise<Record<string, string>>;

package/dist/image-facts.js

@@ -0,0 +1,108 @@
+/**
+ * Canonical metadata promoted from an image's own EXIF, read *before* the
+ * optimizer strips it from the bytes. `--keep-exif` is orthogonal: it governs
+ * whether the uploaded bytes retain EXIF, not whether we promote these keys.
+ *
+ * Promotion is allowlist-only. Anything not named here is discarded, and the
+ * denials (GPS, serials, personal names, free-form comments) are load-bearing:
+ * promoted values render on the public /f/ page.
+ *
+ * Design: .context/2026-07-21-upload-metadata-vocabulary-design.md
+ */
+import exifReader from "exif-reader";
+import sharp from "sharp";
+import { dropUnsafeMetaValues } from "./metadata.js";
+import { formatViewport } from "./metadata-vocab.js";
+/** Below this, the image is a 1:1 photo rather than a scaled screen capture. */
+const SCREEN_CAPTURE_MIN_DENSITY = 72;
+function asString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+/** EXIF's `YYYY:MM:DD HH:MM:SS` (or a parsed Date) → ISO 8601, zone-honest. */
+function formatCaptured(raw, offset) {
+    let stamp;
+    if (raw instanceof Date && !Number.isNaN(raw.getTime())) {
+        // exif-reader builds this Date from the EXIF wall-clock digits as if UTC,
+        // so the ISO prefix reproduces those digits exactly.
+        stamp = raw.toISOString().slice(0, 19);
+    }
+    else {
+        const text = asString(raw);
+        const match = text && /^(\d{4}):(\d{2}):(\d{2})[ T](\d{2}:\d{2}:\d{2})$/.exec(text);
+        if (match)
+            stamp = `${match[1]}-${match[2]}-${match[3]}T${match[4]}`;
+    }
+    if (!stamp)
+        return undefined;
+    // Only claim a zone when EXIF actually carried one. Never append a bare "Z".
+    const zone = offset && /^[+-]\d{2}:\d{2}$/.test(offset) ? offset : "";
+    return `${stamp}${zone}`;
+}
+/** Combine Make + Model without repeating the make (`Canon` + `Canon EOS R5`). */
+function formatDevice(make, model) {
+    if (!model)
+        return make;
+    if (!make)
+        return model;
+    return model.toLowerCase().startsWith(make.toLowerCase()) ? model : `${make} ${model}`;
+}
+/**
+ * Map exif-reader's parsed tags onto canonical keys. Pure and total: junk
+ * input yields `{}`. Only `device`, `software` and `captured` are ever read —
+ * every other tag, including all of GPSInfo, is ignored by construction.
+ */
+export function factsFromExifTags(tags) {
+    const facts = {};
+    if (!tags || typeof tags !== "object")
+        return facts;
+    const root = tags;
+    const image = (root.Image ?? {});
+    const photo = (root.Photo ?? {});
+    const device = formatDevice(asString(image.Make), asString(image.Model));
+    if (device)
+        facts.device = device;
+    const software = asString(image.Software);
+    if (software)
+        facts.software = software;
+    const captured = formatCaptured(photo.DateTimeOriginal, asString(photo.OffsetTimeOriginal));
+    if (captured)
+        facts.captured = captured;
+    // Derived values must satisfy the metadata contract or be dropped silently —
+    // same posture as the existing best-effort gh.title.
+    return dropUnsafeMetaValues(facts);
+}
+/**
+ * Read canonical facts from image bytes. Best-effort by contract: any failure
+ * (not an image, corrupt EXIF, unsupported format) yields `{}` and must never
+ * fail the upload.
+ */
+export async function imageFactsFromBytes(bytes) {
+    if (bytes.byteLength === 0)
+        return {};
+    let meta;
+    try {
+        meta = await sharp(bytes, { failOn: "none" }).metadata();
+    }
+    catch {
+        return {};
+    }
+    if (!meta.format)
+        return {};
+    const facts = {};
+    // A density above 72dpi means a scaled screen capture: recover the logical
+    // size the user actually saw. Camera photos report 72 and are skipped.
+    const { width, height, density } = meta;
+    if (width && height && density && density > SCREEN_CAPTURE_MIN_DENSITY) {
+        const scale = density / SCREEN_CAPTURE_MIN_DENSITY;
+        facts.viewport = formatViewport(width / scale, height / scale, scale);
+    }
+    if (meta.exif) {
+        try {
+            Object.assign(facts, factsFromExifTags(exifReader(meta.exif)));
+        }
+        catch {
+            // Unparseable EXIF is not an error — keep whatever we already derived.
+        }
+    }
+    return facts;
+}

package/dist/mcp/args.d.ts

@@ -1,6 +1,8 @@
 export type ToolArgs = Record<string, unknown>;
 export declare function usage(msg: string): never;
 export declare function optString(args: ToolArgs, name: string): string | undefined;
+/** A boolean flag argument; missing/null reads as `false`. */
+export declare function optBool(args: ToolArgs, name: string): boolean;
 export declare function optPosInt(args: ToolArgs, name: string): number | undefined;
 /** A JSON-object argument of string→string pairs (e.g. a `metadata` or `filters` param). */
 export declare function optStringRecord(args: ToolArgs, name: string): Record<string, string> | undefined;
@@ -11,7 +13,7 @@ export declare function optStringArray(args: ToolArgs, name: string): string[] |
  * `filters` params across the CLI/local MCP (put/attach/set_metadata/
  * find_files) and the remote MCP worker (set_metadata/find_files).
  */
-export declare const METADATA_DESCRIPTION = "Queryable custom metadata (key\u2192value), 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 declare const METADATA_DESCRIPTION = "Queryable custom metadata (key\u2192value), 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) \u2014 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 declare const metadataProp: {
     type: string;
     additionalProperties: {
@@ -19,3 +21,24 @@ export declare const metadataProp: {
     };
     description: string;
 };
+export declare const stateProp: {
+    type: string;
+    enum: ("before" | "after" | "empty" | "error" | "loading")[];
+    description: string;
+};
+export declare const appProp: {
+    type: string;
+    description: string;
+};
+/**
+ * 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 declare function canonicalMetaFromArgs(args: ToolArgs): Record<string, string>;
+/**
+ * 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 declare function metadataArgWithCanonical(args: ToolArgs): Record<string, string> | undefined;