@buildinternet/uploads 0.38.0 → 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

@@ -8,6 +8,7 @@ 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 +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) };

package/dist/commands.d.ts

@@ -457,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";
@@ -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/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/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.

package/dist/metadata-vocab.d.ts

@@ -1,4 +1,4 @@
-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"];

package/dist/metadata-vocab.js

@@ -18,6 +18,7 @@ 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.38.0",
+  "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,7 +48,7 @@
   "devDependencies": {
     "@types/node": "^26.1.0",
     "ai": "^6.0.0",
-    "files-sdk": "^2.1.0",
+    "files-sdk": "^2.2.3",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   },