@buildinternet/uploads 0.38.0 → 0.41.0

package/dist/cli-catalog.js

@@ -164,8 +164,17 @@ export const ROOT_COMMANDS = [
         subcommands: [
             { name: "link", summary: "Claim or inspect the repo binding" },
             { name: "doctor", summary: "Check the GitHub App's webhook event subscriptions" },
+            {
+                name: "rotate-prefix",
+                summary: "Rotate a private repo's randomized attachment URL prefix",
+            },
         ],
     },
+    {
+        name: "ingest",
+        usage: "ingest (--pr <n> | --issue <n>)",
+        summary: "Mirror GitHub-native user-attachments media from a PR/issue into the workspace",
+    },
     {
         name: "list",
         summary: "List objects (--meta k=v filters by queryable metadata)",

package/dist/cli.js

@@ -6,7 +6,7 @@ import { formatRootHelp, formatUnknownCommand, wantsFullHelp } from "./cli-help.
 import { commandSummary, suggestCommand } from "./cli-suggest.js";
 import { writeJson } from "./io.js";
 import { colorEnabled, createStyle } from "./cli-style.js";
-import { runPut, runAttach, runStaged, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runGithub, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
+import { runPut, runAttach, runStaged, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runGithub, runIngest, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
 import { runConfig } from "./commands/config.js";
 import { runSetup } from "./commands/setup.js";
 import { runLogin } from "./commands/login.js";
@@ -308,7 +308,8 @@ export async function runCli(argv) {
             case "purge-expired":
             case "doctor":
             case "comment":
-            case "github": {
+            case "github":
+            case "ingest": {
                 const ctx = createContext(parsed.globals, !showHelp, cmdArgs);
                 switch (parsed.command) {
                     case "attach":
@@ -332,6 +333,9 @@ export async function runCli(argv) {
                     case "github":
                         code = await runGithub(ctx, cmdArgs, showHelp);
                         break;
+                    case "ingest":
+                        code = await runIngest(ctx, cmdArgs, showHelp);
+                        break;
                     case "list":
                         code = await runList(ctx, cmdArgs, showHelp);
                         break;

package/dist/client.d.ts

@@ -256,7 +256,42 @@ export type GithubCommentResult = {
     fixUrl?: string;
     required?: string[];
 };
-/** `POST /v1/:workspace/github/promote` request/response (server contract, PR #310). */
+/** `POST /v1/workspaces/:workspace/github/private-prefix` request (server contract, issue #631/#613). */
+export interface ResolveGhPrefixOptions {
+    repo: string;
+    branch?: string;
+    target?: {
+        kind: "pull" | "issues";
+        num: number;
+    };
+}
+/** `POST /v1/workspaces/:workspace/github/private-prefix` response (server contract, issue #631/#613). */
+export type ResolveGhPrefixResult = {
+    mode: "plain";
+} | {
+    mode: "private";
+    prefixId: string;
+    activePrefixIds?: string[];
+};
+/** `POST /v1/workspaces/:workspace/github/private-prefix/rotate` request (server contract, issue #631/#613). */
+export interface RotateGhPrefixOptions {
+    repo: string;
+    /** Mutually exclusive with `repoLevel`: rotate one branch's id. */
+    branch?: string;
+    /** Mutually exclusive with `branch`: rotate the repo-level id shared by
+     * issue attachments and ingested assets. */
+    repoLevel?: boolean;
+}
+/** `POST /v1/workspaces/:workspace/github/private-prefix/rotate` response (server contract, issue #631/#613). */
+export type RotateGhPrefixResult = {
+    rotated: false;
+    reason: string;
+} | {
+    rotated: true;
+    prefixId: string;
+    moved: number;
+};
+/** `POST /v1/workspaces/:workspace/github/promote` request/response (server contract, PR #310). */
 export interface PromoteBranchAttachmentsOptions {
     repo: string;
     num: number;
@@ -270,7 +305,7 @@ export interface PromoteBranchAttachmentsResult {
     promoted: string[];
     skipped: PromoteSkip[];
 }
-/** `GET`/`POST /v1/:workspace/github/link` result (server contract, phase 4b). */
+/** `GET`/`POST /v1/workspaces/:workspace/github/link` result (server contract, phase 4b). */
 export interface GithubLinkResult {
     repo: string;
     linked: boolean;
@@ -289,14 +324,14 @@ export interface GithubLinkClaimResult extends GithubLinkResult {
      */
     reason?: "not_authorized";
 }
-/** `DELETE /v1/:workspace/github/link` result (issue #318, self-serve unlink). */
+/** `DELETE /v1/workspaces/:workspace/github/link` result (issue #318, self-serve unlink). */
 export interface GithubLinkUnlinkResult {
     repo: string;
     unlinked: boolean;
     reason?: "not_linked";
 }
 /**
- * `GET /v1/:workspace/github/repo-link` result (issue #398). Deliberately
+ * `GET /v1/workspaces/:workspace/github/repo-link` result (issue #398). Deliberately
  * minimal relative to `GithubLinkResult`: never names the owning workspace
  * when it isn't this one — "self"/"other"/"none" is all the stage-time
  * warning needs, and anything richer would leak cross-tenant info to a
@@ -305,10 +340,31 @@ export interface GithubLinkUnlinkResult {
 export interface GithubRepoLinkResult {
     binding: "self" | "other" | "none";
 }
+/**
+ * `POST /v1/workspaces/:workspace/github/ingest` result (Task 6, manual/
+ * backfill entry point for GitHub-native `user-attachments` media). `repo`
+ * comes back lowercased by the server.
+ */
+export interface IngestGithubResult {
+    repo: string;
+    kind: "pull" | "issues";
+    num: number;
+    /** Object keys newly mirrored into the workspace this call. */
+    ingested: string[];
+    /** Object keys whose previously-detached ledger row was un-detached. */
+    reattached: string[];
+    /** Object keys detached because they're no longer referenced. */
+    detached: string[];
+    /** Attachment URLs skipped, with the reason. */
+    skipped: {
+        url: string;
+        reason: string;
+    }[];
+}
 export interface HealthResult {
     ok: boolean;
 }
-/** `GET /v1/:workspace/github/health` result (issue #293 follow-up). */
+/** `GET /v1/workspaces/:workspace/github/health` result (issue #293 follow-up). */
 export interface GithubHealthResult {
     configured: boolean;
     ok: boolean;
@@ -546,10 +602,12 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
     /** `PATCH /v1/:workspace/files/:key` — merge `set`/`delete`; returns the merged map. */
     patchMetadata(key: string, opts: PatchMetadataOptions): Promise<GetMetadataResult>;
     /**
-     * `GET /v1/:workspace/files?meta.<k>=<v>&…&name=…` — ANDed equality filter
-     * over queryable metadata and/or a case-insensitive filename substring.
-     * At least one of non-empty `filters` or `opts.name` is required.
-     * `filters` must be pre-validated when present (see `metadata.ts`).
+     * `GET /v1/workspaces/:workspace/files/search?meta.<k>=<v>&…&name=…` —
+     * ANDed equality filter over queryable metadata and/or a case-insensitive
+     * filename substring. At least one of non-empty `filters` or `opts.name`
+     * is required. `filters` must be pre-validated when present (see
+     * `metadata.ts`). The canonical search route is non-paginated (server cap
+     * 100, narrowable via `limit`), so `cursor` is always null.
      */
     findFiles(filters?: Record<string, string>, opts?: FindFilesOptions): Promise<FindFilesResult>;
     /** `GET /v1/:workspace/files/facets` — workspace metadata key vocabulary. */
@@ -585,6 +643,26 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
         kind: "pull" | "issues";
         resync?: boolean;
     }): Promise<GithubCommentResult>;
+    /**
+     * Resolve the GitHub-key mode (plain vs. randomized private prefix, issue
+     * #631) a caller should stage/list attachments under for `repo`. Fail-open:
+     * ANY failure — a 404 from an older/self-hosted server, a network error, a
+     * non-2xx response, or a malformed body — resolves to `{ mode: "plain" }`
+     * silently (no stderr noise), never throws. Cached per-process, keyed by
+     * repo+branch+target, so repeated calls for the same coordinate (e.g. the
+     * gh-fallback comment gather re-checking on every sync) cost one request.
+     */
+    resolveGhPrefix(opts: ResolveGhPrefixOptions): Promise<ResolveGhPrefixResult>;
+    /**
+     * Rotate the active private-repo attachment prefix for `opts.repo` +
+     * (`opts.branch` or `opts.repoLevel`) (issue #631). Unlike
+     * `resolveGhPrefix`, this is NOT fail-open: it's an explicit, caller-
+     * initiated action, so a failure (including a 404 from an older/self-
+     * hosted server without this route) throws `UploadsError` — the CLI
+     * command decides how to present that, rather than this method silently
+     * degrading to a shape that would look like success.
+     */
+    rotateGhPrefix(opts: RotateGhPrefixOptions): Promise<RotateGhPrefixResult>;
     /**
      * Promote a workspace's branch-staged attachments into a PR's stable
      * attachment prefix (server contract, PR #310 — degrade-safe callers
@@ -617,6 +695,18 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
      * `UploadsError` (status 404) on an older/self-hosted server without
      * this route — callers treat that as "unknown", not "broken".
      */
+    /**
+     * `POST /v1/workspaces/:workspace/github/ingest` (Task 6) — manual/
+     * backfill mirror of a PR/issue's `github.com/user-attachments` media
+     * into the workspace. Only ever had the canonical `/v1/workspaces`
+     * route (no old bearer-only alias) — unlike the other `github/*` client
+     * methods above, which moved onto it in issue #613.
+     */
+    ingestGithub(input: {
+        repo: string;
+        kind: "pull" | "issues";
+        num: number;
+    }): Promise<IngestGithubResult>;
     githubHealth(): Promise<GithubHealthResult>;
     /**
      * Self-serve unlink (issue #318): removes `repo`'s binding, but only if

package/dist/client.js

@@ -186,14 +186,18 @@ export function mintWorkspaceToken(apiUrl, accessToken, input) {
 function encodeKeyPath(key) {
     return key.split("/").map(encodeURIComponent).join("/");
 }
-function filesBase(config) {
-    return `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/files`;
+// Canonical files surface (issue #613): every file operation now goes to
+// `/v1/workspaces/:workspace/files`. Per-key ops share handlers with the
+// legacy wildcard (#636); list/find/facets adapt the canonical envelopes in
+// their wrappers below (#613 shape reconciliation).
+function canonicalFilesBase(config) {
+    return `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/files`;
 }
 function usageBase(config) {
-    return `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/usage`;
+    return `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/usage`;
 }
 function galleriesBase(config) {
-    return `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/galleries`;
+    return `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/galleries`;
 }
 function mapApiError(status, error, code, requiredScope, existingUrl) {
     const normalized = error.toLowerCase();
@@ -306,18 +310,30 @@ export function createUploadsClient(config) {
         if (opts.metadata)
             params.set("metadata", "1");
         const qs = params.toString();
-        const page = await request("GET", `${filesBase(config)}${qs ? `?${qs}` : ""}`);
+        // Canonical list envelope is `{files, prefixes, cursor}` with queryable
+        // metadata always hydrated (issue #613 — the session shape won the
+        // reconciliation). This client keeps its historical `{items, cursor}`
+        // contract: rename the array and honor `opts.metadata` by stripping the
+        // hydrated maps when the caller didn't ask for them.
+        const page = await request("GET", `${canonicalFilesBase(config)}${qs ? `?${qs}` : ""}`);
         return {
-            ...page,
-            items: page.items.map((item) => ({
-                ...item,
-                embedUrl: resolveEmbedUrl(item.url, item.embedUrl),
-            })),
+            cursor: page.cursor,
+            items: page.files.map((item) => {
+                const { metadata, ...rest } = item;
+                return {
+                    ...rest,
+                    ...(opts.metadata && metadata !== undefined ? { metadata } : {}),
+                    embedUrl: resolveEmbedUrl(item.url, item.embedUrl),
+                };
+            }),
         };
     }
     async function getGallery(id) {
         return request("GET", `${galleriesBase(config)}/${encodeURIComponent(id)}`);
     }
+    // Per-process cache for resolveGhPrefix, keyed by repo+branch+target — see
+    // that method's doc.
+    const resolveGhPrefixCache = new Map();
     return {
         async put(body, opts) {
             const key = opts.key ??
@@ -332,7 +348,7 @@ export function createUploadsClient(config) {
             const contentType = opts.contentType ?? inferContentType(opts.filename);
             if (opts.dryRun) {
                 const qs = opts.replace ? "dryRun=1&replace=1" : "dryRun=1";
-                const preview = await request("PUT", `${filesBase(config)}/${encodeKeyPath(key)}?${qs}`);
+                const preview = await request("PUT", `${canonicalFilesBase(config)}/${encodeKeyPath(key)}?${qs}`);
                 if (preview.url == null) {
                     throw new UploadsError("workspace has no publicBaseUrl (cannot resolve a public URL)", "NO_PUBLIC_URL");
                 }
@@ -364,7 +380,7 @@ export function createUploadsClient(config) {
                         headers[`X-Uploads-Meta-${k}`] = v;
                 }
             }
-            const result = await request("PUT", `${filesBase(config)}/${encodeKeyPath(key)}`, {
+            const result = await request("PUT", `${canonicalFilesBase(config)}/${encodeKeyPath(key)}`, {
                 body,
                 headers,
             });
@@ -391,24 +407,26 @@ export function createUploadsClient(config) {
             return items;
         },
         async delete(key) {
-            return request("DELETE", `${filesBase(config)}/${encodeKeyPath(key)}`);
+            return request("DELETE", `${canonicalFilesBase(config)}/${encodeKeyPath(key)}`);
         },
         /** `GET /v1/:workspace/files/:key?metadata=1` — the object's queryable metadata. */
         async getMetadata(key) {
-            return request("GET", `${filesBase(config)}/${encodeKeyPath(key)}?metadata=1`);
+            return request("GET", `${canonicalFilesBase(config)}/${encodeKeyPath(key)}?metadata=1`);
         },
         /** `PATCH /v1/:workspace/files/:key` — merge `set`/`delete`; returns the merged map. */
         async patchMetadata(key, opts) {
-            return request("PATCH", `${filesBase(config)}/${encodeKeyPath(key)}`, {
+            return request("PATCH", `${canonicalFilesBase(config)}/${encodeKeyPath(key)}`, {
                 body: new TextEncoder().encode(JSON.stringify(opts)),
                 headers: { "Content-Type": "application/json" },
             });
         },
         /**
-         * `GET /v1/:workspace/files?meta.<k>=<v>&…&name=…` — ANDed equality filter
-         * over queryable metadata and/or a case-insensitive filename substring.
-         * At least one of non-empty `filters` or `opts.name` is required.
-         * `filters` must be pre-validated when present (see `metadata.ts`).
+         * `GET /v1/workspaces/:workspace/files/search?meta.<k>=<v>&…&name=…` —
+         * ANDed equality filter over queryable metadata and/or a case-insensitive
+         * filename substring. At least one of non-empty `filters` or `opts.name`
+         * is required. `filters` must be pre-validated when present (see
+         * `metadata.ts`). The canonical search route is non-paginated (server cap
+         * 100, narrowable via `limit`), so `cursor` is always null.
          */
         async findFiles(filters = {}, opts = {}) {
             const params = new URLSearchParams();
@@ -420,18 +438,19 @@ export function createUploadsClient(config) {
                 params.set("prefix", opts.prefix);
             if (opts.limit != null)
                 params.set("limit", String(opts.limit));
-            return request("GET", `${filesBase(config)}?${params.toString()}`);
+            const result = await request("GET", `${canonicalFilesBase(config)}/search?${params.toString()}`);
+            return { items: result.items, cursor: null, truncated: result.truncated };
         },
         /** `GET /v1/:workspace/files/facets` — workspace metadata key vocabulary. */
         async listMetadataKeys() {
-            return request("GET", `${filesBase(config)}/facets`);
+            return request("GET", `${canonicalFilesBase(config)}/facets`);
         },
         /** `GET /v1/:workspace/files/facets?key=` — distinct values for one key. */
         async listMetadataValues(key) {
-            return request("GET", `${filesBase(config)}/facets?${new URLSearchParams({ key })}`);
+            return request("GET", `${canonicalFilesBase(config)}/facets?${new URLSearchParams({ key })}`);
         },
         async head(key) {
-            const result = await request("GET", `${filesBase(config)}/${encodeKeyPath(key)}`);
+            const result = await request("GET", `${canonicalFilesBase(config)}/${encodeKeyPath(key)}`);
             return { ...result, embedUrl: resolveEmbedUrl(result.url, result.embedUrl) };
         },
         async createGallery(opts) {
@@ -499,7 +518,54 @@ export function createUploadsClient(config) {
          * the field.
          */
         async upsertGithubComment(opts) {
-            return request("POST", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/comment`, {
+            return request("POST", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/comment`, {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        /**
+         * Resolve the GitHub-key mode (plain vs. randomized private prefix, issue
+         * #631) a caller should stage/list attachments under for `repo`. Fail-open:
+         * ANY failure — a 404 from an older/self-hosted server, a network error, a
+         * non-2xx response, or a malformed body — resolves to `{ mode: "plain" }`
+         * silently (no stderr noise), never throws. Cached per-process, keyed by
+         * repo+branch+target, so repeated calls for the same coordinate (e.g. the
+         * gh-fallback comment gather re-checking on every sync) cost one request.
+         */
+        async resolveGhPrefix(opts) {
+            const cacheKey = JSON.stringify([
+                opts.repo.toLowerCase(),
+                opts.branch ?? "",
+                opts.target ?? null,
+            ]);
+            const cached = resolveGhPrefixCache.get(cacheKey);
+            if (cached)
+                return cached;
+            const resolved = await (async () => {
+                try {
+                    return await request("POST", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/private-prefix`, {
+                        body: new TextEncoder().encode(JSON.stringify(opts)),
+                        headers: { "Content-Type": "application/json" },
+                    });
+                }
+                catch {
+                    return { mode: "plain" };
+                }
+            })();
+            resolveGhPrefixCache.set(cacheKey, resolved);
+            return resolved;
+        },
+        /**
+         * Rotate the active private-repo attachment prefix for `opts.repo` +
+         * (`opts.branch` or `opts.repoLevel`) (issue #631). Unlike
+         * `resolveGhPrefix`, this is NOT fail-open: it's an explicit, caller-
+         * initiated action, so a failure (including a 404 from an older/self-
+         * hosted server without this route) throws `UploadsError` — the CLI
+         * command decides how to present that, rather than this method silently
+         * degrading to a shape that would look like success.
+         */
+        async rotateGhPrefix(opts) {
+            return request("POST", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/private-prefix/rotate`, {
                 body: new TextEncoder().encode(JSON.stringify(opts)),
                 headers: { "Content-Type": "application/json" },
             });
@@ -511,7 +577,7 @@ export function createUploadsClient(config) {
          * that doesn't have this route yet, as "nothing promoted").
          */
         async promoteBranchAttachments(opts) {
-            return request("POST", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/promote`, {
+            return request("POST", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/promote`, {
                 body: new TextEncoder().encode(JSON.stringify(opts)),
                 headers: { "Content-Type": "application/json" },
             });
@@ -520,7 +586,7 @@ export function createUploadsClient(config) {
          * `UploadsError` (status 404) on an older/self-hosted server without this
          * route — callers treat that as "bindings unsupported". */
         async githubLinkStatus(repo) {
-            return request("GET", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/link?repo=${encodeURIComponent(repo)}`);
+            return request("GET", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/link?repo=${encodeURIComponent(repo)}`);
         },
         /**
          * Explicitly claim `repo` for this workspace (first-claim-wins — see
@@ -530,7 +596,7 @@ export function createUploadsClient(config) {
          * server without this route.
          */
         async githubLinkClaim(repo) {
-            return request("POST", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/link`, {
+            return request("POST", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/link`, {
                 body: new TextEncoder().encode(JSON.stringify({ repo })),
                 headers: { "Content-Type": "application/json" },
             });
@@ -543,15 +609,31 @@ export function createUploadsClient(config) {
          * caller (the stage warning) treats ANY failure here as "stay silent".
          */
         async githubRepoLinkStatus(repo) {
-            return request("GET", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/repo-link?repo=${encodeURIComponent(repo)}`);
+            return request("GET", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/repo-link?repo=${encodeURIComponent(repo)}`);
         },
         /**
          * GitHub App configuration + webhook event subscription check. Throws
          * `UploadsError` (status 404) on an older/self-hosted server without
          * this route — callers treat that as "unknown", not "broken".
          */
+        /**
+         * `POST /v1/workspaces/:workspace/github/ingest` (Task 6) — manual/
+         * backfill mirror of a PR/issue's `github.com/user-attachments` media
+         * into the workspace. Only ever had the canonical `/v1/workspaces`
+         * route (no old bearer-only alias) — unlike the other `github/*` client
+         * methods above, which moved onto it in issue #613.
+         */
+        async ingestGithub(input) {
+            const body = input.kind === "pull"
+                ? { repo: input.repo, pr: input.num }
+                : { repo: input.repo, issue: input.num };
+            return request("POST", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/ingest`, {
+                body: new TextEncoder().encode(JSON.stringify(body)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
         async githubHealth() {
-            return request("GET", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/health`);
+            return request("GET", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/health`);
         },
         /**
          * Self-serve unlink (issue #318): removes `repo`'s binding, but only if
@@ -561,7 +643,7 @@ export function createUploadsClient(config) {
          * older/self-hosted server without this route.
          */
         async githubLinkUnlink(repo) {
-            return request("DELETE", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/link?repo=${encodeURIComponent(repo)}`);
+            return request("DELETE", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/link?repo=${encodeURIComponent(repo)}`);
         },
         async health() {
             return request("GET", `${config.apiUrl}/health`, { auth: false });

package/dist/commands/screenshot.js

@@ -2,12 +2,12 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { extractDashValue, flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { writeCommandHelp } from "../cli-style.js";
-import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, writeReplacedNote, } from "../commands.js";
+import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, writeReplacedNote, resolveGhPrefixSafe, } from "../commands.js";
 import { resolvePutDefaults } from "../config.js";
 import { loadDefaultsRaw, resolveScreenshotDefaults } from "../config-file.js";
 import { resolvePutPrefix } from "../destinations.js";
 import { execRunner, ghMetadataFromTargetWithTitle, resolveRepo, } from "../github-gh.js";
-import { ghBranchAttachmentKey } from "../github.js";
+import { deriveRepoSlugFromGit } from "../keys.js";
 import { safeCaptureFacts } from "../capture-facts.js";
 import { parseMetaFlags, validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
@@ -360,7 +360,11 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     // Explicit input (--meta plus the dedicated flags) wins over capture facts.
     const explicitMeta = { ...metaExtras, ...stateAppMetaFromFlags(parsed.flags) };
     const deriveMeta = derivedMetaEnabled(parsed.flags, putDefaults);
-    const withFacts = mergeDerivedMeta(explicitMeta, deriveMeta ? safeCaptureFacts(target, viewport, colorScheme) : {});
+    const repoSlug = deriveMeta && !noGit ? deriveRepoSlugFromGit(run) : undefined;
+    const withFacts = mergeDerivedMeta(explicitMeta, {
+        ...(deriveMeta ? safeCaptureFacts(target, viewport, colorScheme) : {}),
+        ...(repoSlug ? { repo: repoSlug } : {}),
+    });
     let metadata = withFacts;
     if (ghTarget) {
         metadata = { ...withFacts, ...ghMetadataFromTargetWithTitle(ghTarget, run) };
@@ -443,15 +447,28 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     }
     const repo = flagString(parsed.flags, "--repo") ?? putDefaults.repo;
     const ref = flagString(parsed.flags, "--ref") ?? putDefaults.ref;
-    const branchKey = stagingTarget !== undefined
-        ? ghBranchAttachmentKey(stagingTarget.repo, stagingTarget.branch, captured.filename)
-        : undefined;
+    // Resolved once (issue #631), only when it's actually needed for the
+    // upload about to happen (never for the noUpload/no-target bailouts
+    // above) — never per file (screenshot only ever uploads one).
+    const ghPrefix = ghTarget
+        ? await resolveGhPrefixSafe(ctx.client, {
+            repo: ghTarget.repo,
+            target: { kind: ghTarget.kind, num: ghTarget.num },
+        })
+        : stagingTarget !== undefined
+            ? await resolveGhPrefixSafe(ctx.client, {
+                repo: stagingTarget.repo,
+                branch: stagingTarget.branch,
+            })
+            : undefined;
     const alt = altFlag ?? basename(captured.filename);
     const { result, prepared, markdown } = await uploadPreparedImage(ctx.client, finalPng, captured.filename, {
         frame: frameOpts,
         optimize: optimizeOpts,
         ghTarget,
-        key: keyHint ?? branchKey,
+        ghBranchTarget: stagingTarget,
+        ghPrefix,
+        key: keyHint,
         prefix: resolvedPrefix ?? putDefaults.prefix,
         repo,
         ref,

package/dist/commands.d.ts

@@ -1,4 +1,4 @@
-import { type PutResult, type UploadsClient } from "./client.js";
+import { type PutResult, type ResolveGhPrefixOptions, type ResolveGhPrefixResult, type UploadsClient } from "./client.js";
 import { type CommandFlags } from "./cli-args.js";
 import { type ResolvedConfig } from "./config.js";
 import { type GhTarget } from "./github.js";
@@ -11,6 +11,42 @@ import type { DetectRoots } from "./screenshot-local.js";
 export declare const UPLOAD_BATCH_CONCURRENCY = 8;
 /** @deprecated Use UPLOAD_BATCH_CONCURRENCY. */
 export declare const ATTACH_CONCURRENCY = 8;
+/**
+ * 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 declare function resolveGhPrefixSafe(client: UploadsClient, opts: ResolveGhPrefixOptions): Promise<ResolveGhPrefixResult>;
+/**
+ * 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 declare function ghListPrefixes(plainPrefix: string, ghPrefix: ResolveGhPrefixResult, privatePrefixFor: (prefixId: string) => string): string[];
+/**
+ * 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 declare function ghMergedList<T>(prefixes: readonly string[], cursor: string | undefined, fetchItems: (prefix: string, cursor: string | undefined) => Promise<T[]>): Promise<T[]>;
 export { formatUsageHuman } from "./format-usage.js";
 export interface CliContext {
     config: ResolvedConfig;
@@ -90,6 +126,14 @@ export interface UploadPreparedImageOptions {
      * --branch` for the same filename via `ghBranchAttachmentKey`.
      */
     ghBranchTarget?: BranchTarget;
+    /**
+     * Resolved GitHub-key mode (issue #631), from a single upstream
+     * `resolveGhPrefixSafe` call — never resolved here. Passed straight to
+     * `ghAttachmentKeyForMode`/`ghBranchAttachmentKeyForMode`, which own the
+     * plain-vs-private branch. Ignored when neither `ghTarget` nor
+     * `ghBranchTarget` is set.
+     */
+    ghPrefix?: ResolveGhPrefixResult;
     key?: string;
     prefix?: string;
     repo?: string;
@@ -457,6 +501,7 @@ export declare function runFind(ctx: CliContext, args: string[], help?: boolean)
 export declare function runMeta(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runDelete(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runComment(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
+export declare function runIngest(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runGithub(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runUsage(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runReconcile(ctx: CliContext, args: string[], help?: boolean): Promise<number>;