@buildinternet/uploads 0.33.1 → 0.34.0

package/dist/commands.js

@@ -5,6 +5,7 @@ import { createUploadsClient, } from "./client.js";
 import { parseCommandArgs, flagString, flagBool, flagInt, flagValues, UsageError, } from "./cli-args.js";
 import { resolvePutDefaults, workspaceMismatch, workspaceFromToken, } from "./config.js";
 import { buildMarkdown } from "./embed.js";
+import { readLocalRepoCommentConfig, resolveCommentOptions } from "./comment-config.js";
 import { urlForGithubEmbed } from "./public-urls.js";
 import { UploadsError } from "./errors.js";
 import { writeJson, writeStdout } from "./io.js";
@@ -12,7 +13,7 @@ import { imageFactsFromBytes } from "./image-facts.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./metadata-vocab.js";
 import { mergeSidecarMeta } from "./sidecar.js";
-import { ghAttachmentKey, ghBranchAttachmentKey, ghBranchKeyPrefix, ghKeyPrefix, ghMetadataFromTarget, parseGhKey, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, GH_FALLBACK_AUTHOR_NOTE, normalizeGithubCoordinate, } from "./github.js";
+import { ghAttachmentKey, ghBranchAttachmentKey, ghBranchKeyPrefix, ghKeyPrefix, ghMetadataFromTarget, parseGhKey, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, AUTO_RENDER_OPTIONS, GH_FALLBACK_AUTHOR_NOTE, normalizeGithubCoordinate, } from "./github.js";
 import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, resolveDefaultBranch, classifyGhNumber, execRunner, timedExecRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
 import { deriveRepoFromGit } from "./keys.js";
 import { resolvePutPrefix } from "./destinations.js";
@@ -104,9 +105,13 @@ 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. Posts as uploads-sh[bot]
-                        when the GitHub App is installed; otherwise via local gh.
+  --comment             With --pr/--issue, the managed comment sync runs by
+                        default; --comment is accepted as a no-op for
+                        back-compat (kept redundant with the default).
+  --no-comment          With --pr/--issue: skip updating the managed comment
+                        with attachments and linked galleries. Otherwise it
+                        posts as uploads-sh[bot] when the GitHub App is
+                        installed, or via local gh as a fallback.
   --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
@@ -117,7 +122,7 @@ Options:
   --replace             Allow overwriting an existing object on a strict (--key/default) key
                         (or UPLOADS_OVERWRITE=1). No effect on --pr/--issue, which always overwrite.
   --dry-run             Print key + public URL without uploading; reports if the key would replace
-                        (or, on a strict key, be refused). Not with --comment/--gallery
+                        (or, on a strict key, be refused). Not with --gallery
 
 A bare put (no --pr/--issue/--key) on a non-default git branch prints a one-line
 nudge toward --pr/attach --branch (stderr in human mode, a "hint" field in
@@ -543,9 +548,31 @@ export async function syncAttachmentsComment(client, target, run, workspace, opt
         }
     }));
     const marker = attachmentsMarker(workspace);
+    // Honor a committed .uploads.yml on the working tree (issue #307). This CLI
+    // process has no server-side WorkspaceRecord in scope (see the note above),
+    // so it resolves against `null` workspace defaults — a documented
+    // divergence from the bot path (commands.ts:728 / apps/api's
+    // resolveRepoCommentOptions, which also layers the workspace's own
+    // githubComment* fields).
+    let renderOptions = AUTO_RENDER_OPTIONS;
+    try {
+        const root = run("git", ["rev-parse", "--show-toplevel"]).trim();
+        const { config } = readLocalRepoCommentConfig(root);
+        const { options } = resolveCommentOptions(config, null);
+        renderOptions = {
+            imageWidth: options.imageWidth,
+            maxInlineImages: options.maxInlineImages,
+            metaPath: options.metaPath,
+            metaState: options.metaState,
+            note: options.note,
+        };
+    }
+    catch {
+        // Not a git repo, or the config file couldn't be read — fall back to auto.
+    }
     // Append only on the local-gh path: bot posts already carry the uploads-sh
     // bot identity, so this note would be wrong there.
-    const body = `${attachmentsCommentBody(items, previewGalleries, marker)}\n${GH_FALLBACK_AUTHOR_NOTE}`;
+    const body = `${attachmentsCommentBody(items, previewGalleries, marker, renderOptions)}\n${GH_FALLBACK_AUTHOR_NOTE}`;
     const count = items.length + previewGalleries.length;
     // Empty (count 0) renders the neutral empty-state body but must not create a
     // comment — it only rewrites one that already exists (`action: "skipped"`
@@ -1504,7 +1531,10 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const destFlag = flagString(parsed.flags, "--destination");
     const prefixFlag = flagString(parsed.flags, "--prefix");
     const ghTarget = ghTargetFromFlags(parsed.flags, run);
-    const wantComment = parsed.flags.has("--comment");
+    // Comment sync runs by default with --pr/--issue (matches `attach`); opt
+    // out with --no-comment. --comment is accepted as a redundant no-op for
+    // back-compat with scripts written before this default flipped (#537).
+    const wantComment = !parsed.flags.has("--no-comment");
     const galleryId = flagString(parsed.flags, "--gallery");
     const nameFlag = flagString(parsed.flags, "--name");
     const dryRun = flagBool(parsed.flags, "--dry-run");
@@ -1523,17 +1553,21 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         validateMetaMap(merged);
         return merged;
     })();
-    if (wantComment && typeof parsed.flags.get("--comment") === "string") {
+    if (parsed.flags.has("--comment") && typeof parsed.flags.get("--comment") === "string") {
         throw new UsageError("--comment takes no value — place it after the file argument");
     }
+    if (parsed.flags.has("--no-comment") && typeof parsed.flags.get("--no-comment") === "string") {
+        throw new UsageError("--no-comment takes no value");
+    }
     if (parsed.flags.has("--auto") && typeof parsed.flags.get("--auto") === "string") {
         throw new UsageError("--auto takes no value");
     }
     if (parsed.flags.has("--no-auto") && typeof parsed.flags.get("--no-auto") === "string") {
         throw new UsageError("--no-auto takes no value");
     }
-    if (wantComment && !ghTarget)
-        throw new UsageError("--comment requires --pr or --issue");
+    if (parsed.flags.has("--no-comment") && !ghTarget) {
+        throw new UsageError("--no-comment requires --pr or --issue");
+    }
     if (multi) {
         if (keyHint)
             throw new UsageError("--key cannot be combined with multiple files");
@@ -1560,12 +1594,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         if (keyHint)
             throw new UsageError("--name cannot be combined with --key");
     }
-    if (dryRun) {
-        if (wantComment)
-            throw new UsageError("--dry-run cannot be combined with --comment");
-        if (galleryId)
-            throw new UsageError("--dry-run cannot be combined with --gallery");
-    }
+    if (dryRun && galleryId)
+        throw new UsageError("--dry-run cannot be combined with --gallery");
     let resolvedPrefix;
     try {
         resolvedPrefix = resolvePutPrefix({
@@ -1760,7 +1790,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     }
     let comment;
     let commentError;
-    if (wantComment && ghTarget && uploads.length > 0) {
+    if (wantComment && ghTarget && !dryRun && uploads.length > 0) {
         try {
             comment = await syncAttachmentsComment(ctx.client, ghTarget, run, ctx.config.workspace);
             if (logHuman)

package/dist/comment-config.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Published-CLI COPY of the workspace parser/resolver (issue #307)
+ * (packages/comment-config/src/index.ts). The published CLI imports no
+ * @uploads/* package, so that private package cannot be shared here — its
+ * parser/resolver is copied verbatim below. Kept in sync by
+ * test/fixtures/comment-config-golden.json, asserted from both sides (this
+ * package's comment-config.test.ts and the canonical package's
+ * index.test.ts) — change both copies together. `readLocalRepoCommentConfig`
+ * below is CLI-only: it reads the six candidate config paths off the working
+ * tree (the server instead fetches them from GitHub's contents API —
+ * apps/api/src/repo-comment-config.ts).
+ */
+export interface RepoCommentConfig {
+    imageWidth?: "auto" | "full" | number;
+    maxInlineImages?: number;
+    metaPath?: boolean;
+    metaState?: boolean;
+    linkToFilePage?: boolean;
+    note?: string;
+}
+export interface WorkspaceCommentDefaults {
+    imageWidth?: "full" | number;
+    maxInlineImages?: number;
+    showMetadata?: boolean;
+    linkToFilePage?: boolean;
+    note?: string;
+}
+export interface ResolvedCommentOptions {
+    imageWidth: "auto" | "full" | number;
+    maxInlineImages: number;
+    metaPath: boolean;
+    metaState: boolean;
+    linkToFilePage: boolean;
+    note: string | null;
+}
+export type OptionSource = "repo" | "workspace" | "auto";
+export declare const AUTO_COMMENT_OPTIONS: ResolvedCommentOptions;
+export declare const NOTE_MAX_CHARS = 500;
+export declare function parseRepoCommentConfig(text: string, format: "yaml" | "json"): {
+    config: RepoCommentConfig | null;
+    warnings: string[];
+};
+export declare function resolveCommentOptions(repo: RepoCommentConfig | null, ws: WorkspaceCommentDefaults | null): {
+    options: ResolvedCommentOptions;
+    source: Record<keyof ResolvedCommentOptions, OptionSource>;
+};
+/**
+ * Candidate paths, checked in this order — the first hit wins. Must match
+ * the server's REPO_CONFIG_PATHS exactly (apps/api/src/repo-comment-config.ts)
+ * so a committed config resolves identically whether the bot or the local
+ * gh fallback renders the comment.
+ */
+export declare const REPO_CONFIG_PATHS: readonly [".uploads.yml", ".uploads.yaml", ".uploads.json", ".github/uploads.yml", ".github/uploads.yaml", ".github/uploads.json"];
+/**
+ * Read the repo's comment config off the local working tree — the CLI has no
+ * GitHub App installation token to fetch via the contents API, so this reads
+ * `rootDir` directly. Returns the first candidate that exists (readable or
+ * not); an unreadable file (permissions, or a directory at that path) is
+ * treated as absent and the search continues to the next candidate, matching
+ * a 404 in the server-side fetch.
+ */
+export declare function readLocalRepoCommentConfig(rootDir: string): {
+    config: RepoCommentConfig | null;
+    path: string | null;
+    warnings: string[];
+};

package/dist/comment-config.js

@@ -0,0 +1,188 @@
+/**
+ * Published-CLI COPY of the workspace parser/resolver (issue #307)
+ * (packages/comment-config/src/index.ts). The published CLI imports no
+ * @uploads/* package, so that private package cannot be shared here — its
+ * parser/resolver is copied verbatim below. Kept in sync by
+ * test/fixtures/comment-config-golden.json, asserted from both sides (this
+ * package's comment-config.test.ts and the canonical package's
+ * index.test.ts) — change both copies together. `readLocalRepoCommentConfig`
+ * below is CLI-only: it reads the six candidate config paths off the working
+ * tree (the server instead fetches them from GitHub's contents API —
+ * apps/api/src/repo-comment-config.ts).
+ */
+import fs from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+export const AUTO_COMMENT_OPTIONS = {
+    imageWidth: "auto",
+    maxInlineImages: 16, // MAX_INLINE_ATTACHMENT_IMAGES — renderer copies own the constant
+    metaPath: true,
+    metaState: true,
+    linkToFilePage: true,
+    note: null,
+};
+export const NOTE_MAX_CHARS = 500;
+const WIDTH_MIN = 160;
+const WIDTH_MAX = 1000;
+const MAX_INLINE_MIN = 1;
+const MAX_INLINE_MAX = 48;
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, Math.round(n)));
+export function parseRepoCommentConfig(text, format) {
+    const warnings = [];
+    let root;
+    try {
+        root = format === "json" ? JSON.parse(text) : parseYaml(text);
+    }
+    catch {
+        return { config: null, warnings: ["config file could not be parsed; ignoring it"] };
+    }
+    if (typeof root !== "object" || root === null || Array.isArray(root)) {
+        return { config: null, warnings };
+    }
+    const comment = root.comment;
+    if (typeof comment !== "object" || comment === null || Array.isArray(comment)) {
+        return { config: null, warnings };
+    }
+    const c = comment;
+    const config = {};
+    // imageWidth: "auto" | "full" | finite number (clamped)
+    if ("imageWidth" in c) {
+        const v = c.imageWidth;
+        if (v === "auto" || v === "full")
+            config.imageWidth = v;
+        else if (typeof v === "number" && Number.isFinite(v))
+            config.imageWidth = clamp(v, WIDTH_MIN, WIDTH_MAX);
+        else
+            warnings.push(`imageWidth: expected "auto", "full", or a number; dropped`);
+    }
+    // maxInlineImages: finite number (clamped)
+    if ("maxInlineImages" in c) {
+        const v = c.maxInlineImages;
+        if (typeof v === "number" && Number.isFinite(v))
+            config.maxInlineImages = clamp(v, MAX_INLINE_MIN, MAX_INLINE_MAX);
+        else
+            warnings.push(`maxInlineImages: expected a number; dropped`);
+    }
+    // linkToFilePage: boolean
+    if ("linkToFilePage" in c) {
+        const v = c.linkToFilePage;
+        if (typeof v === "boolean")
+            config.linkToFilePage = v;
+        else
+            warnings.push(`linkToFilePage: expected a boolean; dropped`);
+    }
+    // meta.path / meta.state: booleans nested under `meta`
+    if ("meta" in c) {
+        const v = c.meta;
+        if (typeof v === "object" && v !== null && !Array.isArray(v)) {
+            const meta = v;
+            if ("path" in meta) {
+                if (typeof meta.path === "boolean")
+                    config.metaPath = meta.path;
+                else
+                    warnings.push(`meta.path: expected a boolean; dropped`);
+            }
+            if ("state" in meta) {
+                if (typeof meta.state === "boolean")
+                    config.metaState = meta.state;
+                else
+                    warnings.push(`meta.state: expected a boolean; dropped`);
+            }
+        }
+        else {
+            warnings.push(`meta: expected an object; dropped`);
+        }
+    }
+    // note: non-empty trimmed string, max NOTE_MAX_CHARS (never truncated)
+    if ("note" in c) {
+        const v = c.note;
+        if (typeof v === "string") {
+            const trimmed = v.trim();
+            if (trimmed.length === 0) {
+                // empty/whitespace note is treated as absent
+            }
+            else if (trimmed.length > NOTE_MAX_CHARS) {
+                warnings.push(`note: longer than ${NOTE_MAX_CHARS} characters; dropped (not truncated)`);
+            }
+            else {
+                config.note = trimmed;
+            }
+        }
+        else {
+            warnings.push(`note: expected a string; dropped`);
+        }
+    }
+    return { config, warnings };
+}
+export function resolveCommentOptions(repo, ws) {
+    const wsAsRepo = {
+        ...(ws?.imageWidth !== undefined ? { imageWidth: ws.imageWidth } : {}),
+        ...(ws?.maxInlineImages !== undefined ? { maxInlineImages: ws.maxInlineImages } : {}),
+        ...(ws?.showMetadata !== undefined
+            ? { metaPath: ws.showMetadata, metaState: ws.showMetadata }
+            : {}),
+        ...(ws?.linkToFilePage !== undefined ? { linkToFilePage: ws.linkToFilePage } : {}),
+        ...(ws?.note ? { note: ws.note } : {}),
+    };
+    const options = { ...AUTO_COMMENT_OPTIONS };
+    const source = Object.fromEntries(Object.keys(AUTO_COMMENT_OPTIONS).map((k) => [k, "auto"]));
+    const apply = (cfg, from) => {
+        for (const key of [
+            "imageWidth",
+            "maxInlineImages",
+            "metaPath",
+            "metaState",
+            "linkToFilePage",
+        ]) {
+            if (cfg[key] !== undefined && source[key] === "auto") {
+                options[key] = cfg[key];
+                source[key] = from;
+            }
+        }
+        if (cfg.note !== undefined && source.note === "auto") {
+            options.note = cfg.note;
+            source.note = from;
+        }
+    };
+    if (repo)
+        apply(repo, "repo");
+    apply(wsAsRepo, "workspace");
+    return { options, source };
+}
+/**
+ * Candidate paths, checked in this order — the first hit wins. Must match
+ * the server's REPO_CONFIG_PATHS exactly (apps/api/src/repo-comment-config.ts)
+ * so a committed config resolves identically whether the bot or the local
+ * gh fallback renders the comment.
+ */
+export const REPO_CONFIG_PATHS = [
+    ".uploads.yml",
+    ".uploads.yaml",
+    ".uploads.json",
+    ".github/uploads.yml",
+    ".github/uploads.yaml",
+    ".github/uploads.json",
+];
+/**
+ * Read the repo's comment config off the local working tree — the CLI has no
+ * GitHub App installation token to fetch via the contents API, so this reads
+ * `rootDir` directly. Returns the first candidate that exists (readable or
+ * not); an unreadable file (permissions, or a directory at that path) is
+ * treated as absent and the search continues to the next candidate, matching
+ * a 404 in the server-side fetch.
+ */
+export function readLocalRepoCommentConfig(rootDir) {
+    for (const candidate of REPO_CONFIG_PATHS) {
+        let text;
+        try {
+            text = fs.readFileSync(join(rootDir, candidate), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const format = candidate.endsWith(".json") ? "json" : "yaml";
+        const { config, warnings } = parseRepoCommentConfig(text, format);
+        return { config, path: candidate, warnings };
+    }
+    return { config: null, path: null, warnings: [] };
+}

package/dist/github.d.ts

@@ -74,6 +74,22 @@ export declare function attachmentsMarker(workspace?: string): string;
  * into a `<details>` link list. Keeps very large threads from becoming a wall
  * of images. */
 export declare const MAX_INLINE_ATTACHMENT_IMAGES = 16;
+/**
+ * Per-render knobs for the managed comment (issue #307), sourced from repo
+ * comment config. `imageWidth: "auto"` preserves today's per-item width
+ * heuristics (`attachmentImageWidth`/`posterImageWidth`/pair cap); `"full"`
+ * omits the `width` attribute entirely; a number overrides every width site.
+ */
+export interface CommentRenderOptions {
+    imageWidth: "auto" | "full" | number;
+    maxInlineImages: number;
+    metaPath: boolean;
+    metaState: boolean;
+    note: string | null;
+}
+/** Today's behavior, expressed as options — the default for every caller that
+ * hasn't opted into repo comment config. */
+export declare const AUTO_RENDER_OPTIONS: CommentRenderOptions;
 export interface AttachmentItem {
     key: string;
     url: string | null;
@@ -137,7 +153,7 @@ export declare const ATTACHMENT_IMAGE_WIDTH_PAIR = 320;
  * 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[], marker?: string): string;
+export declare function attachmentsCommentBody(items: AttachmentItem[], galleries?: GalleryCommentItem[], marker?: string, options?: CommentRenderOptions): string;
 /**
  * Extra footer line appended only on the local-`gh` fallback path (never on
  * bot-authored comments). Short note that the App isn't on this repo yet.

package/dist/github.js

@@ -162,6 +162,15 @@ export function attachmentsMarker(workspace) {
  * into a `<details>` link list. Keeps very large threads from becoming a wall
  * of images. */
 export const MAX_INLINE_ATTACHMENT_IMAGES = 16;
+/** Today's behavior, expressed as options — the default for every caller that
+ * hasn't opted into repo comment config. */
+export const AUTO_RENDER_OPTIONS = {
+    imageWidth: "auto",
+    maxInlineImages: MAX_INLINE_ATTACHMENT_IMAGES,
+    metaPath: true,
+    metaState: true,
+    note: null,
+};
 /** 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. */
@@ -241,19 +250,19 @@ function escapeMarkdownText(s) {
  * alone it is a stray character, and as a prefix next to `state` it is
  * noise. Only exact `/` after trim is suppressed.
  */
-function metaCaptionParts(meta) {
+function metaCaptionParts(meta, options) {
     const parts = [];
     const path = meta?.path?.trim();
-    if (path && path !== "/")
+    if (options.metaPath && path && path !== "/")
         parts.push(path);
     const state = meta?.state?.trim();
-    if (state)
+    if (options.metaState && state)
         parts.push(state);
     return parts;
 }
 /** `<sub>` caption body for an inline image, or null when there is nothing to say. */
-function metaCaptionHtml(meta) {
-    const parts = metaCaptionParts(meta);
+function metaCaptionHtml(meta, options) {
+    const parts = metaCaptionParts(meta, options);
     return parts.length > 0 ? parts.map(escapeHtmlText).join(" · ") : null;
 }
 /**
@@ -261,12 +270,32 @@ function metaCaptionHtml(meta) {
  * HTML-escapes first, then markdown-escapes: HTML escaping introduces no
  * backslashes or brackets, so the markdown pass cannot corrupt its entities.
  */
-function metaCaptionMarkdown(meta) {
-    const parts = metaCaptionParts(meta);
+function metaCaptionMarkdown(meta, options) {
+    const parts = metaCaptionParts(meta, options);
     if (parts.length === 0)
         return "";
     return ` · ${parts.map((p) => escapeMarkdownText(escapeHtmlText(p))).join(" · ")}`;
 }
+/** Resolved pixel width for an image site, or `null` meaning "omit the width
+ * attribute". `"auto"` defers to the caller's per-item heuristic (`autoPx`);
+ * `"full"` always omits; a number always wins. */
+function resolvedWidth(autoPx, options) {
+    if (options.imageWidth === "auto")
+        return autoPx;
+    if (options.imageWidth === "full")
+        return null;
+    return options.imageWidth;
+}
+/** Every `<img>` tag in the managed comment goes through here so the
+ * omit-width-attribute case ("full") can't drift between call sites.
+ *
+ * `escapedAlt`/`escapedSrc` must already be attribute-escaped (via
+ * `escapeHtmlAttr`) by the caller — this function interpolates them as-is
+ * and does not escape them itself. */
+function imgTag(w, escapedAlt, escapedSrc) {
+    const widthAttr = w === null ? "" : ` width="${w}"`;
+    return `<img${widthAttr} alt="${escapedAlt}" src="${escapedSrc}">`;
+}
 /** Extract the filename stem's before/after token (issue #419 fallback pairing).
  * `base` is the stem lowercased with the token removed; `null` when the stem
  * carries no recognizable before/after token. Requires a separator (`-`, `_`,
@@ -363,32 +392,35 @@ function pairAttachments(items, isImageAt) {
  * than a standalone image so two side by side stay under GitHub's comment
  * column width (and don't overflow on mobile). */
 export const ATTACHMENT_IMAGE_WIDTH_PAIR = 320;
-function renderPairCell(item, label) {
+function renderPairCell(item, label, options) {
     const name = item.key.slice(item.key.lastIndexOf("/") + 1);
     const src = item.embedUrl ?? item.url;
     const link = item.pageUrl ?? item.url;
-    const w = Math.min(attachmentImageWidth(name), ATTACHMENT_IMAGE_WIDTH_PAIR);
+    const autoPx = Math.min(attachmentImageWidth(name), ATTACHMENT_IMAGE_WIDTH_PAIR);
+    const w = resolvedWidth(autoPx, options);
     const alt = escapeHtmlAttr(name);
     const href = escapeHtmlAttr((link ?? src));
     const imgSrc = escapeHtmlAttr(src);
-    const caption = metaCaptionHtml(item.meta);
+    const caption = metaCaptionHtml(item.meta, options);
     const captionHtml = caption ? `<br><sub>${caption}</sub>` : "";
-    return `<td align="center"><sub><strong>${label}</strong></sub><br><a href="${href}"><img width="${w}" alt="${alt}" src="${imgSrc}"></a>${captionHtml}</td>`;
+    return `<td align="center"><sub><strong>${label}</strong></sub><br><a href="${href}">${imgTag(w, alt, imgSrc)}</a>${captionHtml}</td>`;
 }
 /** One side-by-side before/after row (issue #419): a single HTML table so
  * GitHub renders both images on one line, with `Before`/`After` labels and
  * each side's usual path/state caption preserved underneath. */
-function renderPairRow(beforeItem, afterItem) {
-    return `<table><tr>${renderPairCell(beforeItem, "Before")}${renderPairCell(afterItem, "After")}</tr></table>`;
+function renderPairRow(beforeItem, afterItem, options) {
+    return `<table><tr>${renderPairCell(beforeItem, "Before", options)}${renderPairCell(afterItem, "After", options)}</tr></table>`;
 }
 /**
  * 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 = [], marker = ATTACHMENTS_MARKER) {
+export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMENTS_MARKER, options = AUTO_RENDER_OPTIONS) {
     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 = [marker];
+    if (options.note)
+        lines.push(options.note, "");
     if (sortedGalleries.length > 0) {
         lines.push("### 🖼️ Galleries", "");
         for (const gallery of sortedGalleries) {
@@ -397,7 +429,8 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
             for (const preview of gallery.previews ?? []) {
                 const previewHref = preview.itemUrl ? escapeHtmlAttr(preview.itemUrl) : href;
                 const previewSrc = escapeHtmlAttr(preview.embedUrl ?? preview.url);
-                lines.push(`<a href="${previewHref}"><img width="320" alt="${escapeHtmlAttr(preview.alt)}" src="${previewSrc}"></a>`);
+                const previewW = resolvedWidth(320, options);
+                lines.push(`<a href="${previewHref}">${imgTag(previewW, escapeHtmlAttr(preview.alt), previewSrc)}</a>`);
             }
             lines.push(`<sub><a href="${href}">Open gallery</a></sub>`, "");
         }
@@ -421,12 +454,12 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
         const partnerIdx = partnerOf.get(idx);
         if (partnerIdx !== undefined) {
             const partner = sorted[partnerIdx];
-            if (inlinedImages + 2 <= MAX_INLINE_ATTACHMENT_IMAGES) {
+            if (inlinedImages + 2 <= options.maxInlineImages) {
                 inlinedImages += 2;
                 consumedByPair.add(partnerIdx);
                 const beforeItem = roleOf.get(idx) === "before" ? item : partner;
                 const afterItem = roleOf.get(idx) === "before" ? partner : item;
-                lines.push(renderPairRow(beforeItem, afterItem), "");
+                lines.push(renderPairRow(beforeItem, afterItem, options), "");
                 continue;
             }
             // Cap already full for a two-image row — degrade this pair to two
@@ -442,7 +475,7 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
         const isImage = Boolean(src) && inferContentType(name).startsWith("image/");
         const isPosterVideo = Boolean(item.posterUrl) && inferContentType(name).startsWith("video/");
         const inlines = isImage || isPosterVideo;
-        if (inlines && inlinedImages >= MAX_INLINE_ATTACHMENT_IMAGES) {
+        if (inlines && inlinedImages >= options.maxInlineImages) {
             // Cap hit — defer to the collapsed overflow list below rather than
             // embedding every remaining image inline.
             overflowImages.push(item);
@@ -450,37 +483,39 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
         }
         if (isPosterVideo) {
             inlinedImages++;
-            const w = posterImageWidth(item.videoMeta, name);
+            const autoPx = posterImageWidth(item.videoMeta, name);
+            const w = resolvedWidth(autoPx, options);
             const href = escapeHtmlAttr(link ?? item.posterUrl);
-            lines.push(`<a href="${href}"><img width="${w}" alt="${escapeHtmlAttr(name)}" src="${escapeHtmlAttr(item.posterUrl)}"></a>`);
+            lines.push(`<a href="${href}">${imgTag(w, escapeHtmlAttr(name), escapeHtmlAttr(item.posterUrl))}</a>`);
             // GitHub strips <video>, so a still frame needs an explicit affordance
             // or it reads as a screenshot.
             const parts = ["▶ Play video"];
             if (item.videoMeta?.durationSeconds != null) {
                 parts.push(formatDuration(item.videoMeta.durationSeconds));
             }
-            parts.push(...metaCaptionParts(item.meta).map(escapeHtmlText));
+            parts.push(...metaCaptionParts(item.meta, options).map(escapeHtmlText));
             lines.push(`<sub>${parts.join(" · ")}</sub>`, "");
         }
         else 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 prefers the file page.
-            const w = attachmentImageWidth(name);
+            const autoPx = attachmentImageWidth(name);
+            const w = resolvedWidth(autoPx, options);
             const alt = escapeHtmlAttr(name);
             const href = escapeHtmlAttr(link ?? src);
             const imgSrc = escapeHtmlAttr(src);
-            lines.push(`<a href="${href}"><img width="${w}" alt="${alt}" src="${imgSrc}"></a>`);
-            const caption = metaCaptionHtml(item.meta);
+            lines.push(`<a href="${href}">${imgTag(w, alt, imgSrc)}</a>`);
+            const caption = metaCaptionHtml(item.meta, options);
             if (caption)
                 lines.push(`<sub>${caption}</sub>`);
             lines.push("");
         }
         else if (link) {
-            lines.push(`- [${name}](${link})${metaCaptionMarkdown(item.meta)}`);
+            lines.push(`- [${name}](${link})${metaCaptionMarkdown(item.meta, options)}`);
         }
         else {
-            lines.push(`- ${name}${metaCaptionMarkdown(item.meta)}`);
+            lines.push(`- ${name}${metaCaptionMarkdown(item.meta, options)}`);
         }
     }
     if (overflowImages.length > 0) {
@@ -489,7 +524,7 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
         for (const item of overflowImages) {
             const name = item.key.slice(item.key.lastIndexOf("/") + 1);
             const link = item.pageUrl ?? item.url;
-            const suffix = metaCaptionMarkdown(item.meta);
+            const suffix = metaCaptionMarkdown(item.meta, options);
             lines.push(link ? `- [${name}](${link})${suffix}` : `- ${name}${suffix}`);
         }
         lines.push("", "</details>", "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,
@@ -61,7 +61,8 @@
     "opentype.js": "^2.0.0",
     "perfect-freehand": "^1.2.3",
     "roughjs": "^4.6.6",
-    "sharp": "^0.35.3"
+    "sharp": "^0.35.3",
+    "yaml": "^2.6.0"
   },
   "optionalDependencies": {
     "playwright-core": "^1.61.1"