@buildinternet/uploads 0.5.0 → 0.7.0

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,6 +153,127 @@ 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. All uploads are public; pr/issue keys are predictable and remain public for private/internal GitHub repositories, so upload only non-sensitive media.",

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