@buildinternet/uploads 0.26.1 → 0.27.0

package/README.md

@@ -98,6 +98,11 @@ explicit deletes. Promotion (auto or `--promote`) does skip files staged
 more than 30 days before the PR opens, though; they're still there, just no
 longer auto-promoted.
 
+**Metadata edits re-sync the comment too:** `uploads meta set` on a `gh/…`-keyed
+object refreshes the managed comment automatically when it touches `path` or
+`state` — best-effort, so backfilled metadata shows up without waiting on the
+next `attach`.
+
 **Bare `put` stages too, by default (issue #403):** on a non-default git
 branch, a `put` with none of
 `--pr`/`--issue`/`--key`/`--ref`/`--prefix`/`--destination` set

package/dist/cli-catalog.js

@@ -60,6 +60,7 @@ export const SCREENSHOT_FLAGS = [
     "--light",
     "--wait",
     "--out",
+    "--no-sidecar",
     "--no-upload",
     "--destination",
     "--prefix",

package/dist/commands/screenshot.js

@@ -2,15 +2,16 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { writeCommandHelp } from "../cli-style.js";
-import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, } from "../commands.js";
+import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, } from "../commands.js";
 import { resolvePutDefaults } from "../config.js";
 import { loadDefaultsRaw, resolveScreenshotDefaults } from "../config-file.js";
 import { resolvePutPrefix } from "../destinations.js";
 import { execRunner, ghMetadataFromTargetWithTitle, resolveRepo, } from "../github-gh.js";
-import { ghBranchAttachmentKey, ghMetadataForBranch } from "../github.js";
+import { ghBranchAttachmentKey } from "../github.js";
 import { safeCaptureFacts } from "../capture-facts.js";
 import { parseMetaFlags, validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
+import { writeSidecarMeta } from "../sidecar.js";
 import { writeJson, writeStdout } from "../io.js";
 import { assertHideSelector, captureScreenshot, parseViewport, parseWaitUntil, } from "../screenshot.js";
 const SCREENSHOT_HELP = `uploads screenshot <target> [options]
@@ -33,6 +34,15 @@ fail fast with a clear error instead of sending a doomed request.
 After capture, screenshots share the put upload pipeline: optional --frame,
 optimize-by-default, --pr/--issue attachment + --comment, --gallery, --meta.
 
+Branch staging by default (pre-PR): with no --pr/--issue/--branch/--key/--ref/
+--prefix/--destination, a screenshot taken on a non-default git branch stages
+under gh/<owner>/<repo>/branch/<branch>/<name> instead of the dated
+screenshots/<repo>/<date>/... layout — same key/metadata as an explicit
+--branch, carrying every derived fact (path/url/env/viewport, --state) along.
+Staged files auto-attach with full metadata the first time you attach to that
+branch's PR once it opens (or run "uploads attach --promote"). Use --no-git,
+or an explicit --ref/--prefix, to opt back into the dated layout.
+
 Options:
   --via auto|local|remote   Capture backend (default: auto, or UPLOADS_SCREENSHOT_VIA)
   --browser <path>          Explicit local browser executable (or UPLOADS_CHROME_PATH / CHROME_PATH)
@@ -51,7 +61,12 @@ Options:
                             on --via remote — neutralizes animations via injected CSS)
   --eval <js>               Run JS in the page after settle, before capture (--via local only)
   --init-script <file>      Inject a JS file before navigation (--via local only)
-  --out <file>              Also write the PNG to a local file
+  --out <file>              Also write the PNG to a local file. Also writes a sidecar manifest,
+                            <file>.uploads.json, recording this capture's derived metadata
+                            (path/url/env/viewport, plus --state if given) with a content hash; a
+                            later \`put\`/\`attach\` of this exact file picks the metadata back up
+                            automatically (explicit --meta/--state still win). See --no-sidecar.
+  --no-sidecar              Don't write the <file>.uploads.json sidecar alongside --out
   --no-upload                Skip hosting; requires --out (local file only)
   --destination <id>        Typed root: screenshots | gh | f
   --prefix <path>           Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX)
@@ -171,6 +186,9 @@ captureImpl = captureScreenshot) {
     const noUpload = flagBool(parsed.flags, "--no-upload");
     if (noUpload && !outFile)
         throw new UsageError("--no-upload requires --out");
+    const noSidecar = flagBool(parsed.flags, "--no-sidecar");
+    if (noSidecar && !outFile)
+        throw new UsageError("--no-sidecar requires --out");
     const keyHint = flagString(parsed.flags, "--key");
     const destFlag = flagString(parsed.flags, "--destination");
     const prefixFlag = flagString(parsed.flags, "--prefix");
@@ -210,14 +228,38 @@ captureImpl = captureScreenshot) {
         if (noUpload)
             throw new UsageError("--dry-run cannot be combined with --no-upload");
     }
+    const putDefaults = resolvePutDefaults({ envFile: ctx.envFile }, rawDefaults);
+    const noGit = flagBool(parsed.flags, "--no-git") || putDefaults.noGit === true;
     const branchRepo = branchArg !== undefined ? resolveRepo(flagString(parsed.flags, "--repo"), run) : undefined;
+    // Auto branch staging (issue #469 lever 1): mirrors bare `put`'s auto-staging
+    // (issue #403). When no --branch/--pr/--issue/--key/--ref/--prefix/--destination
+    // is given and git use isn't disabled, a screenshot taken on a non-default
+    // git branch stages the same way explicit `--branch`/bare `put` do — same
+    // key shape, same gh.* metadata — instead of landing on the dated
+    // `screenshots/<repo>/<date>/...` layout. This is what lets derived
+    // metadata (path/url/env/viewport, --state) ride through to PR-open
+    // promotion when the capture happens before the PR exists. Skipped
+    // entirely when --branch was given explicitly (already handled above).
+    const autoStagingTarget = branchArg === undefined
+        ? resolvePutStagingTarget({
+            ghTarget,
+            keyHint,
+            refArg: flagString(parsed.flags, "--ref"),
+            prefixArg: prefixFlag,
+            destinationArg: destFlag,
+            noGit,
+            repoArg: flagString(parsed.flags, "--repo") ?? putDefaults.repo,
+            run,
+        })
+        : undefined;
+    const stagingTarget = branchArg !== undefined ? { repo: branchRepo, branch: branchArg } : autoStagingTarget;
     let resolvedPrefix;
     try {
         resolvedPrefix = resolvePutPrefix({
             destination: destFlag,
             prefix: prefixFlag,
             key: keyHint,
-            ghAttachment: Boolean(ghTarget) || branchArg !== undefined,
+            ghAttachment: Boolean(ghTarget) || stagingTarget !== undefined,
         });
     }
     catch (err) {
@@ -233,7 +275,6 @@ captureImpl = captureScreenshot) {
                 return raw;
             throw new UsageError(`invalid --format: ${raw}`);
         })();
-    const putDefaults = resolvePutDefaults({ envFile: ctx.envFile }, rawDefaults);
     const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, putDefaults);
     const frameOpts = frameOptionsFromFlags(parsed.flags);
     const altFlag = flagString(parsed.flags, "--alt");
@@ -248,9 +289,8 @@ captureImpl = captureScreenshot) {
         metadata = { ...withFacts, ...ghMetadataFromTargetWithTitle(ghTarget, run) };
         validateMetaMap(metadata);
     }
-    else if (branchArg !== undefined) {
-        metadata = { ...withFacts, ...ghMetadataForBranch(branchRepo, branchArg) };
-        validateMetaMap(metadata);
+    else if (stagingTarget !== undefined) {
+        metadata = mergeStagingMeta(withFacts, stagingTarget);
     }
     else if (Object.keys(withFacts).length > 0) {
         validateMetaMap(withFacts);
@@ -282,6 +322,8 @@ captureImpl = captureScreenshot) {
         writeFileSync(outFile, captured.png);
         if (logHuman)
             process.stderr.write(`>> wrote ${outFile}\n`);
+        if (!noSidecar)
+            writeSidecarMeta(outFile, captured.png, withFacts);
     }
     if (noUpload) {
         if (ctx.json) {
@@ -294,8 +336,8 @@ captureImpl = captureScreenshot) {
     }
     const repo = flagString(parsed.flags, "--repo") ?? putDefaults.repo;
     const ref = flagString(parsed.flags, "--ref") ?? putDefaults.ref;
-    const branchKey = branchArg !== undefined
-        ? ghBranchAttachmentKey(branchRepo, branchArg, captured.filename)
+    const branchKey = stagingTarget !== undefined
+        ? ghBranchAttachmentKey(stagingTarget.repo, stagingTarget.branch, captured.filename)
         : undefined;
     const alt = altFlag ?? basename(captured.filename);
     const { result, prepared, markdown } = await uploadPreparedImage(ctx.client, captured.png, captured.filename, {
@@ -306,13 +348,26 @@ captureImpl = captureScreenshot) {
         prefix: resolvedPrefix ?? putDefaults.prefix,
         repo,
         ref,
-        deriveRepoFromGit: !(flagBool(parsed.flags, "--no-git") || putDefaults.noGit === true),
+        deriveRepoFromGit: !noGit,
         dryRun,
         metadata,
         provenanceClient: "uploads-cli-screenshot",
         alt: () => alt,
         width,
     });
+    // Staging note (issue #469 lever 1, mirrors #403's bare-put note): only for
+    // the auto-staged case — explicit `--branch` keeps its own "staged: these
+    // auto-attach..." wording below. Same suppression as put's note (--quiet,
+    // UPLOADS_NO_NUDGE=1).
+    const stagingNote = autoStagingTarget && !ctx.quiet && !putDefaults.noNudge
+        ? putStagingNoteText(autoStagingTarget.branch)
+        : undefined;
+    // Stage-time binding warning (issue #398), same check bare put/attach
+    // --branch run, now also reachable from screenshot's staging paths
+    // (explicit --branch and auto-staging alike).
+    const bindingWarning = stagingTarget !== undefined
+        ? await resolveStageBindingWarning({ ctx, defaults: putDefaults, repo: stagingTarget.repo })
+        : undefined;
     let gallery;
     if (galleryId) {
         try {
@@ -347,8 +402,25 @@ captureImpl = captureScreenshot) {
         if (prepared.optimized) {
             process.stderr.write(`>> optimized ${prepared.originalBytes} → ${prepared.outputBytes} bytes\n`);
         }
-        process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n\n`);
+        process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n`);
+        if (stagingTarget !== undefined) {
+            process.stderr.write(`>> find these later: uploads find gh.branch=${stagingTarget.branch.toLowerCase()}\n`);
+            if (autoStagingTarget) {
+                if (stagingNote)
+                    process.stderr.write(`${stagingNote}\n`);
+            }
+            else {
+                process.stderr.write(`>> staged: these auto-attach to this branch's PR when it opens ` +
+                    `(or run \`uploads attach --promote\` after opening)\n`);
+            }
+        }
+        if (bindingWarning)
+            process.stderr.write(`${bindingWarning}\n`);
+        process.stderr.write("\n");
     }
+    // One JSON `hint` slot (mirrors bare put): the binding warning is more
+    // actionable than the generic staging note, so it wins when both fire.
+    const jsonHint = bindingWarning ?? stagingNote;
     switch (format) {
         case "json":
             await writeJson({
@@ -363,6 +435,7 @@ captureImpl = captureScreenshot) {
                 backend: captured.backend,
                 gallery,
                 ...(dryRun ? { dryRun: true } : {}),
+                ...(jsonHint ? { hint: jsonHint } : {}),
             });
             break;
         case "url":

package/dist/commands.d.ts

@@ -167,6 +167,21 @@ export declare function commentViaSuffix(via: AttachmentsCommentResult["via"]):
 export declare class GithubCommentAuthorizationError extends Error {
 }
 export declare function syncAttachmentsComment(client: UploadsClient, target: GhTarget, run: CommandRunner, workspace?: string): Promise<AttachmentsCommentResult>;
+/**
+ * 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 declare function pathMetaHintFor(uploads: {
+    contentType: string;
+    metadata?: Record<string, string>;
+}[]): string | undefined;
 export type AttachUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -355,6 +370,14 @@ export declare function resolvePutStagingTarget(opts: {
     repoArg: string | undefined;
     run: CommandRunner;
 }): BranchTarget | undefined;
+/**
+ * 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 declare function mergeStagingMeta(base: Record<string, string> | undefined, target: BranchTarget): Record<string, string>;
 /**
  * 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

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.
@@ -558,6 +565,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 +633,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 +662,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 +774,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 +791,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 +970,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 +980,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
             comment,
             commentError,
             promotion: promotion ?? null,
+            ...(pathHint ? { hint: pathHint } : {}),
         });
     }
     else {
@@ -971,6 +1009,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 +1309,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 +1605,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 +1695,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 +1790,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 +1849,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 +2230,50 @@ 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,
+        });
+        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>]
 

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/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,

package/dist/sidecar.d.ts

@@ -0,0 +1,31 @@
+/** The sidecar path for a given local file — `<file>.uploads.json`. */
+export declare function sidecarPath(filePath: string): string;
+/** Hex-encoded SHA-256 of `bytes`. */
+export declare function sha256Hex(bytes: Uint8Array): string;
+/** Keep only entries whose key is in the closed canonical metadata vocabulary. */
+export declare function restrictToCanonicalMeta(meta: Record<string, string>): Record<string, string>;
+/**
+ * Write a sidecar manifest next to `filePath`, recording `meta` (restricted
+ * to the canonical vocabulary) and the SHA-256 of `bytes` (the exact bytes
+ * being written to `filePath`). No-ops when `meta` is empty — an image with
+ * no derived metadata gets no sidecar. Best-effort: a write failure (e.g. a
+ * read-only directory) is swallowed, matching the rest of the derived-
+ * metadata pipeline's "never fail the primary operation" contract.
+ */
+export declare function writeSidecarMeta(filePath: string, bytes: Uint8Array, meta: Record<string, string>): void;
+/**
+ * Read back a sidecar manifest for `filePath`, only when it is present,
+ * well-formed, and its recorded hash matches `bytes` (the file's current
+ * content, as read for the upload in progress). Returns `undefined` on any
+ * absence, parse failure, malformed shape, or hash mismatch — a sidecar is a
+ * best-effort convenience and must never fail or noise an upload. Returned
+ * keys are always a subset of `CANONICAL_META_KEYS`, so a hand-edited
+ * manifest can never inject arbitrary metadata.
+ */
+export declare function readSidecarMeta(filePath: string, bytes: Uint8Array): Record<string, string> | undefined;
+/**
+ * Merge `filePath`'s sidecar metadata (if any, per {@link readSidecarMeta})
+ * under `baseMeta` — explicit metadata always wins. Shared by the `put` and
+ * `attach` upload loops (issue #469 lever 2).
+ */
+export declare function mergeSidecarMeta(filePath: string, bytes: Uint8Array, baseMeta: Record<string, string> | undefined): Record<string, string> | undefined;

package/dist/sidecar.js

@@ -0,0 +1,111 @@
+/**
+ * Sidecar manifest for `uploads screenshot --out`: derived metadata written
+ * next to a local screenshot file so a later `put`/`attach` of that exact
+ * file can recover the metadata the hosted copy would have gotten at capture
+ * time. See issue #469 lever 2 (the "sidecar manifest" variant — the
+ * alternative, content-hash-keyed server-side inheritance, is out of scope
+ * here).
+ *
+ * File: `<file>.uploads.json` next to `<file>`, e.g. `shot.png.uploads.json`.
+ * Shape: `{ version, sha256, meta }`. `sha256` is the SHA-256 of the exact
+ * bytes written to `<file>` at capture time — read-back compares it against
+ * the file's *current* bytes, so a file that was regenerated or hand-edited
+ * since capture silently loses its sidecar instead of attaching stale
+ * metadata to a different image.
+ *
+ * `meta` is filtered to the closed `CANONICAL_META_KEYS` vocabulary
+ * (metadata-vocab.ts) on both write and read: the sidecar is a plain JSON
+ * file sitting next to the image, so it must never be a channel for
+ * arbitrary metadata even if hand-edited.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { CANONICAL_META_KEYS, mergeDerivedMeta } from "./metadata-vocab.js";
+const SIDECAR_VERSION = 1;
+/** The sidecar path for a given local file — `<file>.uploads.json`. */
+export function sidecarPath(filePath) {
+    return `${filePath}.uploads.json`;
+}
+/** Hex-encoded SHA-256 of `bytes`. */
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Keep only entries whose key is in the closed canonical metadata vocabulary. */
+export function restrictToCanonicalMeta(meta) {
+    const out = {};
+    for (const key of CANONICAL_META_KEYS) {
+        if (Object.prototype.hasOwnProperty.call(meta, key))
+            out[key] = meta[key];
+    }
+    return out;
+}
+function isPlainStringRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    return Object.values(value).every((v) => typeof v === "string");
+}
+/**
+ * Write a sidecar manifest next to `filePath`, recording `meta` (restricted
+ * to the canonical vocabulary) and the SHA-256 of `bytes` (the exact bytes
+ * being written to `filePath`). No-ops when `meta` is empty — an image with
+ * no derived metadata gets no sidecar. Best-effort: a write failure (e.g. a
+ * read-only directory) is swallowed, matching the rest of the derived-
+ * metadata pipeline's "never fail the primary operation" contract.
+ */
+export function writeSidecarMeta(filePath, bytes, meta) {
+    const restricted = restrictToCanonicalMeta(meta);
+    if (Object.keys(restricted).length === 0)
+        return;
+    try {
+        const manifest = {
+            version: SIDECAR_VERSION,
+            sha256: sha256Hex(bytes),
+            meta: restricted,
+        };
+        writeFileSync(sidecarPath(filePath), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    }
+    catch {
+        // best-effort — never fail the screenshot over a sidecar write
+    }
+}
+/**
+ * Read back a sidecar manifest for `filePath`, only when it is present,
+ * well-formed, and its recorded hash matches `bytes` (the file's current
+ * content, as read for the upload in progress). Returns `undefined` on any
+ * absence, parse failure, malformed shape, or hash mismatch — a sidecar is a
+ * best-effort convenience and must never fail or noise an upload. Returned
+ * keys are always a subset of `CANONICAL_META_KEYS`, so a hand-edited
+ * manifest can never inject arbitrary metadata.
+ */
+export function readSidecarMeta(filePath, bytes) {
+    const path = sidecarPath(filePath);
+    try {
+        if (!existsSync(path))
+            return undefined;
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        const candidate = parsed;
+        if (candidate.version !== SIDECAR_VERSION ||
+            typeof candidate.sha256 !== "string" ||
+            !isPlainStringRecord(candidate.meta)) {
+            return undefined;
+        }
+        if (candidate.sha256 !== sha256Hex(bytes))
+            return undefined; // stale/regenerated file
+        const restricted = restrictToCanonicalMeta(candidate.meta);
+        return Object.keys(restricted).length > 0 ? restricted : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Merge `filePath`'s sidecar metadata (if any, per {@link readSidecarMeta})
+ * under `baseMeta` — explicit metadata always wins. Shared by the `put` and
+ * `attach` upload loops (issue #469 lever 2).
+ */
+export function mergeSidecarMeta(filePath, bytes, baseMeta) {
+    const sidecarMeta = readSidecarMeta(filePath, bytes);
+    return sidecarMeta ? mergeDerivedMeta(baseMeta ?? {}, sidecarMeta) : baseMeta;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,