@buildinternet/uploads 0.19.0 → 0.22.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.
@@ -385,12 +464,27 @@ export async function syncAttachmentsComment(client, target, run, workspace) {
         }
     }
     // gh fallback: gather from this workspace's own data and post via local `gh`.
-    // Note (issue #304): this CLI process has no server-side WorkspaceRecord in
-    // scope, so it cannot honor a workspace's githubCommentLinkToFilePage=false
-    // — it always links to the file page here, matching the default. This only
-    // diverges from the bot-posted comment for a workspace that both sets the
-    // flag false and falls through to this gh-fallback path.
-    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url, embedUrl, pageUrl }) => ({ key, url, embedUrl, pageUrl }));
+    // Note (issues #304, #365): this CLI process has no server-side
+    // WorkspaceRecord in scope, so it cannot honor a workspace's
+    // githubCommentLinkToFilePage=false or githubCommentShowMetadata=false — it
+    // always links to the file page and always shows metadata here, matching the
+    // defaults. This only diverges from the bot-posted comment for a workspace
+    // that both sets one of those flags false and falls through to this path.
+    const items = (await client.listAll({ prefix: ghKeyPrefix(target), metadata: true })).map(({ key, url, embedUrl, pageUrl, metadata }) => {
+        // The list endpoint returns every metadata key; the comment renders only
+        // these two. Narrowing here keeps both render paths byte-identical.
+        const path = metadata?.path;
+        const state = metadata?.state;
+        return {
+            key,
+            url,
+            embedUrl,
+            pageUrl,
+            ...(path || state
+                ? { meta: { ...(path ? { path } : {}), ...(state ? { state } : {}) } }
+                : {}),
+        };
+    });
     const galleries = [];
     let cursor;
     do {
@@ -504,13 +598,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 +624,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 +645,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 +745,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 +865,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 +886,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 +977,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 +998,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 +1101,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 +1208,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 +1251,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 +1319,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 +1351,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 +1693,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 +1720,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 +1818,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 +1945,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/github.d.ts

@@ -75,6 +75,17 @@ export interface AttachmentItem {
     embedUrl?: string | null;
     /** Canonical `/f/` file-page URL (server-computed). Preferred click-through target; falls back to `url`. */
     pageUrl?: string | null;
+    /**
+     * The only canonical metadata the managed comment renders (issue #365).
+     * Deliberately two named fields rather than `Record<string, string>`: the
+     * comment is posted publicly, and keeping the set narrow at the type level
+     * mirrors the server-side query filter that never fetches EXIF-derived
+     * keys like `device`/`software` for this path.
+     */
+    meta?: {
+        path?: string;
+        state?: string;
+    };
 }
 /** A public gallery linked to the PR or issue whose managed comment is syncing. */
 export interface GalleryCommentItem {

package/dist/github.js

@@ -177,6 +177,51 @@ function escapeHtmlAttr(s) {
 function escapeHtmlText(s) {
     return escapeHtmlAttr(s).replace(/'/g, "'").replace(/>/g, ">");
 }
+/**
+ * Backslash-escape the markdown metacharacters that can appear in a metadata
+ * value. `~` is in the set because GitHub's strikethrough extension treats a
+ * matching pair of ONE or two tildes as markup, so an unescaped `/a~b~c` would
+ * render with `b` struck through.
+ */
+function escapeMarkdownText(s) {
+    return s.replace(/([\\`*_[\]~])/g, "\\$1");
+}
+/**
+ * An attachment's caption parts — `path`, then `state` (issue #365). Empty
+ * when neither is usable, so callers emit nothing at all and a body with no
+ * metadata stays byte-identical to the pre-#365 render.
+ *
+ * Neither value is pre-sanitized: metadata values are printable ASCII up to
+ * 512 chars, and while the CLI validates `--state` against a closed enum,
+ * `PATCH /v1/:workspace/files/:key` can set any valid metadata value. A
+ * whitespace-only value passes that validation (length-1 printable ASCII), so
+ * treat it as absent rather than rendering a dangling separator.
+ */
+function metaCaptionParts(meta) {
+    const parts = [];
+    for (const value of [meta?.path, meta?.state]) {
+        const trimmed = value?.trim();
+        if (trimmed)
+            parts.push(trimmed);
+    }
+    return parts;
+}
+/** `<sub>` caption body for an inline image, or null when there is nothing to say. */
+function metaCaptionHtml(meta) {
+    const parts = metaCaptionParts(meta);
+    return parts.length > 0 ? parts.map(escapeHtmlText).join(" · ") : null;
+}
+/**
+ * ` · …` suffix for a markdown list row, or `""` when there is nothing to add.
+ * HTML-escapes first, then markdown-escapes: HTML escaping introduces no
+ * backslashes or brackets, so the markdown pass cannot corrupt its entities.
+ */
+function metaCaptionMarkdown(meta) {
+    const parts = metaCaptionParts(meta);
+    if (parts.length === 0)
+        return "";
+    return ` · ${parts.map((p) => escapeMarkdownText(escapeHtmlText(p))).join(" · ")}`;
+}
 /**
  * Render the one marker-owned GitHub comment. When there are no galleries this
  * intentionally preserves the legacy attachment-only body byte-for-byte.
@@ -224,13 +269,16 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
             const href = escapeHtmlAttr(link ?? src);
             const imgSrc = escapeHtmlAttr(src);
             lines.push(`<a href="${href}"><img width="${w}" alt="${alt}" src="${imgSrc}"></a>`);
+            const caption = metaCaptionHtml(item.meta);
+            if (caption)
+                lines.push(`<sub>${caption}</sub>`);
             lines.push("");
         }
         else if (link) {
-            lines.push(`- [${name}](${link})`);
+            lines.push(`- [${name}](${link})${metaCaptionMarkdown(item.meta)}`);
         }
         else {
-            lines.push(`- ${name}`);
+            lines.push(`- ${name}${metaCaptionMarkdown(item.meta)}`);
         }
     }
     if (overflowImages.length > 0) {
@@ -239,7 +287,8 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
         for (const item of overflowImages) {
             const name = item.key.slice(item.key.lastIndexOf("/") + 1);
             const link = item.pageUrl ?? item.url;
-            lines.push(link ? `- [${name}](${link})` : `- ${name}`);
+            const suffix = metaCaptionMarkdown(item.meta);
+            lines.push(link ? `- [${name}](${link})${suffix}` : `- ${name}${suffix}`);
         }
         lines.push("", "</details>", "");
     }

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>>;