@buildinternet/uploads 0.4.0 → 0.6.0

package/dist/github.js

@@ -10,6 +10,47 @@ export function parseRepoFromRemoteUrl(url) {
     const repo = match?.[1];
     return repo && isValidRepo(repo) ? repo : undefined;
 }
+/** Normalize a GitHub issue or pull-request coordinate for gallery linking. */
+export function normalizeGithubCoordinate(value) {
+    const input = value.trim();
+    let match = /^([^/\s#]+)\/([^/\s#]+)#([1-9][0-9]*)$/.exec(input);
+    if (!match) {
+        try {
+            const url = new URL(input);
+            if (url.protocol !== "https:" ||
+                url.hostname.toLowerCase() !== "github.com" ||
+                url.port ||
+                url.username ||
+                url.password ||
+                url.search ||
+                url.hash)
+                return undefined;
+            match = /^\/([^/]+)\/([^/]+)\/(?:issues|pull)\/([1-9][0-9]*)\/?$/.exec(url.pathname);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!match)
+        return undefined;
+    const [, ownerRaw, repositoryRaw, numberRaw] = match;
+    const repo = ownerRaw + "/" + repositoryRaw;
+    const number = Number(numberRaw);
+    if (!isValidRepo(repo) || !Number.isSafeInteger(number))
+        return undefined;
+    const owner = ownerRaw.toLowerCase();
+    const repository = repositoryRaw.toLowerCase();
+    const coordinate = owner + "/" + repository + "#" + number;
+    return {
+        coordinate,
+        canonicalUrl: "https://github.com/" +
+            encodeURIComponent(owner) +
+            "/" +
+            encodeURIComponent(repository) +
+            "/issues/" +
+            number,
+    };
+}
 export function ghKeyPrefix(target) {
     const [owner, name] = target.repo.split("/");
     return `gh/${sanitizeKeySegment(owner)}/${sanitizeKeySegment(name)}/${target.kind}/${target.num}/`;
@@ -48,9 +89,31 @@ export function attachmentImageWidth(filename) {
 function escapeHtmlAttr(s) {
     return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 }
-export function attachmentsCommentBody(items) {
+function escapeHtmlText(s) {
+    return escapeHtmlAttr(s).replace(/'/g, "&#39;").replace(/>/g, "&gt;");
+}
+/**
+ * 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 = []) {
     const sorted = items.toSorted((a, b) => a.key.localeCompare(b.key));
-    const lines = [ATTACHMENTS_MARKER, "### 📎 Attachments", ""];
+    const sortedGalleries = galleries.toSorted((a, b) => a.title.localeCompare(b.title) || a.url.localeCompare(b.url));
+    const lines = [ATTACHMENTS_MARKER];
+    if (sortedGalleries.length > 0) {
+        lines.push("### 🖼️ Galleries", "");
+        for (const gallery of sortedGalleries) {
+            const href = escapeHtmlAttr(gallery.url);
+            lines.push(`#### <a href="${href}">${escapeHtmlText(gallery.title)}</a>`);
+            for (const preview of gallery.previews ?? []) {
+                lines.push(`<a href="${href}"><img width="320" alt="${escapeHtmlAttr(preview.alt)}" src="${escapeHtmlAttr(preview.url)}"></a>`);
+            }
+            lines.push(`<sub><a href="${href}">Open gallery</a></sub>`, "");
+        }
+        lines.push("");
+    }
+    if (sorted.length > 0 || sortedGalleries.length === 0)
+        lines.push("### 📎 Attachments", "");
     for (const item of sorted) {
         const name = item.key.slice(item.key.lastIndexOf("/") + 1);
         if (item.url && inferContentType(name).startsWith("image/")) {

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey
 export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, resolveDestinationRoot, resolvePutPrefix, type BuiltinDestinationId, } from "./destinations.js";
 export { DEFAULT_API_URL, DEFAULT_WORKSPACE, UPLOADS_CONFIG_KEYS, defaultConfigPath, resolveConfigPath, loadConfigFile, loadEnvFile, resolveApiUrl, resolveConfig, describeConfigSources, redactToken, writeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, workspaceFromToken, workspaceMismatch, type UploadsClientConfig, type ResolvedConfig, type WorkspaceSource, type ConfigValueSource, type ConfigSources, type UploadsConfigKey, type UploadsConfigValues, type PutDefaults, } from "./config.js";
 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 HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, } from "./client.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, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, 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";

package/dist/mcp/tools.js

@@ -88,6 +88,23 @@ const frameProps = {
 function ghTargetFromArgs(args, run) {
     return makeGhTarget(optPosInt(args, "pr"), optPosInt(args, "issue"), optString(args, "repo"), run);
 }
+function galleryId(args) {
+    const id = optString(args, "galleryId");
+    if (!id)
+        usage("galleryId is required");
+    return id;
+}
+function galleryReference(args) {
+    const provider = optString(args, "provider");
+    const coordinate = optString(args, "coordinate");
+    if (!provider)
+        usage("provider is required");
+    if (!coordinate)
+        usage("coordinate is required");
+    if (provider !== "github")
+        usage("provider must be github");
+    return { provider, coordinate };
+}
 const workspaceProp = {
     type: "string",
     description: "Override the workspace for this call (like the CLI's --workspace flag).",
@@ -136,9 +153,130 @@ export function createUploadsMcpTools(opts) {
         return { comment, commentError };
     };
     return [
+        {
+            name: "gallery_create",
+            description: "Create a public ordered media gallery in the workspace. The returned canonical URL is safe to give users, but anyone who knows it can view the gallery and its media.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string", description: "Gallery title (1–120 characters)." },
+                    description: { type: "string", description: "Optional public gallery description." },
+                    workspace: workspaceProp,
+                },
+                required: ["title"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const title = optString(args, "title");
+                if (!title)
+                    usage("title is required");
+                const { client } = clientFor(args);
+                return client.createGallery({ title, description: optString(args, "description") });
+            },
+        },
+        {
+            name: "gallery_get",
+            description: "Get a workspace-owned gallery, including ordered media and its canonical public URL. Gallery media is public to anyone with the URL.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    galleryId: { type: "string", description: "Opaque gallery ID." },
+                    workspace: workspaceProp,
+                },
+                required: ["galleryId"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const { client } = clientFor(args);
+                return client.getGallery(galleryId(args));
+            },
+        },
+        {
+            name: "gallery_add",
+            description: "Add one existing, publicly served workspace object to a gallery. Reads the latest gallery version before writing, so the optimistic API version is handled safely. Does not upload or delete the object.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    galleryId: { type: "string", description: "Opaque gallery ID." },
+                    objectKey: { type: "string", description: "Existing public object key to add." },
+                    caption: { type: "string", description: "Optional public caption." },
+                    altText: { type: "string", description: "Optional public alt text." },
+                    workspace: workspaceProp,
+                },
+                required: ["galleryId", "objectKey"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const objectKey = optString(args, "objectKey");
+                if (!objectKey)
+                    usage("objectKey is required");
+                const { client } = clientFor(args);
+                const id = galleryId(args);
+                const current = await client.getGallery(id);
+                return client.addGalleryItem(id, objectKey, {
+                    expectedVersion: current.version,
+                    caption: optString(args, "caption"),
+                    altText: optString(args, "altText"),
+                });
+            },
+        },
+        {
+            name: "gallery_link",
+            description: "Link a gallery to an external reference. References use provider-neutral fields; github currently accepts owner/repo#number or a strict GitHub issue/PR URL. No GitHub credentials or API calls are used.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    galleryId: { type: "string", description: "Opaque gallery ID." },
+                    provider: { type: "string", description: "External provider (currently github)." },
+                    coordinate: {
+                        type: "string",
+                        description: "Provider-native external reference coordinate.",
+                    },
+                    workspace: workspaceProp,
+                },
+                required: ["galleryId", "provider", "coordinate"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const { client } = clientFor(args);
+                const id = galleryId(args);
+                const current = await client.getGallery(id);
+                return client.linkGalleryExternalReference(id, {
+                    expectedVersion: current.version,
+                    ...galleryReference(args),
+                });
+            },
+        },
+        {
+            name: "gallery_find_by_reference",
+            description: "Find workspace galleries linked to an external reference. Returns gallery summaries and canonical public URLs without contacting the provider.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    provider: { type: "string", description: "External provider (currently github)." },
+                    coordinate: {
+                        type: "string",
+                        description: "Provider-native external reference coordinate.",
+                    },
+                    limit: { type: "number", description: "Page size (default 50, max 100)." },
+                    cursor: { type: "string", description: "Pagination cursor from a previous response." },
+                    workspace: workspaceProp,
+                },
+                required: ["provider", "coordinate"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const { client } = clientFor(args);
+                return client.findGalleriesByReference({
+                    ...galleryReference(args),
+                    limit: optPosInt(args, "limit"),
+                    cursor: optString(args, "cursor"),
+                });
+            },
+        },
         {
             name: "put",
-            description: "Upload a file to uploads.sh and get a public URL plus GitHub-ready embed markdown (the returned `markdown` is ready to paste into a PR or issue). Pass `file` (a local path) or `contentBase64` + `filename` for in-memory content; with `pr`/`issue` the key is stable (same filename → same URL) and `comment` syncs the managed attachments comment.",
+            description: "Upload a file to uploads.sh and get a public URL plus GitHub-ready embed markdown (the returned `markdown` is ready to paste into a PR or issue). Pass `file` (a local path) or `contentBase64` + `filename` for in-memory content; with `pr`/`issue` the key is stable (same filename → same URL) and `comment` syncs the managed attachments comment. All uploads are public; pr/issue keys are predictable and remain public for private/internal GitHub repositories, so upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -302,7 +440,7 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "attach",
-            description: "Upload one or more files as stable PR/issue attachments and maintain a single managed GitHub comment listing them (each upload's `markdown` is ready to paste into GitHub). With no pr/issue, targets the pull request for the current branch.",
+            description: "Upload one or more files as stable PR/issue attachments and maintain a single managed GitHub comment listing them (each upload's `markdown` is ready to paste into GitHub). With no pr/issue, targets the pull request for the current branch. Attachments are public and their repo/number/filename keys are predictable even for private/internal GitHub repositories; upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {

package/dist/package-version.d.ts

@@ -0,0 +1 @@
+export declare function packageVersion(): string;

package/dist/package-version.js

@@ -0,0 +1,19 @@
+/**
+ * Resolve the published package version for CLI headers, --version, and
+ * update checks. Reads package.json once per process.
+ */
+import { createRequire } from "node:module";
+let cachedVersion;
+export function packageVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require("../package.json");
+        cachedVersion = pkg.version ?? "0.0.0";
+    }
+    catch {
+        cachedVersion = "0.0.0";
+    }
+    return cachedVersion;
+}

package/dist/provenance.js

@@ -1,18 +1,4 @@
-import { createRequire } from "node:module";
-let cachedVersion;
-function packageVersion() {
-    if (cachedVersion)
-        return cachedVersion;
-    try {
-        const require = createRequire(import.meta.url);
-        const pkg = require("../package.json");
-        cachedVersion = pkg.version ?? "0.0.0";
-    }
-    catch {
-        cachedVersion = "0.0.0";
-    }
-    return cachedVersion;
-}
+import { packageVersion } from "./package-version.js";
 export function buildCliProvenance(opts) {
     const provenance = {
         client: opts.client ?? "uploads-cli",

package/dist/update-check.d.ts

@@ -0,0 +1,30 @@
+export declare const PACKAGE_NAME = "@buildinternet/uploads";
+export interface UpdateCache {
+    checkedAt: number;
+    latest: string;
+    current: string;
+}
+export interface UpdateCheckOptions {
+    quiet?: boolean;
+    /** mcp is always skipped (stdio purity). */
+    command?: string;
+    currentVersion?: string;
+    cachePath?: string;
+    now?: number;
+    /** Default 24h. Pass 0 in tests to force a network check. */
+    ttlMs?: number;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    write?: (text: string) => void;
+}
+/** Parse major.minor.patch (ignores pre-release). */
+export declare function parseSemver(version: string): [number, number, number] | null;
+/** True when `latest` is strictly greater than `current`. */
+export declare function isNewerVersion(latest: string, current: string): boolean;
+export declare function readUpdateCache(path: string): UpdateCache | undefined;
+export declare function writeUpdateCache(path: string, cache: UpdateCache): void;
+/**
+ * If a newer published version is known (or can be fetched within the timeout),
+ * write a one-line stderr hint. Always resolves; never throws.
+ */
+export declare function maybeHintUpdate(opts?: UpdateCheckOptions): Promise<void>;

package/dist/update-check.js

@@ -0,0 +1,134 @@
+/**
+ * Optional npm update notifier for the CLI.
+ *
+ * Checks the registry at most once per day, never throws, never blocks longer
+ * than a short timeout, and writes only to stderr. Silence with --quiet,
+ * UPLOADS_NO_UPDATE=1, or NO_UPDATE_NOTIFIER=1.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { packageVersion } from "./package-version.js";
+export const PACKAGE_NAME = "@buildinternet/uploads";
+const REGISTRY_LATEST = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 1500;
+function truthyEnv(name) {
+    const v = process.env[name];
+    if (!v)
+        return false;
+    const lower = v.toLowerCase();
+    return lower !== "0" && lower !== "false" && lower !== "no";
+}
+function defaultCachePath() {
+    const base = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+    return join(base, "uploads", "version-check.json");
+}
+/** Parse major.minor.patch (ignores pre-release). */
+export function parseSemver(version) {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+/** True when `latest` is strictly greater than `current`. */
+export function isNewerVersion(latest, current) {
+    const a = parseSemver(latest);
+    const b = parseSemver(current);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] > b[i])
+            return true;
+        if (a[i] < b[i])
+            return false;
+    }
+    return false;
+}
+export function readUpdateCache(path) {
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof raw.checkedAt !== "number" ||
+            typeof raw.latest !== "string" ||
+            typeof raw.current !== "string") {
+            return undefined;
+        }
+        return { checkedAt: raw.checkedAt, latest: raw.latest, current: raw.current };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeUpdateCache(path, cache) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(cache) + "\n", { mode: 0o600 });
+    }
+    catch {
+        // Best-effort — never fail the CLI for a cache write error.
+    }
+}
+/**
+ * If a newer published version is known (or can be fetched within the timeout),
+ * write a one-line stderr hint. Always resolves; never throws.
+ */
+export async function maybeHintUpdate(opts = {}) {
+    try {
+        if (opts.quiet || opts.command === "mcp")
+            return;
+        if (truthyEnv("UPLOADS_NO_UPDATE") || truthyEnv("NO_UPDATE_NOTIFIER"))
+            return;
+        const current = opts.currentVersion ?? packageVersion();
+        const cachePath = opts.cachePath ?? defaultCachePath();
+        const now = opts.now ?? Date.now();
+        const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        const write = opts.write ?? ((text) => process.stderr.write(text));
+        const cached = readUpdateCache(cachePath);
+        let latest;
+        if (cached && now - cached.checkedAt < ttlMs && cached.current === current) {
+            latest = cached.latest;
+        }
+        else {
+            const fetched = await fetchLatestVersion(opts.fetchImpl, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            if (fetched) {
+                latest = fetched;
+                writeUpdateCache(cachePath, { checkedAt: now, latest: fetched, current });
+            }
+            else if (cached?.current === current) {
+                latest = cached.latest; // stale cache if network failed
+            }
+        }
+        if (latest && isNewerVersion(latest, current)) {
+            write(`hint: ${PACKAGE_NAME}@${latest} is available (you have ${current}). Update: npm i -g ${PACKAGE_NAME}\n`);
+        }
+    }
+    catch {
+        // Never surface update-check failures.
+    }
+}
+async function fetchLatestVersion(fetchImpl, timeoutMs) {
+    const fetchFn = fetchImpl ?? globalThis.fetch;
+    if (typeof fetchFn !== "function")
+        return undefined;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchFn(REGISTRY_LATEST, {
+            signal: controller.signal,
+            headers: {
+                accept: "application/json",
+                "user-agent": `${PACKAGE_NAME}/${packageVersion()} (update-check)`,
+            },
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        return typeof body.version === "string" ? body.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/package.json

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