@buildinternet/uploads 0.13.1 → 0.15.0

package/dist/commands.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, 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";
@@ -89,7 +89,9 @@ Options:
   --format human|url|markdown|json
   --pr <num>            Attach to a pull request: key gh/<owner>/<repo>/pull/<num>/<name> (stable URL, no hash)
   --issue <num>         Attach to an issue: key gh/<owner>/<repo>/issues/<num>/<name>
-  --comment             With --pr/--issue: update one managed comment with attachments and linked galleries via local gh auth
+  --comment             With --pr/--issue: update one managed comment with
+                        attachments and linked galleries. Posts as uploads-sh[bot]
+                        when the GitHub App is installed; otherwise via local gh.
   --gallery <id>         Add the uploaded object(s) to this public gallery
   --meta <k=v>          Queryable custom metadata (repeatable; value may contain "="): key ^[a-z][a-z0-9._-]{0,63}$, value 1-512 printable ASCII, max 24 pairs
                         Re-uploading to an existing key WITH --meta replaces that file's
@@ -128,6 +130,25 @@ 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);
 }
+/**
+ * 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.
+ */
+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)
+        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
@@ -272,13 +293,37 @@ export function frameOptionsFromFlags(flags) {
         throw new UsageError("--frame-url requires --frame");
     return { frameId, frameUrl, frameFit };
 }
-/**
- * List every attachment under the target's prefix and create/update the
- * managed comment. Throws on gh failure — callers decide whether that is
- * fatal (`comment` command) or a warning (`put --comment`).
- */
-export async function syncAttachmentsComment(client, target, run) {
-    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url, embedUrl }) => ({ key, url, embedUrl }));
+/** Human-mode suffix noting who posted the managed comment. */
+export function commentViaSuffix(via) {
+    return via === "bot" ? " (uploads-sh[bot])" : " (via gh)";
+}
+export async function syncAttachmentsComment(client, target, run, workspace) {
+    try {
+        const 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" };
+        // 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`);
+        }
+    }
+    catch {
+        // Endpoint absent/unreachable (self-hosted, network, older worker) — fall
+        // through to the gh path below.
+    }
+    // gh fallback: gather from this workspace's own data and post via local `gh`.
+    // 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 {
@@ -313,10 +358,15 @@ export async function syncAttachmentsComment(client, target, run) {
         }
     }));
     if (items.length === 0 && previewGalleries.length === 0)
-        return { action: "skipped", count: 0 };
-    const body = attachmentsCommentBody(items, previewGalleries);
-    const { created } = upsertAttachmentsComment(target, body, run);
-    return { action: created ? "created" : "updated", count: items.length + previewGalleries.length };
+        return { action: "skipped", count: 0, via: "gh" };
+    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,
+        via: "gh",
+    };
 }
 // --- attach ---
 const ATTACH_HELP = `uploads attach <file...> [options]
@@ -338,9 +388,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)
@@ -354,7 +432,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.
@@ -365,13 +444,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");
     }
@@ -384,7 +467,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,
@@ -431,6 +514,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 };
@@ -508,18 +615,68 @@ 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);
+    }
     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");
+    const branchArg = branchFromFlags(parsed.flags, run);
+    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 ??
@@ -532,9 +689,9 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     // target pairs always win over a same-named --meta extra (documented above).
     // Validate the merged map (not just the extras) so the 24-key/8KB caps are
     // enforced client-side even when extras alone are under the cap but extras
-    // + the 4 gh.* pairs push the merged map over it.
+    // + the gh.* pairs push the merged map over it.
     const metaExtras = parseMetaFlags(flagValues(parsed.flags, "--meta"));
-    const metadata = { ...metaExtras, ...ghMetadataFromTarget(target) };
+    const metadata = { ...metaExtras, ...ghMetadataFromTargetWithTitle(target, run) };
     if (Object.keys(metadata).length > 0)
         validateMetaMap(metadata);
     const logHuman = !ctx.quiet && !ctx.json;
@@ -555,12 +712,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);
@@ -568,7 +746,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) {
@@ -587,8 +772,11 @@ 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}\n`);
+            process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         if (!ctx.quiet && uploads.length > 0) {
             const ref = ghMetadataFromTarget(target)["gh.ref"];
             process.stderr.write(`>> find these later: uploads find gh.ref=${ref}\n`);
@@ -596,6 +784,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);
@@ -711,7 +1007,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     let metadata = userMeta;
     let attachedRef;
     if (ghTarget) {
-        const merged = { ...userMeta, ...ghMetadataFromTarget(ghTarget) };
+        const merged = { ...userMeta, ...ghMetadataFromTargetWithTitle(ghTarget, run) };
         validateMetaMap(merged); // enforce 24-key/8KB caps on the merged map (matches attach)
         metadata = merged;
         attachedRef = merged["gh.ref"];
@@ -723,7 +1019,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         if (autoEnabled) {
             const autoTarget = resolveAutoGhTarget(flagString(parsed.flags, "--repo") ?? defaults.repo, flagString(parsed.flags, "--ref") ?? defaults.ref, run);
             if (autoTarget) {
-                const autoMeta = ghMetadataFromTarget(autoTarget);
+                const autoMeta = ghMetadataFromTargetWithTitle(autoTarget, run);
                 const merged = { ...autoMeta, ...userMeta };
                 // Auto resolution must never fail the upload: if merging the gh.* pairs
                 // would exceed the metadata caps, drop them and upload with --meta only.
@@ -796,9 +1092,9 @@ 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}\n`);
+                process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         }
         catch (err) {
             commentError = err instanceof Error ? err.message : String(err);
@@ -1322,7 +1618,8 @@ export async function runDelete(ctx, args, help = false) {
 const COMMENT_HELP = `uploads comment (--pr <num> | --issue <num>) [--repo <owner/name>] [--workspace <name>]
 
 Create or update the managed attachments comment on a GitHub PR or issue,
-listing everything uploaded for it. Uses your local gh auth. Finds its own
+listing everything uploaded for it. Posts as uploads-sh[bot] when the GitHub
+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.
 
@@ -1339,15 +1636,72 @@ 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 });
     }
     else if (!ctx.quiet) {
+        const via = commentViaSuffix(result.via);
         process.stderr.write(result.action === "skipped"
             ? `no attachments under ${ghKeyPrefix(target)} — nothing to do\n`
-            : `${result.action} attachments comment on ${target.repo}#${target.num} (${result.count} file${result.count === 1 ? "" : "s"})\n`);
+            : `${result.action} attachments comment on ${target.repo}#${target.num} (${result.count} file${result.count === 1 ? "" : "s"})${via}\n`);
+    }
+    return 0;
+}
+// --- github link ---
+const GITHUB_HELP = `uploads github link [--repo <owner/name>] [--status] [--workspace <name>]
+
+Claim or inspect 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
+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, the command claims the repo (files:write).
+
+Examples:
+  uploads github link
+  uploads github link --repo buildinternet/uploads
+  uploads github link --status
+`;
+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`;
+}
+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")
+        throw new UsageError(`unknown github subcommand: ${action}`);
+    const repo = resolveRepo(flagString(parsed.flags, "--repo"), run);
+    const statusOnly = flagBool(parsed.flags, "--status");
+    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\n`);
     }
+    await writeStdout(formatGithubLink(repo, result));
     return 0;
 }
 // --- usage / reconcile / purge ---

package/dist/github-gh.d.ts

@@ -9,6 +9,8 @@ export declare const execRunner: CommandRunner;
 export declare function resolveRepo(explicit: string | undefined, run?: CommandRunner): string;
 /** Resolve the pull request associated with the current branch. */
 export declare function resolveCurrentPullRequest(repo: string, run?: CommandRunner): GhTarget;
+/** Resolve the current git branch (`--branch` with no value). Throws UsageError on detached HEAD or outside a git repo. */
+export declare function resolveCurrentBranch(run?: CommandRunner): string;
 /**
  * Classify a bare PR/issue number via the GitHub API so the default `put`
  * path can stamp the right `gh.kind`. Returns undefined on any failure (gh
@@ -16,11 +18,36 @@ export declare function resolveCurrentPullRequest(repo: string, run?: CommandRun
  * uploads without metadata.
  */
 export declare function classifyGhNumber(repo: string, num: number, run?: CommandRunner): GhTarget | undefined;
+/**
+ * Best-effort PR/issue title lookup via local `gh`. Returns undefined on any
+ * failure (gh missing, unauthenticated, network, 404) — mirrors
+ * `resolveCurrentPullRequest`/`classifyGhNumber`'s degrade-don't-throw
+ * pattern. A title is a nice-to-have annotation, never a blocker: callers
+ * must never let this failure abort an upload.
+ */
+export declare function resolveGhTitle(target: GhTarget, run?: CommandRunner): string | undefined;
+/**
+ * `ghMetadataFromTarget`'s 4 pairs, plus a best-effort `gh.title` (issue #267)
+ * when `resolveGhTitle` yields one that also satisfies the metadata-value
+ * rule every other pair follows (1-512 printable ASCII — `metadata.ts`'s
+ * `META_VALUE_MAX`/`isMetaValueSafe`). Truncated to `META_VALUE_MAX` first;
+ * a title left empty or unsafe by truncation (e.g. non-ASCII — real titles
+ * often contain emoji or curly quotes) is silently omitted rather than
+ * sanitized, matching `resolveGhTitle`'s own "degrade, don't fail the
+ * upload" contract.
+ */
+export declare function ghMetadataFromTargetWithTitle(target: GhTarget, run?: CommandRunner): Record<string, string>;
 /**
  * Create the managed attachments comment, or edit it in place if it already
  * exists. Never touches any other comment. Body is passed via stdin
  * (`-F body=@-`) so it is never shell-interpolated.
+ *
+ * `marker` identifies which comment to hunt for (see `findManagedComment`);
+ * `body` is expected to already carry that same marker as its first line
+ * (built via `attachmentsCommentBody(items, galleries, marker)`), so patching
+ * an adopted legacy comment migrates it to the namespaced marker in place.
+ * Defaults to the shared legacy marker for backward compatibility.
  */
-export declare function upsertAttachmentsComment(target: GhTarget, body: string, run?: CommandRunner): {
+export declare function upsertAttachmentsComment(target: GhTarget, body: string, run?: CommandRunner, marker?: string): {
     created: boolean;
 };