@buildinternet/uploads 0.4.0 → 0.6.0

package/dist/commands/admin-enrollment.js

@@ -1,8 +1,12 @@
 import { createEnrollment } from "../client.js";
-import { flagInt, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
-const HELP = `uploads admin enrollment create [options]
+import { flagBool, flagInt, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
+const HELP = `uploads admin invite create [options]
 
-Admin-only: create a short-lived, one-time enrollment code.
+Admin-only: create a short-lived invitation for an existing workspace.
+Prints one magic link whose URL fragment carries the single-use code — treat the
+link like a password. Pass --separate-code for the legacy two-channel output (a
+non-secret page URL plus a code you share separately). The legacy
+"admin enrollment create" spelling is accepted.
 
 Options:
   --admin-token <token>  Or ADMIN_TOKEN (UPLOADS_ADMIN_TOKEN is a legacy alias)
@@ -11,9 +15,39 @@ Options:
   --expires-in <seconds> Default: server policy
   --token-expires-in <seconds>  Upload token lifetime (default: server policy)
   --scopes <list>        Comma-separated files:read,files:write,files:delete
+  --email <address>      Email the invite link to this recipient (from invites@uploads.sh)
+  --separate-code        Two-channel output: non-secret page URL + separate code
   --api-url <url>        Default: https://api.uploads.sh
+  --web-url <url>        Invite-page origin (defaults from --api-url)
+
+Examples:
+  uploads admin invite create --workspace acme --email user@example.com
+  uploads admin invite create --workspace acme --separate-code --json
+  uploads admin invite create --admin-token $ADMIN_TOKEN --workspace acme --label "onboarding"
 `;
 const FILE_SCOPES = new Set(["files:read", "files:write", "files:delete"]);
+export function invitePageUrl(apiUrl, pageId, webUrl) {
+    let url;
+    try {
+        url = new URL(webUrl ?? apiUrl);
+    }
+    catch {
+        throw new UsageError("invalid invite web URL");
+    }
+    if (!webUrl && url.hostname.startsWith("api."))
+        url.hostname = url.hostname.slice(4);
+    url.pathname = "/invite";
+    url.search = "";
+    url.hash = "";
+    url.searchParams.set("id", pageId);
+    return url.toString();
+}
+// Compose the self-contained magic link. The one-time code rides in the URL
+// fragment (#code=…), which browsers never send to the server, so opening the
+// page neither leaks nor consumes it — only the CLI's exchange call redeems it.
+export function inviteMagicLink(pageUrl, code) {
+    return `${pageUrl}#code=${encodeURIComponent(code)}`;
+}
 export function parseScopes(raw) {
     if (raw === undefined)
         return undefined;
@@ -34,26 +68,44 @@ export async function runAdmin(args, opts, help = false) {
         process.stderr.write(HELP);
         return 0;
     }
-    if (parsed.positionals[0] !== "enrollment" || parsed.positionals[1] !== "create")
-        throw new UsageError("expected: uploads admin enrollment create");
+    if (!["invite", "enrollment"].includes(parsed.positionals[0] ?? "") ||
+        parsed.positionals[1] !== "create")
+        throw new UsageError("expected: uploads admin invite create");
     const adminToken = flagString(parsed.flags, "--admin-token") ??
         process.env.ADMIN_TOKEN ??
         process.env.UPLOADS_ADMIN_TOKEN;
     if (!adminToken)
         throw new UsageError("ADMIN_TOKEN is required for admin enrollment creation");
     const apiUrl = flagString(parsed.flags, "--api-url") ?? opts.apiUrl ?? "https://api.uploads.sh";
+    const webUrl = flagString(parsed.flags, "--web-url");
     const workspace = flagString(parsed.flags, "--workspace") ?? "default";
     const label = flagString(parsed.flags, "--label");
+    const email = flagString(parsed.flags, "--email");
     const result = await createEnrollment(apiUrl, adminToken, {
         workspace,
         label,
+        email,
         enrollmentSeconds: flagInt(parsed.flags, "--expires-in", "--expires-in"),
         tokenExpiresInSeconds: flagInt(parsed.flags, "--token-expires-in", "--token-expires-in"),
         scopes: parseScopes(flagString(parsed.flags, "--scopes")),
     });
-    if (opts.json)
-        process.stdout.write(JSON.stringify({ workspace, label: label ?? null, ...result }, null, 2) + "\n");
+    const separateCode = flagBool(parsed.flags, "--separate-code");
+    const pageUrl = invitePageUrl(apiUrl, result.pageId, webUrl);
+    const link = separateCode ? pageUrl : inviteMagicLink(pageUrl, result.code);
+    const footer = `workspace: ${workspace}\nexpires: ${result.expiresAt}\n`;
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({ workspace, label: label ?? null, url: link, ...result }, null, 2) + "\n");
+        return 0;
+    }
+    if (email && result.emailed) {
+        process.stdout.write(`Invite emailed to ${email}\n${footer}`);
+        return 0;
+    }
+    if (email && result.emailed === false)
+        process.stderr.write("warning: email delivery failed; share this link instead\n");
+    if (separateCode)
+        process.stdout.write(`Invite page: ${pageUrl}\nOne-time code (share separately): ${result.code}\n${footer}`);
     else
-        process.stdout.write(`Enrollment code (share once): ${result.code}\nworkspace: ${workspace}\nexpires: ${result.expiresAt}\n`);
+        process.stdout.write(`Invite link (contains the one-time code — treat like a password):\n${link}\n${footer}`);
     return 0;
 }

package/dist/commands/login.js

@@ -15,6 +15,12 @@ Options:
   --path <file>       Config destination
   --force             Replace existing saved credentials
   --no-check          Skip doctor verification
+
+Examples:
+  uploads login --code upe_…
+  uploads login --code-stdin --non-interactive < code.txt
+  printf '%s' upe_… | uploads login --code-stdin --non-interactive
+  uploads login --code upe_… --force --no-check
 `;
 export function validateEnrollmentCode(raw) {
     const code = raw.trim();

package/dist/commands/mcp.js

@@ -1,8 +1,8 @@
-import { createRequire } from "node:module";
 import { parseCommandArgs } from "../cli-args.js";
 import { createMcpServer } from "../mcp/server.js";
 import { serveStdio } from "../mcp/stdio.js";
 import { createUploadsMcpTools } from "../mcp/tools.js";
+import { packageVersion } from "../package-version.js";
 const MCP_HELP = `uploads [globals] mcp
 
 Serve the Model Context Protocol (MCP) over stdio for agent clients. Tools
@@ -22,16 +22,13 @@ Examples:
   uploads --env-file .env mcp
   uploads --token up_default_… mcp
 `;
-// Same relative depth from src/commands/ and dist/commands/, so this works
-// both under vitest (src) and at runtime (dist).
-const { version } = createRequire(import.meta.url)("../../package.json");
 export async function runMcp(args, opts, help = false) {
     if (help || parseCommandArgs(args).help) {
         process.stderr.write(MCP_HELP);
         return 0;
     }
     const server = createMcpServer({
-        serverInfo: { name: "uploads", version },
+        serverInfo: { name: "uploads", version: packageVersion() },
         tools: createUploadsMcpTools({ globals: opts.globals }),
     });
     await serveStdio(server);

package/dist/commands.d.ts

@@ -41,6 +41,7 @@ export declare function syncAttachmentsComment(client: UploadsClient, target: Gh
 }>;
 export declare function runAttach(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runPut(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
+export declare function runGallery(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runList(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runDelete(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runComment(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
@@ -52,6 +53,8 @@ export declare function runHealth(ctx: Pick<CliContext, "json"> & {
 }, args: string[], help?: boolean): Promise<number>;
 export interface DoctorReport {
     ok: boolean;
+    /** Installed @buildinternet/uploads package version. */
+    cliVersion: string;
     apiUrl: string;
     workspace: string;
     workspaceSource: ResolvedConfig["workspaceSource"];

package/dist/commands.js

@@ -6,12 +6,13 @@ import { resolvePutDefaults, workspaceMismatch, workspaceFromToken, } from "./co
 import { buildMarkdown } from "./embed.js";
 import { UploadsError } from "./errors.js";
 import { writeJson, writeStdout } from "./io.js";
-import { ghAttachmentKey, ghKeyPrefix, attachmentsCommentBody, } from "./github.js";
+import { ghAttachmentKey, ghKeyPrefix, attachmentsCommentBody, normalizeGithubCoordinate, } from "./github.js";
 import { resolveRepo, resolveCurrentPullRequest, execRunner, upsertAttachmentsComment, } from "./github-gh.js";
 import { resolvePutPrefix } from "./destinations.js";
 import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
 import { applyFrame, resolveFrameId } from "./frame.js";
 import { buildCliProvenance } from "./provenance.js";
+import { packageVersion } from "./package-version.js";
 // --- put ---
 const PUT_HELP = `uploads put <file> [options]
 
@@ -25,6 +26,10 @@ upload as-is, or --keep-exif when image metadata matters for the discussion.
 Optional --frame wraps the image in a device/browser chrome before optimize
 (default off). See: uploads put --help frames
 
+Uploads are public. --pr/--issue keys include the repo, number, and filename and
+remain public even for private/internal GitHub repositories. Upload only media
+that is safe at a predictable public URL.
+
 Options:
   --key <key>           Object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>)
   --destination <id>    Typed root: screenshots | gh | f (sets --prefix)
@@ -46,13 +51,15 @@ 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: create/update the attachments comment via your local gh auth
+  --comment             With --pr/--issue: update one managed comment with attachments and linked galleries via local gh auth
+  --gallery <id>         Add the uploaded object to this public gallery
 
 Examples:
   uploads put ./shot.png --repo myorg/myapp --ref 1722 --alt "New cards" --width 700
   uploads put ./mobile.png --frame phone
   uploads put ./ui.png --frame browser --frame-url "https://app.example/settings"
   uploads put ./shot.png --destination screenshots
+  uploads put ./after.png --gallery gal_example
 `;
 /**
  * Turns a pr/issue pair (+ optional repo) into a GhTarget; undefined when
@@ -154,11 +161,39 @@ function frameOptionsFromFlags(flags) {
  */
 export async function syncAttachmentsComment(client, target, run) {
     const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url }) => ({ key, url }));
-    if (items.length === 0)
+    const galleries = [];
+    let cursor;
+    do {
+        const page = await client.findGalleriesByReference({
+            provider: "github",
+            // GitHub references intentionally do not distinguish PRs from issues.
+            coordinate: `${target.repo.toLowerCase()}#${target.num}`,
+            cursor,
+        });
+        galleries.push(...page.galleries.map(({ id, title, url }) => ({ title, url, id })));
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+    const previewGalleries = await Promise.all(galleries.map(async ({ id, ...gallery }) => {
+        try {
+            const detail = await client.getGallery(id);
+            return {
+                ...gallery,
+                previews: detail.items
+                    .filter((item) => item.status === "available" && item.url && item.contentType?.startsWith("image/"))
+                    .slice(0, 3)
+                    .map((item) => ({ url: item.url, alt: item.altText ?? item.objectKey })),
+            };
+        }
+        catch {
+            // A deleted or temporarily unavailable gallery still gets a safe title link.
+            return gallery;
+        }
+    }));
+    if (items.length === 0 && previewGalleries.length === 0)
         return { action: "skipped", count: 0 };
-    const body = attachmentsCommentBody(items);
+    const body = attachmentsCommentBody(items, previewGalleries);
     const { created } = upsertAttachmentsComment(target, body, run);
-    return { action: created ? "created" : "updated", count: items.length };
+    return { action: created ? "created" : "updated", count: items.length + previewGalleries.length };
 }
 // --- attach ---
 const ATTACH_HELP = `uploads attach <file...> [options]
@@ -166,6 +201,10 @@ const ATTACH_HELP = `uploads attach <file...> [options]
 Upload one or more stable PR/issue attachments and maintain a single GitHub
 comment. With no target, uses the pull request for the current branch.
 
+Attachments are public and their repo/number/filename keys are predictable.
+Private/internal GitHub repository visibility does not restrict access; upload
+only media that is safe at a public URL.
+
 Still images are optimized to WebP by default (same as put). Use --no-optimize
 to upload originals. Optional --frame wraps images in device/browser chrome.
 
@@ -294,6 +333,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const prefixFlag = flagString(parsed.flags, "--prefix");
     const ghTarget = ghTargetFromFlags(parsed.flags, run);
     const wantComment = parsed.flags.has("--comment");
+    const galleryId = flagString(parsed.flags, "--gallery");
     if (wantComment && typeof parsed.flags.get("--comment") === "string") {
         throw new UsageError("--comment takes no value — place it after the file argument");
     }
@@ -378,6 +418,22 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         }),
     });
     const markdown = buildMarkdown(result.url, { alt, width });
+    let gallery;
+    if (galleryId) {
+        try {
+            // Gallery mutations use optimistic versions. Fetch immediately before this
+            // mutation so `put --gallery` composes safely with other CLI writers.
+            const current = await ctx.client.getGallery(galleryId);
+            const item = await ctx.client.addGalleryItem(galleryId, result.key, {
+                expectedVersion: current.version,
+                altText: alt,
+            });
+            gallery = { id: galleryId, url: current.url, item };
+        }
+        catch (err) {
+            gallery = { id: galleryId, error: galleryError(err) };
+        }
+    }
     const optimizeMeta = {
         optimized: prepared.optimized,
         skippedReason: prepared.skippedReason,
@@ -390,7 +446,13 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     }
     switch (format) {
         case "json":
-            await writeJson({ ...result, markdown, optimize: optimizeMeta, frame: prepared.frame });
+            await writeJson({
+                ...result,
+                markdown,
+                optimize: optimizeMeta,
+                frame: prepared.frame,
+                gallery,
+            });
             break;
         case "url":
             await writeStdout(`${result.url}\n`);
@@ -399,7 +461,13 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             await writeStdout(`${markdown}\n`);
             break;
         default:
-            await writeStdout(`URL: ${result.url}\nMARKDOWN: ${markdown}\n`);
+            await writeStdout(`URL: ${result.url}\nMARKDOWN: ${markdown}${gallery?.url ? `\nGALLERY: ${gallery.url}` : ""}\n`);
+    }
+    if (gallery?.url && format !== "human") {
+        process.stderr.write(`gallery: ${gallery.url}\n`);
+    }
+    if (gallery?.error) {
+        process.stderr.write(`warning: upload succeeded but adding it to gallery ${gallery.id} failed: ${gallery.error.message}\n`);
     }
     if (wantComment && ghTarget) {
         try {
@@ -413,7 +481,222 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             process.stderr.write(`warning: upload succeeded but the GitHub comment failed (is gh installed and authenticated?): ${err instanceof Error ? err.message : String(err)}\n`);
         }
     }
-    return 0;
+    return gallery?.error ? 1 : 0;
+}
+function galleryError(err) {
+    if (err instanceof UploadsError)
+        return { message: err.message, code: err.code, status: err.status };
+    return { message: err instanceof Error ? err.message : String(err) };
+}
+// --- galleries ---
+const GALLERY_HELP = `uploads gallery <command> [args]
+
+Public galleries can be viewed by anyone who knows the URL. Do not add sensitive media.
+Deleting a gallery only removes the gallery record; it never deletes its uploaded objects.
+
+Commands:
+  create --title <title> [--description <text>]
+  show <gallery-id>
+  list [--limit <n>] [--cursor <c>] [--all]
+  delete <gallery-id>
+  add <gallery-id> <object-key...> [--caption <text>] [--alt <text>]
+  link <gallery-id> --github <owner/repo#number|github-url>
+  unlink <gallery-id> --github <owner/repo#number|github-url>
+  list --github <owner/repo#number|github-url> [--limit <n>] [--cursor <c>] [--all]
+
+Examples:
+  uploads gallery create --title "Settings redesign"
+  uploads gallery add gal_example screenshots/app/after.webp --alt "Updated settings page"
+  uploads gallery show gal_example
+  uploads gallery link gal_example --github buildinternet/uploads#58
+  uploads gallery list --github https://github.com/buildinternet/uploads/pull/58
+`;
+function githubCoordinateFromFlags(flags) {
+    const value = flagString(flags, "--github");
+    if (!value)
+        throw new UsageError("--github requires an owner/repo#number coordinate or GitHub issue/PR URL");
+    const normalized = normalizeGithubCoordinate(value);
+    if (!normalized)
+        throw new UsageError("--github must be owner/repo#number or an https://github.com/.../issues|pull/number URL");
+    return normalized.coordinate;
+}
+export async function runGallery(ctx, args, help = false) {
+    const parsed = parseCommandArgs(args);
+    const action = parsed.positionals[0];
+    if (help || parsed.help || !action) {
+        process.stderr.write(GALLERY_HELP);
+        return help || parsed.help ? 0 : 2;
+    }
+    switch (action) {
+        case "create": {
+            const title = flagString(parsed.flags, "--title");
+            if (!title)
+                throw new UsageError("gallery create requires --title");
+            const gallery = await ctx.client.createGallery({
+                title,
+                description: flagString(parsed.flags, "--description"),
+            });
+            if (ctx.json)
+                await writeJson(gallery);
+            else
+                await writeStdout(`${gallery.url}\n`);
+            if (!ctx.quiet && !ctx.json)
+                process.stderr.write("warning: galleries are public to anyone with the URL\n");
+            return 0;
+        }
+        case "show": {
+            const id = parsed.positionals[1];
+            if (!id)
+                throw new UsageError("gallery show requires a gallery ID");
+            const gallery = await ctx.client.getGallery(id);
+            if (ctx.json)
+                await writeJson(gallery);
+            else
+                await writeStdout(`${gallery.url}\n`);
+            return 0;
+        }
+        case "list": {
+            const limit = flagInt(parsed.flags, "--limit", "--limit");
+            const cursor = flagString(parsed.flags, "--cursor");
+            const github = parsed.flags.has("--github")
+                ? githubCoordinateFromFlags(parsed.flags)
+                : undefined;
+            if (flagBool(parsed.flags, "--all")) {
+                const galleries = [];
+                let nextCursor = cursor;
+                do {
+                    const page = github
+                        ? await ctx.client.findGalleriesByReference({
+                            provider: "github",
+                            coordinate: github,
+                            limit,
+                            cursor: nextCursor,
+                        })
+                        : await ctx.client.listGalleries({ limit, cursor: nextCursor });
+                    galleries.push(...page.galleries);
+                    nextCursor = page.nextCursor ?? undefined;
+                } while (nextCursor);
+                if (ctx.json)
+                    await writeJson({ galleries, nextCursor: null });
+                else
+                    for (const gallery of galleries)
+                        await writeStdout(`${gallery.id}  ${gallery.url}  ${gallery.title}\n`);
+                return 0;
+            }
+            const page = github
+                ? await ctx.client.findGalleriesByReference({
+                    provider: "github",
+                    coordinate: github,
+                    limit,
+                    cursor,
+                })
+                : await ctx.client.listGalleries({ limit, cursor });
+            if (ctx.json)
+                await writeJson(page);
+            else {
+                for (const gallery of page.galleries)
+                    await writeStdout(`${gallery.id}  ${gallery.url}  ${gallery.title}\n`);
+                if (page.nextCursor)
+                    process.stderr.write(`cursor: ${page.nextCursor}\n`);
+            }
+            return 0;
+        }
+        case "link": {
+            const id = parsed.positionals[1];
+            if (!id)
+                throw new UsageError("gallery link requires a gallery ID");
+            const coordinate = githubCoordinateFromFlags(parsed.flags);
+            const current = await ctx.client.getGallery(id);
+            const reference = await ctx.client.linkGalleryExternalReference(id, {
+                expectedVersion: current.version,
+                provider: "github",
+                coordinate,
+            });
+            if (ctx.json)
+                await writeJson({ galleryId: id, reference });
+            else
+                await writeStdout((reference.canonicalUrl ?? reference.coordinate) + "\n");
+            return 0;
+        }
+        case "unlink": {
+            const id = parsed.positionals[1];
+            if (!id)
+                throw new UsageError("gallery unlink requires a gallery ID");
+            const coordinate = githubCoordinateFromFlags(parsed.flags);
+            const references = await ctx.client.listGalleryExternalReferences(id);
+            const reference = references.references.find((entry) => entry.provider === "github" && entry.coordinate === coordinate);
+            if (!reference) {
+                const output = { galleryId: id, coordinate, deleted: false };
+                if (ctx.json)
+                    await writeJson(output);
+                else if (!ctx.quiet)
+                    process.stderr.write("GitHub reference was already absent\n");
+                return 0;
+            }
+            const current = await ctx.client.getGallery(id);
+            const result = await ctx.client.unlinkGalleryExternalReference(id, reference.id, {
+                expectedVersion: current.version,
+            });
+            if (ctx.json)
+                await writeJson({ galleryId: id, coordinate, ...result });
+            else if (!ctx.quiet)
+                process.stderr.write("unlinked " + coordinate + "\n");
+            return 0;
+        }
+        case "delete": {
+            const id = parsed.positionals[1];
+            if (!id)
+                throw new UsageError("gallery delete requires a gallery ID");
+            const current = await ctx.client.getGallery(id);
+            const result = await ctx.client.deleteGallery(id, { expectedVersion: current.version });
+            if (ctx.json)
+                await writeJson(result);
+            else if (!ctx.quiet)
+                process.stderr.write(`deleted gallery ${result.id} (objects kept)\n`);
+            return 0;
+        }
+        case "add": {
+            const id = parsed.positionals[1];
+            const keys = parsed.positionals.slice(2);
+            if (!id || keys.length === 0)
+                throw new UsageError("gallery add requires a gallery ID and one or more object keys");
+            const caption = flagString(parsed.flags, "--caption");
+            const altText = flagString(parsed.flags, "--alt");
+            const added = [];
+            let galleryUrl;
+            const failures = [];
+            for (const objectKey of keys) {
+                try {
+                    // Always re-read before the next write: each add increments the version,
+                    // and this also avoids stale versions after an independent writer.
+                    const current = await ctx.client.getGallery(id);
+                    galleryUrl = current.url;
+                    added.push(await ctx.client.addGalleryItem(id, objectKey, {
+                        expectedVersion: current.version,
+                        caption,
+                        altText,
+                    }));
+                }
+                catch (err) {
+                    failures.push({ objectKey, error: galleryError(err) });
+                }
+            }
+            const output = { galleryId: id, galleryUrl: galleryUrl ?? null, added, failures };
+            if (ctx.json)
+                await writeJson(output);
+            else {
+                if (galleryUrl)
+                    await writeStdout(`GALLERY: ${galleryUrl}\n`);
+                for (const item of added)
+                    await writeStdout(`${item.objectKey}\n`);
+                for (const failure of failures)
+                    process.stderr.write(`warning: could not add ${failure.objectKey}: ${failure.error.message}\n`);
+            }
+            return failures.length === 0 ? 0 : 1;
+        }
+        default:
+            throw new UsageError(`unknown gallery command: ${action}`);
+    }
 }
 // --- list ---
 const LIST_HELP = `uploads list [--prefix <p>] [--pr <num> | --issue <num>] [--repo <owner/name>] [--limit <n>] [--cursor <c>] [--all] [--workspace <name>]
@@ -466,8 +749,13 @@ export async function runList(ctx, args, help = false, run = execRunner) {
 // --- delete ---
 const DELETE_HELP = `uploads delete <key> [--dry-run] [--workspace <name>]
 
+Options:
+  --dry-run             Preview without deleting
+  --workspace, -w <name>
+
 Examples:
   uploads delete screenshots/myapp/42/shot-a1b2c3.png
+  uploads delete screenshots/myapp/42/shot-a1b2c3.png --dry-run
 `;
 export async function runDelete(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
@@ -635,6 +923,7 @@ Checks API health, token auth, and workspace/token alignment.
 Examples:
   uploads --env-file .env doctor
   uploads --workspace acme --env-file .env doctor
+  uploads doctor --json
 `;
 /** Doctor's health + auth + workspace checks, shared by the CLI and the MCP tool. */
 export async function buildDoctorReport(config, client) {
@@ -681,6 +970,7 @@ export async function buildDoctorReport(config, client) {
     }
     return {
         ok: health.ok && authOk,
+        cliVersion: packageVersion(),
         apiUrl: config.apiUrl,
         workspace: config.workspace,
         workspaceSource: config.workspaceSource,
@@ -705,6 +995,7 @@ export async function runDoctor(ctx, args, help = false) {
         return report.ok ? 0 : 1;
     }
     const lines = [
+        `cli:       @buildinternet/uploads@${report.cliVersion}`,
         `config:    ${report.configPath}${report.configExists ? "" : " (missing)"}`,
         `api:       ${report.apiUrl} (${report.health.ok ? "ok" : "failed"})`,
         `workspace: ${report.workspace}`,

package/dist/github.d.ts

@@ -5,9 +5,16 @@ export interface GhTarget {
     kind: GhTargetKind;
     num: number;
 }
+/** A normalized GitHub issue/PR coordinate used for gallery references. */
+export interface GithubCoordinate {
+    coordinate: string;
+    canonicalUrl: string;
+}
 export declare function isValidRepo(repo: string): boolean;
 /** Parse "owner/name" from a git remote URL (SSH or HTTPS), else undefined. */
 export declare function parseRepoFromRemoteUrl(url: string): string | undefined;
+/** Normalize a GitHub issue or pull-request coordinate for gallery linking. */
+export declare function normalizeGithubCoordinate(value: string): GithubCoordinate | undefined;
 export declare function ghKeyPrefix(target: GhTarget): string;
 /**
  * Stable attachment key: same filename → same key → same public URL, so
@@ -21,6 +28,17 @@ export interface AttachmentItem {
     key: string;
     url: string | null;
 }
+/** A public gallery linked to the PR or issue whose managed comment is syncing. */
+export interface GalleryCommentItem {
+    title: string;
+    /** Canonical URL returned by the API; callers must not synthesize it. */
+    url: string;
+    /** A bounded set of available images, all of which link back to the gallery. */
+    previews?: {
+        url: string;
+        alt: string;
+    }[];
+}
 /** Default max width for images in the managed attachments comment (HTML img). */
 export declare const ATTACHMENT_IMAGE_WIDTH_DEFAULT = 400;
 /** Portrait / device mockups — keep phones readable, not full-column. */
@@ -32,4 +50,8 @@ export declare const ATTACHMENT_IMAGE_WIDTH_WIDE = 640;
  * practical signal (we don't re-fetch dimensions when rebuilding the comment).
  */
 export declare function attachmentImageWidth(filename: string): number;
-export declare function attachmentsCommentBody(items: AttachmentItem[]): string;
+/**
+ * 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;