@buildinternet/uploads 0.13.0 → 0.14.0

package/dist/client.d.ts

@@ -1,4 +1,6 @@
 import type { UploadsClientConfig } from "./config.js";
+/** Scoped-operator-token permission scope. */
+export type TokenScope = "files:read" | "files:write" | "files:delete" | "operator:read" | "operator:write" | "workspace:invite" | "workspace:manage";
 /** Allowlisted object provenance (maps to X-Uploads-Meta-* on put). */
 export type ProvenanceInput = {
     client?: string;
@@ -168,6 +170,17 @@ export interface FindGalleriesByReferenceOptions {
     limit?: number;
     cursor?: string;
 }
+/** Reasons the bot did not post; the CLI treats any of them as "fall back to gh". */
+export type GithubCommentDeclineReason = "app_unconfigured" | "not_installed" | "forbidden" | "unavailable";
+export type GithubCommentResult = {
+    posted: true;
+    action: "created" | "updated" | "skipped";
+    count: number;
+    commentUrl?: string;
+} | {
+    posted: false;
+    reason: GithubCommentDeclineReason;
+};
 export interface HealthResult {
     ok: boolean;
 }
@@ -212,7 +225,7 @@ export interface EnrollmentExchangeResult {
     apiUrl?: string;
     workspace: string;
     token: string;
-    scopes?: Array<"files:read" | "files:write" | "files:delete">;
+    scopes?: Array<TokenScope>;
     expiresAt?: string;
 }
 export interface EnrollmentCreateResult {
@@ -229,9 +242,16 @@ export declare function createEnrollment(apiUrl: string, adminToken: string, inp
     email?: string;
     enrollmentSeconds?: number;
     tokenExpiresInSeconds?: number;
-    scopes?: Array<"files:read" | "files:write" | "files:delete">;
+    scopes?: Array<TokenScope>;
 }): Promise<EnrollmentCreateResult>;
-/** Static OAuth client id allowlisted by the auth worker's `validateClient`. */
+/**
+ * OAuth client id for the device flow. Registered server-side as a managed
+ * official `oauth_client` row (seeded by apps/auth migration
+ * 20260719000000_seed_cli_oauth_client.sql — issue #251): public PKCE client,
+ * no secret, device-code grant only. The auth worker's device endpoints
+ * validate this id against that table, so operators can disable it from
+ * /admin/oauth. The literal must match the seeded row's client_id.
+ */
 export declare const DEVICE_CLIENT_ID = "uploads-cli";
 /**
  * User-Agent for device-flow requests. Stored on the Better Auth session row
@@ -302,7 +322,7 @@ export declare function createWorkspaceRequest(apiUrl: string, accessToken: stri
 export interface MintTokenResult {
     token: string;
     workspace: string;
-    scopes: Array<"files:read" | "files:write" | "files:delete">;
+    scopes: Array<TokenScope>;
     label: string | null;
     expiresAt: string | null;
 }
@@ -332,7 +352,7 @@ export declare function createWorkspaceInvite(apiUrl: string, accessToken: strin
  */
 export declare function mintWorkspaceToken(apiUrl: string, accessToken: string, input: {
     workspace: string;
-    scopes?: Array<"files:read" | "files:write" | "files:delete">;
+    scopes?: Array<TokenScope>;
     label?: string;
     ttlSeconds?: number;
 }): Promise<MintTokenResult>;
@@ -387,6 +407,11 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
         id: string;
     }>;
     findGalleriesByReference(opts: FindGalleriesByReferenceOptions): Promise<GalleryListResult>;
+    upsertGithubComment(opts: {
+        repo: string;
+        num: number;
+        kind: "pull" | "issues";
+    }): Promise<GithubCommentResult>;
     health(): Promise<HealthResult>;
     /** Workspace storage / upload counters (+ limits when configured). */
     usage(): Promise<UsageResult>;

package/dist/client.js

@@ -37,7 +37,14 @@ export function createEnrollment(apiUrl, adminToken, input) {
 // D5). Better Auth's `device.code`/`device.token` endpoints take
 // `application/json` bodies, NOT the RFC's form-encoding — the JSON shapes
 // below are what the worker expects.
-/** Static OAuth client id allowlisted by the auth worker's `validateClient`. */
+/**
+ * OAuth client id for the device flow. Registered server-side as a managed
+ * official `oauth_client` row (seeded by apps/auth migration
+ * 20260719000000_seed_cli_oauth_client.sql — issue #251): public PKCE client,
+ * no secret, device-code grant only. The auth worker's device endpoints
+ * validate this id against that table, so operators can disable it from
+ * /admin/oauth. The literal must match the seeded row's client_id.
+ */
 export const DEVICE_CLIENT_ID = "uploads-cli";
 /**
  * User-Agent for device-flow requests. Stored on the Better Auth session row
@@ -445,6 +452,12 @@ export function createUploadsClient(config) {
                 params.set("cursor", opts.cursor);
             return request("GET", galleriesBase(config) + "/by-reference?" + params);
         },
+        async upsertGithubComment(opts) {
+            return request("POST", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/comment`, {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
         async health() {
             return request("GET", `${config.apiUrl}/health`, { auth: false });
         },

package/dist/commands/screenshot.js

@@ -2,12 +2,11 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { writeCommandHelp } from "../cli-style.js";
-import { frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, syncAttachmentsComment, uploadPreparedImage, } from "../commands.js";
+import { frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, } from "../commands.js";
 import { resolvePutDefaults } from "../config.js";
 import { loadDefaultsRaw, resolveScreenshotDefaults } from "../config-file.js";
 import { resolvePutPrefix } from "../destinations.js";
-import { ghMetadataFromTarget } from "../github.js";
-import { execRunner } from "../github-gh.js";
+import { execRunner, ghMetadataFromTargetWithTitle } from "../github-gh.js";
 import { parseMetaFlags, validateMetaMap } from "../metadata.js";
 import { writeJson, writeStdout } from "../io.js";
 import { assertHideSelector, captureScreenshot, parseViewport, parseWaitUntil, } from "../screenshot.js";
@@ -67,7 +66,9 @@ Options:
   --keep-exif               Keep EXIF/XMP/ICC when optimizing
   --pr <num>                Attach to a pull request (stable URL, no hash)
   --issue <num>             Attach to an issue
-  --comment                 With --pr/--issue: update the managed attachments comment
+  --comment                 With --pr/--issue: update the managed attachments comment.
+                             Posts as uploads-sh[bot] when the GitHub App is installed;
+                             otherwise via local gh.
   --gallery <id>            Add the uploaded object to this public gallery
   --meta <k=v>              Queryable custom metadata (repeatable)
   --workspace, -w <name>    Override workspace
@@ -214,7 +215,7 @@ captureImpl = captureScreenshot) {
     const metaExtras = parseMetaFlags(flagValues(parsed.flags, "--meta"));
     let metadata = metaExtras;
     if (ghTarget) {
-        metadata = { ...metaExtras, ...ghMetadataFromTarget(ghTarget) };
+        metadata = { ...metaExtras, ...ghMetadataFromTargetWithTitle(ghTarget, run) };
         validateMetaMap(metadata);
     }
     else if (Object.keys(metaExtras).length > 0) {
@@ -296,7 +297,7 @@ captureImpl = captureScreenshot) {
         try {
             comment = await syncAttachmentsComment(ctx.client, ghTarget, run);
             if (logHuman)
-                process.stderr.write(`>> attachments comment ${comment.action}\n`);
+                process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         }
         catch (err) {
             commentError = err instanceof Error ? err.message : String(err);

package/dist/commands.d.ts

@@ -89,13 +89,22 @@ export declare function frameOptionsFromFlags(flags: CommandFlags["flags"]): {
 };
 /**
  * List every attachment under the target's prefix and create/update the
- * managed comment. Throws on gh failure — callers decide whether that is
- * fatal (`comment` command) or a warning (`put --comment`).
+ * managed comment. Prefers the server-side bot endpoint (`uploads-sh[bot]`,
+ * rendered from this workspace's own data); any failure to post that way —
+ * not installed, declined, self-hosted 404, network error — falls through to
+ * the local-`gh` path so self-hosters keep working unchanged. Throws on gh
+ * failure — callers decide whether that is fatal (`comment` command) or a
+ * warning (`put --comment`).
  */
-export declare function syncAttachmentsComment(client: UploadsClient, target: GhTarget, run: CommandRunner): Promise<{
+export interface AttachmentsCommentResult {
     action: "created" | "updated" | "skipped";
     count: number;
-}>;
+    /** Who posted the comment: the GitHub App bot, or the local `gh` fallback. */
+    via: "bot" | "gh";
+}
+/** Human-mode suffix noting who posted the managed comment. */
+export declare function commentViaSuffix(via: AttachmentsCommentResult["via"]): string;
+export declare function syncAttachmentsComment(client: UploadsClient, target: GhTarget, run: CommandRunner): Promise<AttachmentsCommentResult>;
 export type AttachUploadItem = PutResult & {
     file: string;
     markdown: string;

package/dist/commands.js

@@ -10,7 +10,7 @@ import { UploadsError } from "./errors.js";
 import { writeJson, writeStdout } from "./io.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, attachmentsCommentBody, normalizeGithubCoordinate, } from "./github.js";
-import { resolveRepo, resolveCurrentPullRequest, classifyGhNumber, execRunner, upsertAttachmentsComment, } from "./github-gh.js";
+import { resolveRepo, resolveCurrentPullRequest, classifyGhNumber, execRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
 import { resolvePutPrefix } from "./destinations.js";
 import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
 import { applyFrame, resolveFrameId } from "./frame.js";
@@ -89,7 +89,9 @@ Options:
   --format human|url|markdown|json
   --pr <num>            Attach to a pull request: key gh/<owner>/<repo>/pull/<num>/<name> (stable URL, no hash)
   --issue <num>         Attach to an issue: key gh/<owner>/<repo>/issues/<num>/<name>
-  --comment             With --pr/--issue: update one managed comment with attachments and linked galleries via local gh auth
+  --comment             With --pr/--issue: update one managed comment with
+                        attachments and linked galleries. Posts as uploads-sh[bot]
+                        when the GitHub App is installed; otherwise via local gh.
   --gallery <id>         Add the uploaded object(s) to this public gallery
   --meta <k=v>          Queryable custom metadata (repeatable; value may contain "="): key ^[a-z][a-z0-9._-]{0,63}$, value 1-512 printable ASCII, max 24 pairs
                         Re-uploading to an existing key WITH --meta replaces that file's
@@ -272,12 +274,25 @@ export function frameOptionsFromFlags(flags) {
         throw new UsageError("--frame-url requires --frame");
     return { frameId, frameUrl, frameFit };
 }
-/**
- * List every attachment under the target's prefix and create/update the
- * managed comment. Throws on gh failure — callers decide whether that is
- * fatal (`comment` command) or a warning (`put --comment`).
- */
+/** Human-mode suffix noting who posted the managed comment. */
+export function commentViaSuffix(via) {
+    return via === "bot" ? " (uploads-sh[bot])" : " (via gh)";
+}
 export async function syncAttachmentsComment(client, target, run) {
+    try {
+        const bot = await client.upsertGithubComment({
+            repo: target.repo,
+            num: target.num,
+            kind: target.kind,
+        });
+        if (bot.posted)
+            return { action: bot.action, count: bot.count, via: "bot" };
+    }
+    catch {
+        // Endpoint absent/unreachable (self-hosted, network, older worker) — fall
+        // through to the gh path below.
+    }
+    // gh fallback: gather from this workspace's own data and post via local `gh`.
     const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url, embedUrl }) => ({ key, url, embedUrl }));
     const galleries = [];
     let cursor;
@@ -313,10 +328,14 @@ export async function syncAttachmentsComment(client, target, run) {
         }
     }));
     if (items.length === 0 && previewGalleries.length === 0)
-        return { action: "skipped", count: 0 };
+        return { action: "skipped", count: 0, via: "gh" };
     const body = attachmentsCommentBody(items, previewGalleries);
     const { created } = upsertAttachmentsComment(target, body, run);
-    return { action: created ? "created" : "updated", count: items.length + previewGalleries.length };
+    return {
+        action: created ? "created" : "updated",
+        count: items.length + previewGalleries.length,
+        via: "gh",
+    };
 }
 // --- attach ---
 const ATTACH_HELP = `uploads attach <file...> [options]
@@ -532,9 +551,9 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     // target pairs always win over a same-named --meta extra (documented above).
     // Validate the merged map (not just the extras) so the 24-key/8KB caps are
     // enforced client-side even when extras alone are under the cap but extras
-    // + the 4 gh.* pairs push the merged map over it.
+    // + the gh.* pairs push the merged map over it.
     const metaExtras = parseMetaFlags(flagValues(parsed.flags, "--meta"));
-    const metadata = { ...metaExtras, ...ghMetadataFromTarget(target) };
+    const metadata = { ...metaExtras, ...ghMetadataFromTargetWithTitle(target, run) };
     if (Object.keys(metadata).length > 0)
         validateMetaMap(metadata);
     const logHuman = !ctx.quiet && !ctx.json;
@@ -588,7 +607,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
             process.stderr.write(`warning: could not upload ${failure.file}: ${failure.error.message}\n`);
         }
         if (!ctx.quiet && comment)
-            process.stderr.write(`>> attachments comment ${comment.action}\n`);
+            process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         if (!ctx.quiet && uploads.length > 0) {
             const ref = ghMetadataFromTarget(target)["gh.ref"];
             process.stderr.write(`>> find these later: uploads find gh.ref=${ref}\n`);
@@ -711,7 +730,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     let metadata = userMeta;
     let attachedRef;
     if (ghTarget) {
-        const merged = { ...userMeta, ...ghMetadataFromTarget(ghTarget) };
+        const merged = { ...userMeta, ...ghMetadataFromTargetWithTitle(ghTarget, run) };
         validateMetaMap(merged); // enforce 24-key/8KB caps on the merged map (matches attach)
         metadata = merged;
         attachedRef = merged["gh.ref"];
@@ -723,7 +742,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         if (autoEnabled) {
             const autoTarget = resolveAutoGhTarget(flagString(parsed.flags, "--repo") ?? defaults.repo, flagString(parsed.flags, "--ref") ?? defaults.ref, run);
             if (autoTarget) {
-                const autoMeta = ghMetadataFromTarget(autoTarget);
+                const autoMeta = ghMetadataFromTargetWithTitle(autoTarget, run);
                 const merged = { ...autoMeta, ...userMeta };
                 // Auto resolution must never fail the upload: if merging the gh.* pairs
                 // would exceed the metadata caps, drop them and upload with --meta only.
@@ -798,7 +817,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         try {
             comment = await syncAttachmentsComment(ctx.client, ghTarget, run);
             if (logHuman)
-                process.stderr.write(`>> attachments comment ${comment.action}\n`);
+                process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         }
         catch (err) {
             commentError = err instanceof Error ? err.message : String(err);
@@ -1322,7 +1341,8 @@ export async function runDelete(ctx, args, help = false) {
 const COMMENT_HELP = `uploads comment (--pr <num> | --issue <num>) [--repo <owner/name>] [--workspace <name>]
 
 Create or update the managed attachments comment on a GitHub PR or issue,
-listing everything uploaded for it. Uses your local gh auth. Finds its own
+listing everything uploaded for it. Posts as uploads-sh[bot] when the GitHub
+App is installed on the repo; otherwise via your local gh auth. Finds its own
 prior comment via a hidden marker and edits it in place; never touches other
 comments or the description.
 
@@ -1344,9 +1364,10 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
         await writeJson({ ...target, ...result });
     }
     else if (!ctx.quiet) {
+        const via = commentViaSuffix(result.via);
         process.stderr.write(result.action === "skipped"
             ? `no attachments under ${ghKeyPrefix(target)} — nothing to do\n`
-            : `${result.action} attachments comment on ${target.repo}#${target.num} (${result.count} file${result.count === 1 ? "" : "s"})\n`);
+            : `${result.action} attachments comment on ${target.repo}#${target.num} (${result.count} file${result.count === 1 ? "" : "s"})${via}\n`);
     }
     return 0;
 }

package/dist/github-gh.d.ts

@@ -16,6 +16,25 @@ export declare function resolveCurrentPullRequest(repo: string, run?: CommandRun
  * uploads without metadata.
  */
 export declare function classifyGhNumber(repo: string, num: number, run?: CommandRunner): GhTarget | 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 declare function resolveGhTitle(target: GhTarget, run?: CommandRunner): string | 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 declare function ghMetadataFromTargetWithTitle(target: GhTarget, run?: CommandRunner): Record<string, string>;
 /**
  * Create the managed attachments comment, or edit it in place if it already
  * exists. Never touches any other comment. Body is passed via stdin

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`
@@ -91,12 +92,62 @@ 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.
  */
 function findManagedComment(target, run) {
-    const raw = run("gh", ["api", `repos/${target.repo}/issues/${target.num}/comments?per_page=100`]);
+    const raw = run("gh", [
+        "api",
+        `repos/${target.repo}/issues/${target.num}/comments?per_page=100`,
+        "--paginate",
+    ]);
     const comments = JSON.parse(raw);
     return comments.find((c) => typeof c.body === "string" && c.body.includes(ATTACHMENTS_MARKER));
 }

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";
@@ -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({

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.0",
+  "version": "0.14.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,