@buildinternet/uploads 0.38.0 → 0.41.0

package/dist/commands.js

@@ -13,9 +13,9 @@ import { imageFactsFromBytes } from "./image-facts.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./metadata-vocab.js";
 import { mergeSidecarMeta } from "./sidecar.js";
-import { ghAttachmentKey, ghBranchAttachmentKey, ghBranchKeyPrefix, ghKeyPrefix, ghMetadataFromTarget, parseGhKey, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, AUTO_RENDER_OPTIONS, GH_FALLBACK_AUTHOR_NOTE, normalizeGithubCoordinate, } from "./github.js";
+import { ghAttachmentKeyForMode, ghBranchAttachmentKeyForMode, ghBranchKeyPrefix, ghKeyPrefix, ghPrivateKeyPrefix, ghPrivateBranchKeyPrefix, ghMetadataFromTarget, parseGhKey, parseGhPrivateKey, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, AUTO_RENDER_OPTIONS, GH_FALLBACK_AUTHOR_NOTE, normalizeGithubCoordinate, } from "./github.js";
 import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, resolveDefaultBranch, classifyGhNumber, execRunner, timedExecRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
-import { deriveRepoFromGit } from "./keys.js";
+import { deriveRepoFromGit, deriveRepoSlugFromGit } from "./keys.js";
 import { resolvePutPrefix } from "./destinations.js";
 import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
 import { applyFrame, resolveFrameId } from "./frame.js";
@@ -28,6 +28,56 @@ import { colorEnabled, writeCommandHelp } from "./cli-style.js";
 export const UPLOAD_BATCH_CONCURRENCY = 8;
 /** @deprecated Use UPLOAD_BATCH_CONCURRENCY. */
 export const ATTACH_CONCURRENCY = UPLOAD_BATCH_CONCURRENCY;
+/**
+ * Fail-open wrapper around `client.resolveGhPrefix` (issue #631): resolves to
+ * `{ mode: "plain" }` on ANY failure — an HTTP/network error (already handled
+ * inside `resolveGhPrefix` itself), or a self-hosted/older server or test
+ * double that lacks the method entirely (the outer try/catch here). Never
+ * blocks an upload or a read-back, and never logs — this is not an error.
+ * Call once per command invocation and thread the resolved mode through
+ * (uploadPuts/uploadAttachments/uploadBranchAttachments each do this once
+ * internally, ahead of their per-file loop); `resolveGhPrefix` itself also
+ * caches per-process by repo+branch+target, so repeat callers in the same
+ * process (e.g. attach's promote + comment-sync + upload, all for the same
+ * target) cost one request total.
+ */
+export async function resolveGhPrefixSafe(client, opts) {
+    try {
+        return await client.resolveGhPrefix(opts);
+    }
+    catch {
+        return { mode: "plain" };
+    }
+}
+/**
+ * The list of prefixes to fan a multi-prefix list/gather across (issue
+ * #631): the plain prefix plus every active private prefix, if any — a
+ * repo's history can be split across the plain shape and MULTIPLE private
+ * prefixes (e.g. a prefix rotation, or the repo went private after some
+ * files were uploaded), not just the currently-resolved one. Falls back to
+ * `[prefixId]` when the server omits `activePrefixIds` (optional field — an
+ * older/self-hosted worker), so a private repo is never listed as zero
+ * private prefixes. Collapses to `[plainPrefix]` in plain mode, so callers
+ * that special-case a single-prefix array stay byte-identical to pre-#631.
+ */
+export function ghListPrefixes(plainPrefix, ghPrefix, privatePrefixFor) {
+    if (ghPrefix.mode !== "private")
+        return [plainPrefix];
+    return [plainPrefix, ...(ghPrefix.activePrefixIds ?? [ghPrefix.prefixId]).map(privatePrefixFor)];
+}
+/**
+ * Merge-list helper for a multi-prefix fan-out: runs `fetchItems` per prefix
+ * concurrently and concatenates in prefix order. Encodes the first-prefix-
+ * only cursor rule once — a cursor is opaque and scoped to the prefix it was
+ * minted against, so a multi-prefix merge only ever hands it to the FIRST
+ * prefix; every other prefix always starts from its own beginning (undefined
+ * cursor), or a cursor minted for one prefix's keyspace would get replayed
+ * against a different one.
+ */
+export async function ghMergedList(prefixes, cursor, fetchItems) {
+    const pages = await Promise.all(prefixes.map((prefix, i) => fetchItems(prefix, i === 0 ? cursor : undefined)));
+    return pages.flat();
+}
 export { formatUsageHuman } from "./format-usage.js";
 /** Read a local file (or `-` for stdin). Missing path → FILE_NOT_FOUND (exit 2). */
 export function readFileArg(fileArg) {
@@ -385,10 +435,11 @@ export async function uploadPreparedImage(client, bytes, sourceName, opts) {
         frameFit: opts.frame.frameFit,
         optimize: opts.optimize,
     });
+    const ghMode = opts.ghPrefix ?? { mode: "plain" };
     let key = opts.ghTarget
-        ? ghAttachmentKey(opts.ghTarget, prepared.filename)
+        ? ghAttachmentKeyForMode(ghMode, opts.ghTarget, prepared.filename)
         : opts.ghBranchTarget
-            ? ghBranchAttachmentKey(opts.ghBranchTarget.repo, opts.ghBranchTarget.branch, prepared.filename)
+            ? ghBranchAttachmentKeyForMode(ghMode, opts.ghBranchTarget.repo, opts.ghBranchTarget.branch, prepared.filename)
             : opts.key;
     if (key && prepared.optimized)
         key = rewriteKeyExtension(key, prepared.filename);
@@ -510,9 +561,21 @@ export async function syncAttachmentsComment(client, target, run, workspace, opt
     // always links to the file page and always shows metadata here, matching the
     // defaults. This only diverges from the bot-posted comment for a workspace
     // that both sets one of those flags false and falls through to this path.
-    const items = (await client.listAll({ prefix: ghKeyPrefix(target), metadata: true })).map(({ key, url, embedUrl, pageUrl, metadata }) => {
-        // The list endpoint returns every metadata key; the comment renders only
-        // these two. Narrowing here keeps both render paths byte-identical.
+    //
+    // Also list every active private prefix for this repo (issue #631): a
+    // private repo's attachments can live under a randomized prefix instead of
+    // the plain one. `resolveGhPrefixSafe` is fail-open (any resolve failure,
+    // including a client that lacks the method entirely) — plain-only listing,
+    // silently, matching pre-#631 behavior exactly.
+    const ghPrefix = await resolveGhPrefixSafe(client, {
+        repo: target.repo,
+        target: { kind: target.kind, num: target.num },
+    });
+    const prefixes = ghListPrefixes(ghKeyPrefix(target), ghPrefix, (id) => ghPrivateKeyPrefix(id, target));
+    const items = await ghMergedList(prefixes, undefined, async (prefix) => (await client.listAll({ prefix, metadata: true })).map(({ key, url, embedUrl, pageUrl, metadata }) => {
+        // The list endpoint returns every metadata key; the comment
+        // renders only these two. Narrowing here keeps both render paths
+        // byte-identical.
         const path = metadata?.path;
         const state = metadata?.state;
         return {
@@ -524,7 +587,7 @@ export async function syncAttachmentsComment(client, target, run, workspace, opt
                 ? { meta: { ...(path ? { path } : {}), ...(state ? { state } : {}) } }
                 : {}),
         };
-    });
+    }));
     const galleries = [];
     let cursor;
     do {
@@ -791,9 +854,14 @@ async function uploadAttachmentBatch(opts) {
  * original cause of the first failure — for rethrowing single-file CLI paths.
  */
 export async function uploadAttachments(opts) {
+    // Resolved once for the whole batch (issue #631) — never per file.
+    const ghPrefix = await resolveGhPrefixSafe(opts.client, {
+        repo: opts.target.repo,
+        target: { kind: opts.target.kind, num: opts.target.num },
+    });
     return uploadAttachmentBatch({
         ...opts,
-        keyFor: (filename) => ghAttachmentKey(opts.target, filename),
+        keyFor: (filename) => ghAttachmentKeyForMode(ghPrefix, opts.target, filename),
     });
 }
 /**
@@ -804,9 +872,14 @@ export async function uploadAttachments(opts) {
  * `syncAttachmentsComment` for a branch target.
  */
 export async function uploadBranchAttachments(opts) {
+    // Resolved once for the whole batch (issue #631) — never per file.
+    const ghPrefix = await resolveGhPrefixSafe(opts.client, {
+        repo: opts.target.repo,
+        branch: opts.target.branch,
+    });
     return uploadAttachmentBatch({
         ...opts,
-        keyFor: (filename) => ghBranchAttachmentKey(opts.target.repo, opts.target.branch, filename),
+        keyFor: (filename) => ghBranchAttachmentKeyForMode(ghPrefix, opts.target.repo, opts.target.branch, filename),
     });
 }
 function errorDetail(err) {
@@ -828,6 +901,18 @@ export async function uploadPuts(opts) {
     if (opts.files.length > 1 && opts.nameOverride) {
         throw new UsageError("--name cannot be combined with multiple files");
     }
+    // Resolved once for the whole batch (issue #631) — never per file.
+    const ghPrefix = opts.ghTarget
+        ? await resolveGhPrefixSafe(opts.client, {
+            repo: opts.ghTarget.repo,
+            target: { kind: opts.ghTarget.kind, num: opts.ghTarget.num },
+        })
+        : opts.ghBranchTarget
+            ? await resolveGhPrefixSafe(opts.client, {
+                repo: opts.ghBranchTarget.repo,
+                branch: opts.ghBranchTarget.branch,
+            })
+            : undefined;
     const slots = await mapBounded(opts.files, opts.concurrency ?? UPLOAD_BATCH_CONCURRENCY, async (file) => {
         try {
             const sourceName = opts.nameOverride ??
@@ -845,6 +930,7 @@ export async function uploadPuts(opts) {
                 optimize: opts.optimize,
                 ghTarget: opts.ghTarget,
                 ghBranchTarget: opts.ghBranchTarget,
+                ghPrefix,
                 key: opts.explicitKey,
                 prefix: opts.prefix,
                 repo: opts.repo,
@@ -899,7 +985,7 @@ export async function uploadPuts(opts) {
     return { uploads, failures, firstError, sentMetadata };
 }
 /**
- * Best-effort call to `POST /v1/:workspace/github/promote` (server contract,
+ * Best-effort call to `POST /v1/workspaces/: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
@@ -1447,18 +1533,28 @@ async function resolveStagedBinding(client, repo) {
  */
 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 }),
+    const plainPrefix = ghBranchKeyPrefix(repo, branch);
+    // Also list every active private prefix, if any (issue #631) — mirrors
+    // syncAttachmentsComment's gh-fallback gather above: a repo's staged
+    // history can be split across the plain shape and MULTIPLE private
+    // prefixes (e.g. a prefix rotation, or the repo went private after some
+    // files were staged), not just the currently-resolved one. Fail-open: any
+    // resolve failure degrades to plain-only, byte-identical to pre-#631.
+    const ghPrefix = await resolveGhPrefixSafe(client, { repo, branch });
+    const prefixes = ghListPrefixes(plainPrefix, ghPrefix, (id) => ghPrivateBranchKeyPrefix(id));
+    const [files, binding] = await Promise.all([
+        ghMergedList(prefixes, undefined, async (prefix) => {
+            const list = await client.list({ prefix, metadata: true });
+            return 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,
+            }));
+        }),
         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>]
@@ -1699,6 +1795,23 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             }
         }
     }
+    // Derived `repo` (spec: 2026-08-11-screenshots-project-grouping-design.md):
+    // the capturing repo, on every layout including gh/staging. mergeDerivedMeta
+    // keeps explicit --meta repo= wins and never breaks the caps.
+    //
+    // `metadata === undefined` means "leave whatever's already stored for this
+    // key untouched" (client.ts only sends X-Uploads-Meta-* when the map is
+    // defined; a defined map is a full replace server-side). A bare `uploads
+    // put` with no --meta/gh/staging context leaves `metadata` undefined by
+    // design — never synthesize `{ repo }` there just because a repo happens
+    // to be derivable, or a plain re-upload of an existing key would silently
+    // wipe everything already stored on it. Only fold repo in when `metadata`
+    // is already a defined object for another reason.
+    if (!noGit && derivedMetaEnabled(parsed.flags, defaults) && metadata !== undefined) {
+        const slug = deriveRepoSlugFromGit(run);
+        if (slug)
+            metadata = mergeDerivedMeta(metadata, { repo: slug });
+    }
     // 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.
@@ -2219,16 +2332,31 @@ export async function runList(ctx, args, help = false, run = execRunner) {
     const prefixFlag = flagString(parsed.flags, "--prefix");
     let prefix = prefixFlag ?? (defaults.prefix ? `${defaults.prefix}/` : undefined);
     const ghTarget = ghTargetFromFlags(parsed.flags, run);
+    // Also list every active private prefix, if any (issue #631) — mirrors
+    // syncAttachmentsComment's gh-fallback gather: a repo's attachment
+    // history can be split across the plain shape and MULTIPLE private
+    // prefixes, not just the currently-resolved one. `prefixes` stays
+    // undefined outside --pr/--issue (unchanged behavior); when defined it
+    // collapses to just `[prefix]` in plain mode, so the single-request path
+    // below is byte-identical to pre-#631 output there.
+    let prefixes;
     if (ghTarget) {
         if (prefixFlag)
             throw new UsageError("--prefix cannot be combined with --pr/--issue");
         prefix = ghKeyPrefix(ghTarget);
+        const ghPrefix = await resolveGhPrefixSafe(ctx.client, {
+            repo: ghTarget.repo,
+            target: { kind: ghTarget.kind, num: ghTarget.num },
+        });
+        prefixes = ghListPrefixes(prefix, ghPrefix, (id) => ghPrivateKeyPrefix(id, ghTarget));
     }
     const limit = flagInt(parsed.flags, "--limit", "--limit");
     const cursor = flagString(parsed.flags, "--cursor");
     if (flagBool(parsed.flags, "--all")) {
         // --all may start from a caller-provided --cursor and drains from there.
-        const items = await ctx.client.listAll({ prefix, limit, cursor });
+        const items = prefixes && prefixes.length > 1
+            ? await ghMergedList(prefixes, cursor, (p, c) => ctx.client.listAll({ prefix: p, limit, cursor: c }))
+            : await ctx.client.listAll({ prefix, limit, cursor });
         if (ctx.json)
             await writeJson({ items, cursor: null });
         else
@@ -2236,7 +2364,16 @@ export async function runList(ctx, args, help = false, run = execRunner) {
                 await writeStdout(`${item.key}${item.url ? `  ${item.url}` : ""}\n`);
         return 0;
     }
-    const result = await ctx.client.list({ prefix, limit, cursor });
+    // Merged multi-prefix pages don't have a meaningful combined cursor —
+    // dropped (null) only when there's more than one prefix to merge; the
+    // single-prefix path (every non-private call, plus every call before
+    // #631) is untouched. Same first-prefix-only cursor guard as --all above.
+    const result = prefixes && prefixes.length > 1
+        ? {
+            items: await ghMergedList(prefixes, cursor, async (p, c) => (await ctx.client.list({ prefix: p, limit, cursor: c })).items),
+            cursor: null,
+        }
+        : await ctx.client.list({ prefix, limit, cursor });
     if (ctx.json)
         await writeJson(result);
     else {
@@ -2434,10 +2571,37 @@ const COMMENT_RENDERED_META_KEYS = ["path", "state"];
  * metadata tweak, not an explicit comment command); any failure degrades to
  * a stderr hint instead of failing the metadata write that already landed.
  */
+/**
+ * Resolve the `{repo, kind, num}` target for a key, whether plain
+ * (`parseGhKey`) or private-prefixed (issue #631, `parseGhPrivateKey` —
+ * cannot recover the repo from the key alone, since the randomized prefix
+ * deliberately omits it). For a private key, reads `gh.repo` metadata — the
+ * attach/put that created this key already wrote it — via the same metadata
+ * client call `meta get` uses. Fail-open: any read failure, or a key that
+ * isn't gh-managed at all, resolves to undefined (nothing to resync).
+ */
+async function resolveGhTargetForResync(client, key) {
+    const plain = parseGhKey(key);
+    if (plain)
+        return plain;
+    const priv = parseGhPrivateKey(key);
+    if (!priv)
+        return undefined;
+    try {
+        const { metadata } = await client.getMetadata(key);
+        const repo = metadata["gh.repo"];
+        if (!repo)
+            return undefined;
+        return { repo, kind: priv.kind, num: priv.num };
+    }
+    catch {
+        return undefined;
+    }
+}
 async function resyncCommentAfterMetaSet(ctx, key, touchedKeys) {
     if (!touchedKeys.some((k) => COMMENT_RENDERED_META_KEYS.includes(k)))
         return;
-    const target = parseGhKey(key);
+    const target = await resolveGhTargetForResync(ctx.client, key);
     if (!target)
         return;
     try {
@@ -2551,10 +2715,53 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
     }
     return 0;
 }
+// --- ingest ---
+const INGEST_HELP = `uploads ingest — mirror GitHub-native attachments from a PR/issue into the workspace
+
+Usage:
+  uploads ingest --pr <n> [--repo owner/name]
+  uploads ingest --issue <n> [--repo owner/name]
+
+Scans the PR/issue description and comments for github.com/user-attachments
+media, mirrors new ones into the workspace (indexed, not added to the managed
+comment), and detaches ones no longer referenced. Works on any repo linked to
+the workspace; the .uploads.yml ingestGithubAttachments knob only gates the
+automatic webhook path.
+
+Examples:
+  uploads ingest --pr 123
+  uploads ingest --issue 45 --repo acme/app --format json
+`;
+export async function runIngest(ctx, args, help = false, run = execRunner) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        writeCommandHelp(INGEST_HELP);
+        return 0;
+    }
+    const target = ghTargetFromFlags(parsed.flags, run);
+    if (!target) {
+        throw new UsageError("--pr or --issue required");
+    }
+    const result = await ctx.client.ingestGithub(target);
+    const jsonMode = ctx.json || flagString(parsed.flags, "--format") === "json";
+    if (jsonMode) {
+        await writeJson(result);
+        return 0;
+    }
+    if (!ctx.quiet) {
+        let line = `Ingested ${result.ingested.length}, re-attached ${result.reattached.length}, detached ${result.detached.length}, skipped ${result.skipped.length}\n`;
+        for (const skip of result.skipped) {
+            line += `  skipped: ${skip.url} (${skip.reason})\n`;
+        }
+        process.stderr.write(line);
+    }
+    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>]
+uploads github rotate-prefix [--repo <owner/name>] [--branch <name> | --repo-level] [--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
@@ -2570,17 +2777,28 @@ 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
+handler needs (required: issues, pull_request; recommended: issue_comment —
+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.
 
+\`rotate-prefix\` mints a fresh randomized URL prefix for a private repo's
+attachments and moves everything under the old one to it, so the old URLs
+404 at origin immediately (see docs/private-attachments.md). --branch
+defaults to the current git branch; --repo-level rotates the id shared by
+issue attachments and ingested assets instead of a branch's id. Rotation
+is an explicit action — an unauthorized caller gets an error, not a silent
+no-op.
+
 Examples:
   uploads github link
   uploads github link --repo buildinternet/uploads
   uploads github link --status
   uploads github unlink --repo buildinternet/uploads
   uploads github doctor
+  uploads github rotate-prefix --branch feature-x
+  uploads github rotate-prefix --repo-level
 `;
 /** Older servers' health payload predates recommendedEvents/missingRecommendedEvents — treat as no recommendations rather than crashing. */
 function missingRecommendedEventsOf(result) {
@@ -2590,7 +2808,7 @@ function recommendedNoteLine(result) {
     const missing = missingRecommendedEventsOf(result);
     if (missing.length === 0)
         return "";
-    return `note: not subscribed to ${missing.join(", ")} (recommended) — enables bot-comment self-healing; subscribe under the App's Permissions & events\n`;
+    return `note: not subscribed to ${missing.join(", ")} (recommended) — enables bot-comment self-healing and comment-attachment ingestion; subscribe under the App's Permissions & events\n`;
 }
 function formatGithubDoctor(result) {
     if (!result.configured) {
@@ -2600,7 +2818,18 @@ function formatGithubDoctor(result) {
         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` +
+        // The ACTUAL subscribed list, not just the required subset — printing
+        // requiredEvents here once misdiagnosed a live App as "not subscribed to
+        // issue_comment" when it was (2026-08-11). `events` is non-null on every
+        // ok result (the null case returns above); the requiredEvents fallback
+        // only guards a malformed payload from an older server.
+        const subscribed = Array.isArray(result.events)
+            ? [...result.events].sort()
+            : [...result.requiredEvents];
+        const allPresent = missingRecommendedEventsOf(result).length === 0;
+        return (`github app: ok — subscribed to ${subscribed.join(", ")}` +
+            (allPresent ? " (all required + recommended events)" : "") +
+            "\n" +
             recommendedNoteLine(result));
     }
     return (`github app: missing webhook event subscription(s): ${result.missingEvents.join(", ")}\n` +
@@ -2689,6 +2918,34 @@ async function runGithubUnlink(ctx, repo) {
         : `${repo} was not bound to any workspace — nothing to unlink\n`);
     return 0;
 }
+function formatGithubRotatePrefix(repo, branchLabel, result) {
+    if (!result.rotated) {
+        return `nothing to rotate for ${repo} (${branchLabel}): ${result.reason}\n`;
+    }
+    return `rotated ${repo} (${branchLabel}): moved ${result.moved} object${result.moved === 1 ? "" : "s"} to a new prefix (${result.prefixId})\n`;
+}
+async function runGithubRotatePrefix(ctx, repo, branch, repoLevel) {
+    let result;
+    try {
+        result = await ctx.client.rotateGhPrefix(repoLevel ? { repo, repoLevel: true } : { repo, branch });
+    }
+    catch (err) {
+        if (err instanceof UploadsError && err.status === 404) {
+            throw new UsageError("server does not support private-prefix rotation yet (404) — upgrade the uploads.sh API/self-hosted worker");
+        }
+        if (err instanceof UploadsError && err.status === 403) {
+            throw new UsageError(`not authorized to rotate ${repo}'s attachment prefix (${err.message})`);
+        }
+        throw err;
+    }
+    if (ctx.json) {
+        await writeJson(result);
+        return result.rotated ? 0 : 1;
+    }
+    const branchLabel = repoLevel ? "repo-level" : (branch ?? "");
+    await writeStdout(formatGithubRotatePrefix(repo, branchLabel, result));
+    return result.rotated ? 0 : 1;
+}
 export async function runGithub(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
     const action = parsed.positionals[0];
@@ -2696,14 +2953,24 @@ export async function runGithub(ctx, args, help = false, run = execRunner) {
         writeCommandHelp(GITHUB_HELP);
         return help || parsed.help ? 0 : 2;
     }
-    if (action !== "link" && action !== "unlink" && action !== "doctor") {
-        throw new UsageError(`unknown github subcommand: ${action} (expected link or doctor)`, {
-            example: "uploads github link",
-        });
+    if (action !== "link" &&
+        action !== "unlink" &&
+        action !== "doctor" &&
+        action !== "rotate-prefix") {
+        throw new UsageError(`unknown github subcommand: ${action} (expected link, unlink, doctor, or rotate-prefix)`, { example: "uploads github link" });
     }
     if (action === "doctor")
         return runGithubDoctor(ctx);
     const repo = resolveRepo(flagString(parsed.flags, "--repo"), run);
+    if (action === "rotate-prefix") {
+        const repoLevel = flagBool(parsed.flags, "--repo-level");
+        const branchFlag = flagString(parsed.flags, "--branch");
+        if (repoLevel && branchFlag !== undefined) {
+            throw new UsageError("pass either --branch or --repo-level, not both");
+        }
+        const branch = repoLevel ? undefined : (branchFlag ?? resolveCurrentBranch(run));
+        return runGithubRotatePrefix(ctx, repo, branch, repoLevel);
+    }
     if (action === "unlink")
         return runGithubUnlink(ctx, repo);
     const statusOnly = flagBool(parsed.flags, "--status");

package/dist/comment-config.d.ts

@@ -17,6 +17,7 @@ export interface RepoCommentConfig {
     metaState?: boolean;
     linkToFilePage?: boolean;
     note?: string;
+    ingestGithubAttachments?: boolean;
 }
 export interface WorkspaceCommentDefaults {
     imageWidth?: "full" | number;
@@ -24,6 +25,7 @@ export interface WorkspaceCommentDefaults {
     showMetadata?: boolean;
     linkToFilePage?: boolean;
     note?: string;
+    ingestGithubAttachments?: boolean;
 }
 export interface ResolvedCommentOptions {
     imageWidth: "auto" | "full" | number;
@@ -32,6 +34,7 @@ export interface ResolvedCommentOptions {
     metaState: boolean;
     linkToFilePage: boolean;
     note: string | null;
+    ingestGithubAttachments: boolean;
 }
 export type OptionSource = "repo" | "workspace" | "auto";
 export declare const AUTO_COMMENT_OPTIONS: ResolvedCommentOptions;

package/dist/comment-config.js

@@ -20,6 +20,7 @@ export const AUTO_COMMENT_OPTIONS = {
     metaState: true,
     linkToFilePage: true,
     note: null,
+    ingestGithubAttachments: false,
 };
 export const NOTE_MAX_CHARS = 500;
 const WIDTH_MIN = 160;
@@ -71,6 +72,14 @@ export function parseRepoCommentConfig(text, format) {
         else
             warnings.push(`linkToFilePage: expected a boolean; dropped`);
     }
+    // ingestGithubAttachments: boolean
+    if ("ingestGithubAttachments" in c) {
+        const v = c.ingestGithubAttachments;
+        if (typeof v === "boolean")
+            config.ingestGithubAttachments = v;
+        else
+            warnings.push(`ingestGithubAttachments: expected a boolean; dropped`);
+    }
     // meta.path / meta.state: booleans nested under `meta`
     if ("meta" in c) {
         const v = c.meta;
@@ -123,6 +132,9 @@ export function resolveCommentOptions(repo, ws) {
             : {}),
         ...(ws?.linkToFilePage !== undefined ? { linkToFilePage: ws.linkToFilePage } : {}),
         ...(ws?.note ? { note: ws.note } : {}),
+        ...(ws?.ingestGithubAttachments !== undefined
+            ? { ingestGithubAttachments: ws.ingestGithubAttachments }
+            : {}),
     };
     const options = { ...AUTO_COMMENT_OPTIONS };
     const source = Object.fromEntries(Object.keys(AUTO_COMMENT_OPTIONS).map((k) => [k, "auto"]));
@@ -133,6 +145,7 @@ export function resolveCommentOptions(repo, ws) {
             "metaPath",
             "metaState",
             "linkToFilePage",
+            "ingestGithubAttachments",
         ]) {
             if (cfg[key] !== undefined && source[key] === "auto") {
                 options[key] = cfg[key];

package/dist/github.d.ts

@@ -19,8 +19,47 @@ export declare function normalizeGithubCoordinate(value: string): GithubCoordina
  * Inverse of `ghKeyPrefix`: parse the PR/issue coordinate back out of a
  * stable attachment key (`gh/<owner>/<name>/<kind>/<num>/<filename>`), or
  * undefined for any other key shape.
+ *
+ * A real GitHub owner CAN be named `private`, so the strict private-repo
+ * shape (`gh/private/<32-hex-id>/...`, see `parseGhPrivateKey`) is checked
+ * first and rejected here — otherwise a private-prefixed key would
+ * misparse as an ordinary key with owner "private". The accepted ambiguity:
+ * a key whose second segment is NOT 32-lowercase-hex (e.g.
+ * `gh/private/realrepo/pull/5/x.png`) still parses here as owner "private",
+ * repo "private/realrepo" — that's an ordinary public-repo key for a repo
+ * actually named "private", not a private-prefix key.
  */
 export declare function parseGhKey(key: string): GhTarget | undefined;
+/** Literal root under which every private-repo attachment key lives. */
+export declare const GH_PRIVATE_ROOT = "gh/private/";
+/**
+ * Private-repo key prefix: `gh/private/<32-hex-id>/<kind>/<num>/`.
+ * Deliberately omits the repo (unlike `ghKeyPrefix`) — the id is a random,
+ * unguessable per-repo prefix rather than an owner/name path, so callers
+ * that need the repo back must read `gh.repo` metadata (see
+ * `parseGhPrivateKey`, which cannot recover it from the key alone).
+ */
+export declare function ghPrivateKeyPrefix(prefixId: string, target: GhTarget): string;
+/** Private-repo attachment key: `ghPrivateKeyPrefix` + the sanitized filename. */
+export declare function ghPrivateAttachmentKey(prefixId: string, target: GhTarget, filename: string): string;
+/**
+ * Private-repo branch-staged key prefix: `gh/private/<32-hex-id>/branch/`.
+ * Unlike `ghBranchKeyPrefix`, there is deliberately NO branch-name segment —
+ * the branch name itself is not embedded in a private-repo key.
+ */
+export declare function ghPrivateBranchKeyPrefix(prefixId: string): string;
+/** Private-repo branch-staged attachment key: `ghPrivateBranchKeyPrefix` + the sanitized filename. */
+export declare function ghPrivateBranchAttachmentKey(prefixId: string, filename: string): string;
+/**
+ * Inverse of `ghPrivateKeyPrefix`: parse the prefix id/kind/number back out
+ * of a private-repo attachment key, or undefined for any other key shape.
+ * Cannot recover the repo — callers that need it read `gh.repo` metadata.
+ */
+export declare function parseGhPrivateKey(key: string): {
+    prefixId: string;
+    kind: GhTargetKind;
+    num: number;
+} | undefined;
 export declare function ghKeyPrefix(target: GhTarget): string;
 /**
  * Stable attachment key: same filename → same key → same public URL, so
@@ -37,6 +76,29 @@ export declare function ghAttachmentKey(target: GhTarget, filename: string): str
 export declare function ghBranchKeyPrefix(repo: string, branch: string): string;
 /** Branch-staged attachment key: `ghBranchKeyPrefix` + the sanitized filename. */
 export declare function ghBranchAttachmentKey(repo: string, branch: string, filename: string): string;
+/**
+ * Structural stand-in for `ResolveGhPrefixResult` (defined in client.ts) —
+ * kept local so these key builders don't need to import client types just
+ * to own the plain-vs-private branch.
+ */
+export type GhKeyMode = {
+    mode: "plain";
+} | {
+    mode: "private";
+    prefixId: string;
+};
+/**
+ * Mode-owning attachment key builder: collapses the
+ * `mode === "private" ? ghPrivateAttachmentKey(...) : ghAttachmentKey(...)`
+ * ternary repeated across call sites into one place.
+ */
+export declare function ghAttachmentKeyForMode(mode: GhKeyMode, target: GhTarget, filename: string): string;
+/**
+ * Mode-owning branch-staged attachment key builder. The private form
+ * ignores `repo`/`branch` (a private-repo key has no branch-name segment,
+ * see `ghPrivateBranchKeyPrefix`) and uses the prefix id instead.
+ */
+export declare function ghBranchAttachmentKeyForMode(mode: GhKeyMode, repo: string, branch: string, filename: string): string;
 /**
  * `gh.*` metadata for a branch-staged attach: `gh.repo`, `gh.kind=branch`,
  * `gh.branch` (lowercased), and `gh.staged-at` (ISO 8601 UTC, no fractional