@buildinternet/uploads 0.23.0 → 0.25.0

package/README.md

@@ -91,8 +91,20 @@ attachments when one opens: automatically via the
 [GitHub App](https://uploads.sh/docs/github-app) webhook, or on the first
 `attach` after the PR exists (`--promote` forces it with no new files,
 `--no-promote` opts out). `uploads github link` inspects or claims the
-workspace↔repo binding the webhook path uses. Promoted staging is cleaned up
-server-side after ~7 days (~30 for branches that never got a PR).
+workspace↔repo binding the webhook path uses. Promotion is copy-and-keep —
+the staged original is never deleted, so any URL already embedded keeps
+serving — and staged objects follow only normal per-workspace retention and
+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.
+
+**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
+(and not `--no-git`) stages exactly like `attach --branch` — same key,
+same `gh.*` metadata. The classic dated layout
+(`<prefix>/<repo>/<ref-or-date>/<name>`) remains the default branch/detached
+HEAD/non-repo/`--no-git` behavior, and the explicit-flags opt-out.
 
 **Screenshot capture:** `uploads screenshot <url|file.html>` renders a page to a
 hosted image in one step — no separate browser tooling needed. `--via auto`

package/dist/cli-catalog.js

@@ -114,6 +114,10 @@ export const ROOT_COMMANDS = [
         summary: "Upload (+ URL + markdown for GitHub)",
         essential: true,
     },
+    {
+        name: "staged",
+        summary: "Show what's staged for a branch, and whether it will auto-attach",
+    },
     {
         name: "screenshot",
         usage: "screenshot <target>",

package/dist/cli.js

@@ -4,7 +4,7 @@ import { UploadsError } from "./errors.js";
 import { commandWorkspace, flagString, isHelpFlag, parseArgv, parseCommandArgs, UsageError, } from "./cli-args.js";
 import { formatRootHelp, wantsFullHelp } from "./cli-help.js";
 import { colorEnabled, createStyle } from "./cli-style.js";
-import { runPut, runAttach, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runGithub, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
+import { runPut, runAttach, runStaged, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runGithub, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
 import { runConfig } from "./commands/config.js";
 import { runSetup } from "./commands/setup.js";
 import { runLogin } from "./commands/login.js";
@@ -269,6 +269,7 @@ export async function runCli(argv) {
                 break;
             case "attach":
             case "put":
+            case "staged":
             case "screenshot":
             case "gallery":
             case "list":
@@ -289,6 +290,9 @@ export async function runCli(argv) {
                     case "put":
                         code = await runPut(ctx, cmdArgs, showHelp);
                         break;
+                    case "staged":
+                        code = await runStaged(ctx, cmdArgs, showHelp);
+                        break;
                     case "screenshot":
                         code = await runScreenshot(ctx, cmdArgs, showHelp);
                         break;

package/dist/client.d.ts

@@ -249,6 +249,16 @@ export interface GithubLinkUnlinkResult {
     unlinked: boolean;
     reason?: "not_linked";
 }
+/**
+ * `GET /v1/:workspace/github/repo-link` result (issue #398). Deliberately
+ * minimal relative to `GithubLinkResult`: never names the owning workspace
+ * when it isn't this one — "self"/"other"/"none" is all the stage-time
+ * warning needs, and anything richer would leak cross-tenant info to a
+ * caller that's just probing a repo it detected from local git context.
+ */
+export interface GithubRepoLinkResult {
+    binding: "self" | "other" | "none";
+}
 export interface HealthResult {
     ok: boolean;
 }
@@ -528,6 +538,14 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
      * server without this route.
      */
     githubLinkClaim(repo: string): Promise<GithubLinkClaimResult>;
+    /**
+     * Tri-state binding status for `repo` relative to this workspace (issue
+     * #398, `attach --branch`'s stage-time warning) — never names another
+     * workspace, unlike `githubLinkStatus` above. Throws `UploadsError`
+     * (status 404) on an older/self-hosted server without this route; the
+     * caller (the stage warning) treats ANY failure here as "stay silent".
+     */
+    githubRepoLinkStatus(repo: string): Promise<GithubRepoLinkResult>;
     /**
      * GitHub App configuration + webhook event subscription check. Throws
      * `UploadsError` (status 404) on an older/self-hosted server without

package/dist/client.js

@@ -516,6 +516,16 @@ export function createUploadsClient(config) {
                 headers: { "Content-Type": "application/json" },
             });
         },
+        /**
+         * Tri-state binding status for `repo` relative to this workspace (issue
+         * #398, `attach --branch`'s stage-time warning) — never names another
+         * workspace, unlike `githubLinkStatus` above. Throws `UploadsError`
+         * (status 404) on an older/self-hosted server without this route; the
+         * caller (the stage warning) treats ANY failure here as "stay silent".
+         */
+        async githubRepoLinkStatus(repo) {
+            return request("GET", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/repo-link?repo=${encodeURIComponent(repo)}`);
+        },
         /**
          * GitHub App configuration + webhook event subscription check. Throws
          * `UploadsError` (status 404) on an older/self-hosted server without

package/dist/commands.d.ts

@@ -82,6 +82,13 @@ export interface UploadPreparedImageOptions {
     optimize: OptimizeImageOptions;
     /** gh attachment key wins over `key` when both are set (matches every call site). */
     ghTarget?: GhTarget;
+    /**
+     * Branch-staged key (issue #403): wins over `key`, loses to `ghTarget` (the
+     * two are mutually exclusive at every call site — a PR/issue target always
+     * implies staging is moot). Produces the exact same key as `attach
+     * --branch` for the same filename via `ghBranchAttachmentKey`.
+     */
+    ghBranchTarget?: BranchTarget;
     key?: string;
     prefix?: string;
     repo?: string;
@@ -258,6 +265,8 @@ export declare function uploadPuts(opts: {
     /** Single-file --key. */
     explicitKey?: string;
     ghTarget?: GhTarget;
+    /** Branch-staged key (issue #403) — see UploadPreparedImageOptions.ghBranchTarget. */
+    ghBranchTarget?: BranchTarget;
     prefix?: string;
     repo?: string;
     ref?: string;
@@ -290,6 +299,106 @@ export declare function uploadPuts(opts: {
     firstError?: unknown;
 }>;
 export declare function runAttach(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
+/**
+ * One source of truth for the "staged, but not going to auto-attach" advisory
+ * text (issue #398), shared by the `attach --branch`/bare-`put` stage-time
+ * warning below and the `uploads staged` view (issue #405) — both surfaces
+ * must say the exact same thing for the same binding state, verified by
+ * tests on both call sites. Returns undefined for `"self"` (the happy path —
+ * callers each phrase that themselves) and any unrecognized value.
+ */
+export declare function stagingBindingAdvisory(binding: string, repo: string): string | undefined;
+/**
+ * Best-effort stage-time binding warning (issue #398): after `attach
+ * --branch` stages files, checks whether `repo` is bound to THIS workspace —
+ * webhook auto-promotion at PR open only fires for a repo already bound
+ * (#297), and staging alone never binds one. Fires only for `binding: "none"`
+ * (unbound) or `"other"` (bound elsewhere); `"self"` and any failure
+ * (network, non-200, older server without the route, `binding: "unknown"`)
+ * are silent — this is advisory only and must never make staging look like
+ * it failed. Same suppression as the #393 put nudge: `--quiet`,
+ * `UPLOADS_NO_NUDGE=1` (env or config).
+ */
+export declare function resolveStageBindingWarning(opts: {
+    ctx: CliContext;
+    defaults: PutDefaults;
+    repo: string;
+}): Promise<string | 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
+ * organizing unit instead of the date, superseding the #393 CLI nudge for
+ * this case (see `putStagingNoteText`). Reuses the same detection stack as
+ * `resolvePutNudge` (`deriveRepoFromGit` / `resolveCurrentBranch` /
+ * `resolveDefaultBranch` / main-master fallback) plus a `resolveRepo` lookup
+ * (needed for the "owner/name" staging key) and an explicit-flag opt-out:
+ * `ghTarget`/`keyHint`/`refArg`/`prefixArg`/`destinationArg` set, or `noGit`,
+ * forces the classic dated (or typed-destination) layout. Never throws — any
+ * failure (not a repo, detached HEAD, gh missing/unauthenticated/timed out,
+ * unresolvable repo) degrades to "no staging", leaving the caller to fall
+ * back to the dated path.
+ *
+ * Plain-params (not CLI `flags`) so both `runPut` and the local stdio MCP
+ * `put` tool — same staging default, issue #403's scope — can call this
+ * without either depending on the other's argument shape.
+ */
+export declare function resolvePutStagingTarget(opts: {
+    ghTarget: GhTarget | undefined;
+    keyHint: string | undefined;
+    refArg: string | undefined;
+    prefixArg: string | undefined;
+    /** Explicit `--destination` (CLI) / `destination` (MCP) also opts out — it
+     * resolves to its own prefix via `resolvePutPrefix`, which staging would
+     * otherwise silently override. */
+    destinationArg: string | undefined;
+    noGit: boolean;
+    repoArg: string | undefined;
+    run: CommandRunner;
+}): BranchTarget | undefined;
+/**
+ * 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
+ * to the branch prefix instead of landing on the dated layout. Used verbatim
+ * for both the human-mode stderr line and the JSON `hint` field.
+ */
+export declare function putStagingNoteText(branch: string): string;
+/** One file currently staged for a branch (issue #405). */
+export interface StagedFile {
+    /** Full object key (`gh/<owner>/<repo>/branch/<branch>/<filename>`). */
+    key: string;
+    /** `key` with the staging prefix stripped. */
+    filename: string;
+    size?: number;
+    /** `gh.staged-at` metadata (ISO 8601 UTC), when present. */
+    stagedAt?: string;
+    url: string | null;
+}
+/** Tri-state binding, folded into a ready-to-render advisory (issue #405/#398). */
+export interface StagedBinding {
+    state: "self" | "other" | "none" | "unknown";
+    /** True only for "self" — the only state where staged files actually auto-attach. */
+    autoAttach: boolean;
+    message: string;
+}
+export interface StagedResult {
+    repo: string;
+    branch: string;
+    files: StagedFile[];
+    binding: StagedBinding;
+}
+/**
+ * Shared core for `uploads staged` (CLI) and the `staged` MCP tool (issue
+ * #405): one `list` call against the branch staging prefix
+ * (`ghBranchKeyPrefix` — never hand-built) plus the #398 binding check. Never
+ * throws on the binding check (see `resolveStagedBinding`); a failed `list`
+ * call still propagates, same as every other read command.
+ */
+export declare function resolveStaged(opts: {
+    client: UploadsClient;
+    repo: string;
+    branch: string;
+}): Promise<StagedResult>;
+export declare function runStaged(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runPut(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runGallery(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runList(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;

package/dist/commands.js

@@ -11,7 +11,7 @@ import { writeJson, writeStdout } from "./io.js";
 import { imageFactsFromBytes } from "./image-facts.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./metadata-vocab.js";
-import { ghAttachmentKey, ghBranchAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, normalizeGithubCoordinate, } from "./github.js";
+import { ghAttachmentKey, ghBranchAttachmentKey, ghBranchKeyPrefix, ghKeyPrefix, ghMetadataFromTarget, 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";
@@ -373,7 +373,11 @@ export async function uploadPreparedImage(client, bytes, sourceName, opts) {
         frameFit: opts.frame.frameFit,
         optimize: opts.optimize,
     });
-    let key = opts.ghTarget ? ghAttachmentKey(opts.ghTarget, prepared.filename) : opts.key;
+    let key = opts.ghTarget
+        ? ghAttachmentKey(opts.ghTarget, prepared.filename)
+        : opts.ghBranchTarget
+            ? ghBranchAttachmentKey(opts.ghBranchTarget.repo, opts.ghBranchTarget.branch, prepared.filename)
+            : opts.key;
     if (key && prepared.optimized)
         key = rewriteKeyExtension(key, prepared.filename);
     const result = await client.put(prepared.bytes, {
@@ -743,6 +747,7 @@ export async function uploadPuts(opts) {
                 frame: opts.frame,
                 optimize: opts.optimize,
                 ghTarget: opts.ghTarget,
+                ghBranchTarget: opts.ghBranchTarget,
                 key: opts.explicitKey,
                 prefix: opts.prefix,
                 repo: opts.repo,
@@ -1009,8 +1014,17 @@ async function runAttachBranch(ctx, parsed, branch, run) {
     if (uploads.length === 0 && failures.length === 1 && parsed.positionals.length === 1) {
         throw firstError instanceof Error ? firstError : new Error(String(firstError));
     }
+    // Stage-time binding warning (issue #398): only worth checking once staging
+    // actually produced something to warn about. Best-effort — see
+    // resolveStageBindingWarning; never affects exit code or the upload itself.
+    const bindingWarning = uploads.length > 0 ? await resolveStageBindingWarning({ ctx, defaults, repo }) : undefined;
     if (ctx.json) {
-        await writeJson({ target, uploads, failures });
+        await writeJson({
+            target,
+            uploads,
+            failures,
+            ...(bindingWarning ? { hint: bindingWarning } : {}),
+        });
     }
     else {
         for (const result of uploads) {
@@ -1034,9 +1048,58 @@ async function runAttachBranch(ctx, parsed, branch, run) {
             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`);
     }
     return failures.length === 0 ? 0 : 1;
 }
+/**
+ * One source of truth for the "staged, but not going to auto-attach" advisory
+ * text (issue #398), shared by the `attach --branch`/bare-`put` stage-time
+ * warning below and the `uploads staged` view (issue #405) — both surfaces
+ * must say the exact same thing for the same binding state, verified by
+ * tests on both call sites. Returns undefined for `"self"` (the happy path —
+ * callers each phrase that themselves) and any unrecognized value.
+ */
+export function stagingBindingAdvisory(binding, repo) {
+    switch (binding) {
+        case "none":
+            return (`staged, but ${repo} isn't linked to your workspace yet — staged files only ` +
+                `auto-attach on PR open for linked repos. Link it once with: uploads attach <file> ` +
+                `(on any PR) or uploads github link. After the PR opens: uploads attach --promote`);
+        case "other":
+            return (`staged, but ${repo} is linked to a different workspace — these files won't ` +
+                `auto-attach from here.`);
+        default:
+            return undefined; // "self", or any unrecognized value
+    }
+}
+/**
+ * Best-effort stage-time binding warning (issue #398): after `attach
+ * --branch` stages files, checks whether `repo` is bound to THIS workspace —
+ * webhook auto-promotion at PR open only fires for a repo already bound
+ * (#297), and staging alone never binds one. Fires only for `binding: "none"`
+ * (unbound) or `"other"` (bound elsewhere); `"self"` and any failure
+ * (network, non-200, older server without the route, `binding: "unknown"`)
+ * are silent — this is advisory only and must never make staging look like
+ * it failed. Same suppression as the #393 put nudge: `--quiet`,
+ * `UPLOADS_NO_NUDGE=1` (env or config).
+ */
+export async function resolveStageBindingWarning(opts) {
+    const { ctx, defaults, repo } = opts;
+    if (ctx.quiet)
+        return undefined;
+    if (defaults.noNudge)
+        return undefined;
+    try {
+        const { binding } = await ctx.client.githubRepoLinkStatus(repo);
+        const advisory = stagingBindingAdvisory(binding, repo);
+        return advisory ? `note: ${advisory}` : undefined;
+    }
+    catch {
+        return undefined; // any failure (network, non-200, older server) — stay silent
+    }
+}
 /**
  * `attach --promote` with zero file arguments: resolve the PR target (same
  * resolution as the default `runAttach` path), promote this workspace's
@@ -1156,6 +1219,191 @@ function resolvePutNudge(opts) {
         return 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
+ * organizing unit instead of the date, superseding the #393 CLI nudge for
+ * this case (see `putStagingNoteText`). Reuses the same detection stack as
+ * `resolvePutNudge` (`deriveRepoFromGit` / `resolveCurrentBranch` /
+ * `resolveDefaultBranch` / main-master fallback) plus a `resolveRepo` lookup
+ * (needed for the "owner/name" staging key) and an explicit-flag opt-out:
+ * `ghTarget`/`keyHint`/`refArg`/`prefixArg`/`destinationArg` set, or `noGit`,
+ * forces the classic dated (or typed-destination) layout. Never throws — any
+ * failure (not a repo, detached HEAD, gh missing/unauthenticated/timed out,
+ * unresolvable repo) degrades to "no staging", leaving the caller to fall
+ * back to the dated path.
+ *
+ * Plain-params (not CLI `flags`) so both `runPut` and the local stdio MCP
+ * `put` tool — same staging default, issue #403's scope — can call this
+ * without either depending on the other's argument shape.
+ */
+export function resolvePutStagingTarget(opts) {
+    const { ghTarget, keyHint, refArg, prefixArg, destinationArg, noGit, repoArg, run } = opts;
+    if (ghTarget || keyHint || noGit)
+        return undefined;
+    if (refArg || prefixArg || destinationArg)
+        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 dated layout
+        if (onDefaultBranch)
+            return undefined;
+        // Same bounded-timeout treatment as the #393 nudge's `gh pr view` call —
+        // this is best-effort, and must never be felt as a hang.
+        const timed = run === execRunner ? timedExecRunner(PUT_NUDGE_GH_TIMEOUT_MS) : run;
+        const repo = resolveRepo(repoArg, timed);
+        return { repo, branch };
+    }
+    catch {
+        return undefined; // gh/git unavailable, or repo unresolvable — dated layout
+    }
+}
+/**
+ * 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
+ * to the branch prefix instead of landing on the dated layout. Used verbatim
+ * for both the human-mode stderr line and the JSON `hint` field.
+ */
+export function putStagingNoteText(branch) {
+    return (`note: staged for branch ${branch} — auto-attaches to this branch's PR when it opens ` +
+        `(or run: uploads attach --promote once it exists). Use --ref/--prefix for a plain dated upload.`);
+}
+/**
+ * Binding lookup for `uploads staged`, folded into a renderable `StagedBinding`.
+ * `"none"`/`"other"` reuse `stagingBindingAdvisory` — the exact #398 wording,
+ * one source of truth. `"self"` gets its own message (the #398 warning stays
+ * silent on "self"; this view is the one place that names the happy path
+ * explicitly). Any failure (network, non-200, older server without the
+ * route) degrades to `"unknown"` rather than throwing — this is a read-only
+ * view and a binding check failing must never make it fail outright.
+ */
+async function resolveStagedBinding(client, repo) {
+    try {
+        const { binding } = await client.githubRepoLinkStatus(repo);
+        switch (binding) {
+            case "self":
+                return {
+                    state: "self",
+                    autoAttach: true,
+                    message: "these auto-attach when this branch's PR opens",
+                };
+            case "none":
+            case "other":
+                return {
+                    state: binding,
+                    autoAttach: false,
+                    // stagingBindingAdvisory is total for "none"/"other" — never undefined here.
+                    message: stagingBindingAdvisory(binding, repo),
+                };
+            default:
+                return { state: "unknown", autoAttach: false, message: "binding status unrecognized" };
+        }
+    }
+    catch {
+        return {
+            state: "unknown",
+            autoAttach: false,
+            message: "could not check binding status (offline, or an older server without this route)",
+        };
+    }
+}
+/**
+ * Shared core for `uploads staged` (CLI) and the `staged` MCP tool (issue
+ * #405): one `list` call against the branch staging prefix
+ * (`ghBranchKeyPrefix` — never hand-built) plus the #398 binding check. Never
+ * throws on the binding check (see `resolveStagedBinding`); a failed `list`
+ * call still propagates, same as every other read command.
+ */
+export async function resolveStaged(opts) {
+    const { client, repo, branch } = opts;
+    const prefix = ghBranchKeyPrefix(repo, branch);
+    const [list, binding] = await Promise.all([
+        client.list({ prefix, metadata: true }),
+        resolveStagedBinding(client, repo),
+    ]);
+    const files = list.items.map((item) => ({
+        key: item.key,
+        filename: item.key.slice(prefix.length),
+        size: item.size,
+        stagedAt: item.metadata?.["gh.staged-at"],
+        url: item.url,
+    }));
+    return { repo, branch, files, binding };
+}
+const STAGED_HELP = `uploads staged [--branch <name>] [--repo <owner/name>] [--format json] [--workspace <name>]
+
+Read-only view of what's staged for a branch (\`attach --branch\` / bare
+\`put\` on a non-default branch, issue #403) and whether it will auto-attach
+once a PR opens. One \`list\` call against the branch staging prefix
+(gh/<owner>/<repo>/branch/<branch>/) plus a binding check — files:read only,
+no new server surface.
+
+Defaults: current git branch (same resolution as \`attach --branch\`, worktree-
+safe), repo from --repo / gh / git remote (same as every other command).
+
+Binding: self means these files auto-attach when this branch's PR opens; none
+or other means they won't (repo unlinked, or linked to a different
+workspace) — same advisory as the attach --branch stage-time warning.
+
+Examples:
+  uploads staged
+  uploads staged --branch feature/thing --repo owner/name
+  uploads staged --format json
+`;
+export async function runStaged(ctx, args, help = false, run = execRunner) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        writeCommandHelp(STAGED_HELP);
+        return 0;
+    }
+    const format = ctx.json
+        ? "json"
+        : (() => {
+            const raw = flagString(parsed.flags, "--format");
+            if (!raw || raw === "human")
+                return "human";
+            if (raw === "json")
+                return "json";
+            throw new UsageError(`invalid --format: ${raw} (expected: json)`);
+        })();
+    const repo = resolveRepo(flagString(parsed.flags, "--repo"), run);
+    const branch = flagString(parsed.flags, "--branch") ?? resolveCurrentBranch(run);
+    const result = await resolveStaged({ client: ctx.client, repo, branch });
+    if (format === "json") {
+        // Always a valid JSON document, even with zero files — never empty
+        // stdout (issue #405 explicitly calls out find --format json's empty-
+        // stdout-on-no-matches wart as a wrong pattern to avoid here).
+        await writeJson(result);
+        return 0;
+    }
+    if (result.files.length === 0) {
+        await writeStdout(`nothing staged for ${branch} in ${repo}\n`);
+        return 0;
+    }
+    for (const file of result.files) {
+        const size = file.size !== undefined ? formatByteSize(file.size) : "? B";
+        const staged = file.stagedAt ? `  staged ${file.stagedAt}` : "";
+        await writeStdout(`${file.filename}  ${size}${staged}  ${file.url ?? "(no url)"}\n`);
+    }
+    process.stderr.write(`binding: ${result.binding.state} — ${result.binding.message}\n`);
+    // Promote is pointless advice when the repo belongs to another workspace —
+    // the cross-tenant gate (#297) would reject it from here.
+    if (result.binding.state !== "other") {
+        process.stderr.write(`once the PR exists: uploads attach --promote\n`);
+    }
+    return 0;
+}
 export async function runPut(ctx, args, help = false, run = execRunner) {
     if (help) {
         writeCommandHelp(PUT_HELP);
@@ -1274,7 +1522,25 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             })()
             : defaults.width;
     const noGit = flagBool(parsed.flags, "--no-git") || defaults.noGit === true;
-    // gh.* metadata: explicit --pr/--issue target wins over --meta; otherwise
+    // 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.
+    const stagingTarget = resolvePutStagingTarget({
+        ghTarget,
+        keyHint,
+        refArg: flagString(parsed.flags, "--ref"),
+        prefixArg: prefixFlag,
+        destinationArg: destFlag,
+        noGit,
+        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).
@@ -1286,6 +1552,14 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         metadata = merged;
         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;
+    }
     else {
         // gh.* additionally needs git, which the shared derived gate ignores.
         if (!noGit && derivedMetaEnabled(parsed.flags, defaults)) {
@@ -1306,18 +1580,31 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             }
         }
     }
-    // Bare-put nudge (issue #393): 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 = resolvePutNudge({
-        ctx,
-        flags: parsed.flags,
-        ghTarget,
-        keyHint,
-        noGit,
-        defaults,
-        run,
-    });
+    // 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
+        ? undefined
+        : resolvePutNudge({
+            ctx,
+            flags: parsed.flags,
+            ghTarget,
+            keyHint,
+            noGit,
+            defaults,
+            run,
+        });
+    // Staging note (issue #403): same suppression as the #393 nudge
+    // (--quiet, UPLOADS_NO_NUDGE=1 env/config); staging itself is NOT gated by
+    // either — only whether the note is printed/hinted.
+    const stagingNote = stagingTarget && !ctx.quiet && !defaults.noNudge
+        ? putStagingNoteText(stagingTarget.branch)
+        : undefined;
     const logHuman = !ctx.quiet && format === "human";
     if (logHuman) {
         if (multi) {
@@ -1336,6 +1623,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         nameOverride: nameFlag,
         explicitKey: keyHint,
         ghTarget,
+        ghBranchTarget: stagingTarget,
         prefix: resolvedPrefix ?? defaults.prefix,
         repo: flagString(parsed.flags, "--repo") ?? defaults.repo,
         ref: flagString(parsed.flags, "--ref") ?? defaults.ref,
@@ -1354,6 +1642,19 @@ 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));
     }
+    // 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.
+    const bindingWarning = stagingTarget && uploads.length > 0
+        ? await resolveStageBindingWarning({ ctx, defaults, repo: stagingTarget.repo })
+        : 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;
     const galleriesByKey = new Map();
     let galleryHadError = false;
     if (galleryId && uploads.length > 0) {
@@ -1399,7 +1700,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 failures,
                 comment,
                 commentError,
-                ...(nudge ? { hint: nudge } : {}),
+                ...(jsonHint ? { hint: jsonHint } : {}),
             });
         }
         else {
@@ -1432,6 +1733,10 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             }
             if (nudge)
                 process.stderr.write(`${nudge}\n`);
+            if (stagingNote)
+                process.stderr.write(`${stagingNote}\n`);
+            if (bindingWarning)
+                process.stderr.write(`${bindingWarning}\n`);
         }
         return failures.length === 0 && !galleryHadError ? 0 : 1;
     }
@@ -1463,7 +1768,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 frame: result.frame,
                 gallery,
                 ...(dryRun ? { dryRun: true } : {}),
-                ...(nudge ? { hint: nudge } : {}),
+                ...(jsonHint ? { hint: jsonHint } : {}),
             });
             break;
         case "url":
@@ -1485,6 +1790,10 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     }
     if (nudge && format !== "json")
         process.stderr.write(`${nudge}\n`);
+    if (stagingNote && format !== "json")
+        process.stderr.write(`${stagingNote}\n`);
+    if (bindingWarning && format !== "json")
+        process.stderr.write(`${bindingWarning}\n`);
     return gallery?.error ? 1 : 0;
 }
 // --- galleries ---

package/dist/github.d.ts

@@ -123,6 +123,10 @@ export declare const ATTACHMENT_IMAGE_WIDTH_WIDE = 640;
  * practical signal (we don't re-fetch dimensions when rebuilding the comment).
  */
 export declare function attachmentImageWidth(filename: string): number;
+/** Max display width for one image inside a before/after pair row — smaller
+ * than a standalone image so two side by side stay under GitHub's comment
+ * column width (and don't overflow on mobile). */
+export declare const ATTACHMENT_IMAGE_WIDTH_PAIR = 320;
 /**
  * Render the one marker-owned GitHub comment. When there are no galleries this
  * intentionally preserves the legacy attachment-only body byte-for-byte.

package/dist/github.js

@@ -255,6 +255,120 @@ function metaCaptionMarkdown(meta) {
         return "";
     return ` · ${parts.map((p) => escapeMarkdownText(escapeHtmlText(p))).join(" · ")}`;
 }
+/** Extract the filename stem's before/after token (issue #419 fallback pairing).
+ * `base` is the stem lowercased with the token removed; `null` when the stem
+ * carries no recognizable before/after token. Requires a separator (`-`, `_`,
+ * or `.`) between the token and the rest of the name — except when the token
+ * IS the whole stem (`before.png`) — so `beforehand.png` doesn't false-match. */
+// Token bounded by `-`, `_`, `.`, or stem start/end, so `hero-before.webp`
+// and `paired-view-before-desktop.webp` match but `beforehand.webp` does
+// not. Mirrors before-after.ts's TOKEN_RE (file page), applied to the stem.
+const STEM_TOKEN_RE = /(^|[-_.])(before|after)($|[-_.])/i;
+function filenameStemToken(name) {
+    const dot = name.lastIndexOf(".");
+    const stem = dot > 0 ? name.slice(0, dot) : name;
+    const m = STEM_TOKEN_RE.exec(stem);
+    if (!m)
+        return null;
+    const state = m[2].toLowerCase();
+    const tokenStart = m.index + m[1].length;
+    const tokenEnd = tokenStart + m[2].length;
+    // Base = stem with the token and one adjoining delimiter removed, so
+    // `paired-view-before-desktop` and `paired-view-after-desktop` both
+    // collapse to `paired-view-desktop` and group together.
+    const base = m[1].length > 0
+        ? stem.slice(0, m.index) + stem.slice(tokenEnd)
+        : stem.slice(tokenEnd + m[3].length);
+    return { base: base.toLowerCase(), state };
+}
+/**
+ * Pair up attachments for the before/after side-by-side row (issue #419).
+ * `isImageAt[i]` mirrors the renderer's own image test — only images pair;
+ * videos and non-image links render exactly as before.
+ *
+ * Priority order, checked independently per candidate item so rule 2 only
+ * ever claims items rule 1 left untouched:
+ *  1. Same `path` metadata (trimmed, not bare `/`), one item `state=before`
+ *     and one `state=after`. Ambiguous groups (more than one of a state)
+ *     don't pair — no way to know which side goes with which.
+ *  2. No usable `path` metadata: filename stems that differ only by a
+ *     before/after token, same extension. Same ambiguity rule.
+ */
+function pairAttachments(items, isImageAt) {
+    const partnerOf = new Map();
+    const roleOf = new Map();
+    const pair = (beforeIdx, afterIdx) => {
+        partnerOf.set(beforeIdx, afterIdx);
+        partnerOf.set(afterIdx, beforeIdx);
+        roleOf.set(beforeIdx, "before");
+        roleOf.set(afterIdx, "after");
+    };
+    // Priority 1: same path metadata, exactly one before + one after.
+    const pathGroups = new Map();
+    items.forEach((item, i) => {
+        if (!isImageAt[i])
+            return;
+        const path = item.meta?.path?.trim();
+        if (!path || path === "/")
+            return;
+        const state = item.meta?.state?.trim().toLowerCase();
+        if (state !== "before" && state !== "after")
+            return;
+        const g = pathGroups.get(path) ?? { before: [], after: [] };
+        g[state].push(i);
+        pathGroups.set(path, g);
+    });
+    for (const g of pathGroups.values()) {
+        if (g.before.length === 1 && g.after.length === 1)
+            pair(g.before[0], g.after[0]);
+    }
+    // Priority 2: no usable path metadata — filename stem token, same extension.
+    const stemGroups = new Map();
+    items.forEach((item, i) => {
+        if (!isImageAt[i] || partnerOf.has(i))
+            return;
+        const path = item.meta?.path?.trim();
+        if (path && path !== "/")
+            return; // usable path metadata — rule 1 owns this item
+        const name = item.key.slice(item.key.lastIndexOf("/") + 1);
+        const tok = filenameStemToken(name);
+        if (!tok)
+            return;
+        const dot = name.lastIndexOf(".");
+        const ext = dot > 0 ? name.slice(dot).toLowerCase() : "";
+        const key = `${tok.base}${ext}`;
+        const g = stemGroups.get(key) ?? { before: [], after: [] };
+        g[tok.state].push(i);
+        stemGroups.set(key, g);
+    });
+    for (const g of stemGroups.values()) {
+        if (g.before.length === 1 && g.after.length === 1)
+            pair(g.before[0], g.after[0]);
+    }
+    return { partnerOf, roleOf };
+}
+/** Max display width for one image inside a before/after pair row — smaller
+ * than a standalone image so two side by side stay under GitHub's comment
+ * column width (and don't overflow on mobile). */
+export const ATTACHMENT_IMAGE_WIDTH_PAIR = 320;
+function renderPairCell(item, label) {
+    const name = item.key.slice(item.key.lastIndexOf("/") + 1);
+    const src = item.embedUrl ?? item.url;
+    const link = item.pageUrl ?? item.url;
+    const w = Math.min(attachmentImageWidth(name), ATTACHMENT_IMAGE_WIDTH_PAIR);
+    const alt = escapeHtmlAttr(name);
+    const href = escapeHtmlAttr((link ?? src));
+    const imgSrc = escapeHtmlAttr(src);
+    const caption = metaCaptionHtml(item.meta);
+    const captionHtml = caption ? `<br><sub>${caption}</sub>` : "";
+    return `<td align="center"><sub><strong>${label}</strong></sub><br><a href="${href}"><img width="${w}" alt="${alt}" src="${imgSrc}"></a>${captionHtml}</td>`;
+}
+/** One side-by-side before/after row (issue #419): a single HTML table so
+ * GitHub renders both images on one line, with `Before`/`After` labels and
+ * each side's usual path/state caption preserved underneath. */
+function renderPairRow(beforeItem, afterItem) {
+    return `<table><tr>${renderPairCell(beforeItem, "Before")}${renderPairCell(afterItem, "After")}</tr></table>`;
+}
 /**
  * Render the one marker-owned GitHub comment. When there are no galleries this
  * intentionally preserves the legacy attachment-only body byte-for-byte.
@@ -279,9 +393,36 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
     }
     if (sorted.length > 0 || sortedGalleries.length === 0)
         lines.push("### 📎 Attachments", "");
+    const isImageAt = sorted.map((item) => {
+        const name = item.key.slice(item.key.lastIndexOf("/") + 1);
+        const src = item.embedUrl ?? item.url;
+        return Boolean(src) && inferContentType(name).startsWith("image/");
+    });
+    const { partnerOf, roleOf } = pairAttachments(sorted, isImageAt);
+    const consumedByPair = new Set();
     let inlinedImages = 0;
     const overflowImages = [];
-    for (const item of sorted) {
+    for (let idx = 0; idx < sorted.length; idx++) {
+        if (consumedByPair.has(idx))
+            continue;
+        const item = sorted[idx];
+        const partnerIdx = partnerOf.get(idx);
+        if (partnerIdx !== undefined) {
+            const partner = sorted[partnerIdx];
+            if (inlinedImages + 2 <= MAX_INLINE_ATTACHMENT_IMAGES) {
+                inlinedImages += 2;
+                consumedByPair.add(partnerIdx);
+                const beforeItem = roleOf.get(idx) === "before" ? item : partner;
+                const afterItem = roleOf.get(idx) === "before" ? partner : item;
+                lines.push(renderPairRow(beforeItem, afterItem), "");
+                continue;
+            }
+            // Cap already full for a two-image row — degrade this pair to two
+            // ordinary overflow entries rather than only half-rendering the row.
+            overflowImages.push(item, partner);
+            consumedByPair.add(partnerIdx);
+            continue;
+        }
         const name = item.key.slice(item.key.lastIndexOf("/") + 1);
         const stable = item.url;
         const src = item.embedUrl ?? item.url;

package/dist/mcp/tools.js

@@ -1,13 +1,13 @@
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, makeGhTarget, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
+import { buildDoctorReport, makeGhTarget, 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 } from "../github.js";
+import { ghKeyPrefix, ghMetadataForBranch } from "../github.js";
 import { safeCaptureFacts } from "../capture-facts.js";
 import { validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
-import { execRunner, ghMetadataFromTargetWithTitle, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
+import { execRunner, ghMetadataFromTargetWithTitle, resolveCurrentBranch, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
 import { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCanonical, metadataProp, optBool, optPosInt, optString, optStringArray, optStringRecord, stateProp, usage, } from "./args.js";
 import { batchFailureMessage, ToolBatchError } from "./server.js";
 import { attachmentFromText, buildReportPayload, parseReportType, REPORT_TYPES, submitReport, validateReportMessage, } from "../report.js";
@@ -415,9 +415,35 @@ export function createUploadsMcpTools(opts) {
                 const alt = optString(args, "alt");
                 const width = optPosInt(args, "width") ?? defaults.width;
                 const contentType = optString(args, "contentType");
+                // Bare-put branch staging (issue #403): local stdio MCP put mirrors
+                // the CLI default — 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 layout. Never throws — see resolvePutStagingTarget.
+                const stagingTarget = resolvePutStagingTarget({
+                    ghTarget: target,
+                    keyHint: keyArg,
+                    refArg,
+                    prefixArg,
+                    destinationArg: destArg,
+                    noGit,
+                    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 putShared = {
                     client,
                     ghTarget: target,
+                    ghBranchTarget: stagingTarget,
                     prefix: resolvedPrefix ?? defaults.prefix,
                     repo: optString(args, "repo") ?? defaults.repo,
                     ref: refArg ?? defaults.ref,
@@ -427,7 +453,7 @@ export function createUploadsMcpTools(opts) {
                     replace: replaceArg,
                     optimize: optimizeOpts,
                     frame: frameOpts,
-                    metadata,
+                    metadata: putMetadata,
                     // The shared metadata description promises uploads.sh derives these
                     // "automatically where it can" — MCP has no --no-auto, so always on.
                     deriveImageFacts: true,
@@ -458,6 +484,7 @@ export function createUploadsMcpTools(opts) {
                         frame: frameOpts,
                         optimize: optimizeOpts,
                         ghTarget: target,
+                        ghBranchTarget: stagingTarget,
                         key: keyArg,
                         prefix: resolvedPrefix ?? defaults.prefix,
                         repo: optString(args, "repo") ?? defaults.repo,
@@ -466,7 +493,7 @@ export function createUploadsMcpTools(opts) {
                         deriveRepoFromGit: !noGit,
                         dryRun,
                         replace: replaceArg,
-                        metadata,
+                        metadata: putMetadata,
                         provenanceClient: "uploads-mcp",
                         alt: () => alt ?? sourceName,
                         width,
@@ -925,6 +952,31 @@ export function createUploadsMcpTools(opts) {
                 return client.list({ prefix, limit, cursor });
             },
         },
+        {
+            name: "staged",
+            description: "Read-only view of what's staged for a git branch (attach --branch / bare put on a non-default branch) and whether it will auto-attach once a PR opens. One list call against the branch staging prefix plus a repo-binding check (files:read only). Returns { repo, branch, files, binding }; binding.state is self/other/none/unknown and binding.autoAttach is true only for self.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    branch: {
+                        type: "string",
+                        description: "Branch name (default: current git branch, worktree-safe).",
+                    },
+                    repo: {
+                        type: "string",
+                        description: "owner/name repo (default: gh/git remote inference).",
+                    },
+                    workspace: workspaceProp,
+                },
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const { client } = clientFor(args);
+                const repo = resolveRepo(optString(args, "repo"), run);
+                const branch = optString(args, "branch") ?? resolveCurrentBranch(run);
+                return resolveStaged({ client, repo, branch });
+            },
+        },
         {
             name: "delete",
             description: "Delete an uploaded object by key. Set dryRun to preview without deleting.",

package/package.json

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