@buildinternet/uploads 0.38.0 → 0.41.0

package/dist/github.js

@@ -57,14 +57,78 @@ export function normalizeGithubCoordinate(value) {
  * Inverse of `ghKeyPrefix`: parse the PR/issue coordinate back out of a
  * stable attachment key (`gh/<owner>/<name>/<kind>/<num>/<filename>`), or
  * undefined for any other key shape.
+ *
+ * A real GitHub owner CAN be named `private`, so the strict private-repo
+ * shape (`gh/private/<32-hex-id>/...`, see `parseGhPrivateKey`) is checked
+ * first and rejected here — otherwise a private-prefixed key would
+ * misparse as an ordinary key with owner "private". The accepted ambiguity:
+ * a key whose second segment is NOT 32-lowercase-hex (e.g.
+ * `gh/private/realrepo/pull/5/x.png`) still parses here as owner "private",
+ * repo "private/realrepo" — that's an ordinary public-repo key for a repo
+ * actually named "private", not a private-prefix key.
  */
 export function parseGhKey(key) {
+    if (parseGhPrivateKey(key))
+        return undefined;
     const match = /^gh\/([^/]+)\/([^/]+)\/(pull|issues)\/([1-9][0-9]*)\/./.exec(key);
     if (!match)
         return undefined;
     const [, owner, name, kind, num] = match;
     return { repo: `${owner}/${name}`, kind: kind, num: Number(num) };
 }
+/** Literal root under which every private-repo attachment key lives. */
+export const GH_PRIVATE_ROOT = "gh/private/";
+/** Strict shape for a randomized private-repo prefix id: 32 lowercase hex chars. */
+const PRIVATE_PREFIX_ID_RE = /^[0-9a-f]{32}$/;
+/**
+ * Guard every private-key builder against a malformed `prefixId` — a
+ * caller bug here must never silently produce a guessable-ish key.
+ */
+function assertPrivatePrefixId(prefixId) {
+    if (!PRIVATE_PREFIX_ID_RE.test(prefixId)) {
+        throw new Error(`invalid private prefix id: "${prefixId}" must be 32 lowercase hex characters`);
+    }
+}
+/**
+ * Private-repo key prefix: `gh/private/<32-hex-id>/<kind>/<num>/`.
+ * Deliberately omits the repo (unlike `ghKeyPrefix`) — the id is a random,
+ * unguessable per-repo prefix rather than an owner/name path, so callers
+ * that need the repo back must read `gh.repo` metadata (see
+ * `parseGhPrivateKey`, which cannot recover it from the key alone).
+ */
+export function ghPrivateKeyPrefix(prefixId, target) {
+    assertPrivatePrefixId(prefixId);
+    return `${GH_PRIVATE_ROOT}${prefixId}/${target.kind}/${target.num}/`;
+}
+/** Private-repo attachment key: `ghPrivateKeyPrefix` + the sanitized filename. */
+export function ghPrivateAttachmentKey(prefixId, target, filename) {
+    return `${ghPrivateKeyPrefix(prefixId, target)}${sanitizeKeySegment(filename)}`;
+}
+/**
+ * Private-repo branch-staged key prefix: `gh/private/<32-hex-id>/branch/`.
+ * Unlike `ghBranchKeyPrefix`, there is deliberately NO branch-name segment —
+ * the branch name itself is not embedded in a private-repo key.
+ */
+export function ghPrivateBranchKeyPrefix(prefixId) {
+    assertPrivatePrefixId(prefixId);
+    return `${GH_PRIVATE_ROOT}${prefixId}/branch/`;
+}
+/** Private-repo branch-staged attachment key: `ghPrivateBranchKeyPrefix` + the sanitized filename. */
+export function ghPrivateBranchAttachmentKey(prefixId, filename) {
+    return `${ghPrivateBranchKeyPrefix(prefixId)}${sanitizeKeySegment(filename)}`;
+}
+/**
+ * Inverse of `ghPrivateKeyPrefix`: parse the prefix id/kind/number back out
+ * of a private-repo attachment key, or undefined for any other key shape.
+ * Cannot recover the repo — callers that need it read `gh.repo` metadata.
+ */
+export function parseGhPrivateKey(key) {
+    const match = /^gh\/private\/([0-9a-f]{32})\/(pull|issues)\/([1-9][0-9]*)\/./.exec(key);
+    if (!match)
+        return undefined;
+    const [, prefixId, kind, num] = match;
+    return { prefixId, kind: kind, num: Number(num) };
+}
 export function ghKeyPrefix(target) {
     const [owner, name] = target.repo.split("/");
     return `gh/${sanitizeKeySegment(owner)}/${sanitizeKeySegment(name)}/${target.kind}/${target.num}/`;
@@ -91,6 +155,26 @@ export function ghBranchKeyPrefix(repo, branch) {
 export function ghBranchAttachmentKey(repo, branch, filename) {
     return `${ghBranchKeyPrefix(repo, branch)}${sanitizeKeySegment(filename)}`;
 }
+/**
+ * Mode-owning attachment key builder: collapses the
+ * `mode === "private" ? ghPrivateAttachmentKey(...) : ghAttachmentKey(...)`
+ * ternary repeated across call sites into one place.
+ */
+export function ghAttachmentKeyForMode(mode, target, filename) {
+    return mode.mode === "private"
+        ? ghPrivateAttachmentKey(mode.prefixId, target, filename)
+        : ghAttachmentKey(target, filename);
+}
+/**
+ * Mode-owning branch-staged attachment key builder. The private form
+ * ignores `repo`/`branch` (a private-repo key has no branch-name segment,
+ * see `ghPrivateBranchKeyPrefix`) and uses the prefix id instead.
+ */
+export function ghBranchAttachmentKeyForMode(mode, repo, branch, filename) {
+    return mode.mode === "private"
+        ? ghPrivateBranchAttachmentKey(mode.prefixId, filename)
+        : ghBranchAttachmentKey(repo, branch, filename);
+}
 /**
  * `gh.*` metadata for a branch-staged attach: `gh.repo`, `gh.kind=branch`,
  * `gh.branch` (lowercased), and `gh.staged-at` (ISO 8601 UTC, no fractional

package/dist/index.d.ts

@@ -4,10 +4,10 @@ export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey
 export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, resolveDestinationRoot, resolvePutPrefix, type BuiltinDestinationId, } from "./destinations.js";
 export { DEFAULT_API_URL, DEFAULT_WORKSPACE, UPLOADS_CONFIG_KEYS, defaultConfigPath, resolveConfigPath, loadConfigFile, loadEnvFile, resolveApiUrl, resolveConfig, describeConfigSources, redactToken, writeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, workspaceFromToken, workspaceMismatch, type UploadsClientConfig, type ResolvedConfig, type WorkspaceSource, type ConfigValueSource, type ConfigSources, type UploadsConfigKey, type UploadsConfigValues, type PutDefaults, } from "./config.js";
 export { UploadsError, type UploadsErrorCode } from "./errors.js";
-export { createUploadsClient, type UploadsClient, type PutOptions, type ProvenanceInput, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type GalleryItem, type Gallery, type GallerySummary, type GalleryListOptions, type GalleryListResult, type CreateGalleryOptions, type AddGalleryItemOptions, type DeleteGalleryOptions, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, type FindFilesOptions, type FindFilesItem, type FindFilesResult, type MetadataKeysResult, type MetadataValuesResult, type GetMetadataResult, type PatchMetadataOptions, } from "./client.js";
+export { createUploadsClient, type UploadsClient, type PutOptions, type ProvenanceInput, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type GalleryItem, type Gallery, type GallerySummary, type GalleryListOptions, type GalleryListResult, type CreateGalleryOptions, type AddGalleryItemOptions, type DeleteGalleryOptions, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, type FindFilesOptions, type FindFilesItem, type FindFilesResult, type MetadataKeysResult, type MetadataValuesResult, type GetMetadataResult, type PatchMetadataOptions, type ResolveGhPrefixOptions, type ResolveGhPrefixResult, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";
-export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, type AttachmentItem, type GhTarget, type GhTargetKind, } from "./github.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, GH_PRIVATE_ROOT, ghPrivateKeyPrefix, ghPrivateAttachmentKey, ghPrivateBranchKeyPrefix, ghPrivateBranchAttachmentKey, ghAttachmentKeyForMode, ghBranchAttachmentKeyForMode, parseGhKey, parseGhPrivateKey, type AttachmentItem, type GhTarget, type GhTargetKind, type GhKeyMode, } from "./github.js";
 export { DEFAULT_OPTIMIZE_MAX_EDGE, DEFAULT_OPTIMIZE_QUALITY, optimizeImageForUpload, rewriteKeyExtension, withImageExtension, type OptimizeImageOptions, type OptimizeImageResult, type OptimizeOutputFormat, } from "./optimize.js";
 export { FRAME_PRESETS, applyFrame, listFramePresets, resolveFrameId, type FrameFit, type FrameOptions, type FrameResult, } from "./frame.js";
 export { execRunner, resolveRepo, upsertAttachmentsComment, type CommandRunner, } from "./github-gh.js";

package/dist/index.js

@@ -7,7 +7,11 @@ export { UploadsError } from "./errors.js";
 export { createUploadsClient, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";
-export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, 
+// Private-repo randomized-prefix builders (issue #631) — needed by the
+// hosted MCP (apps/mcp), which builds keys in-process rather than via
+// the CLI's own commands.ts.
+GH_PRIVATE_ROOT, ghPrivateKeyPrefix, ghPrivateAttachmentKey, ghPrivateBranchKeyPrefix, ghPrivateBranchAttachmentKey, ghAttachmentKeyForMode, ghBranchAttachmentKeyForMode, parseGhKey, parseGhPrivateKey, } from "./github.js";
 export { DEFAULT_OPTIMIZE_MAX_EDGE, DEFAULT_OPTIMIZE_QUALITY, optimizeImageForUpload, rewriteKeyExtension, withImageExtension, } from "./optimize.js";
 export { FRAME_PRESETS, applyFrame, listFramePresets, resolveFrameId, } from "./frame.js";
 export { execRunner, resolveRepo, upsertAttachmentsComment, } from "./github-gh.js";

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

@@ -1,10 +1,11 @@
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, makeGhTarget, mergeStagingMeta, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
+import { buildDoctorReport, ghListPrefixes, ghMergedList, makeGhTarget, mergeStagingMeta, resolveGhPrefixSafe, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
-import { ghBranchAttachmentKey, ghKeyPrefix } from "../github.js";
+import { ghKeyPrefix, ghPrivateKeyPrefix } 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.
@@ -778,14 +801,26 @@ export function createUploadsMcpTools(opts) {
                     }
                     throw err;
                 }
-                const branchKey = stagingTarget
-                    ? ghBranchAttachmentKey(stagingTarget.repo, stagingTarget.branch, captured.filename)
-                    : undefined;
+                // Resolved once (issue #631), only now that upload is actually
+                // about to happen — never per file (screenshot uploads exactly one).
+                const ghPrefix = target
+                    ? await resolveGhPrefixSafe(client, {
+                        repo: target.repo,
+                        target: { kind: target.kind, num: target.num },
+                    })
+                    : stagingTarget
+                        ? await resolveGhPrefixSafe(client, {
+                            repo: stagingTarget.repo,
+                            branch: stagingTarget.branch,
+                        })
+                        : undefined;
                 const { result, prepared, markdown } = await uploadPreparedImage(client, captured.png, captured.filename, {
                     frame: frameOpts,
                     optimize: optimizeOpts,
                     ghTarget: target,
-                    key: keyArg ?? branchKey,
+                    ghBranchTarget: stagingTarget,
+                    ghPrefix,
+                    key: keyArg,
                     prefix: resolvedPrefix ?? defaults.prefix,
                     repo: optString(args, "repo") ?? defaults.repo,
                     ref: refArg ?? defaults.ref,
@@ -957,16 +992,35 @@ export function createUploadsMcpTools(opts) {
                 const prefixArg = optString(args, "prefix");
                 let prefix = prefixArg ?? (defaults.prefix ? `${defaults.prefix}/` : undefined);
                 const target = ghTargetFromArgs(args, run);
+                const { client } = clientFor(args);
+                // Also list every active private prefix, if any (issue #631) —
+                // mirrors syncAttachmentsComment's gh-fallback gather: a repo's
+                // attachment history can be split across the plain shape and
+                // MULTIPLE private prefixes, not just the currently-resolved one.
+                // `prefixes` stays undefined outside pr/issue (unchanged behavior);
+                // collapses to `[prefix]` in plain mode, so the single-request path
+                // below is byte-identical to pre-#631.
+                let prefixes;
                 if (target) {
                     if (prefixArg)
                         usage("prefix cannot be combined with pr/issue");
                     prefix = ghKeyPrefix(target);
+                    const ghPrefix = await resolveGhPrefixSafe(client, {
+                        repo: target.repo,
+                        target: { kind: target.kind, num: target.num },
+                    });
+                    prefixes = ghListPrefixes(prefix, ghPrefix, (id) => ghPrivateKeyPrefix(id, target));
                 }
                 const limit = optPosInt(args, "limit");
                 const cursor = optString(args, "cursor");
-                const { client } = clientFor(args);
                 if (optBool(args, "all")) {
-                    const items = await client.listAll({ prefix, limit, cursor });
+                    const items = prefixes && prefixes.length > 1
+                        ? await ghMergedList(prefixes, cursor, (p, c) => client.listAll({ prefix: p, limit, cursor: c }))
+                        : await client.listAll({ prefix, limit, cursor });
+                    return { items, cursor: null };
+                }
+                if (prefixes && prefixes.length > 1) {
+                    const items = await ghMergedList(prefixes, cursor, async (p, c) => (await client.list({ prefix: p, limit, cursor: c })).items);
                     return { items, cursor: null };
                 }
                 return client.list({ prefix, limit, cursor });

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.41.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"
   },