@buildinternet/uploads 0.43.0 → 0.45.0

package/dist/client.d.ts

@@ -305,6 +305,32 @@ export interface PromoteBranchAttachmentsResult {
     promoted: string[];
     skipped: PromoteSkip[];
 }
+/**
+ * `POST /v1/workspaces/:workspace/github/attach` request/response (server
+ * contract, issue #702). `source` is a raw object key or an uploads.sh URL
+ * (storage host, embed host, or `/f/` page). Exactly one of `pr`/`issue` is
+ * required. Copy by default; `move: true` deletes the source object after a
+ * successful copy.
+ */
+export interface AttachExistingOptions {
+    source: string;
+    repo: string;
+    pr?: number;
+    issue?: number;
+    move?: boolean;
+    filename?: string;
+}
+export interface AttachExistingResult {
+    key: string;
+    url: string | null;
+    embedUrl: string | null;
+    pageUrl?: string;
+    moved: boolean;
+    source: {
+        key: string;
+    };
+    comment: GithubCommentResult;
+}
 /** `GET`/`POST /v1/workspaces/:workspace/github/link` result (server contract, phase 4b). */
 export interface GithubLinkResult {
     repo: string;
@@ -670,6 +696,15 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
      * that doesn't have this route yet, as "nothing promoted").
      */
     promoteBranchAttachments(opts: PromoteBranchAttachmentsOptions): Promise<PromoteBranchAttachmentsResult>;
+    /**
+     * Attach an already-uploaded object to a PR/issue via a server-side copy
+     * (issue #702) — see `AttachExistingOptions`. Throws `UploadsError` on
+     * any failure (including a 404 from an older/self-hosted server without
+     * this route, or `source_not_found`) — unlike the degrade-safe promote/
+     * comment calls, this is the CLI's only way to move the object, so a
+     * failure must be visible, not silently swallowed.
+     */
+    attachExisting(opts: AttachExistingOptions): Promise<AttachExistingResult>;
     /** Current binding for `repo`, or `{ linked: false }` if unclaimed. Throws
      * `UploadsError` (status 404) on an older/self-hosted server without this
      * route — callers treat that as "bindings unsupported". */

package/dist/client.js

@@ -582,6 +582,20 @@ export function createUploadsClient(config) {
                 headers: { "Content-Type": "application/json" },
             });
         },
+        /**
+         * Attach an already-uploaded object to a PR/issue via a server-side copy
+         * (issue #702) — see `AttachExistingOptions`. Throws `UploadsError` on
+         * any failure (including a 404 from an older/self-hosted server without
+         * this route, or `source_not_found`) — unlike the degrade-safe promote/
+         * comment calls, this is the CLI's only way to move the object, so a
+         * failure must be visible, not silently swallowed.
+         */
+        async attachExisting(opts) {
+            return request("POST", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/attach`, {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
         /** Current binding for `repo`, or `{ linked: false }` if unclaimed. Throws
          * `UploadsError` (status 404) on an older/self-hosted server without this
          * route — callers treat that as "bindings unsupported". */

package/dist/commands/hook.d.ts

@@ -1,7 +1,11 @@
 /**
  * `uploads hook pre-pr-screenshot` — agent PreToolUse / beforeShellExecution
- * handler. When the shell command is `gh pr create`, the branch touches UI
- * files, and nothing is staged on uploads.sh, emit a non-blocking advisory.
+ * handler, triggered on `gh pr create`. Two advisories, mutually exclusive:
+ *  - staged-but-unattached files exist for the branch (any reason they got
+ *    there) → a promote suggestion (issue #700): `uploads attach --promote`
+ *    once the PR this command is about to open exists.
+ *  - nothing is staged, but the branch touches UI files → the original
+ *    (issue #379) "consider staging screenshots" advisory.
  *
  * Always fail-open. Disable with UPLOADS_HOOK_DISABLE=1.
  */

package/dist/commands/hook.js

@@ -1,7 +1,11 @@
 /**
  * `uploads hook pre-pr-screenshot` — agent PreToolUse / beforeShellExecution
- * handler. When the shell command is `gh pr create`, the branch touches UI
- * files, and nothing is staged on uploads.sh, emit a non-blocking advisory.
+ * handler, triggered on `gh pr create`. Two advisories, mutually exclusive:
+ *  - staged-but-unattached files exist for the branch (any reason they got
+ *    there) → a promote suggestion (issue #700): `uploads attach --promote`
+ *    once the PR this command is about to open exists.
+ *  - nothing is staged, but the branch touches UI files → the original
+ *    (issue #379) "consider staging screenshots" advisory.
  *
  * Always fail-open. Disable with UPLOADS_HOOK_DISABLE=1.
  */
@@ -22,9 +26,12 @@ Invoked by Claude Code / Codex / Grok / Cursor hooks. Never blocks.
 Harness manifests no-op (exit 0, no output) when this binary is not on PATH.
 
   pre-pr-screenshot
-    If the shell command is \`gh pr create\`, the branch touches UI files, and
-    no screenshots are staged for the branch, emit an advisory to stage with
-    \`uploads attach … --branch\`.
+    If the shell command is \`gh pr create\`:
+      - staged-but-unattached files exist for the branch → suggest promoting
+        them into the PR's managed comment once it exists (issue #700):
+        \`uploads attach --promote --pr <num>\`.
+      - otherwise, if the branch touches UI files → suggest staging with
+        \`uploads attach … --branch\`.
 
 Disable with UPLOADS_HOOK_DISABLE=1.
 `;
@@ -158,14 +165,29 @@ export async function runPrePrScreenshot(deps) {
     const branch = git.branch();
     if (!branch)
         return null;
+    const staged = await (deps.countStaged ?? defaultCountStaged)(branch);
+    if (staged === null)
+        return null; // error/unconfigured → fail open
+    // Promote suggestion (issue #700): staged-but-unattached files already
+    // exist for this branch right as its PR is about to open. The PR doesn't
+    // exist yet at this PreToolUse point, so its number isn't knowable here —
+    // the wording still gives the exact command shape, and a bare
+    // `attach --promote` (which infers the PR from the branch) works too.
+    if (staged > 0) {
+        const fork = (deps.isFork ?? (() => defaultIsFork(cwd)))();
+        const forkNote = fork === true
+            ? " Note: this looks like a fork branch, so staged screenshots won't auto-promote into the PR comment yet (see issue #317) — attach them manually if you use uploads."
+            : "";
+        const message = `${staged} file${staged === 1 ? "" : "s"} staged for branch '${branch}' on uploads.sh ` +
+            `${staged === 1 ? "isn't" : "aren't"} attached to a pull request yet. Once this PR opens, run ` +
+            "`uploads attach --promote --pr <num>` (or a bare `uploads attach --promote`, which infers " +
+            `the PR from the branch) to collect ${staged === 1 ? "it" : "them"} into the managed attachments comment.${forkNote}`;
+        return formatAdvisory(message, isCursorHookInput(raw));
+    }
     const testFiles = deps.testFiles ?? process.env.UPLOADS_HOOK_TEST_FILES;
     const changed = testFiles ? testFiles.split("\n").filter(Boolean) : git.changedFiles();
     if (!anyVisual(changed))
         return null;
-    const staged = await (deps.countStaged ?? defaultCountStaged)(branch);
-    // null = error/unconfigured → fail open; >0 = already staged
-    if (staged === null || staged > 0)
-        return null;
     const fork = (deps.isFork ?? (() => defaultIsFork(cwd)))();
     const forkNote = fork === true
         ? " Note: this looks like a fork branch, so staged screenshots won't auto-promote into the PR comment yet (see issue #317) — attach them manually if you use uploads."

package/dist/commands/screenshot.js

@@ -2,7 +2,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { extractDashValue, 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, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, writeReplacedNote, resolveGhPrefixSafe, } from "../commands.js";
+import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, writeReplacedNote, resolveGhPrefixSafe, resolveAutoPrTarget, resolvePutNudgeContext, putNudgeText, autoPrNoteText, } from "../commands.js";
 import { resolvePutDefaults } from "../config.js";
 import { loadDefaultsRaw, resolveScreenshotDefaults } from "../config-file.js";
 import { resolvePutPrefix } from "../destinations.js";
@@ -44,9 +44,18 @@ sets the whole object key verbatim (no folding).
 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
+Auto-PR context (issue #700): with no --pr/--issue/--branch/--key/--ref/
+--prefix/--destination, a screenshot taken on a branch that maps to exactly
+one open PR behaves as if --pr <n> had been passed — stable gh/ key, managed
+comment sync (with --comment) — instead of branch staging below. A one-line
+note announces this. 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.
+
+Branch staging by default (pre-PR): when auto-PR above doesn't apply and none
+of --pr/--issue/--branch/--key/--ref/--prefix/--destination is given, 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
@@ -102,6 +111,7 @@ Options:
   --optimize-max-edge <px>  Max long edge when optimizing (default: 2400)
   --optimize-quality <1-100> WebP quality (default: 85)
   --keep-exif               Keep EXIF/XMP/ICC when optimizing
+  --no-pr                   Skip auto-PR context (or UPLOADS_NO_AUTO_PR=1) — see above
   --pr <num>                Attach to a pull request (stable URL, no hash)
   --issue <num>             Attach to an issue
   --branch [name]           Stage against a branch, pre-PR (default: current git branch):
@@ -320,7 +330,32 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     }
     const putDefaults = resolvePutDefaults({ envFile: ctx.envFile }, rawDefaults);
     const noGit = flagBool(parsed.flags, "--no-git") || putDefaults.noGit === true;
+    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") || putDefaults.noAutoPr === true;
     const branchRepo = branchArg !== undefined ? resolveRepo(flagString(parsed.flags, "--repo"), run) : undefined;
+    // Auto-PR context (issue #700): when no --branch/--pr/--issue/--key/--ref/
+    // --prefix/--destination is given, git use isn't disabled, and --no-pr/
+    // UPLOADS_NO_AUTO_PR hasn't opted out, a screenshot taken on a branch that
+    // maps to exactly one open PR behaves as if --pr <n> had been passed —
+    // stable key + managed comment sync — instead of the #469 auto-staging
+    // default below. Mirrors put's #700 handling exactly (resolveAutoPrTarget).
+    const autoPrTarget = ghTarget || branchArg !== undefined
+        ? undefined
+        : resolveAutoPrTarget({
+            ghTarget,
+            keyHint,
+            refArg: flagString(parsed.flags, "--ref"),
+            prefixArg: prefixFlag,
+            destinationArg: destFlag,
+            branchArg,
+            noGit,
+            noAutoPr,
+            repoArg: flagString(parsed.flags, "--repo") ?? putDefaults.repo,
+            run,
+        });
+    const effectiveGhTarget = ghTarget ?? autoPrTarget;
     // 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
@@ -329,10 +364,11 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     // `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).
+    // entirely when --branch was given explicitly (already handled above), or
+    // when the #700 auto-PR match above already took over.
     const autoStagingTarget = branchArg === undefined
         ? resolvePutStagingTarget({
-            ghTarget,
+            ghTarget: effectiveGhTarget,
             keyHint,
             refArg: flagString(parsed.flags, "--ref"),
             prefixArg: prefixFlag,
@@ -349,7 +385,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
             destination: destFlag,
             prefix: prefixFlag,
             key: keyHint,
-            ghAttachment: Boolean(ghTarget) || stagingTarget !== undefined,
+            ghAttachment: Boolean(effectiveGhTarget) || stagingTarget !== undefined,
         });
     }
     catch (err) {
@@ -379,8 +415,8 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
         ...(repoSlug ? { repo: repoSlug } : {}),
     });
     let metadata = withFacts;
-    if (ghTarget) {
-        metadata = { ...withFacts, ...ghMetadataFromTargetWithTitle(ghTarget, run) };
+    if (effectiveGhTarget) {
+        metadata = { ...withFacts, ...ghMetadataFromTargetWithTitle(effectiveGhTarget, run) };
         validateMetaMap(metadata);
     }
     else if (stagingTarget !== undefined) {
@@ -475,10 +511,10 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     // Resolved once (issue #631), only when it's actually needed for the
     // upload about to happen (never for the noUpload/no-target bailouts
     // above) — never per file (screenshot only ever uploads one).
-    const ghPrefix = ghTarget
+    const ghPrefix = effectiveGhTarget
         ? await resolveGhPrefixSafe(ctx.client, {
-            repo: ghTarget.repo,
-            target: { kind: ghTarget.kind, num: ghTarget.num },
+            repo: effectiveGhTarget.repo,
+            target: { kind: effectiveGhTarget.kind, num: effectiveGhTarget.num },
         })
         : stagingTarget !== undefined
             ? await resolveGhPrefixSafe(ctx.client, {
@@ -486,11 +522,29 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
                 branch: stagingTarget.branch,
             })
             : undefined;
+    // Bare-screenshot nudge context (issue #393/#700): only relevant when
+    // neither auto-PR nor staging took over — mirrors put's handling exactly.
+    // Resolved before upload; finished into text below once the key is known.
+    const nudgeContext = effectiveGhTarget || stagingTarget
+        ? undefined
+        : resolvePutNudgeContext({
+            quiet: ctx.quiet,
+            noNudge: putDefaults.noNudge === true,
+            ghTarget,
+            keyHint,
+            hasBranchFlag: branchArg !== undefined,
+            noGit,
+            repoArg: flagString(parsed.flags, "--repo") ?? putDefaults.repo,
+            run,
+        });
+    const autoPrNote = autoPrTarget && !ctx.quiet && !putDefaults.noNudge
+        ? autoPrNoteText(autoPrTarget.num)
+        : undefined;
     const alt = altFlag ?? basename(captured.filename);
     const { result, prepared, markdown } = await uploadPreparedImage(ctx.client, finalPng, captured.filename, {
         frame: frameOpts,
         optimize: optimizeOpts,
-        ghTarget,
+        ghTarget: effectiveGhTarget,
         ghBranchTarget: stagingTarget,
         ghPrefix,
         key: keyHint,
@@ -532,11 +586,16 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
             gallery = { id: galleryId, error: err instanceof Error ? err.message : String(err) };
         }
     }
+    // Concrete bare-screenshot nudge text (issue #700): built once the upload
+    // key exists, so the ready-made follow-up names it verbatim.
+    const nudge = nudgeContext
+        ? putNudgeText(nudgeContext.branch, nudgeContext.pr, [result.key])
+        : undefined;
     let comment;
     let commentError;
-    if (wantComment && ghTarget) {
+    if (wantComment && effectiveGhTarget) {
         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`);
         }
@@ -564,6 +623,10 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
                     `(or run \`uploads attach --promote\` after opening)\n`);
             }
         }
+        if (autoPrNote)
+            process.stderr.write(`${autoPrNote}\n`);
+        if (nudge)
+            process.stderr.write(`${nudge}\n`);
         if (bindingWarning)
             process.stderr.write(`${bindingWarning}\n`);
         if (contextNudge)
@@ -573,16 +636,23 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     // One JSON `hint` slot (mirrors bare put): the clip note (issue #652) wins
     // first — it's about the just-captured image itself, more immediately
     // actionable than the other three, which are about upload/staging
-    // mechanics. Then the binding warning, more actionable than the generic
-    // staging note; a replaced-object note (issue #618) is lowest priority —
-    // it only surfaces when nothing else already claimed the slot. Since state
-    // folds into the derived key, replaced + state means a same-side re-capture,
+    // mechanics. Then the auto-PR note and the #393/#700 nudge (issue #700),
+    // then the binding warning, more actionable than the generic staging note;
+    // a replaced-object note (issue #618) is lowest priority — it only
+    // surfaces when nothing else already claimed the slot. Since state folds
+    // into the derived key, replaced + state means a same-side re-capture,
     // which is the intended replace-in-place flow — word it as informational,
     // not as a problem.
     const replacedHint = result.replaced && explicitMeta.state
         ? `re-capture replaced the previous state=${explicitMeta.state} object at ${result.key} — expected for repeat captures of the same URL + state`
         : undefined;
-    const jsonHint = clipHint ?? bindingWarning ?? stagingNote ?? replacedHint ?? contextNudge;
+    const jsonHint = clipHint ??
+        autoPrNote ??
+        nudge ??
+        bindingWarning ??
+        stagingNote ??
+        replacedHint ??
+        contextNudge;
     switch (format) {
         case "json":
             await writeJson({

package/dist/commands.d.ts

@@ -411,6 +411,82 @@ export declare function resolveStageBindingWarning(opts: {
     defaults: PutDefaults;
     repo: string;
 }): Promise<string | undefined>;
+/**
+ * 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.
+ */
+export declare function putNudgeText(branch: string, pr: number | undefined, keys?: string[]): string;
+/**
+ * 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 declare function autoPrNoteText(pr: number): string;
+/**
+ * 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 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.
+ */
+export declare function resolvePutNudgeContext(opts: {
+    quiet: boolean;
+    noNudge: boolean;
+    ghTarget: GhTarget | undefined;
+    keyHint: string | undefined;
+    /** True when an explicit `--branch`-style flag was given (CLI `attach`
+     * parity; `put`/MCP `put` don't accept one — pass false there). */
+    hasBranchFlag?: boolean;
+    noGit: boolean;
+    repoArg: string | undefined;
+    run: CommandRunner;
+}): {
+    branch: string;
+    pr: number | undefined;
+} | 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 declare function resolveAutoPrTarget(opts: {
+    ghTarget: GhTarget | undefined;
+    keyHint: string | undefined;
+    refArg: string | undefined;
+    prefixArg: string | undefined;
+    destinationArg: string | undefined;
+    /** Explicit `--branch` (screenshot only) also opts out — put has no
+     * `--branch` flag today, so callers pass undefined there. */
+    branchArg?: string | undefined;
+    noGit: boolean;
+    noAutoPr: boolean;
+    repoArg: string | undefined;
+    run: CommandRunner;
+}): GhTarget | undefined;
 /**
  * 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