@buildinternet/uploads 0.13.1 → 0.15.0

package/dist/github-gh.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { UsageError } from "./cli-args.js";
-import { ATTACHMENTS_MARKER, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
+import { ATTACHMENTS_MARKER, ghMetadataFromTarget, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
+import { META_VALUE_MAX, isMetaValueSafe } from "./metadata.js";
 export const execRunner = (cmd, args, input) => execFileSync(cmd, args, { encoding: "utf8", input, stdio: ["pipe", "pipe", "pipe"] });
 /**
  * Resolve "owner/name". Order: explicit --repo (validated) → `gh repo view`
@@ -67,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
@@ -91,22 +106,90 @@ export function classifyGhNumber(repo, num, run = execRunner) {
     }
     return undefined;
 }
+/**
+ * Best-effort PR/issue title lookup via local `gh`. Returns undefined on any
+ * failure (gh missing, unauthenticated, network, 404) — mirrors
+ * `resolveCurrentPullRequest`/`classifyGhNumber`'s degrade-don't-throw
+ * pattern. A title is a nice-to-have annotation, never a blocker: callers
+ * must never let this failure abort an upload.
+ */
+export function resolveGhTitle(target, run = execRunner) {
+    try {
+        const out = run("gh", [
+            target.kind === "pull" ? "pr" : "issue",
+            "view",
+            String(target.num),
+            "--repo",
+            target.repo,
+            "--json",
+            "title",
+            "--jq",
+            ".title",
+        ]).trim();
+        return out.length > 0 ? out : undefined;
+    }
+    catch {
+        // gh missing / unauthenticated / not found / network — caller skips
+        return undefined;
+    }
+}
+/**
+ * `ghMetadataFromTarget`'s 4 pairs, plus a best-effort `gh.title` (issue #267)
+ * when `resolveGhTitle` yields one that also satisfies the metadata-value
+ * rule every other pair follows (1-512 printable ASCII — `metadata.ts`'s
+ * `META_VALUE_MAX`/`isMetaValueSafe`). Truncated to `META_VALUE_MAX` first;
+ * a title left empty or unsafe by truncation (e.g. non-ASCII — real titles
+ * often contain emoji or curly quotes) is silently omitted rather than
+ * sanitized, matching `resolveGhTitle`'s own "degrade, don't fail the
+ * upload" contract.
+ */
+export function ghMetadataFromTargetWithTitle(target, run = execRunner) {
+    const base = ghMetadataFromTarget(target);
+    const title = resolveGhTitle(target, run);
+    if (title === undefined)
+        return base;
+    const truncated = title.length > META_VALUE_MAX ? title.slice(0, META_VALUE_MAX) : title;
+    return isMetaValueSafe(truncated) ? { ...base, "gh.title": truncated } : base;
+}
 /**
  * PR comments live on the issues endpoint, so one path covers PRs and issues.
- * Only the first 100 comments are searched (accepted v1 limitation).
+ * `--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) {
-    const raw = run("gh", ["api", `repos/${target.repo}/issues/${target.num}/comments?per_page=100`]);
+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

@@ -3,9 +3,9 @@ import { buildDoctorReport, makeGhTarget, syncAttachmentsComment, uploadAttachme
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
-import { ghKeyPrefix, ghMetadataFromTarget } from "../github.js";
+import { ghKeyPrefix } from "../github.js";
 import { validateMetaMap } from "../metadata.js";
-import { execRunner, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
+import { execRunner, ghMetadataFromTargetWithTitle, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
 import { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
 import { batchFailureMessage, ToolBatchError } from "./server.js";
 import { attachmentFromText, buildReportPayload, parseReportType, REPORT_TYPES, submitReport, validateReportMessage, } from "../report.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);
@@ -830,10 +830,10 @@ export function createUploadsMcpTools(opts) {
                 // explicit target pairs always win over a same-named metadata extra
                 // (mirrors runAttach in ../commands.js). Validate the merged map (not
                 // just the extras) so the 24-key/8KB caps are enforced client-side —
-                // extras alone might pass while extras + the 4 gh.* pairs exceed the
+                // extras alone might pass while extras + the gh.* pairs exceed the
                 // cap, which would otherwise only be caught server-side after upload.
                 const metaExtras = optStringRecord(args, "metadata") ?? {};
-                const metadata = { ...metaExtras, ...ghMetadataFromTarget(target) };
+                const metadata = { ...metaExtras, ...ghMetadataFromTargetWithTitle(target, run) };
                 if (Object.keys(metadata).length > 0)
                     validateMetaMap(metadata);
                 const { uploads, failures } = await uploadAttachments({
@@ -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/dist/metadata.d.ts

@@ -8,6 +8,14 @@ export declare const META_MAX_KEYS = 24;
 export declare const META_MAX_TOTAL_BYTES = 8192;
 /** Throws `UsageError` with a readable message if `key`/`value` violate the metadata rules. */
 export declare function validateMetaEntry(key: string, value: string): void;
+/**
+ * Non-throwing version of `validateMetaEntry`'s value check (length +
+ * printable-ASCII), for callers that want to silently drop a value that
+ * doesn't fit rather than reject the whole request — e.g. a best-effort
+ * `gh.title` derived from a real-world PR/issue title, which may contain
+ * unicode (emoji, curly quotes) that the metadata value rule disallows.
+ */
+export declare function isMetaValueSafe(value: string): boolean;
 /**
  * Split `k=v` on the FIRST "=" (so values may themselves contain "="), then
  * validate the pair. Throws `UsageError` on malformed input.

package/dist/metadata.js

@@ -38,6 +38,16 @@ export function validateMetaEntry(key, value) {
         throw new UsageError(`invalid metadata value for key "${key}": must be 1-${META_VALUE_MAX} printable ASCII characters`);
     }
 }
+/**
+ * Non-throwing version of `validateMetaEntry`'s value check (length +
+ * printable-ASCII), for callers that want to silently drop a value that
+ * doesn't fit rather than reject the whole request — e.g. a best-effort
+ * `gh.title` derived from a real-world PR/issue title, which may contain
+ * unicode (emoji, curly quotes) that the metadata value rule disallows.
+ */
+export function isMetaValueSafe(value) {
+    return value.length >= 1 && value.length <= META_VALUE_MAX && VALUE_SAFE_RE.test(value);
+}
 /**
  * Split `k=v` on the FIRST "=" (so values may themselves contain "="), then
  * validate the pair. Throws `UsageError` on malformed input.

package/package.json

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