@buildinternet/uploads 0.43.0 → 0.45.0

package/dist/commands.js

@@ -14,7 +14,7 @@ import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./metadata-vocab.js";
 import { mergeSidecarMeta } from "./sidecar.js";
 import { ghAttachmentKeyForMode, ghBranchAttachmentKeyForMode, ghBranchKeyPrefix, ghKeyPrefix, ghPrivateKeyPrefix, ghPrivateBranchKeyPrefix, ghMetadataFromTarget, parseGhKey, parseGhPrivateKey, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, AUTO_RENDER_OPTIONS, GH_FALLBACK_AUTHOR_NOTE, normalizeGithubCoordinate, } from "./github.js";
-import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, resolveDefaultBranch, classifyGhNumber, execRunner, timedExecRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
+import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, resolveDefaultBranch, classifyGhNumber, execRunner, timedExecRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, hasLinkCandidate, extractCandidateUrls, fetchAdoptionCandidateText, } from "./github-gh.js";
 import { deriveRepoFromGit, deriveRepoSlugFromGit } from "./keys.js";
 import { noProjectContextNudge } from "./project-context-nudge.js";
 import { resolvePutPrefix } from "./destinations.js";
@@ -152,6 +152,7 @@ Options:
   --no-git              Don't derive --repo from git (or UPLOADS_NO_GIT=1)
   --auto                Resolve current PR/issue and stamp gh.* metadata (default on)
   --no-auto             Skip gh.* auto-resolution (also skipped by --no-git or UPLOADS_NO_AUTO_META=1)
+  --no-pr               Skip auto-PR context (or UPLOADS_NO_AUTO_PR=1) — see below
   --workspace, -w <name>  Override workspace (wins over UPLOADS_WORKSPACE and token inference)
   --format human|url|markdown|json
   --pr <num>            Attach to a pull request: key gh/<owner>/<repo>/pull/<num>/<name> (stable URL, no hash)
@@ -175,9 +176,17 @@ Options:
   --dry-run             Print key + public URL without uploading; reports if the key would replace
                         (or, on a strict key, be refused). Not with --gallery
 
-A bare put (no --pr/--issue/--key) on a non-default git branch prints a one-line
-nudge toward --pr/attach --branch (stderr in human mode, a "hint" field in
---format json). Suppress with --quiet, UPLOADS_NO_NUDGE=1, or config UPLOADS_NO_NUDGE=1.
+A bare put (no --pr/--issue/--key/--ref/--prefix/--destination) on a git branch
+that maps to exactly one open PR now behaves as if --pr <n> had been passed
+(issue #700): stable gh/ key, managed comment sync — instead of the #403
+branch-staging default. A one-line note announces this (stderr in human mode,
+the "hint" field in --format json). Opt out with --no-pr, UPLOADS_NO_AUTO_PR=1,
+or config UPLOADS_NO_AUTO_PR=1; never fires outside a git repo, on the default
+branch, with --no-git, or when no single open PR can be resolved (falls back to
+branch staging, then the plain dated layout). When it doesn't fire and the
+upload lands on the dated layout with a detectable PR, a similar one-line nudge
+names the PR and a ready-made follow-up (uploads attach --pr <n> <key>...).
+Suppress either note with --quiet, UPLOADS_NO_NUDGE=1, or config UPLOADS_NO_NUDGE=1.
 
 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.
@@ -555,6 +564,59 @@ export async function syncAttachmentsComment(client, target, run, workspace, opt
                 `Posting via local gh in the meantime.\n`);
         }
     }
+    // Link adoption (issue #708): local-gh fallback parity with the bot's own
+    // adoption (issue #701, apps/api/src/github-link-adopt.ts). When the bot
+    // already handled this target the server already adopted for us, so this
+    // only runs once we've fallen through to gh. Scans the PR/issue body and
+    // every comment for pasted uploads.sh URLs and adopts each one that
+    // resolves (server-side, inside `POST .../github/attach`) to a file in
+    // THIS workspace's own bound-repo attachment prefix — copy, never move,
+    // same as the bot path. Best-effort end to end: any failure (not a git
+    // repo, `gh` unavailable/unauthenticated, config unreadable) degrades to
+    // "adopt nothing" rather than blocking the comment sync it rides along
+    // with.
+    let adoptedCount = 0;
+    let preAdoptionAttachmentCount;
+    try {
+        const root = run("git", ["rev-parse", "--show-toplevel"]).trim();
+        const { config: adoptConfig } = readLocalRepoCommentConfig(root);
+        const { options: adoptOptions } = resolveCommentOptions(adoptConfig, null);
+        if (adoptOptions.adoptLinkedFiles) {
+            const text = fetchAdoptionCandidateText(target, run);
+            if (hasLinkCandidate(text)) {
+                const urls = extractCandidateUrls(text);
+                if (urls.length > 0) {
+                    // Baseline BEFORE this pass's adoptions land (mirrors the bot
+                    // path's `gatherCommentBody` call before its own copies) — feeds
+                    // the noise guard below without a lone adoption inflating its own
+                    // count. Plain prefix only (not the private-prefix listing done
+                    // for the final render below) — good enough for a guard decision.
+                    preAdoptionAttachmentCount = (await client.listAll({ prefix: ghKeyPrefix(target) }))
+                        .length;
+                    for (const url of urls) {
+                        try {
+                            await client.attachExisting({
+                                source: url,
+                                repo: target.repo,
+                                ...(target.kind === "pull" ? { pr: target.num } : { issue: target.num }),
+                            });
+                            adoptedCount++;
+                        }
+                        catch {
+                            // Not a resolvable uploads.sh URL, belongs to a different
+                            // workspace, or the source was deleted — silently dropped,
+                            // matching the bot path's contract (a throw from
+                            // `resolveAttachSourceKey` is caught per-URL there too).
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Not a git repo, `.uploads.yml` unreadable, or `gh` unavailable for the
+        // PR/comments fetch — degrade to no adoption this pass.
+    }
     // gh fallback: gather from this workspace's own data and post via local `gh`.
     // Note (issues #304, #365): this CLI process has no server-side
     // WorkspaceRecord in scope, so it cannot honor a workspace's
@@ -647,13 +709,23 @@ export async function syncAttachmentsComment(client, target, run, workspace, opt
     }
     // Append only on the local-gh path: bot posts already carry the uploads-sh
     // bot identity, so this note would be wrong there.
-    const body = `${attachmentsCommentBody(items, previewGalleries, marker, renderOptions)}\n${GH_FALLBACK_AUTHOR_NOTE}`;
+    const body = `${attachmentsCommentBody(items, previewGalleries, marker, renderOptions, target)}\n${GH_FALLBACK_AUTHOR_NOTE}`;
     const count = items.length + previewGalleries.length;
+    // Noise guard (issue #708, mirrors the bot's `shouldSyncAfterAdopt`): a
+    // lone adopted link with nothing else already attached is already fully
+    // visible inline in the PR/comment — don't create a brand-new comment just
+    // to repeat it. `upsertAttachmentsComment` still PATCHes an existing
+    // managed comment unconditionally (its own `if (existing)` branch runs
+    // regardless of `createIfMissing`), so "a managed comment already exists"
+    // and "other attachments are already present" both heal/sync for free
+    // here without any extra condition — this only ever suppresses a fresh
+    // create.
+    const skipLoneAdoptionCreate = adoptedCount === 1 && (preAdoptionAttachmentCount ?? 0) === 0;
     // Empty (count 0) renders the neutral empty-state body but must not create a
     // comment — it only rewrites one that already exists (`action: "skipped"`
     // when none does).
     const { action } = upsertAttachmentsComment(target, body, run, marker, {
-        createIfMissing: count > 0,
+        createIfMissing: count > 0 && !skipLoneAdoptionCreate,
     });
     return { action, count, via: "gh" };
 }
@@ -683,6 +755,15 @@ 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).
 
+An argument that doesn't exist on disk but resolves as an already-uploaded
+object — a bare key (e.g. "f/AbC123/shot.webp") or an uploads.sh URL (storage
+host, embed host, or /f/ page) — attaches via a server-side copy instead of a
+re-upload: the source's own derived metadata (path/url/viewport/state/…)
+rides along, and gh.repo/gh.kind/gh.number/gh.ref are stamped fresh. Copy by
+default; --move deletes the source after a successful copy. A path that
+exists on disk always wins as a local file, even if it also happens to look
+like a key.
+
 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>
@@ -714,6 +795,8 @@ Options:
                         resolved PR and refresh the comment; not with
                         --branch/--issue/--no-promote
   --no-promote          Skip auto-promoting branch-staged attachments (default path only)
+  --move                With an already-uploaded key/URL argument: delete the source
+                        object after a successful server-side copy (default: copy)
   --repo <owner/repo>   Repository (default: gh/git inference)
   --no-comment          Upload only; don't create/update the managed comment
   --content-type <mime> Override Content-Type (applied to every file; ignored when optimize rewrites)
@@ -768,6 +851,57 @@ sentMetadata) {
     const missingPath = uploads.some((u, i) => u.contentType.startsWith("image/") && !sentMetadata[i]?.path);
     return missingPath ? "tip: add --meta path=/route so this shot is findable by page" : undefined;
 }
+/**
+ * Bounded fan-out for `uploads attach`'s already-uploaded-object args (issue
+ * #702) — attach args are independent server calls (no shared batch state
+ * like `uploadAttachments`'s optimize/frame prep), so this stays a thin
+ * wrapper rather than a variant of that function.
+ */
+const ATTACH_EXISTING_CONCURRENCY = 4;
+async function attachExistingBatch(client, target, sources, move) {
+    const outcomes = await mapBounded(sources, ATTACH_EXISTING_CONCURRENCY, async (source) => {
+        try {
+            const result = await client.attachExisting({
+                source,
+                repo: target.repo,
+                pr: target.kind === "pull" ? target.num : undefined,
+                issue: target.kind === "issues" ? target.num : undefined,
+                move,
+            });
+            return { ok: true, source, result };
+        }
+        catch (err) {
+            const message = err instanceof UploadsError && err.code === "NOT_FOUND"
+                ? `not a local file, and no such object in this workspace: ${source}`
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            return {
+                ok: false,
+                source,
+                cause: err,
+                error: {
+                    message,
+                    code: err instanceof UploadsError ? err.code : undefined,
+                    status: err instanceof UploadsError ? err.status : undefined,
+                },
+            };
+        }
+    });
+    const results = [];
+    const failures = [];
+    let firstError;
+    for (const outcome of outcomes) {
+        if (outcome.ok) {
+            results.push(outcome.result);
+        }
+        else {
+            failures.push({ file: outcome.source, error: outcome.error });
+            firstError ??= outcome.cause;
+        }
+    }
+    return { results, failures, firstError };
+}
 /**
  * Shared prepare + put loop for both PR/issue attach (`uploadAttachments`)
  * and branch-staged attach (`uploadBranchAttachments`) — bounded concurrency,
@@ -1021,6 +1155,9 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     if (parsed.flags.has("--no-promote") && typeof parsed.flags.get("--no-promote") === "string") {
         throw new UsageError("--no-promote takes no value — place it after the file arguments");
     }
+    if (parsed.flags.has("--move") && typeof parsed.flags.get("--move") === "string") {
+        throw new UsageError("--move takes no value — place it after the file arguments");
+    }
     if (parsed.flags.has("--promote")) {
         if (parsed.positionals.length > 0) {
             throw new UsageError("--promote takes no file arguments — attaching a file to a PR already auto-promotes " +
@@ -1073,23 +1210,61 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     };
     if (Object.keys(metadata).length > 0)
         validateMetaMap(metadata);
+    // Args that exist on disk are always local files, even if they'd also
+    // parse as a key/URL. Everything else is a candidate for the server-side
+    // attach-existing path (issue #702) — resolved/validated server-side, so a
+    // typo'd path and a genuinely-missing object key report the same way.
+    const localFiles = parsed.positionals.filter((p) => existsSync(p));
+    const remoteArgs = parsed.positionals.filter((p) => !existsSync(p));
+    const moveExisting = parsed.flags.has("--move");
+    if (moveExisting && remoteArgs.length === 0) {
+        throw new UsageError("--move only applies to already-uploaded key/URL arguments");
+    }
     const logHuman = !ctx.quiet && !ctx.json;
-    if (logHuman) {
-        const n = parsed.positionals.length;
+    if (logHuman && localFiles.length > 0) {
+        const n = localFiles.length;
         process.stderr.write(`>> uploading ${n} file${n === 1 ? "" : "s"}\n`);
     }
-    const { uploads, failures, firstError, sentMetadata } = await uploadAttachments({
-        client: ctx.client,
-        target,
-        files: parsed.positionals,
-        contentType: contentTypeOverride,
-        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) {
+    const uploadResult = localFiles.length > 0
+        ? await uploadAttachments({
+            client: ctx.client,
+            target,
+            files: localFiles,
+            contentType: contentTypeOverride,
+            optimize: optimizeOpts,
+            frame: frameOpts,
+            metadata,
+            deriveImageFacts: derivedMetaEnabled(parsed.flags, defaults),
+        })
+        : { uploads: [], failures: [], firstError: undefined, sentMetadata: [] };
+    const { uploads, sentMetadata } = uploadResult;
+    const localFailures = uploadResult.failures;
+    if (logHuman && remoteArgs.length > 0) {
+        const n = remoteArgs.length;
+        process.stderr.write(`>> attaching ${n} existing object${n === 1 ? "" : "s"}\n`);
+    }
+    const remoteResult = remoteArgs.length > 0
+        ? await attachExistingBatch(ctx.client, target, remoteArgs, moveExisting)
+        : {
+            results: [],
+            failures: [],
+            firstError: undefined,
+        };
+    const { results: attachedExisting, failures: remoteFailures } = remoteResult;
+    const failures = [...localFailures, ...remoteFailures];
+    const firstError = localFailures.length > 0 ? uploadResult.firstError : remoteResult.firstError;
+    // Single-arg total failure: rethrow so CLI exit codes stay auth/network-aware.
+    // The remote-attach path's friendlier not-found message (attachExistingBatch)
+    // wins over the raw client error text, but the original error's class/code
+    // (UploadsError) is preserved so exit-code mapping stays unaffected.
+    if (uploads.length === 0 &&
+        attachedExisting.length === 0 &&
+        failures.length === 1 &&
+        parsed.positionals.length === 1) {
+        const only = failures[0];
+        if (firstError instanceof UploadsError && firstError.message !== only.error.message) {
+            throw new UploadsError(only.error.message, firstError.code, firstError.status);
+        }
         throw firstError instanceof Error ? firstError : new Error(String(firstError));
     }
     // Auto-promote: before the comment sync, best-effort promote this
@@ -1131,6 +1306,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         await writeJson({
             target,
             uploads,
+            attachedExisting,
             failures,
             comment,
             commentError,
@@ -1152,6 +1328,13 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
             const embedLine = result.embedUrl ? `EMBED: ${result.embedUrl}\n` : "";
             await writeStdout(`URL: ${result.url}\n${embedLine}MARKDOWN: ${result.markdown}\n`);
         }
+        for (const attached of attachedExisting) {
+            if (logHuman) {
+                process.stderr.write(`>> ${attached.source.key}: attached${attached.moved ? " (moved)" : ""} as ${attached.key}\n`);
+            }
+            const embedLine = attached.embedUrl ? `EMBED: ${attached.embedUrl}\n` : "";
+            await writeStdout(`URL: ${attached.url}\n${embedLine}`);
+        }
         for (const failure of failures) {
             process.stderr.write(`warning: could not upload ${failure.file}: ${failure.error.message}\n`);
         }
@@ -1347,36 +1530,54 @@ async function runAttachPromoteOnly(ctx, parsed, run) {
  * enough to never be felt as a hang. */
 const PUT_NUDGE_GH_TIMEOUT_MS = 3000;
 /**
- * The bare-put nudge's wording (issue #393): teaches `--pr`/`attach --branch`
- * as an upgrade from a targetless `put`. `pr` present → names the PR;
- * otherwise a generic variant that still points at `--pr <num>`. Used
- * verbatim for both the human-mode stderr line and the JSON `hint` field.
+ * The bare-put nudge's wording (issue #393, made concrete by issue #700):
+ * teaches `--pr`/`attach --branch` as an upgrade from a targetless `put`.
+ * `pr` present → names the PR and, once upload `keys` are known, appends a
+ * ready-made follow-up command naming them verbatim (e.g. `uploads attach
+ * --pr 1250 f/abc123.webp`); otherwise a generic variant that still points
+ * at `--pr <num>`. Used verbatim for both the human-mode stderr line and the
+ * JSON `hint` field.
  */
-function putNudgeText(branch, pr) {
+export function putNudgeText(branch, pr, keys = []) {
     const prClause = pr !== undefined ? ` (PR #${pr} open) — rerun with --pr ${pr}` : ` — rerun with --pr <num>`;
-    return (`note: on branch ${branch}${prClause} for a stable key plus a managed comment ` +
-        `that collects this PR's media, or stage pre-PR files with: uploads attach <file> --branch`);
+    const base = `note: on branch ${branch}${prClause} for a stable key plus a managed comment ` +
+        `that collects this PR's media, or stage pre-PR files with: uploads attach <file> --branch`;
+    if (pr === undefined || keys.length === 0)
+        return base;
+    return `${base}. Already uploaded? uploads attach --pr ${pr} ${keys.join(" ")}`;
 }
 /**
- * Best-effort bare-put nudge (issue #393): fires only when `put` has no
- * targeting flag at all (`--pr`/`--issue`/`--key`; `--branch` too, though
+ * Auto-PR note (issue #700): announces at the moment it fires that a bare
+ * put/screenshot on this branch was auto-attached to `pr` — the default
+ * behavior change this issue introduces — and how to opt out.
+ */
+export function autoPrNoteText(pr) {
+    return (`note: branch maps to open PR #${pr} — auto-attached (stable key + managed comment sync). ` +
+        `Opt out with --no-pr or UPLOADS_NO_AUTO_PR=1.`);
+}
+/**
+ * Best-effort bare-put/screenshot nudge context (issue #393): resolves the
+ * branch and, when detectable, the open PR for it — fires only when there is
+ * no targeting flag at all (`--pr`/`--issue`/`--key`; `--branch` too, though
  * `put` doesn't currently accept it — defensive parity with `attach`), is
  * inside a git repo (reusing `deriveRepoFromGit`, the same detection the
  * default screenshot key's repo segment uses), and the current branch isn't
  * the default one. Never throws — any failure (not a repo, detached HEAD,
  * `gh` missing/unauthenticated/timed out) degrades to "no nudge" or, once a
- * branch is already known, to the generic no-PR wording. Must never affect
- * put's exit code, stdout, or upload behavior.
+ * branch is already known, to a context with `pr: undefined` (the generic
+ * no-PR wording). Must never affect put's exit code, stdout, or upload
+ * behavior. Callers turn the result into text via `putNudgeText`, once any
+ * upload keys are known.
  */
-function resolvePutNudge(opts) {
-    const { ctx, flags, ghTarget, keyHint, noGit, defaults, run } = opts;
-    if (ctx.quiet)
+export function resolvePutNudgeContext(opts) {
+    const { quiet, noNudge, ghTarget, keyHint, hasBranchFlag, noGit, repoArg, run } = opts;
+    if (quiet)
         return undefined;
-    if (defaults.noNudge)
+    if (noNudge)
         return undefined;
     if (ghTarget || keyHint || noGit)
         return undefined;
-    if (flags.has("--branch"))
+    if (hasBranchFlag)
         return undefined; // not a real put flag today; defensive only
     try {
         if (deriveRepoFromGit(run) === undefined)
@@ -1401,19 +1602,69 @@ function resolvePutNudge(opts) {
             // fast/fake, and execFileSync's `timeout` option is meaningless
             // against anything that isn't actually shelling out.
             const timed = run === execRunner ? timedExecRunner(PUT_NUDGE_GH_TIMEOUT_MS) : run;
-            const repoArg = flagString(flags, "--repo") ?? defaults.repo;
             const repo = resolveRepo(repoArg, timed);
             pr = resolveCurrentPullRequest(repo, timed).num;
         }
         catch {
             pr = undefined; // gh missing/unauthenticated/timed out/no open PR — generic wording
         }
-        return putNudgeText(branch, pr);
+        return { branch, pr };
     }
     catch {
         return undefined;
     }
 }
+/**
+ * Auto-PR context (issue #700): when a bare put/screenshot has no explicit
+ * destination flag at all (`--pr`/`--issue`/`--key`/`--ref`/`--prefix`/
+ * `--destination`, and for `screenshot` no explicit `--branch`) and runs on a
+ * branch that maps to exactly one open PR, this resolves that PR so the
+ * caller can behave as if `--pr <n>` had been passed — stable key + managed
+ * comment sync — instead of the #403/#469 staging default or the plain dated
+ * layout. `resolveCurrentPullRequest`'s `gh pr view <branch>` lookup is
+ * already the unambiguous case: it names the single open PR whose head is
+ * that branch, or fails (no open PR, or `gh` unavailable/unauthenticated) —
+ * there is no "ambiguous, more than one" state to further disambiguate.
+ * Opt-out: `noAutoPr` (the caller folds in `--no-pr` and
+ * `UPLOADS_NO_AUTO_PR=1`/config). Never fires outside a git checkout, on the
+ * default branch, or with `--no-git`; any failure (not a repo, detached
+ * HEAD, gh missing/unauthenticated/timed out, no open PR) degrades to
+ * undefined so the caller falls back to its normal staging/dated behavior.
+ */
+export function resolveAutoPrTarget(opts) {
+    const { ghTarget, keyHint, refArg, prefixArg, destinationArg, branchArg, noGit, noAutoPr, repoArg, run, } = opts;
+    if (noAutoPr)
+        return undefined;
+    if (ghTarget || keyHint || noGit)
+        return undefined;
+    if (refArg || prefixArg || destinationArg || branchArg !== undefined)
+        return undefined;
+    try {
+        if (deriveRepoFromGit(run) === undefined)
+            return undefined; // not a (usable) git repo
+        let branch;
+        try {
+            branch = resolveCurrentBranch(run);
+        }
+        catch {
+            return undefined; // detached HEAD, or git unavailable
+        }
+        const defaultBranch = resolveDefaultBranch(run);
+        const onDefaultBranch = defaultBranch
+            ? branch === defaultBranch
+            : branch === "main" || branch === "master"; // undetermined: err toward the old default
+        if (onDefaultBranch)
+            return undefined;
+        // Same bounded-timeout treatment as the #393 nudge's `gh pr view` call —
+        // this must never be felt as a hang.
+        const timed = run === execRunner ? timedExecRunner(PUT_NUDGE_GH_TIMEOUT_MS) : run;
+        const repo = resolveRepo(repoArg, timed);
+        return resolveCurrentPullRequest(repo, timed);
+    }
+    catch {
+        return undefined; // gh/git unavailable, no open PR, or repo unresolvable
+    }
+}
 /**
  * Bare-put branch-staging trigger (issue #403): put on a non-default git
  * branch stages to the branch prefix by default — the branch becomes the
@@ -1638,10 +1889,39 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         });
     }
     const multi = files.length > 1;
+    // Resolved early (issue #700): both the auto-PR opt-out default and the
+    // `--no-git`-gated staging/auto-PR detection below need it before the rest
+    // of put's flag parsing.
+    const defaults = resolvePutDefaults({ envFile: ctx.envFile });
+    const noGit = flagBool(parsed.flags, "--no-git") || defaults.noGit === true;
     const keyHint = flagString(parsed.flags, "--key");
     const destFlag = flagString(parsed.flags, "--destination");
     const prefixFlag = flagString(parsed.flags, "--prefix");
     const ghTarget = ghTargetFromFlags(parsed.flags, run);
+    if (parsed.flags.has("--no-pr") && typeof parsed.flags.get("--no-pr") === "string") {
+        throw new UsageError("--no-pr takes no value");
+    }
+    const noAutoPr = flagBool(parsed.flags, "--no-pr") || defaults.noAutoPr === true;
+    // Auto-PR context (issue #700): a bare put (no --pr/--issue/--key/--ref/
+    // --prefix/--destination, not --no-git/--no-pr) on a branch that maps to
+    // exactly one open PR behaves as if `--pr <n>` had been passed — see
+    // resolveAutoPrTarget. Supersedes both the #403 staging default and the
+    // #393 nudge for this case; computed before the gh.* metadata resolution
+    // below since it takes over that resolution entirely.
+    const autoPrTarget = ghTarget
+        ? undefined
+        : resolveAutoPrTarget({
+            ghTarget,
+            keyHint,
+            refArg: flagString(parsed.flags, "--ref"),
+            prefixArg: prefixFlag,
+            destinationArg: destFlag,
+            noGit,
+            noAutoPr,
+            repoArg: flagString(parsed.flags, "--repo") ?? defaults.repo,
+            run,
+        });
+    const effectiveGhTarget = ghTarget ?? autoPrTarget;
     // Comment sync runs by default with --pr/--issue (matches `attach`); opt
     // out with --no-comment. --comment is accepted as a redundant no-op for
     // back-compat with scripts written before this default flipped (#537).
@@ -1676,7 +1956,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     if (parsed.flags.has("--no-auto") && typeof parsed.flags.get("--no-auto") === "string") {
         throw new UsageError("--no-auto takes no value");
     }
-    if (parsed.flags.has("--no-comment") && !ghTarget) {
+    if (parsed.flags.has("--no-comment") && !effectiveGhTarget) {
         throw new UsageError("--no-comment requires --pr or --issue");
     }
     if (multi) {
@@ -1713,7 +1993,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             destination: destFlag,
             prefix: prefixFlag,
             key: keyHint,
-            ghAttachment: Boolean(ghTarget),
+            ghAttachment: Boolean(effectiveGhTarget),
         });
     }
     catch (err) {
@@ -1729,7 +2009,6 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 return raw;
             throw new UsageError(`invalid --format: ${raw}`);
         })();
-    const defaults = resolvePutDefaults({ envFile: ctx.envFile });
     const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
     const frameOpts = frameOptionsFromFlags(parsed.flags);
     const contentTypeOverride = flagString(parsed.flags, "--content-type");
@@ -1742,16 +2021,16 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 throw new UsageError(`invalid --width: ${widthRaw}`);
             })()
             : defaults.width;
-    const noGit = flagBool(parsed.flags, "--no-git") || defaults.noGit === true;
     // Bare-put branch staging (issue #403): a bare put (no --pr/--issue/--key/
     // --ref/--prefix/--destination, not --no-git) on a non-default git branch
     // stages to the branch prefix — identical key/metadata to `attach
     // --branch` — instead of the dated layout. Computed before gh.* metadata
     // resolution below since it takes over that resolution entirely (branch
     // metadata, not PR/issue metadata) and supersedes the #393 nudge for this
-    // case.
+    // case. `effectiveGhTarget` (explicit --pr/--issue OR the #700 auto-PR
+    // match) wins over staging, same as it wins over the dated layout.
     const stagingTarget = resolvePutStagingTarget({
-        ghTarget,
+        ghTarget: effectiveGhTarget,
         keyHint,
         refArg: flagString(parsed.flags, "--ref"),
         prefixArg: prefixFlag,
@@ -1760,15 +2039,16 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         repoArg: flagString(parsed.flags, "--repo") ?? defaults.repo,
         run,
     });
-    // gh.* metadata: explicit --pr/--issue target wins over --meta; staging
-    // wins over --meta the same way (matches attach --branch); otherwise
-    // best-effort auto resolution (on by default) where --meta wins. --no-git,
-    // --no-auto, or UPLOADS_NO_AUTO_META disable auto; --auto forces past the
-    // config default but never past --no-git (no repo to resolve).
+    // gh.* metadata: explicit --pr/--issue target (or the #700 auto-PR match)
+    // wins over --meta; staging wins over --meta the same way (matches attach
+    // --branch); otherwise best-effort auto resolution (on by default) where
+    // --meta wins. --no-git, --no-auto, or UPLOADS_NO_AUTO_META disable auto;
+    // --auto forces past the config default but never past --no-git (no repo
+    // to resolve).
     let metadata = userMeta;
     let attachedRef;
-    if (ghTarget) {
-        const merged = { ...userMeta, ...ghMetadataFromTargetWithTitle(ghTarget, run) };
+    if (effectiveGhTarget) {
+        const merged = { ...userMeta, ...ghMetadataFromTargetWithTitle(effectiveGhTarget, run) };
         validateMetaMap(merged); // enforce 24-key/8KB caps on the merged map (matches attach)
         metadata = merged;
         attachedRef = merged["gh.ref"];
@@ -1818,23 +2098,26 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     // buckets — one advisory line at the moment the context went missing.
     // --no-git is an explicit choice, so it suppresses the nudge too.
     const contextNudge = !ctx.quiet && !defaults.noNudge && !noGit ? noProjectContextNudge(metadata) : undefined;
-    // Bare-put nudge (issue #393): only relevant when staging didn't take over
-    // — once `stagingTarget` resolves, staging IS the upgrade the nudge used to
-    // point at, so this is skipped entirely rather than firing redundantly.
-    // Still fires as before for a bare put that lands on the dated layout with
-    // a detectable PR (e.g. an explicit --ref/--prefix opts out of staging).
-    // Computed once, used for both the trailing stderr line (human mode) and
-    // the JSON `hint` field below. Best-effort — see resolvePutNudge; never
-    // affects exit code, stdout, or the upload.
-    const nudge = stagingTarget
+    // Bare-put nudge (issue #393): only relevant when neither auto-PR nor
+    // staging took over — once `effectiveGhTarget`/`stagingTarget` resolves,
+    // that IS the upgrade the nudge used to point at, so this is skipped
+    // entirely rather than firing redundantly. Still fires as before for a
+    // bare put that lands on the dated layout with a detectable PR (e.g. an
+    // explicit --ref/--prefix opts out of staging AND auto-PR, or --no-pr/
+    // UPLOADS_NO_AUTO_PR opts out of auto-PR specifically). The concrete
+    // key-naming text (issue #700) is finished below, once upload keys exist.
+    // Best-effort — see resolvePutNudgeContext; never affects exit code,
+    // stdout, or the upload.
+    const nudgeContext = effectiveGhTarget || stagingTarget
         ? undefined
-        : resolvePutNudge({
-            ctx,
-            flags: parsed.flags,
+        : resolvePutNudgeContext({
+            quiet: ctx.quiet,
+            noNudge: defaults.noNudge === true,
             ghTarget,
             keyHint,
+            hasBranchFlag: parsed.flags.has("--branch"),
             noGit,
-            defaults,
+            repoArg: flagString(parsed.flags, "--repo") ?? defaults.repo,
             run,
         });
     // Staging note (issue #403): same suppression as the #393 nudge
@@ -1843,6 +2126,12 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const stagingNote = stagingTarget && !ctx.quiet && !defaults.noNudge
         ? putStagingNoteText(stagingTarget.branch)
         : undefined;
+    // Auto-PR note (issue #700): announces the default-behavior change at the
+    // moment it fires, so a bare put that silently became a --pr attach isn't
+    // a surprise — names the PR and how to opt out. Same suppression as the
+    // other advisories (--quiet, UPLOADS_NO_NUDGE=1); NOT gated by --no-pr/
+    // UPLOADS_NO_AUTO_PR since those are what prevent it from firing at all.
+    const autoPrNote = autoPrTarget && !ctx.quiet && !defaults.noNudge ? autoPrNoteText(autoPrTarget.num) : undefined;
     const logHuman = !ctx.quiet && format === "human";
     if (logHuman) {
         if (multi) {
@@ -1860,7 +2149,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         files,
         nameOverride: nameFlag,
         explicitKey: keyHint,
-        ghTarget,
+        ghTarget: effectiveGhTarget,
         ghBranchTarget: stagingTarget,
         prefix: resolvedPrefix ?? defaults.prefix,
         repo: flagString(parsed.flags, "--repo") ?? defaults.repo,
@@ -1880,6 +2169,13 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     if (uploads.length === 0 && failures.length > 0 && !multi) {
         throw firstError instanceof Error ? firstError : new Error(String(firstError));
     }
+    // Concrete bare-put nudge text (issue #700): built once upload keys exist,
+    // so the ready-made follow-up names them, e.g.
+    // "uploads attach --pr 1250 f/abc123.webp". Falls back to the plain
+    // #393 wording when there are no successful uploads to name.
+    const nudge = nudgeContext && uploads.length > 0
+        ? putNudgeText(nudgeContext.branch, nudgeContext.pr, uploads.map((u) => u.key))
+        : undefined;
     // Stage-time binding warning (issue #398/#400): same check `attach
     // --branch` runs, now also on the bare-put staging path. Best-effort — see
     // resolveStageBindingWarning; never affects exit code or the upload.
@@ -1887,20 +2183,19 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         ? 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
+    // `path` meta. Only relevant on the (explicit or auto) gh target path — the
+    // bare-put staging/dated paths aren't attached to a PR/issue yet, so
+    // there's nothing to look up from a page later.
+    const pathHint = effectiveGhTarget && uploads.length > 0 && !ctx.quiet
         ? pathMetaHintFor(uploads, sentMetadata)
         : 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. pathHint only ever fires on the ghTarget path, so
-    // it never competes with the other three.
-    const jsonHint = nudge ?? bindingWarning ?? stagingNote ?? pathHint ?? contextNudge;
+    // One JSON `hint` slot, shared across every advisory this command can
+    // surface. `autoPrNote` and `nudge` are mutually exclusive with each other
+    // and with `stagingNote` (each corresponds to a different destination the
+    // upload landed on); pathHint only ever fires on the gh-target path, so it
+    // never competes with the other three. Same precedence stderr prints,
+    // below.
+    const jsonHint = autoPrNote ?? nudge ?? bindingWarning ?? stagingNote ?? pathHint ?? contextNudge;
     const galleriesByKey = new Map();
     let galleryHadError = false;
     if (galleryId && uploads.length > 0) {
@@ -1923,9 +2218,9 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     }
     let comment;
     let commentError;
-    if (wantComment && ghTarget && !dryRun && uploads.length > 0) {
+    if (wantComment && effectiveGhTarget && !dryRun && uploads.length > 0) {
         try {
-            comment = await syncAttachmentsComment(ctx.client, ghTarget, run, ctx.config.workspace);
+            comment = await syncAttachmentsComment(ctx.client, effectiveGhTarget, run, ctx.config.workspace);
             if (logHuman)
                 process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         }
@@ -1977,6 +2272,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             for (const failure of failures) {
                 process.stderr.write(`warning: could not upload ${failure.file}: ${failure.error.message}\n`);
             }
+            if (autoPrNote)
+                process.stderr.write(`${autoPrNote}\n`);
             if (nudge)
                 process.stderr.write(`${nudge}\n`);
             if (stagingNote)
@@ -2040,6 +2337,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     if (gallery?.error) {
         process.stderr.write(`warning: upload succeeded but adding it to gallery ${gallery.id} failed: ${gallery.error.message}\n`);
     }
+    if (autoPrNote && format !== "json")
+        process.stderr.write(`${autoPrNote}\n`);
     if (nudge && format !== "json")
         process.stderr.write(`${nudge}\n`);
     if (stagingNote && format !== "json")