@buildinternet/uploads 0.14.0 → 0.16.0

package/dist/commands.js

@@ -1,5 +1,5 @@
-import { readFileSync } from "node:fs";
-import { basename } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, extname } from "node:path";
 import { mapBounded } from "./async.js";
 import { createUploadsClient, } from "./client.js";
 import { parseCommandArgs, flagString, flagBool, flagInt, flagValues, UsageError, } from "./cli-args.js";
@@ -9,8 +9,8 @@ import { urlForGithubEmbed } from "./public-urls.js";
 import { UploadsError } from "./errors.js";
 import { writeJson, writeStdout } from "./io.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
-import { ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, attachmentsCommentBody, normalizeGithubCoordinate, } from "./github.js";
-import { resolveRepo, resolveCurrentPullRequest, classifyGhNumber, execRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
+import { ghAttachmentKey, ghBranchAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, normalizeGithubCoordinate, } from "./github.js";
+import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, classifyGhNumber, execRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
 import { resolvePutPrefix } from "./destinations.js";
 import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
 import { applyFrame, resolveFrameId } from "./frame.js";
@@ -130,6 +130,72 @@ export function makeGhTarget(pr, issue, repoArg, run) {
 export function ghTargetFromFlags(flags, run) {
     return makeGhTarget(flagInt(flags, "--pr", "--pr"), flagInt(flags, "--issue", "--issue"), flagString(flags, "--repo"), run);
 }
+/**
+ * Extensions that mark a `--branch` value as almost certainly a filename that
+ * got swallowed by the optional-value lookahead (e.g. `--branch shot.png`
+ * with no other file args). Branch names legitimately contain dots (e.g.
+ * `release/1.2`, `v1.2.3`), so this only matches known media/document
+ * extensions, never bare dotted segments.
+ */
+const BRANCH_LIKE_FILE_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".bmp",
+    ".svg",
+    ".ico",
+    ".tif",
+    ".tiff",
+    ".heic",
+    ".avif",
+    ".mp4",
+    ".mov",
+    ".avi",
+    ".webm",
+    ".mkv",
+    ".pdf",
+]);
+/**
+ * True when `value` looks like a filename that was mistakenly consumed as the
+ * `--branch` value: it names a file that exists on disk, or its extension is
+ * a known media/document type. Ordinary branch names (including dotted ones
+ * like `v1.2` or `release/1.2`) never match either check.
+ */
+function looksLikeFileNotBranch(value) {
+    if (existsSync(value))
+        return true;
+    return BRANCH_LIKE_FILE_EXTENSIONS.has(extname(value).toLowerCase());
+}
+/**
+ * Reads `--branch [name]` — an optional-value flag: `--branch` alone resolves
+ * the current git branch (`resolveCurrentBranch`); `--branch feature/x` uses
+ * the given name verbatim. Returns undefined when the flag is absent at all
+ * (distinct from an empty/whitespace value, which is rejected). Throws
+ * UsageError if `--branch` is given more than once, or if the value looks
+ * like a filename accidentally swallowed by the optional-value lookahead
+ * (e.g. `uploads attach --branch shot.png` with no other file args) — see
+ * `looksLikeFileNotBranch`.
+ */
+export function branchFromFlags(flags, run) {
+    if (!flags.has("--branch"))
+        return undefined;
+    const raw = flags.get("--branch");
+    if (Array.isArray(raw))
+        throw new UsageError("--branch may only be given once");
+    if (raw === true)
+        return resolveCurrentBranch(run);
+    if (typeof raw === "string" && raw.trim().length > 0) {
+        if (looksLikeFileNotBranch(raw)) {
+            throw new UsageError(`"${raw}" looks like a file, not a branch name — did you mean ` +
+                `"uploads attach ${raw} --branch" (auto-detect the current branch), ` +
+                `or "uploads attach --branch <name> ${raw}" (explicit branch name)?`);
+        }
+        return raw;
+    }
+    throw new UsageError("--branch requires a non-empty branch name");
+}
 /**
  * Best-effort GitHub target for the default put path (no --pr/--issue). A
  * numeric --ref is classified as pull vs issue; otherwise the current branch's
@@ -278,22 +344,53 @@ export function frameOptionsFromFlags(flags) {
 export function commentViaSuffix(via) {
     return via === "bot" ? " (uploads-sh[bot])" : " (via gh)";
 }
-export async function syncAttachmentsComment(client, target, run) {
+/**
+ * Thrown by `syncAttachmentsComment` when the server declines with
+ * `not_authorized` (issue #297 baseline control) — this repo is bound to a
+ * different workspace, or unbound and unclaimable by the communal `default`
+ * workspace. Deliberately not caught by the generic "bot endpoint
+ * unreachable" fallback below: falling back to gh here would let the
+ * human's own credentials post anyway, defeating the point of the
+ * server-side gate.
+ */
+export class GithubCommentAuthorizationError extends Error {
+}
+export async function syncAttachmentsComment(client, target, run, workspace) {
+    let bot;
     try {
-        const bot = await client.upsertGithubComment({
+        bot = await client.upsertGithubComment({
             repo: target.repo,
             num: target.num,
             kind: target.kind,
         });
-        if (bot.posted)
-            return { action: bot.action, count: bot.count, via: "bot" };
     }
     catch {
         // Endpoint absent/unreachable (self-hosted, network, older worker) — fall
         // through to the gh path below.
+        bot = undefined;
+    }
+    if (bot) {
+        if (bot.posted)
+            return { action: bot.action, count: bot.count, via: "bot" };
+        if (bot.reason === "not_authorized") {
+            throw new GithubCommentAuthorizationError(`${bot.message ?? `${target.repo} is not authorized for this workspace.`}\n` +
+                `Run \`uploads github link --status --repo ${target.repo}\` to see who owns the ` +
+                `binding, use that workspace instead, or post the comment manually with gh.`);
+        }
+        // Installed-but-unapproved is a fixable misconfiguration, not a silent
+        // degrade: tell the user (and how to fix it) before falling back to gh.
+        if (bot.reason === "forbidden" && bot.message) {
+            process.stderr.write(`note: ${bot.message}${bot.fixUrl ? `\n  ${bot.fixUrl}` : ""}\n` +
+                `Posting via local gh in the meantime.\n`);
+        }
     }
     // gh fallback: gather from this workspace's own data and post via local `gh`.
-    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url, embedUrl }) => ({ key, url, embedUrl }));
+    // Note (issue #304): this CLI process has no server-side WorkspaceRecord in
+    // scope, so it cannot honor a workspace's githubCommentLinkToFilePage=false
+    // — it always links to the file page here, matching the default. This only
+    // diverges from the bot-posted comment for a workspace that both sets the
+    // flag false and falls through to this gh-fallback path.
+    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url, embedUrl, pageUrl }) => ({ key, url, embedUrl, pageUrl }));
     const galleries = [];
     let cursor;
     do {
@@ -329,8 +426,9 @@ export async function syncAttachmentsComment(client, target, run) {
     }));
     if (items.length === 0 && previewGalleries.length === 0)
         return { action: "skipped", count: 0, via: "gh" };
-    const body = attachmentsCommentBody(items, previewGalleries);
-    const { created } = upsertAttachmentsComment(target, body, run);
+    const marker = attachmentsMarker(workspace);
+    const body = attachmentsCommentBody(items, previewGalleries, marker);
+    const { created } = upsertAttachmentsComment(target, body, run, marker);
     return {
         action: created ? "created" : "updated",
         count: items.length + previewGalleries.length,
@@ -357,9 +455,37 @@ URL and every embed hot-swap. Human mode prints ">> replaced existing object
 Still images are optimized to WebP by default (same as put). Use --no-optimize
 to upload originals. Optional --frame wraps images in device/browser chrome.
 
+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>
+("/" in the branch name sanitizes to "-", e.g. feature/x -> feature-x).
+With no value, --branch resolves the current git branch. Staged files are
+public like every other attachment — same public-URL caveat applies. There is
+no managed comment for a branch (no PR/issue to comment on yet); --branch
+never runs the comment sync and cannot combine with --pr/--issue/--comment.
+
+Promotion: once a PR exists, staged files for the current branch are picked
+up automatically the first time you attach to that PR (a plain "uploads
+attach <file> --pr <num>", or the inferred-PR default with no target flags) —
+they're copied into the PR's attachment prefix before the managed comment is
+built, so they show up in the same run. Pass --no-promote to skip that. If
+you'd rather promote without attaching a new file (e.g. right after
+"gh pr create" with nothing new to upload), run "uploads attach --promote"
+with no file arguments — it resolves the PR the same way, promotes, and
+refreshes the comment; it exits 0 even if nothing was staged. --promote only
+takes effect with zero files and cannot combine with --branch/--issue/
+--no-promote. Promotion never applies to issues. Staged files stay findable
+with "uploads find gh.branch=<branch>" either way.
+
 Options:
   --pr <num>            Attach to this pull request
   --issue <num>         Attach to this issue
+  --branch [name]       Stage against a branch, pre-PR (default: current git branch);
+                        not with --pr/--issue/--comment
+  --promote             No files: promote branch-staged attachments into the
+                        resolved PR and refresh the comment; not with
+                        --branch/--issue/--no-promote
+  --no-promote          Skip auto-promoting branch-staged attachments (default path only)
   --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)
@@ -373,7 +499,8 @@ Options:
   --workspace, -w <name>  Override workspace
   --meta <k=v>          Extra queryable metadata (repeatable; value may contain "=").
                         gh.repo/gh.kind/gh.number/gh.ref are always set from the resolved
-                        target — a --meta pair with the same key is overridden by it.
+                        target (or gh.repo/gh.kind/gh.branch/gh.staged-at with --branch) —
+                        a --meta pair with the same key is overridden by it.
                         Because attach always sends its own gh.* pairs, re-attaching to
                         the same key always replaces that file's entire metadata set
                         (never preserves) — use "uploads meta set" to add to it instead.
@@ -384,13 +511,17 @@ Examples:
   uploads attach ./shot.png --pr 123 --repo myorg/myapp
   uploads attach ./artifact.zip --issue 45 --no-comment
   uploads attach ./shot.png --meta app=myapp --meta page=settings
+  uploads attach ./shot.png --branch
+  uploads attach ./shot.png --branch feature/new-settings
+  uploads attach --promote
 `;
 /**
- * Prepare + put each path as a PR/issue attachment with bounded concurrency.
- * Per-file errors collect in `failures` (does not throw). `firstError` is the
+ * Shared prepare + put loop for both PR/issue attach (`uploadAttachments`)
+ * and branch-staged attach (`uploadBranchAttachments`) — bounded concurrency,
+ * per-file errors collect in `failures` (does not throw). `firstError` is the
  * original cause of the first failure — for rethrowing single-file CLI paths.
  */
-export async function uploadAttachments(opts) {
+async function uploadAttachmentBatch(opts) {
     if (opts.files.some((f) => f === "-")) {
         throw new UsageError("attach does not support stdin; pass one or more file paths");
     }
@@ -403,7 +534,7 @@ export async function uploadAttachments(opts) {
             });
             const result = await opts.client.put(prepared.bytes, {
                 filename: prepared.filename,
-                key: ghAttachmentKey(opts.target, prepared.filename),
+                key: opts.keyFor(prepared.filename),
                 contentType: prepared.optimized ? prepared.contentType : opts.contentType,
                 provenance: buildCliProvenance({
                     sourceName,
@@ -450,6 +581,30 @@ export async function uploadAttachments(opts) {
     }
     return { uploads, failures, firstError };
 }
+/**
+ * Prepare + put each path as a PR/issue attachment with bounded concurrency.
+ * Per-file errors collect in `failures` (does not throw). `firstError` is the
+ * original cause of the first failure — for rethrowing single-file CLI paths.
+ */
+export async function uploadAttachments(opts) {
+    return uploadAttachmentBatch({
+        ...opts,
+        keyFor: (filename) => ghAttachmentKey(opts.target, filename),
+    });
+}
+/**
+ * Prepare + put each path as a branch-staged attachment (pre-PR) with
+ * bounded concurrency. Same shape as `uploadAttachments`, keyed under
+ * `gh/<owner>/<repo>/branch/<branch>/<filename>` instead of a PR/issue
+ * number. Never syncs the managed comment — callers must not call
+ * `syncAttachmentsComment` for a branch target.
+ */
+export async function uploadBranchAttachments(opts) {
+    return uploadAttachmentBatch({
+        ...opts,
+        keyFor: (filename) => ghBranchAttachmentKey(opts.target.repo, opts.target.branch, filename),
+    });
+}
 function errorDetail(err) {
     if (err instanceof UploadsError)
         return { message: err.message, code: err.code, status: err.status };
@@ -527,18 +682,72 @@ export async function uploadPuts(opts) {
     }
     return { uploads, failures, firstError };
 }
+/**
+ * Best-effort call to `POST /v1/:workspace/github/promote` (server contract,
+ * PR #310). Degrade-safe like `syncAttachmentsComment`'s bot path: an older
+ * or self-hosted worker without this route (404), a forbidden token (403),
+ * or a network error all collapse to "nothing promoted" — the caller must
+ * never let this fail the attach. Returns undefined on any failure.
+ */
+async function attemptPromoteBranch(client, target, branch) {
+    try {
+        return await client.promoteBranchAttachments({ repo: target.repo, num: target.num, branch });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Human-mode note for a promotion that actually promoted something. */
+function promotionNote(promotion, branch) {
+    const n = promotion.promoted.length;
+    const branchSuffix = branch ? ` from branch ${branch}` : "";
+    return `>> promoted ${n} staged attachment${n === 1 ? "" : "s"}${branchSuffix}\n`;
+}
 export async function runAttach(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
         writeCommandHelp(ATTACH_HELP);
         return 0;
     }
+    if (parsed.flags.has("--no-comment") && typeof parsed.flags.get("--no-comment") === "string") {
+        throw new UsageError("--no-comment takes no value — place it after the file arguments");
+    }
+    if (parsed.flags.has("--promote") && typeof parsed.flags.get("--promote") === "string") {
+        throw new UsageError("--promote takes no value — place it after the file arguments");
+    }
+    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("--promote")) {
+        if (parsed.positionals.length > 0) {
+            throw new UsageError("--promote takes no file arguments — attaching a file to a PR already auto-promotes " +
+                "staged files; use `uploads attach <file> --pr <num>` instead");
+        }
+        if (parsed.flags.has("--branch"))
+            throw new UsageError("--promote cannot be combined with --branch");
+        if (parsed.flags.has("--issue"))
+            throw new UsageError("--promote cannot be combined with --issue");
+        if (parsed.flags.has("--no-promote"))
+            throw new UsageError("--promote cannot be combined with --no-promote");
+        return runAttachPromoteOnly(ctx, parsed, run);
+    }
+    // Validate --branch (including the filename-lookahead guard) before the
+    // zero-positionals bailout below — otherwise `uploads attach --branch
+    // shot.png` (where shot.png is swallowed as the branch value, leaving no
+    // file args) would silently print help instead of a clear UsageError.
+    const branchArg = branchFromFlags(parsed.flags, run);
     if (parsed.positionals.length === 0) {
         writeCommandHelp(ATTACH_HELP);
         return 2;
     }
-    if (parsed.flags.has("--no-comment") && typeof parsed.flags.get("--no-comment") === "string") {
-        throw new UsageError("--no-comment takes no value — place it after the file arguments");
+    if (branchArg !== undefined) {
+        if (parsed.flags.has("--pr"))
+            throw new UsageError("--branch cannot be combined with --pr");
+        if (parsed.flags.has("--issue"))
+            throw new UsageError("--branch cannot be combined with --issue");
+        if (parsed.flags.has("--comment"))
+            throw new UsageError("--branch cannot be combined with --comment");
+        return runAttachBranch(ctx, parsed, branchArg, run);
     }
     const explicitTarget = ghTargetFromFlags(parsed.flags, run);
     const target = explicitTarget ??
@@ -574,12 +783,33 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     if (uploads.length === 0 && failures.length === 1 && parsed.positionals.length === 1) {
         throw firstError instanceof Error ? firstError : new Error(String(firstError));
     }
+    // Auto-promote: before the comment sync, best-effort promote this
+    // workspace's own branch-staged attachments (from an earlier `attach
+    // --branch` while the PR didn't exist yet) into this PR's attachment
+    // prefix, so the comment gather below sees them in the same invocation.
+    // Never for issues (branch staging only ever targets a future PR), never
+    // with --no-promote, and silently skipped (no client call at all) when the
+    // current git branch can't be resolved (detached HEAD, not a repo) — this
+    // must never fail the attach itself.
+    let promotion;
+    let promotedBranch;
+    if (target.kind === "pull" && !parsed.flags.has("--no-promote")) {
+        try {
+            promotedBranch = resolveCurrentBranch(run);
+        }
+        catch {
+            promotedBranch = undefined;
+        }
+        if (promotedBranch !== undefined) {
+            promotion = await attemptPromoteBranch(ctx.client, target, promotedBranch);
+        }
+    }
     let comment;
     let commentError;
     // Skip comment refresh when every upload failed — nothing new from this batch.
     if (!parsed.flags.has("--no-comment") && uploads.length > 0) {
         try {
-            comment = await syncAttachmentsComment(ctx.client, target, run);
+            comment = await syncAttachmentsComment(ctx.client, target, run, ctx.config.workspace);
         }
         catch (err) {
             commentError = err instanceof Error ? err.message : String(err);
@@ -587,7 +817,14 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         }
     }
     if (ctx.json) {
-        await writeJson({ target, uploads, failures, comment, commentError });
+        await writeJson({
+            target,
+            uploads,
+            failures,
+            comment,
+            commentError,
+            promotion: promotion ?? null,
+        });
     }
     else {
         for (const result of uploads) {
@@ -606,6 +843,9 @@ export async function runAttach(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 (!ctx.quiet && promotion && promotion.promoted.length > 0) {
+            process.stderr.write(promotionNote(promotion, promotedBranch));
+        }
         if (!ctx.quiet && comment)
             process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         if (!ctx.quiet && uploads.length > 0) {
@@ -615,6 +855,114 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     }
     return failures.length === 0 ? 0 : 1;
 }
+/**
+ * `attach --branch` path: stages files under
+ * `gh/<owner>/<repo>/branch/<branch>/<filename>` instead of a PR/issue
+ * number. Never syncs the managed comment (there is no PR/issue to comment
+ * on yet, and the comment-gatherer only lists PR/issue prefixes anyway —
+ * branch-staged keys are invisible to it by construction).
+ */
+async function runAttachBranch(ctx, parsed, branch, run) {
+    const repo = resolveRepo(flagString(parsed.flags, "--repo"), run);
+    const defaults = resolvePutDefaults({ envFile: ctx.envFile });
+    const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
+    const frameOpts = frameOptionsFromFlags(parsed.flags);
+    const contentTypeOverride = flagString(parsed.flags, "--content-type");
+    const metaExtras = parseMetaFlags(flagValues(parsed.flags, "--meta"));
+    const metadata = { ...metaExtras, ...ghMetadataForBranch(repo, branch) };
+    validateMetaMap(metadata);
+    const logHuman = !ctx.quiet && !ctx.json;
+    if (logHuman) {
+        const n = parsed.positionals.length;
+        process.stderr.write(`>> uploading ${n} file${n === 1 ? "" : "s"} (staged for branch ${branch})\n`);
+    }
+    const target = { repo, branch };
+    const { uploads, failures, firstError } = await uploadBranchAttachments({
+        client: ctx.client,
+        target,
+        files: parsed.positionals,
+        contentType: contentTypeOverride,
+        optimize: optimizeOpts,
+        frame: frameOpts,
+        metadata,
+    });
+    // Single-file total failure: rethrow so CLI exit codes stay auth/network-aware.
+    if (uploads.length === 0 && failures.length === 1 && parsed.positionals.length === 1) {
+        throw firstError instanceof Error ? firstError : new Error(String(firstError));
+    }
+    if (ctx.json) {
+        await writeJson({ target, uploads, failures });
+    }
+    else {
+        for (const result of uploads) {
+            if (logHuman) {
+                if (result.frame?.framed) {
+                    process.stderr.write(`>> ${basename(result.file)}: framed with ${result.frame.frameId}\n`);
+                }
+                const note = formatOptimizeNote(result.optimize);
+                if (note)
+                    process.stderr.write(`>> ${basename(result.file)}: ${note}\n`);
+                writeReplacedNote(result.replaced, false);
+            }
+            const embedLine = result.embedUrl ? `EMBED: ${result.embedUrl}\n` : "";
+            await writeStdout(`URL: ${result.url}\n${embedLine}MARKDOWN: ${result.markdown}\n`);
+        }
+        for (const failure of failures) {
+            process.stderr.write(`warning: could not upload ${failure.file}: ${failure.error.message}\n`);
+        }
+        if (!ctx.quiet && uploads.length > 0) {
+            process.stderr.write(`>> find these later: uploads find gh.branch=${branch.toLowerCase()}\n`);
+        }
+    }
+    return failures.length === 0 ? 0 : 1;
+}
+/**
+ * `attach --promote` with zero file arguments: resolve the PR target (same
+ * resolution as the default `runAttach` path), promote this workspace's
+ * branch-staged attachments into it, then run the comment sync — useful
+ * right after `gh pr create` when the PR was opened without a fresh attach
+ * (auto-promotion on the default path only fires when you attach a file).
+ * Unlike the default path's best-effort branch resolution, this is an
+ * explicit user action: `resolveCurrentBranch` throwing (detached HEAD, not
+ * a repo) propagates as a UsageError instead of silently skipping. Always
+ * exits 0 — an empty staging prefix is success, not a failure.
+ */
+async function runAttachPromoteOnly(ctx, parsed, run) {
+    const explicitTarget = ghTargetFromFlags(parsed.flags, run);
+    const target = explicitTarget ??
+        resolveCurrentPullRequest(resolveRepo(flagString(parsed.flags, "--repo"), run), run);
+    const branch = resolveCurrentBranch(run);
+    const promotion = await attemptPromoteBranch(ctx.client, target, branch);
+    let comment;
+    let commentError;
+    if (!parsed.flags.has("--no-comment")) {
+        try {
+            comment = await syncAttachmentsComment(ctx.client, target, run, ctx.config.workspace);
+        }
+        catch (err) {
+            commentError = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`warning: promotion succeeded but the GitHub comment failed (is gh installed and authenticated?): ${commentError}\n`);
+        }
+    }
+    if (ctx.json) {
+        await writeJson({
+            target,
+            uploads: [],
+            failures: [],
+            comment,
+            commentError,
+            promotion: promotion ?? null,
+        });
+    }
+    else {
+        if (!ctx.quiet && promotion && promotion.promoted.length > 0) {
+            process.stderr.write(promotionNote(promotion, branch));
+        }
+        if (!ctx.quiet && comment)
+            process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
+    }
+    return 0;
+}
 export async function runPut(ctx, args, help = false, run = execRunner) {
     if (help) {
         writeCommandHelp(PUT_HELP);
@@ -815,7 +1163,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     let commentError;
     if (wantComment && ghTarget && uploads.length > 0) {
         try {
-            comment = await syncAttachmentsComment(ctx.client, ghTarget, run);
+            comment = await syncAttachmentsComment(ctx.client, ghTarget, run, ctx.config.workspace);
             if (logHuman)
                 process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         }
@@ -1346,6 +1694,11 @@ App is installed on the repo; otherwise via your local gh auth. Finds its own
 prior comment via a hidden marker and edits it in place; never touches other
 comments or the description.
 
+If this repo is bound to a different workspace (or unbound and you're on the
+communal "default" workspace), the bot post is declined and this command
+fails rather than silently falling back to gh — see \`uploads github link
+--status\`.
+
 Examples:
   uploads --env-file .env comment --pr 123
   uploads comment --issue 45 --repo buildinternet/uploads
@@ -1359,7 +1712,7 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
     const target = ghTargetFromFlags(parsed.flags, run);
     if (!target)
         throw new UsageError("comment requires --pr or --issue");
-    const result = await syncAttachmentsComment(ctx.client, target, run);
+    const result = await syncAttachmentsComment(ctx.client, target, run, ctx.config.workspace);
     if (ctx.json) {
         await writeJson({ ...target, ...result });
     }
@@ -1371,6 +1724,138 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
     }
     return 0;
 }
+// --- github link ---
+const GITHUB_HELP = `uploads github link [--repo <owner/name>] [--status] [--workspace <name>]
+uploads github unlink [--repo <owner/name>] [--workspace <name>]
+uploads github doctor [--workspace <name>]
+
+Claim, inspect, or release this workspace's binding to a GitHub repo (see the
+managed attachments comment / webhook auto-promotion, which use this
+binding). First-claim-wins: claiming an already-bound repo never steals it
+from whichever workspace claimed it first — the command reports who owns it,
+and how to get it released, instead.
+
+--repo defaults the same way as --pr/--issue elsewhere (gh repo view, then
+the git remote). --status only inspects the current binding (files:read);
+without it, "link" claims the repo (files:write). "unlink" releases a
+binding this workspace owns — it 403s (via the server) if another workspace
+owns it; an operator can reassign or remove that binding instead.
+
+\`doctor\` checks the GitHub App itself: whether it's configured on the
+server, and whether it's subscribed to the webhook events uploads.sh's
+handler needs (issues, pull_request — see docs/github-app). A missing
+subscription is the classic silent failure: the App's ping stays green
+while webhook auto-promotion and title-cache invalidation quietly do
+nothing.
+
+Examples:
+  uploads github link
+  uploads github link --repo buildinternet/uploads
+  uploads github link --status
+  uploads github unlink --repo buildinternet/uploads
+  uploads github doctor
+`;
+function formatGithubDoctor(result) {
+    if (!result.configured) {
+        return `github app: not configured on this server${result.hint ? ` — ${result.hint}` : ""}\n`;
+    }
+    if (result.events === null) {
+        return `github app: configured, but health check failed${result.hint ? ` — ${result.hint}` : ""}\n`;
+    }
+    if (result.ok) {
+        return `github app: ok — subscribed to ${result.requiredEvents.join(", ")}\n`;
+    }
+    return (`github app: missing webhook event subscription(s): ${result.missingEvents.join(", ")}\n` +
+        (result.hint ? `  ${result.hint}\n` : ""));
+}
+function formatGithubLink(repo, result) {
+    return result.workspace
+        ? `${repo} is bound to workspace "${result.workspace}"${result.source ? ` (${result.source})` : ""}\n`
+        : `${repo} is not bound to any workspace\n`;
+}
+async function runGithubDoctor(ctx) {
+    let result;
+    try {
+        result = await ctx.client.githubHealth();
+    }
+    catch (err) {
+        if (err instanceof UploadsError && err.status === 404) {
+            throw new UsageError("server does not support the GitHub App health check yet (404) — upgrade the uploads.sh API/self-hosted worker");
+        }
+        throw err;
+    }
+    if (ctx.json) {
+        await writeJson(result);
+    }
+    else {
+        await writeStdout(formatGithubDoctor(result));
+    }
+    return result.ok ? 0 : 1;
+}
+async function runGithubLink(ctx, repo, statusOnly) {
+    let result;
+    try {
+        result = statusOnly
+            ? await ctx.client.githubLinkStatus(repo)
+            : await ctx.client.githubLinkClaim(repo);
+    }
+    catch (err) {
+        if (err instanceof UploadsError && err.status === 404) {
+            throw new UsageError("server does not support repo bindings yet (404) — upgrade the uploads.sh API/self-hosted worker");
+        }
+        throw err;
+    }
+    if (ctx.json) {
+        await writeJson(result);
+        return 0;
+    }
+    if (!statusOnly && result.claimed === false) {
+        process.stderr.write(`note: ${repo} is already bound to a different workspace ("${result.workspace}") — first-claim-wins, not overwritten. Run "uploads github unlink --repo ${repo}" from that workspace, or ask an operator to reassign it.\n`);
+    }
+    await writeStdout(formatGithubLink(repo, result));
+    return 0;
+}
+async function runGithubUnlink(ctx, repo) {
+    let result;
+    try {
+        result = await ctx.client.githubLinkUnlink(repo);
+    }
+    catch (err) {
+        if (err instanceof UploadsError && err.status === 404) {
+            throw new UsageError("server does not support repo bindings yet (404) — upgrade the uploads.sh API/self-hosted worker");
+        }
+        if (err instanceof UploadsError && err.status === 403) {
+            throw new UsageError(`${repo} is bound to a different workspace — ask an operator to reassign or remove it (${err.message})`);
+        }
+        throw err;
+    }
+    if (ctx.json) {
+        await writeJson(result);
+        return 0;
+    }
+    await writeStdout(result.unlinked
+        ? `unlinked ${repo}\n`
+        : `${repo} was not bound to any workspace — nothing to unlink\n`);
+    return 0;
+}
+export async function runGithub(ctx, args, help = false, run = execRunner) {
+    const parsed = parseCommandArgs(args);
+    const action = parsed.positionals[0];
+    if (help || parsed.help || !action) {
+        writeCommandHelp(GITHUB_HELP);
+        return help || parsed.help ? 0 : 2;
+    }
+    if (action !== "link" && action !== "unlink" && action !== "doctor") {
+        throw new UsageError(`unknown github subcommand: ${action}`);
+    }
+    if (action === "doctor")
+        return runGithubDoctor(ctx);
+    const repo = resolveRepo(flagString(parsed.flags, "--repo"), run);
+    if (action === "unlink")
+        return runGithubUnlink(ctx, repo);
+    const statusOnly = flagBool(parsed.flags, "--status");
+    return runGithubLink(ctx, repo, statusOnly);
+}
 // --- usage / reconcile / purge ---
 const USAGE_HELP = `uploads usage [--workspace <name>]