@buildinternet/uploads 0.14.0 → 0.16.0

package/dist/github-gh.d.ts

@@ -9,6 +9,8 @@ export declare const execRunner: CommandRunner;
 export declare function resolveRepo(explicit: string | undefined, run?: CommandRunner): string;
 /** Resolve the pull request associated with the current branch. */
 export declare function resolveCurrentPullRequest(repo: string, run?: CommandRunner): GhTarget;
+/** Resolve the current git branch (`--branch` with no value). Throws UsageError on detached HEAD or outside a git repo. */
+export declare function resolveCurrentBranch(run?: CommandRunner): string;
 /**
  * Classify a bare PR/issue number via the GitHub API so the default `put`
  * path can stamp the right `gh.kind`. Returns undefined on any failure (gh
@@ -39,7 +41,13 @@ export declare function ghMetadataFromTargetWithTitle(target: GhTarget, run?: Co
  * Create the managed attachments comment, or edit it in place if it already
  * exists. Never touches any other comment. Body is passed via stdin
  * (`-F body=@-`) so it is never shell-interpolated.
+ *
+ * `marker` identifies which comment to hunt for (see `findManagedComment`);
+ * `body` is expected to already carry that same marker as its first line
+ * (built via `attachmentsCommentBody(items, galleries, marker)`), so patching
+ * an adopted legacy comment migrates it to the namespaced marker in place.
+ * Defaults to the shared legacy marker for backward compatibility.
  */
-export declare function upsertAttachmentsComment(target: GhTarget, body: string, run?: CommandRunner): {
+export declare function upsertAttachmentsComment(target: GhTarget, body: string, run?: CommandRunner, marker?: string): {
     created: boolean;
 };

package/dist/github-gh.js

@@ -68,6 +68,20 @@ export function resolveCurrentPullRequest(repo, run = execRunner) {
     }
     throw new UsageError("could not infer a pull request for the current branch — pass --pr <num> or --issue <num>");
 }
+/** Resolve the current git branch (`--branch` with no value). Throws UsageError on detached HEAD or outside a git repo. */
+export function resolveCurrentBranch(run = execRunner) {
+    let branch;
+    try {
+        branch = run("git", ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    }
+    catch {
+        throw new UsageError("could not determine the current git branch — pass --branch <name> or run inside a git repo");
+    }
+    if (branch === "" || branch === "HEAD") {
+        throw new UsageError("could not determine the current branch (detached HEAD) — pass --branch <name>");
+    }
+    return branch;
+}
 /**
  * Classify a bare PR/issue number via the GitHub API so the default `put`
  * path can stamp the right `gh.kind`. Returns undefined on any failure (gh
@@ -141,23 +155,41 @@ export function ghMetadataFromTargetWithTitle(target, run = execRunner) {
  * PR comments live on the issues endpoint, so one path covers PRs and issues.
  * `--paginate` follows Link headers and merges every page into one array, so the
  * marker comment is found even on threads past 100 comments.
+ *
+ * Hunts for `marker` (the namespaced, per-workspace marker) first; when none
+ * is found, falls back to a comment carrying the shared legacy
+ * `ATTACHMENTS_MARKER` (pre-4b, unnamespaced) so it can be adopted and
+ * migrated in place. When `marker` IS the legacy marker (no workspace to
+ * namespace with) this collapses to a single hunt, unchanged from pre-4b
+ * behavior.
  */
-function findManagedComment(target, run) {
+function findManagedComment(target, run, marker) {
     const raw = run("gh", [
         "api",
         `repos/${target.repo}/issues/${target.num}/comments?per_page=100`,
         "--paginate",
     ]);
     const comments = JSON.parse(raw);
+    const namespacedHit = comments.find((c) => typeof c.body === "string" && c.body.includes(marker));
+    if (namespacedHit)
+        return namespacedHit;
+    if (marker === ATTACHMENTS_MARKER)
+        return undefined;
     return comments.find((c) => typeof c.body === "string" && c.body.includes(ATTACHMENTS_MARKER));
 }
 /**
  * Create the managed attachments comment, or edit it in place if it already
  * exists. Never touches any other comment. Body is passed via stdin
  * (`-F body=@-`) so it is never shell-interpolated.
+ *
+ * `marker` identifies which comment to hunt for (see `findManagedComment`);
+ * `body` is expected to already carry that same marker as its first line
+ * (built via `attachmentsCommentBody(items, galleries, marker)`), so patching
+ * an adopted legacy comment migrates it to the namespaced marker in place.
+ * Defaults to the shared legacy marker for backward compatibility.
  */
-export function upsertAttachmentsComment(target, body, run = execRunner) {
-    const existing = findManagedComment(target, run);
+export function upsertAttachmentsComment(target, body, run = execRunner, marker = ATTACHMENTS_MARKER) {
+    const existing = findManagedComment(target, run, marker);
     if (existing) {
         run("gh", [
             "api",

package/dist/github.d.ts

@@ -22,6 +22,26 @@ export declare function ghKeyPrefix(target: GhTarget): string;
  * (unlike buildScreenshotKey).
  */
 export declare function ghAttachmentKey(target: GhTarget, filename: string): string;
+/**
+ * Branch-staged attachment key prefix: `gh/<owner>/<repo>/branch/<branch>/`.
+ * Pre-PR staging (Phase 1 of branch-staged attachments) — no PR/issue number
+ * exists yet. `branch` goes through `sanitizeKeySegment` like every other key
+ * segment, so e.g. `feature/x` becomes `feature-x`.
+ */
+export declare function ghBranchKeyPrefix(repo: string, branch: string): string;
+/** Branch-staged attachment key: `ghBranchKeyPrefix` + the sanitized filename. */
+export declare function ghBranchAttachmentKey(repo: string, branch: string, filename: string): string;
+/**
+ * `gh.*` metadata for a branch-staged attach: `gh.repo`, `gh.kind=branch`,
+ * `gh.branch` (lowercased), and `gh.staged-at` (ISO 8601 UTC, no fractional
+ * seconds). No `gh.number`/`gh.ref`/`gh.title` — there is no PR/issue yet.
+ * Throws `UsageError` when the lowercased branch name fails the metadata
+ * value rule (printable ASCII, 1-512 chars) — unlike `gh.title`'s best-effort
+ * degrade, a branch name the caller explicitly chose (via `--branch` or the
+ * current git branch) is worth failing loudly on rather than silently
+ * dropping from the metadata set.
+ */
+export declare function ghMetadataForBranch(repo: string, branch: string, now?: Date): Record<string, string>;
 /**
  * The four `gh.*` queryable-metadata pairs `uploads attach` writes
  * automatically (`.context/2026-07-13-file-metadata-design.md`). `gh.kind`
@@ -36,11 +56,25 @@ export declare function ghAttachmentKey(target: GhTarget, filename: string): str
 export declare function ghMetadataFromTarget(target: GhTarget): Record<string, string>;
 /** Hidden marker identifying the one comment this CLI manages. Never change it — existing comments are found by exact match. */
 export declare const ATTACHMENTS_MARKER = "<!-- uploads.sh:attachments -->";
+/**
+ * Per-workspace marker (`<!-- uploads.sh:attachments ws=<workspace> -->`) so
+ * two workspaces managing the same repo don't clobber each other's comment.
+ * Falls back to the shared legacy marker when `workspace` is missing or does
+ * not look like a safe slug — degrade, don't guess or risk breaking the
+ * comment's HTML.
+ */
+export declare function attachmentsMarker(workspace?: string): string;
+/** Max attachments embedded as inline `<img>` tags before the rest collapse
+ * into a `<details>` link list. Keeps very large threads from becoming a wall
+ * of images. */
+export declare const MAX_INLINE_ATTACHMENT_IMAGES = 16;
 export interface AttachmentItem {
     key: string;
     url: string | null;
     /** Prefer for `<img src>` on GitHub (Camo-friendly host). Falls back to `url`. */
     embedUrl?: string | null;
+    /** Canonical `/f/` file-page URL (server-computed). Preferred click-through target; falls back to `url`. */
+    pageUrl?: string | null;
 }
 /** A public gallery linked to the PR or issue whose managed comment is syncing. */
 export interface GalleryCommentItem {
@@ -70,4 +104,4 @@ export declare function attachmentImageWidth(filename: string): number;
  * Render the one marker-owned GitHub comment. When there are no galleries this
  * intentionally preserves the legacy attachment-only body byte-for-byte.
  */
-export declare function attachmentsCommentBody(items: AttachmentItem[], galleries?: GalleryCommentItem[]): string;
+export declare function attachmentsCommentBody(items: AttachmentItem[], galleries?: GalleryCommentItem[], marker?: string): string;

package/dist/github.js

@@ -1,5 +1,7 @@
 import { inferContentType } from "./embed.js";
 import { sanitizeKeySegment } from "./keys.js";
+import { UsageError } from "./cli-args.js";
+import { isMetaValueSafe } from "./metadata.js";
 const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 export function isValidRepo(repo) {
     return REPO_RE.test(repo);
@@ -63,6 +65,42 @@ export function ghKeyPrefix(target) {
 export function ghAttachmentKey(target, filename) {
     return `${ghKeyPrefix(target)}${sanitizeKeySegment(filename)}`;
 }
+/**
+ * Branch-staged attachment key prefix: `gh/<owner>/<repo>/branch/<branch>/`.
+ * Pre-PR staging (Phase 1 of branch-staged attachments) — no PR/issue number
+ * exists yet. `branch` goes through `sanitizeKeySegment` like every other key
+ * segment, so e.g. `feature/x` becomes `feature-x`.
+ */
+export function ghBranchKeyPrefix(repo, branch) {
+    const [owner, name] = repo.split("/");
+    return `gh/${sanitizeKeySegment(owner)}/${sanitizeKeySegment(name)}/branch/${sanitizeKeySegment(branch)}/`;
+}
+/** Branch-staged attachment key: `ghBranchKeyPrefix` + the sanitized filename. */
+export function ghBranchAttachmentKey(repo, branch, filename) {
+    return `${ghBranchKeyPrefix(repo, branch)}${sanitizeKeySegment(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
+ * seconds). No `gh.number`/`gh.ref`/`gh.title` — there is no PR/issue yet.
+ * Throws `UsageError` when the lowercased branch name fails the metadata
+ * value rule (printable ASCII, 1-512 chars) — unlike `gh.title`'s best-effort
+ * degrade, a branch name the caller explicitly chose (via `--branch` or the
+ * current git branch) is worth failing loudly on rather than silently
+ * dropping from the metadata set.
+ */
+export function ghMetadataForBranch(repo, branch, now = new Date()) {
+    const branchLower = branch.toLowerCase();
+    if (!isMetaValueSafe(branchLower)) {
+        throw new UsageError(`invalid --branch: "${branch}" must be printable ASCII to stage as gh.branch metadata`);
+    }
+    return {
+        "gh.repo": repo.toLowerCase(),
+        "gh.kind": "branch",
+        "gh.branch": branchLower,
+        "gh.staged-at": now.toISOString().replace(/\.\d{3}Z$/, "Z"),
+    };
+}
 /**
  * The four `gh.*` queryable-metadata pairs `uploads attach` writes
  * automatically (`.context/2026-07-13-file-metadata-design.md`). `gh.kind`
@@ -85,6 +123,28 @@ export function ghMetadataFromTarget(target) {
 }
 /** Hidden marker identifying the one comment this CLI manages. Never change it — existing comments are found by exact match. */
 export const ATTACHMENTS_MARKER = "<!-- uploads.sh:attachments -->";
+/** Workspace slugs are `[a-z0-9-]`-ish; only markers built from a slug matching
+ * this are trusted as a distinct namespace — anything else (empty, unsafe
+ * chars) degrades to the shared legacy marker rather than emitting untrusted
+ * text into comment HTML. */
+const WORKSPACE_SLUG_RE = /^[a-z0-9-]{1,64}$/;
+/**
+ * Per-workspace marker (`<!-- uploads.sh:attachments ws=<workspace> -->`) so
+ * two workspaces managing the same repo don't clobber each other's comment.
+ * Falls back to the shared legacy marker when `workspace` is missing or does
+ * not look like a safe slug — degrade, don't guess or risk breaking the
+ * comment's HTML.
+ */
+export function attachmentsMarker(workspace) {
+    if (workspace && WORKSPACE_SLUG_RE.test(workspace)) {
+        return `<!-- uploads.sh:attachments ws=${workspace} -->`;
+    }
+    return ATTACHMENTS_MARKER;
+}
+/** Max attachments embedded as inline `<img>` tags before the rest collapse
+ * into a `<details>` link list. Keeps very large threads from becoming a wall
+ * of images. */
+export const MAX_INLINE_ATTACHMENT_IMAGES = 16;
 /** Default max width for images in the managed attachments comment (HTML img). */
 export const ATTACHMENT_IMAGE_WIDTH_DEFAULT = 400;
 /** Portrait / device mockups — keep phones readable, not full-column. */
@@ -116,10 +176,10 @@ function escapeHtmlText(s) {
  * Render the one marker-owned GitHub comment. When there are no galleries this
  * intentionally preserves the legacy attachment-only body byte-for-byte.
  */
-export function attachmentsCommentBody(items, galleries = []) {
+export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMENTS_MARKER) {
     const sorted = items.toSorted((a, b) => a.key.localeCompare(b.key));
     const sortedGalleries = galleries.toSorted((a, b) => a.title.localeCompare(b.title) || a.url.localeCompare(b.url));
-    const lines = [ATTACHMENTS_MARKER];
+    const lines = [marker];
     if (sortedGalleries.length > 0) {
         lines.push("### 🖼️ Galleries", "");
         for (const gallery of sortedGalleries) {
@@ -136,27 +196,48 @@ export function attachmentsCommentBody(items, galleries = []) {
     }
     if (sorted.length > 0 || sortedGalleries.length === 0)
         lines.push("### 📎 Attachments", "");
+    let inlinedImages = 0;
+    const overflowImages = [];
     for (const item of sorted) {
         const name = item.key.slice(item.key.lastIndexOf("/") + 1);
         const stable = item.url;
         const src = item.embedUrl ?? item.url;
-        if (src && inferContentType(name).startsWith("image/")) {
+        const link = item.pageUrl ?? stable; // click-through: file page when known, else raw
+        const isImage = Boolean(src) && inferContentType(name).startsWith("image/");
+        if (isImage && inlinedImages >= MAX_INLINE_ATTACHMENT_IMAGES) {
+            // Cap hit — defer to the collapsed overflow list below rather than
+            // embedding every remaining image inline.
+            overflowImages.push(item);
+            continue;
+        }
+        if (isImage) {
+            inlinedImages++;
             // Markdown ![]() has no width control — phone frames become full-column giants.
-            // img src uses embed host when available (Camo revalidates); click-through keeps stable URL.
+            // img src uses embed host when available (Camo revalidates); click-through prefers the file page.
             const w = attachmentImageWidth(name);
             const alt = escapeHtmlAttr(name);
-            const href = escapeHtmlAttr(stable ?? src);
+            const href = escapeHtmlAttr(link ?? src);
             const imgSrc = escapeHtmlAttr(src);
             lines.push(`<a href="${href}"><img width="${w}" alt="${alt}" src="${imgSrc}"></a>`);
             lines.push("");
         }
-        else if (stable) {
-            lines.push(`- [${name}](${stable})`);
+        else if (link) {
+            lines.push(`- [${name}](${link})`);
         }
         else {
             lines.push(`- ${name}`);
         }
     }
+    if (overflowImages.length > 0) {
+        const n = overflowImages.length;
+        lines.push(`<details><summary>${n} more attachment${n === 1 ? "" : "s"}</summary>`, "");
+        for (const item of overflowImages) {
+            const name = item.key.slice(item.key.lastIndexOf("/") + 1);
+            const link = item.pageUrl ?? item.url;
+            lines.push(link ? `- [${name}](${link})` : `- ${name}`);
+        }
+        lines.push("", "</details>", "");
+    }
     lines.push('<sub>Maintained by <a href="https://uploads.sh">uploads.sh</a> — re-uploading a file with the same name updates it everywhere it is embedded.</sub>');
     return lines.join("\n");
 }

package/dist/index.d.ts

@@ -7,7 +7,7 @@ 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 GetMetadataResult, type PatchMetadataOptions, } 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, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, isValidRepo, parseRepoFromRemoteUrl, type AttachmentItem, type GhTarget, type GhTargetKind, } from "./github.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, type AttachmentItem, type GhTarget, type GhTargetKind, } 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,7 @@ 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, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, } 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/mcp/tools.js

@@ -123,11 +123,11 @@ export function createUploadsMcpTools(opts) {
         });
         return { config, client: clientFactory(config) };
     }
-    const syncComment = async (client, target) => {
+    const syncComment = async (client, target, workspace) => {
         let comment;
         let commentError;
         try {
-            comment = await syncAttachmentsComment(client, target, run);
+            comment = await syncAttachmentsComment(client, target, run, workspace);
         }
         catch (err) {
             // Uploads already succeeded; the comment is best-effort by design.
@@ -402,7 +402,7 @@ export function createUploadsMcpTools(opts) {
                 catch (err) {
                     usage(err instanceof Error ? err.message : String(err));
                 }
-                const { client } = clientFor(args);
+                const { config, client } = clientFor(args);
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
                 const frameOpts = mcpFrameOptions(args);
                 const optimizeOpts = mcpOptimizeOptions(args, defaults);
@@ -436,7 +436,7 @@ export function createUploadsMcpTools(opts) {
                         throw new ToolBatchError(batchFailureMessage(failures), { uploads, failures });
                     }
                     if (wantComment && target && uploads.length > 0) {
-                        const { comment, commentError } = await syncComment(client, target);
+                        const { comment, commentError } = await syncComment(client, target, config.workspace);
                         return { uploads, failures, comment, commentError };
                     }
                     return { uploads, failures };
@@ -469,7 +469,7 @@ export function createUploadsMcpTools(opts) {
                         filename: prepared.filename,
                     };
                     if (wantComment && target) {
-                        const { comment, commentError } = await syncComment(client, target);
+                        const { comment, commentError } = await syncComment(client, target, config.workspace);
                         return { ...result, markdown, optimize, frame: prepared.frame, comment, commentError };
                     }
                     return {
@@ -504,7 +504,7 @@ export function createUploadsMcpTools(opts) {
                     ...(dryRun ? { dryRun: true } : {}),
                 };
                 if (wantComment && target) {
-                    const { comment, commentError } = await syncComment(client, target);
+                    const { comment, commentError } = await syncComment(client, target, config.workspace);
                     return { ...flat, comment, commentError };
                 }
                 return flat;
@@ -761,7 +761,7 @@ export function createUploadsMcpTools(opts) {
                     ...(dryRun ? { dryRun: true } : {}),
                 };
                 if (wantComment && target) {
-                    const { comment, commentError } = await syncComment(client, target);
+                    const { comment, commentError } = await syncComment(client, target, config.workspace);
                     return { ...flat, comment, commentError };
                 }
                 return flat;
@@ -821,7 +821,7 @@ export function createUploadsMcpTools(opts) {
                 const explicitTarget = ghTargetFromArgs(args, run);
                 const target = explicitTarget ??
                     resolveCurrentPullRequest(resolveRepo(optString(args, "repo"), run), run);
-                const { client } = clientFor(args);
+                const { config, client } = clientFor(args);
                 const contentType = optString(args, "contentType");
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
                 const frameOpts = mcpFrameOptions(args);
@@ -856,7 +856,7 @@ export function createUploadsMcpTools(opts) {
                 }
                 if (optBool(args, "noComment"))
                     return { target, uploads, failures };
-                const { comment, commentError } = await syncComment(client, target);
+                const { comment, commentError } = await syncComment(client, target, config.workspace);
                 return { target, uploads, failures, comment, commentError };
             },
         },
@@ -1062,8 +1062,8 @@ export function createUploadsMcpTools(opts) {
                 const target = ghTargetFromArgs(args, run);
                 if (!target)
                     usage("comment requires pr or issue");
-                const { client } = clientFor(args);
-                const result = await syncAttachmentsComment(client, target, run);
+                const { config, client } = clientFor(args);
+                const result = await syncAttachmentsComment(client, target, run, config.workspace);
                 return { ...target, ...result };
             },
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,