@buildinternet/uploads 0.26.1 → 0.28.0

package/dist/commands.js

@@ -11,7 +11,8 @@ 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, ghBranchKeyPrefix, ghKeyPrefix, ghMetadataFromTarget, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, normalizeGithubCoordinate, } from "./github.js";
+import { mergeSidecarMeta } from "./sidecar.js";
+import { ghAttachmentKey, ghBranchAttachmentKey, ghBranchKeyPrefix, ghKeyPrefix, ghMetadataFromTarget, parseGhKey, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, normalizeGithubCoordinate, } from "./github.js";
 import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, resolveDefaultBranch, classifyGhNumber, execRunner, timedExecRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
 import { deriveRepoFromGit } from "./keys.js";
 import { resolvePutPrefix } from "./destinations.js";
@@ -56,6 +57,12 @@ upload as-is, or --keep-exif when image metadata matters for the discussion.
 Optional --frame wraps the image in a device/browser chrome before optimize
 (default off). See: uploads put --help frames
 
+If the file has a sidecar manifest (<file>.uploads.json, written by
+"screenshot --out") and its content hash still matches this file, that
+capture's derived metadata (path/url/env/viewport/state) is merged in
+automatically — explicit --meta/--state always win. A regenerated or edited
+file loses its sidecar silently (hash no longer matches).
+
 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.
@@ -443,13 +450,21 @@ export function commentViaSuffix(via) {
  */
 export class GithubCommentAuthorizationError extends Error {
 }
-export async function syncAttachmentsComment(client, target, run, workspace) {
+/**
+ * `opts.resync` marks an explicit `uploads comment` invocation rather than a
+ * background sync (attach, screenshot, put --comment). It costs the server one
+ * extra comment listing and in exchange collapses any duplicate managed
+ * comment (issue #480) — worth it on the rare, explicitly-asked-for resync,
+ * not on every attach.
+ */
+export async function syncAttachmentsComment(client, target, run, workspace, opts = {}) {
     let bot;
     try {
         bot = await client.upsertGithubComment({
             repo: target.repo,
             num: target.num,
             kind: target.kind,
+            ...(opts.resync ? { resync: true } : {}),
         });
     }
     catch {
@@ -558,6 +573,12 @@ URL and every embed hot-swap. Human mode prints ">> replaced existing object
 Still images are optimized to WebP by default (same as put). Use --no-optimize
 to upload originals. Optional --frame wraps images in device/browser chrome.
 
+If a file has a sidecar manifest (<file>.uploads.json, written by
+"screenshot --out") and its content hash still matches, that capture's
+derived metadata (path/url/env/viewport/state) is merged in automatically —
+explicit --meta/--state always win. A regenerated or edited file loses its
+sidecar silently (hash no longer matches).
+
 Branch staging (pre-PR): --branch [name] stages files against a git branch
 before a pull request exists, e.g. for a coding agent working a branch that
 hasn't opened a PR yet. Key: gh/<owner>/<repo>/branch/<branch>/<filename>
@@ -620,6 +641,21 @@ Examples:
   uploads attach ./shot.png --branch feature/new-settings
   uploads attach --promote
 `;
+/**
+ * Lever 3 (issue #469): a nudge for when an image lands on a PR/issue with
+ * no `path` metadata — `path` is one of the highest-value queryable tags
+ * (same tier as `state=`), and unlike `uploads screenshot` (which derives it
+ * from the captured URL), a plain `attach`/`put --pr`/`put --issue` of an
+ * already-existing image has nothing to derive it from, so it's easy to
+ * forget. Fires once per batch (not per file) — checks the metadata the
+ * server actually stored (`PutResult.metadata`), not what was requested, so
+ * a merge/validation drop still surfaces the gap. Non-image uploads (zips,
+ * PDFs, etc.) are exempt — "findable by page" doesn't apply to them.
+ */
+export function pathMetaHintFor(uploads) {
+    const missingPath = uploads.some((u) => u.contentType.startsWith("image/") && !u.metadata?.path);
+    return missingPath ? "tip: add --meta path=/route so this shot is findable by page" : undefined;
+}
 /**
  * Shared prepare + put loop for both PR/issue attach (`uploadAttachments`)
  * and branch-staged attach (`uploadBranchAttachments`) — bounded concurrency,
@@ -634,11 +670,14 @@ async function uploadAttachmentBatch(opts) {
         try {
             const sourceName = basename(file);
             const bytes = readFileArg(file);
+            // Sidecar manifest from a prior `screenshot --out` of this exact file
+            // (issue #469 lever 2) — see mergeSidecarMeta.
+            const baseMetadata = mergeSidecarMeta(file, bytes, opts.metadata);
             // 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;
+                ? await mergeImageFacts(bytes, baseMetadata)
+                : baseMetadata;
             const prepared = await prepareImageForUpload(bytes, sourceName, {
                 ...opts.frame,
                 optimize: opts.optimize,
@@ -743,7 +782,11 @@ export async function uploadPuts(opts) {
                         ? basename(opts.explicitKey)
                         : "stdin.bin"
                     : basename(file));
-            const { result, prepared, markdown } = await uploadPreparedImage(opts.client, readFileArg(file), sourceName, {
+            const bytes = readFileArg(file);
+            // Sidecar manifest from a prior `screenshot --out` of this exact file
+            // (issue #469 lever 2) — see mergeSidecarMeta. Not applicable to stdin.
+            const metadata = file !== "-" ? mergeSidecarMeta(file, bytes, opts.metadata) : opts.metadata;
+            const { result, prepared, markdown } = await uploadPreparedImage(opts.client, bytes, sourceName, {
                 frame: opts.frame,
                 optimize: opts.optimize,
                 ghTarget: opts.ghTarget,
@@ -756,7 +799,7 @@ export async function uploadPuts(opts) {
                 contentType: opts.contentType,
                 dryRun: opts.dryRun,
                 replace: opts.replace,
-                metadata: opts.metadata,
+                metadata,
                 deriveImageFacts: opts.deriveImageFacts,
                 provenanceClient: opts.provenanceClient,
                 alt: () => opts.alt ?? basename(sourceName),
@@ -935,6 +978,8 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
             process.stderr.write(`warning: uploads succeeded but the GitHub comment failed (is gh installed and authenticated?): ${commentError}\n`);
         }
     }
+    // Lever 3 (issue #469): tip when an image lands here with no `path` meta.
+    const pathHint = uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads) : undefined;
     if (ctx.json) {
         await writeJson({
             target,
@@ -943,6 +988,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
             comment,
             commentError,
             promotion: promotion ?? null,
+            ...(pathHint ? { hint: pathHint } : {}),
         });
     }
     else {
@@ -971,6 +1017,8 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
             const ref = ghMetadataFromTarget(target)["gh.ref"];
             process.stderr.write(`>> find these later: uploads find gh.ref=${ref}\n`);
         }
+        if (pathHint)
+            process.stderr.write(`${pathHint}\n`);
     }
     return failures.length === 0 ? 0 : 1;
 }
@@ -1269,6 +1317,18 @@ export function resolvePutStagingTarget(opts) {
         return undefined; // gh/git unavailable, or repo unresolvable — dated layout
     }
 }
+/**
+ * Merges a staging target's `gh.*` branch metadata over `base` and validates
+ * the result (same builder, same contract as `attach --branch`) — the one
+ * merge+validate step shared by every staging call site: `runPut`,
+ * `runScreenshot`, and both the local stdio MCP `put` and `screenshot`
+ * tools.
+ */
+export function mergeStagingMeta(base, target) {
+    const merged = { ...base, ...ghMetadataForBranch(target.repo, target.branch) };
+    validateMetaMap(merged);
+    return merged;
+}
 /**
  * The bare-put staging note's wording (issue #403): replaces the #393 nudge
  * for the (now default) case where a bare put on a non-default branch stages
@@ -1553,12 +1613,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         attachedRef = merged["gh.ref"];
     }
     else if (stagingTarget) {
-        const merged = {
-            ...userMeta,
-            ...ghMetadataForBranch(stagingTarget.repo, stagingTarget.branch),
-        };
-        validateMetaMap(merged); // matches attach --branch's unwrapped call — same builder, same contract
-        metadata = merged;
+        metadata = mergeStagingMeta(userMeta, stagingTarget);
     }
     else {
         // gh.* additionally needs git, which the shared derived gate ignores.
@@ -1648,13 +1703,19 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const bindingWarning = stagingTarget && uploads.length > 0
         ? await resolveStageBindingWarning({ ctx, defaults, repo: stagingTarget.repo })
         : undefined;
+    // Lever 3 (issue #469): tip when a --pr/--issue put lands an image with no
+    // `path` meta. Only relevant on the ghTarget path — the bare-put paths
+    // above (staging/auto/dated) aren't attached to a PR/issue yet, so there's
+    // nothing to look up from a page later.
+    const pathHint = ghTarget && uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads) : undefined;
     // One JSON `hint` slot, shared with the #393 nudge (mutually exclusive with
     // it — nudge is undefined whenever staging took over). When staging fires,
     // prefer the more actionable binding warning over the generic staging note
     // (mirrors attach --branch, whose only JSON hint content IS the binding
     // warning); stderr prints the nudge/staging-note and binding-warning lines
-    // independently, below.
-    const jsonHint = nudge ?? bindingWarning ?? stagingNote;
+    // independently, below. pathHint only ever fires on the ghTarget path, so
+    // it never competes with the other three.
+    const jsonHint = nudge ?? bindingWarning ?? stagingNote ?? pathHint;
     const galleriesByKey = new Map();
     let galleryHadError = false;
     if (galleryId && uploads.length > 0) {
@@ -1737,6 +1798,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 process.stderr.write(`${stagingNote}\n`);
             if (bindingWarning)
                 process.stderr.write(`${bindingWarning}\n`);
+            if (pathHint)
+                process.stderr.write(`${pathHint}\n`);
         }
         return failures.length === 0 && !galleryHadError ? 0 : 1;
     }
@@ -1794,6 +1857,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         process.stderr.write(`${stagingNote}\n`);
     if (bindingWarning && format !== "json")
         process.stderr.write(`${bindingWarning}\n`);
+    if (pathHint && format !== "json")
+        process.stderr.write(`${pathHint}\n`);
     return gallery?.error ? 1 : 0;
 }
 // --- galleries ---
@@ -2173,12 +2238,51 @@ export async function runMeta(ctx, args, help = false) {
             else
                 for (const [k, v] of Object.entries(result.metadata))
                     await writeStdout(`${k}=${v}\n`);
+            await resyncCommentAfterMetaSet(ctx, key, [...Object.keys(set ?? {}), ...del]);
             return 0;
         }
         default:
             throw new UsageError(`unknown meta command: ${action}`);
     }
 }
+/** The metadata keys the managed comment renders (path/state, PR #370). */
+const COMMENT_RENDERED_META_KEYS = ["path", "state"];
+/**
+ * Best-effort managed-comment refresh after `meta set` touches a
+ * display-relevant key on a PR/issue-keyed object (issue #470) — without
+ * this, backfilled `path=`/`state=` never reaches the rendered comment until
+ * an unrelated attach fires. Bot endpoint only (no gh fallback — this is a
+ * metadata tweak, not an explicit comment command); any failure degrades to
+ * a stderr hint instead of failing the metadata write that already landed.
+ */
+async function resyncCommentAfterMetaSet(ctx, key, touchedKeys) {
+    if (!touchedKeys.some((k) => COMMENT_RENDERED_META_KEYS.includes(k)))
+        return;
+    const target = parseGhKey(key);
+    if (!target)
+        return;
+    try {
+        const bot = await ctx.client.upsertGithubComment({
+            repo: target.repo,
+            num: target.num,
+            kind: target.kind,
+            resync: true,
+        });
+        if (bot.posted) {
+            if (!ctx.quiet && !ctx.json) {
+                process.stderr.write(`refreshed the managed comment on ${target.repo}#${target.num}\n`);
+            }
+            return;
+        }
+    }
+    catch {
+        // Fall through to the hint.
+    }
+    if (!ctx.quiet && !ctx.json) {
+        const flag = target.kind === "pull" ? "--pr" : "--issue";
+        process.stderr.write(`tip: run \`uploads comment ${flag} ${target.num}\` to refresh the PR comment\n`);
+    }
+}
 // --- delete ---
 const DELETE_HELP = `uploads delete <key> [--dry-run] [--workspace <name>]
 
@@ -2241,7 +2345,9 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
     const target = ghTargetFromFlags(parsed.flags, run);
     if (!target)
         throw new UsageError("comment requires --pr or --issue");
-    const result = await syncAttachmentsComment(ctx.client, target, run, ctx.config.workspace);
+    const result = await syncAttachmentsComment(ctx.client, target, run, ctx.config.workspace, {
+        resync: true,
+    });
     if (ctx.json) {
         await writeJson({ ...target, ...result });
     }

package/dist/github-gh.d.ts

@@ -55,7 +55,8 @@ export declare function resolveGhTitle(target: GhTarget, run?: CommandRunner): s
 export declare function ghMetadataFromTargetWithTitle(target: GhTarget, run?: CommandRunner): Record<string, string>;
 /**
  * Create the managed attachments comment, or edit it in place if it already
- * exists. Never touches any other comment. Body is passed via stdin
+ * exists. Never touches any other comment except best-effort deletes of
+ * duplicate marker comments (see below). Body is passed via stdin
  * (`-F body=@-`) so it is never shell-interpolated.
  *
  * `marker` identifies which comment to hunt for (see `findManagedComment`);
@@ -63,6 +64,27 @@ export declare function ghMetadataFromTargetWithTitle(target: GhTarget, run?: Co
  * (built via `attachmentsCommentBody(items, galleries, marker)`), so patching
  * an adopted legacy comment migrates it to the namespaced marker in place.
  * Defaults to the shared legacy marker for backward compatibility.
+ *
+ * Self-healing dedupe (issue #486, mirroring the bot path's #470/#484 fix):
+ * a create race (two concurrent `uploads attach` runs, neither finding an
+ * existing comment) can leave more than one marker comment on the thread.
+ * This path has no id cache, so unlike the bot path a duplicate here never
+ * heals on its own — every sync just patches the oldest and leaves the rest
+ * stale. After patching (or creating), any extra exact-`marker` hits are
+ * deleted best-effort via `gh api -X DELETE`; a failed delete is swallowed
+ * and never fails the caller's command, and the next sync retries anyway.
+ *
+ * On why this duplicates the bot path rather than deferring to it: the gh
+ * fallback is a supported path, not a stopgap, so it is held at behavioral
+ * parity deliberately. This file already reimplements the hunt, the legacy
+ * adoption and the create-vs-patch gate against a different transport (the
+ * `gh` subprocess, not the App's token), and #486 existed precisely because
+ * the two drifted. Treat any behavior change to `upsertBotComment`
+ * (apps/api/src/github-comment.ts) as owing a matching change here. Note
+ * this is the one place the CLI deletes a GitHub resource under the
+ * invoking human's own credentials — bounded to comments carrying this
+ * workspace's exact namespaced marker, whose content is always
+ * regenerable.
  */
 export declare function upsertAttachmentsComment(target: GhTarget, body: string, run?: CommandRunner, marker?: string, opts?: {
     createIfMissing?: boolean;

package/dist/github-gh.js

@@ -187,7 +187,9 @@ export function ghMetadataFromTargetWithTitle(target, run = execRunner) {
 /**
  * PR comments live on the issues endpoint, so one path covers PRs and issues.
  * `--paginate` follows Link headers and merges every page into one array, so the
- * marker comment is found even on threads past 100 comments.
+ * marker comment is found even on threads past 100 comments. GitHub returns
+ * comments oldest-first, so `hits[0]` (after merging paginated pages, which
+ * preserve that order) is the oldest exact-`marker` hit.
  *
  * Hunts for `marker` (the namespaced, per-workspace marker) first; when none
  * is found, falls back to a comment carrying the shared legacy
@@ -195,6 +197,12 @@ export function ghMetadataFromTargetWithTitle(target, run = execRunner) {
  * migrated in place. When `marker` IS the legacy marker (no workspace to
  * namespace with) this collapses to a single hunt, unchanged from pre-4b
  * behavior.
+ *
+ * Collects EVERY comment carrying `marker` (a create race can leave more
+ * than one — issue #486, mirroring the bot path's #470 fix): the oldest is
+ * `comment`, the rest come back as `extras` for the caller to delete. Only
+ * exact-`marker` hits are ever extras — a legacy (unnamespaced) comment may
+ * belong to a different workspace, so it is adopted at most, never deleted.
  */
 function findManagedComment(target, run, marker) {
     const raw = run("gh", [
@@ -203,16 +211,25 @@ function findManagedComment(target, run, marker) {
         "--paginate",
     ]);
     const comments = JSON.parse(raw);
-    const namespacedHit = comments.find((c) => typeof c.body === "string" && c.body.includes(marker));
-    if (namespacedHit)
-        return namespacedHit;
+    const hits = comments.filter((c) => typeof c.body === "string" && c.body.includes(marker));
+    if (hits.length > 0) {
+        // In legacy mode (no workspace to namespace with) our "exact" marker IS
+        // the shared one, so a second hit is not our own duplicate — it may be
+        // another workspace's comment. Adopt the oldest and never delete: the
+        // adopt-only contract is about the marker being ambiguous, which is just
+        // as true when it is the marker we are hunting on.
+        const extras = marker === ATTACHMENTS_MARKER ? undefined : hits.slice(1);
+        return { comment: hits[0], extras };
+    }
     if (marker === ATTACHMENTS_MARKER)
-        return undefined;
-    return comments.find((c) => typeof c.body === "string" && c.body.includes(ATTACHMENTS_MARKER));
+        return {};
+    const legacyHit = comments.find((c) => typeof c.body === "string" && c.body.includes(ATTACHMENTS_MARKER));
+    return { comment: legacyHit };
 }
 /**
  * Create the managed attachments comment, or edit it in place if it already
- * exists. Never touches any other comment. Body is passed via stdin
+ * exists. Never touches any other comment except best-effort deletes of
+ * duplicate marker comments (see below). Body is passed via stdin
  * (`-F body=@-`) so it is never shell-interpolated.
  *
  * `marker` identifies which comment to hunt for (see `findManagedComment`);
@@ -220,10 +237,41 @@ function findManagedComment(target, run, marker) {
  * (built via `attachmentsCommentBody(items, galleries, marker)`), so patching
  * an adopted legacy comment migrates it to the namespaced marker in place.
  * Defaults to the shared legacy marker for backward compatibility.
+ *
+ * Self-healing dedupe (issue #486, mirroring the bot path's #470/#484 fix):
+ * a create race (two concurrent `uploads attach` runs, neither finding an
+ * existing comment) can leave more than one marker comment on the thread.
+ * This path has no id cache, so unlike the bot path a duplicate here never
+ * heals on its own — every sync just patches the oldest and leaves the rest
+ * stale. After patching (or creating), any extra exact-`marker` hits are
+ * deleted best-effort via `gh api -X DELETE`; a failed delete is swallowed
+ * and never fails the caller's command, and the next sync retries anyway.
+ *
+ * On why this duplicates the bot path rather than deferring to it: the gh
+ * fallback is a supported path, not a stopgap, so it is held at behavioral
+ * parity deliberately. This file already reimplements the hunt, the legacy
+ * adoption and the create-vs-patch gate against a different transport (the
+ * `gh` subprocess, not the App's token), and #486 existed precisely because
+ * the two drifted. Treat any behavior change to `upsertBotComment`
+ * (apps/api/src/github-comment.ts) as owing a matching change here. Note
+ * this is the one place the CLI deletes a GitHub resource under the
+ * invoking human's own credentials — bounded to comments carrying this
+ * workspace's exact namespaced marker, whose content is always
+ * regenerable.
  */
 export function upsertAttachmentsComment(target, body, run = execRunner, marker = ATTACHMENTS_MARKER, opts = {}) {
     const createIfMissing = opts.createIfMissing ?? true;
-    const existing = findManagedComment(target, run, marker);
+    const { comment: existing, extras } = findManagedComment(target, run, marker);
+    const deleteExtras = () => {
+        for (const extra of extras ?? []) {
+            try {
+                run("gh", ["api", `repos/${target.repo}/issues/comments/${extra.id}`, "-X", "DELETE"]);
+            }
+            catch {
+                // Best effort only — a failed delete must never fail the caller's command.
+            }
+        }
+    };
     if (existing) {
         run("gh", [
             "api",
@@ -233,12 +281,15 @@ export function upsertAttachmentsComment(target, body, run = execRunner, marker
             "-F",
             "body=@-",
         ], body);
+        deleteExtras();
         return { action: "updated" };
     }
     // Patch-only (createIfMissing false, i.e. an empty body) with no existing
     // comment: nothing to do — never create one just to say it's empty.
     if (!createIfMissing)
         return { action: "skipped" };
+    // No existing marker hit means `extras` is necessarily empty here (see
+    // `findManagedComment`) — nothing to delete after a create.
     run("gh", ["api", `repos/${target.repo}/issues/${target.num}/comments`, "-F", "body=@-"], body);
     return { action: "created" };
 }

package/dist/github.d.ts

@@ -15,6 +15,12 @@ export declare function isValidRepo(repo: string): boolean;
 export declare function parseRepoFromRemoteUrl(url: string): string | undefined;
 /** Normalize a GitHub issue or pull-request coordinate for gallery linking. */
 export declare function normalizeGithubCoordinate(value: string): GithubCoordinate | undefined;
+/**
+ * Inverse of `ghKeyPrefix`: parse the PR/issue coordinate back out of a
+ * stable attachment key (`gh/<owner>/<name>/<kind>/<num>/<filename>`), or
+ * undefined for any other key shape.
+ */
+export declare function parseGhKey(key: string): GhTarget | undefined;
 export declare function ghKeyPrefix(target: GhTarget): string;
 /**
  * Stable attachment key: same filename → same key → same public URL, so

package/dist/github.js

@@ -53,6 +53,18 @@ export function normalizeGithubCoordinate(value) {
             number,
     };
 }
+/**
+ * Inverse of `ghKeyPrefix`: parse the PR/issue coordinate back out of a
+ * stable attachment key (`gh/<owner>/<name>/<kind>/<num>/<filename>`), or
+ * undefined for any other key shape.
+ */
+export function parseGhKey(key) {
+    const match = /^gh\/([^/]+)\/([^/]+)\/(pull|issues)\/([1-9][0-9]*)\/./.exec(key);
+    if (!match)
+        return undefined;
+    const [, owner, name, kind, num] = match;
+    return { repo: `${owner}/${name}`, kind: kind, num: Number(num) };
+}
 export function ghKeyPrefix(target) {
     const [owner, name] = target.repo.split("/");
     return `gh/${sanitizeKeySegment(owner)}/${sanitizeKeySegment(name)}/${target.kind}/${target.num}/`;

package/dist/install-source.d.ts

@@ -0,0 +1,14 @@
+export type InstallKind = "global" | "workspace" | "npx" | "unknown";
+export type PackageManager = "npm" | "pnpm" | "bun";
+export interface InstallSource {
+    kind: InstallKind;
+    /** Falls back to npm for every non-global kind. */
+    manager: PackageManager;
+    /** Upgrades the global install. Only meaningful when kind is "global". */
+    upgradeCommand: string[];
+}
+/**
+ * @param modulePath Absolute path of a file inside the installed package,
+ *   normally `realpathSync(fileURLToPath(import.meta.url))`.
+ */
+export declare function detectInstallSource(modulePath: string): InstallSource;

package/dist/install-source.js

@@ -0,0 +1,42 @@
+/**
+ * Classify where the running CLI was installed from.
+ *
+ * `uploads update` upgrades the global npm package. That is only safe when the
+ * CLI actually came from a global install — upgrading a workspace checkout
+ * would overwrite a developer's build with the published version.
+ *
+ * Pure and path-only: no filesystem or process access, so it is fully testable.
+ */
+import { PACKAGE_NAME } from "./update-check.js";
+const UPGRADE_COMMANDS = {
+    npm: ["npm", "install", "-g", `${PACKAGE_NAME}@latest`],
+    pnpm: ["pnpm", "add", "-g", `${PACKAGE_NAME}@latest`],
+    bun: ["bun", "add", "-g", `${PACKAGE_NAME}@latest`],
+};
+function classify(path) {
+    // npx is checked first: a cache entry can also contain a global-looking marker.
+    if (path.includes("/_npx/"))
+        return { kind: "npx", manager: "npm" };
+    if (path.includes("/.bun/install/global/"))
+        return { kind: "global", manager: "bun" };
+    if (path.includes("/pnpm/global/"))
+        return { kind: "global", manager: "pnpm" };
+    if (path.includes("/lib/node_modules/"))
+        return { kind: "global", manager: "npm" };
+    // Windows npm globals have no `lib` segment: `<prefix>\npm\node_modules\<pkg>`.
+    if (path.includes("/npm/node_modules/"))
+        return { kind: "global", manager: "npm" };
+    // No node_modules segment at all means we are running out of a source checkout.
+    if (!path.includes("/node_modules/"))
+        return { kind: "workspace", manager: "npm" };
+    return { kind: "unknown", manager: "npm" };
+}
+/**
+ * @param modulePath Absolute path of a file inside the installed package,
+ *   normally `realpathSync(fileURLToPath(import.meta.url))`.
+ */
+export function detectInstallSource(modulePath) {
+    const normalized = modulePath.split("\\").join("/");
+    const { kind, manager } = classify(normalized);
+    return { kind, manager, upgradeCommand: UPGRADE_COMMANDS[manager] };
+}

package/dist/mcp/tools.js

@@ -1,9 +1,9 @@
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, makeGhTarget, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
+import { buildDoctorReport, makeGhTarget, mergeStagingMeta, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
-import { ghKeyPrefix, ghMetadataForBranch } from "../github.js";
+import { ghBranchAttachmentKey, ghKeyPrefix } from "../github.js";
 import { safeCaptureFacts } from "../capture-facts.js";
 import { validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
@@ -430,16 +430,7 @@ export function createUploadsMcpTools(opts) {
                     repoArg: optString(args, "repo") ?? defaults.repo,
                     run,
                 });
-                const putMetadata = stagingTarget
-                    ? (() => {
-                        const merged = {
-                            ...metadata,
-                            ...ghMetadataForBranch(stagingTarget.repo, stagingTarget.branch),
-                        };
-                        validateMetaMap(merged); // same builder, same contract as attach --branch
-                        return merged;
-                    })()
-                    : metadata;
+                const putMetadata = stagingTarget ? mergeStagingMeta(metadata, stagingTarget) : metadata;
                 const putShared = {
                     client,
                     ghTarget: target,
@@ -695,25 +686,41 @@ export function createUploadsMcpTools(opts) {
                 const metadata = metadataArgWithCanonical(args);
                 if (metadata)
                     validateMetaMap(metadata);
+                const { config, client } = clientFor(args);
+                const defaults = resolvePutDefaults({ envFile: globals.envFile });
+                const frameOpts = mcpFrameOptions(args);
+                const optimizeOpts = mcpOptimizeOptions(args, defaults);
+                const noGit = optBool(args, "noGit") || defaults.noGit === true;
+                const alt = optString(args, "alt");
+                const width = optPosInt(args, "width") ?? defaults.width;
+                // Auto branch staging (issue #469 lever 1): mirrors the CLI screenshot
+                // command and the put tool above (issue #403) — no pr/issue/key/ref/
+                // prefix/destination, not noGit, on a non-default git branch stages
+                // to the branch prefix (identical key/metadata to `attach --branch`)
+                // instead of the dated `screenshots/<repo>/<date>/...` layout. Never
+                // throws — see resolvePutStagingTarget.
+                const stagingTarget = resolvePutStagingTarget({
+                    ghTarget: target,
+                    keyHint: keyArg,
+                    refArg,
+                    prefixArg,
+                    destinationArg: destArg,
+                    noGit,
+                    repoArg: optString(args, "repo") ?? defaults.repo,
+                    run,
+                });
                 let resolvedPrefix;
                 try {
                     resolvedPrefix = resolvePutPrefix({
                         destination: destArg,
                         prefix: prefixArg,
                         key: keyArg,
-                        ghAttachment: Boolean(target),
+                        ghAttachment: Boolean(target) || stagingTarget !== undefined,
                     });
                 }
                 catch (err) {
                     usage(err instanceof Error ? err.message : String(err));
                 }
-                const { config, client } = clientFor(args);
-                const defaults = resolvePutDefaults({ envFile: globals.envFile });
-                const frameOpts = mcpFrameOptions(args);
-                const optimizeOpts = mcpOptimizeOptions(args, defaults);
-                const noGit = optBool(args, "noGit") || defaults.noGit === true;
-                const alt = optString(args, "alt");
-                const width = optPosInt(args, "width") ?? defaults.width;
                 // Dynamic import only: keeps mcp/tools.ts (and therefore anything
                 // that statically imports it) free of a static reference to the
                 // local-backend chain. If this fails, the runtime can't do Node-side
@@ -730,9 +737,15 @@ export function createUploadsMcpTools(opts) {
                 // Keep undefined when nothing at all was supplied or derived, so the
                 // "omit to leave stored metadata untouched" contract still holds.
                 const captureDerived = safeCaptureFacts(targetArg, viewport, colorSchemeArg);
-                const metadataWithCaptureFacts = metadata === undefined && Object.keys(captureDerived).length === 0
+                const metadataBase = metadata === undefined && Object.keys(captureDerived).length === 0
                     ? undefined
                     : mergeDerivedMeta(metadata ?? {}, captureDerived);
+                // gh.* metadata: explicit pr/issue target wins; staging wins the same
+                // way (matches attach --branch/bare put); otherwise capture-derived +
+                // explicit only.
+                const metadataWithCaptureFacts = stagingTarget
+                    ? mergeStagingMeta(metadataBase, stagingTarget)
+                    : metadataBase;
                 let captured;
                 try {
                     captured = await screenshotModule.captureScreenshot({
@@ -761,11 +774,14 @@ export function createUploadsMcpTools(opts) {
                     }
                     throw err;
                 }
+                const branchKey = stagingTarget
+                    ? ghBranchAttachmentKey(stagingTarget.repo, stagingTarget.branch, captured.filename)
+                    : undefined;
                 const { result, prepared, markdown } = await uploadPreparedImage(client, captured.png, captured.filename, {
                     frame: frameOpts,
                     optimize: optimizeOpts,
                     ghTarget: target,
-                    key: keyArg,
+                    key: keyArg ?? branchKey,
                     prefix: resolvedPrefix ?? defaults.prefix,
                     repo: optString(args, "repo") ?? defaults.repo,
                     ref: refArg ?? defaults.ref,
@@ -1142,7 +1158,10 @@ export function createUploadsMcpTools(opts) {
                 if (!target)
                     usage("comment requires pr or issue");
                 const { config, client } = clientFor(args);
-                const result = await syncAttachmentsComment(client, target, run, config.workspace);
+                // Explicit resync, same as `uploads comment` (issue #480).
+                const result = await syncAttachmentsComment(client, target, run, config.workspace, {
+                    resync: true,
+                });
                 return { ...target, ...result };
             },
         },