@buildinternet/uploads 0.37.3 → 0.40.0

package/dist/cli-catalog.js

@@ -166,6 +166,11 @@ export const ROOT_COMMANDS = [
             { name: "doctor", summary: "Check the GitHub App's webhook event subscriptions" },
         ],
     },
+    {
+        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,7 @@ export type GithubCommentResult = {
     fixUrl?: string;
     required?: string[];
 };
-/** `POST /v1/:workspace/github/promote` request/response (server contract, PR #310). */
+/** `POST /v1/workspaces/:workspace/github/promote` request/response (server contract, PR #310). */
 export interface PromoteBranchAttachmentsOptions {
     repo: string;
     num: number;
@@ -270,7 +270,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 +289,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 +305,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;
@@ -617,6 +638,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,19 @@ export function mintWorkspaceToken(apiUrl, accessToken, input) {
 function encodeKeyPath(key) {
     return key.split("/").map(encodeURIComponent).join("/");
 }
+// Stays on the legacy `/v1/:workspace/files` wildcard for now (issue #613):
+// the canonical files vertical has no upload PUT, POST /sign, or GET/PATCH
+// /:key metadata yet, and its list/search adopted the session response shape
+// rather than the bearer one. Move this once the canonical vertical grows
+// those routes and the bearer list shape is reconciled.
 function filesBase(config) {
     return `${config.apiUrl}/v1/${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();
@@ -499,7 +504,7 @@ 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" },
             });
@@ -511,7 +516,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 +525,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 +535,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 +548,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 +582,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,13 @@ 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, } from "../commands.js";
+import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, writeReplacedNote, } 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";
@@ -31,6 +32,15 @@ localhost/private-network URLs are reachable only by the
 local backend — with --via remote (or auto falling back to remote) these
 fail fast with a clear error instead of sending a doomed request.
 
+The object name is derived from the target URL (host + path), not chosen by
+you — e.g. https://app.example/settings becomes app.example-settings.png.
+--state folds into that derived name (a -before/-after/... suffix), so
+capturing the same URL with --state before then --state after produces two
+distinct objects instead of the second silently overwriting the first.
+Re-capturing the same URL + --state replaces that object in place — the
+intended idempotency for repeat captures. --key bypasses all of this and
+sets the whole object key verbatim (no folding).
+
 After capture, screenshots share the put upload pipeline: optional --frame,
 optimize-by-default, --pr/--issue attachment + --comment, --gallery, --meta.
 
@@ -351,7 +361,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) };
@@ -381,6 +395,9 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
         reducedMotion,
         evalJs,
         initScript,
+        // Skip folding when an explicit --key was given — --key sets the whole
+        // key, so there's no auto-derived name to fold state into.
+        state: keyHint ? undefined : explicitMeta.state,
         measureSelectors: annotateSelectors.length > 0 ? annotateSelectors : undefined,
         apiUrl: ctx.config.apiUrl,
         token: ctx.config.token,
@@ -497,6 +514,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
         if (prepared.optimized) {
             process.stderr.write(`>> optimized ${prepared.originalBytes} → ${prepared.outputBytes} bytes\n`);
         }
+        writeReplacedNote(result.replaced, ctx.quiet, dryRun, result.wouldRefuse);
         process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n`);
         if (stagingTarget !== undefined) {
             process.stderr.write(`>> find these later: uploads find gh.branch=${stagingTarget.branch.toLowerCase()}\n`);
@@ -514,8 +532,16 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
         process.stderr.write("\n");
     }
     // One JSON `hint` slot (mirrors bare put): the binding warning is more
-    // actionable than the generic staging note, so it wins when both fire.
-    const jsonHint = bindingWarning ?? stagingNote;
+    // actionable than the generic staging note, so it wins when both fire; a
+    // replaced-object note (issue #618) is the lowest priority of the three —
+    // it only surfaces when nothing else already claimed the slot. Since state
+    // folds into the derived key, replaced + state means a same-side re-capture,
+    // which is the intended replace-in-place flow — word it as informational,
+    // not as a problem.
+    const replacedHint = result.replaced && explicitMeta.state
+        ? `re-capture replaced the previous state=${explicitMeta.state} object at ${result.key} — expected for repeat captures of the same URL + state`
+        : undefined;
+    const jsonHint = bindingWarning ?? stagingNote ?? replacedHint;
     switch (format) {
         case "json":
             await writeJson({

package/dist/commands.d.ts

@@ -63,6 +63,7 @@ export declare function warnNearMissMeta(ctx: CliContext, meta: Record<string, s
  * point is `--help` discoverability and `--state` validation.
  */
 export declare function stateAppMetaFromFlags(flags: CommandFlags["flags"]): Record<string, string>;
+export declare function writeReplacedNote(replaced: boolean | undefined, quiet: boolean, dryRun?: boolean, wouldRefuse?: boolean): void;
 export type PreparedUpload = OptimizeImageResult & {
     frame?: Pick<FrameResult, "framed" | "frameId" | "skippedReason">;
 };
@@ -456,6 +457,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>;

package/dist/commands.js

@@ -15,7 +15,7 @@ import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./me
 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 { 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";
@@ -315,7 +315,7 @@ function formatOptimizeNote(opt) {
     }
     return undefined;
 }
-function writeReplacedNote(replaced, quiet, dryRun = false, wouldRefuse = false) {
+export function writeReplacedNote(replaced, quiet, dryRun = false, wouldRefuse = false) {
     if (quiet)
         return;
     if (dryRun && wouldRefuse) {
@@ -899,7 +899,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
@@ -1699,6 +1699,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.
@@ -2551,6 +2568,48 @@ 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>]
@@ -2570,7 +2629,8 @@ 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.
@@ -2590,7 +2650,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 +2660,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` +

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/config-file.d.ts

@@ -1,5 +1,7 @@
 import type { UploadsClientConfig } from "./config.js";
-export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", "UPLOADS_SESSION_TOKEN", "UPLOADS_DEFAULT_PREFIX", "UPLOADS_DEFAULT_REPO", "UPLOADS_DEFAULT_REF", "UPLOADS_DEFAULT_WIDTH", "UPLOADS_NO_GIT", "UPLOADS_NO_OPTIMIZE", "UPLOADS_KEEP_EXIF", "UPLOADS_NO_AUTO_META", "UPLOADS_SCREENSHOT_VIA", "UPLOADS_NO_NUDGE"];
+export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", 
+/** Better Auth device-flow session bearer — keeps session.cliVersion fresh. */
+"UPLOADS_SESSION_TOKEN", "UPLOADS_DEFAULT_PREFIX", "UPLOADS_DEFAULT_REPO", "UPLOADS_DEFAULT_REF", "UPLOADS_DEFAULT_WIDTH", "UPLOADS_NO_GIT", "UPLOADS_NO_OPTIMIZE", "UPLOADS_KEEP_EXIF", "UPLOADS_NO_AUTO_META", "UPLOADS_SCREENSHOT_VIA", "UPLOADS_NO_NUDGE"];
 export type UploadsConfigKey = (typeof UPLOADS_CONFIG_KEYS)[number];
 export type UploadsConfigValues = Partial<Record<UploadsConfigKey, string>>;
 export interface PutDefaults {

package/dist/keys.d.ts

@@ -8,6 +8,12 @@ export declare function sha256Short(bytes: Uint8Array): Promise<string>;
  * every existing caller.
  */
 export declare function deriveRepoFromGit(run?: (cmd: string, args: string[], input?: string) => string): string | undefined;
+/**
+ * Full `owner/name` slug (lowercase, matching the `gh.repo` convention) from
+ * the cwd's git remote — the derived `repo` metadata value. Unlike
+ * `deriveRepoFromGit` above (key-segment name only), this keeps the owner.
+ */
+export declare function deriveRepoSlugFromGit(run?: (cmd: string, args: string[], input?: string) => string): string | undefined;
 export declare function buildScreenshotKey(opts: {
     filename: string;
     fileBytes: Uint8Array;

package/dist/keys.js

@@ -1,4 +1,5 @@
 import { execSync } from "node:child_process";
+import { parseRepoFromRemoteUrl } from "./github.js";
 export function sanitizeKeySegment(s) {
     return s.replace(/[^A-Za-z0-9._-]/g, "-");
 }
@@ -28,6 +29,22 @@ export function deriveRepoFromGit(run) {
         return undefined;
     }
 }
+/**
+ * Full `owner/name` slug (lowercase, matching the `gh.repo` convention) from
+ * the cwd's git remote — the derived `repo` metadata value. Unlike
+ * `deriveRepoFromGit` above (key-segment name only), this keeps the owner.
+ */
+export function deriveRepoSlugFromGit(run) {
+    try {
+        const url = run
+            ? run("git", ["config", "--get", "remote.origin.url"])
+            : execSync("git config --get remote.origin.url", { encoding: "utf8" });
+        return parseRepoFromRemoteUrl(url)?.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function buildScreenshotKey(opts) {
     const dot = opts.filename.lastIndexOf(".");
     const ext = dot >= 0 ? opts.filename.slice(dot + 1) : "";

package/dist/mcp/args.d.ts

@@ -23,7 +23,7 @@ export declare const metadataProp: {
 };
 export declare const stateProp: {
     type: string;
-    enum: ("before" | "after" | "empty" | "error" | "loading")[];
+    enum: ("after" | "before" | "empty" | "error" | "loading")[];
     description: string;
 };
 export declare const appProp: {

package/dist/mcp/tools.js

@@ -5,6 +5,7 @@ import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
 import { ghBranchAttachmentKey, ghKeyPrefix } from "../github.js";
 import { safeCaptureFacts } from "../capture-facts.js";
+import { deriveRepoSlugFromGit } from "../keys.js";
 import { validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
 import { execRunner, ghMetadataFromTargetWithTitle, resolveCurrentBranch, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
@@ -430,7 +431,23 @@ export function createUploadsMcpTools(opts) {
                     repoArg: optString(args, "repo") ?? defaults.repo,
                     run,
                 });
-                const putMetadata = stagingTarget ? mergeStagingMeta(metadata, stagingTarget) : metadata;
+                // Derived `repo` metadata (spec: 2026-08-11-screenshots-project-grouping-design.md).
+                // Same derivation the CLI does; MCP always derives (no --no-auto), so
+                // this is only suppressed by noGit. metadataProp's contract: omitting
+                // `metadata` means "leave what's already stored for this key
+                // untouched" — an object (even {}) triggers a full replace. So only
+                // fold the derived repo into a defined object when the caller already
+                // supplied metadata, or branch staging is building one below anyway
+                // (mergeStagingMeta always returns a defined object); never
+                // synthesize metadata on a bare re-upload just to add repo, or a
+                // no-metadata put would silently wipe everything already stored.
+                const repoSlug = !noGit ? deriveRepoSlugFromGit(run) : undefined;
+                const metadataWithRepo = repoSlug !== undefined && (metadata !== undefined || stagingTarget !== undefined)
+                    ? mergeDerivedMeta(metadata ?? {}, { repo: repoSlug })
+                    : metadata;
+                const putMetadata = stagingTarget
+                    ? mergeStagingMeta(metadataWithRepo, stagingTarget)
+                    : metadataWithRepo;
                 const putShared = {
                     client,
                     ghTarget: target,
@@ -737,9 +754,15 @@ export function createUploadsMcpTools(opts) {
                 // Keep undefined when nothing at all was supplied or derived, so the
                 // "omit to leave stored metadata untouched" contract still holds.
                 const captureDerived = safeCaptureFacts(targetArg, viewport, colorSchemeArg);
-                const metadataBase = metadata === undefined && Object.keys(captureDerived).length === 0
+                // Derived `repo` metadata (spec: 2026-08-11-screenshots-project-grouping-design.md).
+                // Same derivation the CLI does, suppressed by noGit.
+                const repoSlug = !noGit ? deriveRepoSlugFromGit(run) : undefined;
+                const captureDerivedWithRepo = repoSlug
+                    ? { ...captureDerived, repo: repoSlug }
+                    : captureDerived;
+                const metadataBase = metadata === undefined && Object.keys(captureDerivedWithRepo).length === 0
                     ? undefined
-                    : mergeDerivedMeta(metadata ?? {}, captureDerived);
+                    : mergeDerivedMeta(metadata ?? {}, captureDerivedWithRepo);
                 // gh.* metadata: explicit pr/issue target wins; staging wins the same
                 // way (matches attach --branch/bare put); otherwise capture-derived +
                 // explicit only.
@@ -761,6 +784,10 @@ export function createUploadsMcpTools(opts) {
                         hide: optStringArray(args, "hide"),
                         hideDevTools: optBool(args, "noHideDevTools") ? false : undefined,
                         reducedMotion: optBool(args, "reducedMotion"),
+                        // Skip folding when an explicit key was given — key sets the
+                        // whole object key, so there's no auto-derived name to fold
+                        // state into.
+                        state: keyArg ? undefined : metadataWithCaptureFacts?.state,
                         apiUrl: config.apiUrl,
                         token: config.token,
                     });

package/dist/metadata-vocab.d.ts

@@ -1,8 +1,10 @@
-export declare const CANONICAL_META_KEYS: readonly ["url", "path", "env", "theme", "viewport", "device", "software", "captured", "state", "app"];
+export declare const CANONICAL_META_KEYS: readonly ["url", "path", "env", "theme", "viewport", "device", "software", "captured", "state", "app", "repo"];
 export type CanonicalMetaKey = (typeof CANONICAL_META_KEYS)[number];
 /** Closed enum for `state` — the highest-value hand-supplied search facet. */
 export declare const META_STATE_VALUES: readonly ["before", "after", "empty", "error", "loading"];
 export type MetaStateValue = (typeof META_STATE_VALUES)[number];
+/** True when `value` is exactly one of the canonical state values. */
+export declare function isMetaStateValue(value: string): value is MetaStateValue;
 /**
  * Validate a `--state` value. Fails fast with a suggestion when the value is a
  * recognized near-miss, otherwise lists the valid set.

package/dist/metadata-vocab.js

@@ -18,11 +18,16 @@ export const CANONICAL_META_KEYS = [
     "captured",
     "state",
     "app",
+    "repo",
 ];
 const CANONICAL_KEY_SET = new Set(CANONICAL_META_KEYS);
 /** Closed enum for `state` — the highest-value hand-supplied search facet. */
 export const META_STATE_VALUES = ["before", "after", "empty", "error", "loading"];
 const STATE_VALUE_SET = new Set(META_STATE_VALUES);
+/** True when `value` is exactly one of the canonical state values. */
+export function isMetaStateValue(value) {
+    return STATE_VALUE_SET.has(value);
+}
 /** Common spellings agents reach for, mapped to the canonical `state` value. */
 const STATE_ALIASES = {
     pre: "before",

package/dist/screenshot.d.ts

@@ -65,6 +65,14 @@ export interface CaptureScreenshotOptions {
     fullPage?: boolean;
     colorScheme?: "dark" | "light";
     waitUntil?: WaitUntil;
+    /**
+     * Folded into the auto-derived filename's stem (e.g. `-before`) so a
+     * before/after pair of the same URL yields two distinct object names
+     * instead of silently overwriting each other. Callers must omit this when
+     * the caller also gave an explicit object key/name — folding only applies
+     * to the auto-derived name.
+     */
+    state?: string;
     /** Extra CSS selectors to hide (display:none) before capture. */
     hide?: string[];
     /**
@@ -120,6 +128,26 @@ export interface CaptureScreenshotResult {
     /** Present when `measureSelectors` was given and the local backend ran. */
     measures?: Record<string, MeasuredBox>;
 }
+/**
+ * Folds a `--state` value into an auto-derived filename's stem, e.g.
+ * `localhost-docs-mcp.png` + "before" → `localhost-docs-mcp-before.png`. This
+ * is what keeps a before/after pair (same URL, two states) from colliding on
+ * the same object key (issue #618) — without it, the second capture silently
+ * overwrote the first.
+ *
+ * No-op when `state` is undefined, and idempotent: re-folding a filename that
+ * already ends with `-<state>` (e.g. re-deriving from a stored filename)
+ * doesn't double-append.
+ *
+ * Only the canonical state values fold. Callers pass the merged metadata bag's
+ * `state`, which a free-form `--meta state=…` can populate with any printable
+ * ASCII (validateMetaMap allows `/` and spaces) — that stays metadata-only
+ * rather than entering the object key.
+ *
+ * Callers must skip this entirely when the caller gave an explicit key/name
+ * (e.g. `--key`) — this only applies to the auto-derived filename.
+ */
+export declare function foldStateIntoFilename(filename: string, state: string | undefined): string;
 /**
  * Resolve target + options into PNG bytes via the local or remote backend.
  * Shared by the CLI `screenshot` command and the MCP `screenshot` tool.

package/dist/screenshot.js

@@ -12,6 +12,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, resolve as resolvePath } from "node:path";
 import { pathToFileURL } from "node:url";
 import { UploadsError } from "./errors.js";
+import { isMetaStateValue } from "./metadata-vocab.js";
 import { captureRemote, MAX_REMOTE_HTML_BYTES } from "./screenshot-remote.js";
 /**
  * Host selectors for framework dev toolbars/overlays that otherwise pollute a
@@ -159,6 +160,35 @@ function deriveFilename(target) {
     const stem = [url.hostname, pathPart].filter(Boolean).join("-");
     return `${stem || "screenshot"}.png`;
 }
+/**
+ * Folds a `--state` value into an auto-derived filename's stem, e.g.
+ * `localhost-docs-mcp.png` + "before" → `localhost-docs-mcp-before.png`. This
+ * is what keeps a before/after pair (same URL, two states) from colliding on
+ * the same object key (issue #618) — without it, the second capture silently
+ * overwrote the first.
+ *
+ * No-op when `state` is undefined, and idempotent: re-folding a filename that
+ * already ends with `-<state>` (e.g. re-deriving from a stored filename)
+ * doesn't double-append.
+ *
+ * Only the canonical state values fold. Callers pass the merged metadata bag's
+ * `state`, which a free-form `--meta state=…` can populate with any printable
+ * ASCII (validateMetaMap allows `/` and spaces) — that stays metadata-only
+ * rather than entering the object key.
+ *
+ * Callers must skip this entirely when the caller gave an explicit key/name
+ * (e.g. `--key`) — this only applies to the auto-derived filename.
+ */
+export function foldStateIntoFilename(filename, state) {
+    if (!state || !isMetaStateValue(state))
+        return filename;
+    const match = /^(.*?)(\.[^./]+)?$/.exec(filename);
+    const stem = match?.[1] ?? filename;
+    const ext = match?.[2] ?? "";
+    if (stem.endsWith(`-${state}`))
+        return filename;
+    return `${stem}-${state}${ext}`;
+}
 /**
  * Best-effort local-browser probe used only to decide `auto` routing. Never
  * throws — any failure (e.g. optional playwright-core not installed) means
@@ -183,7 +213,7 @@ export async function captureScreenshot(opts) {
     const target = classifyTarget(opts.target);
     const viewport = opts.viewport ?? DEFAULT_SCREENSHOT_VIEWPORT;
     const waitUntil = opts.waitUntil ?? "load";
-    const filename = deriveFilename(target);
+    const filename = foldStateIntoFilename(deriveFilename(target), opts.state);
     // Only private-network URLs are truly unreachable remotely; an .html file
     // is sent to the remote backend as an inline `html` body (though anything
     // it references via file:// or relative paths won't resolve there).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.37.3",
+  "version": "0.40.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,
@@ -38,7 +38,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "files-sdk": "^2.1.0"
+    "files-sdk": "^2.2.3"
   },
   "peerDependenciesMeta": {
     "files-sdk": {
@@ -48,8 +48,8 @@
   "devDependencies": {
     "@types/node": "^26.1.0",
     "ai": "^6.0.0",
-    "files-sdk": "^2.1.0",
-    "typescript": "^6.0.3",
+    "files-sdk": "^2.2.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   },
   "publishConfig": {