@buildinternet/uploads 0.54.0 → 0.55.1

package/README.md

@@ -31,6 +31,8 @@ uploads put --url https://cdn.example/shot.png --pr 123
 uploads put --url http://localhost:4321/shot.png
 uploads gallery create --title "Release screenshots"
 uploads put ./after.png --gallery gal_example
+uploads feed create --repo owner/repo
+uploads feed create --repo owner/repo --pr 123
 # custom metadata (queryable): page URL, in-app path, which surface
 uploads put ./shot.png --meta url=https://app.example/settings --meta path=/settings --meta app=web
 uploads meta get screenshots/myapp/42/shot.webp
@@ -43,7 +45,7 @@ Inside this monorepo only, `pnpm uploads …` builds the package first so you pi
 up local source; product docs and PR “how to try it” examples should use the
 global `uploads` form above.
 
-Commands: `attach`, `put`, `screenshot`, `annotate`, `gallery`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
+Commands: `attach`, `put`, `screenshot`, `annotate`, `gallery`, `feed`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
 `reconcile`, `purge-expired`, `setup`, `install`, `login`, `whoami` (alias `status`),
 `logout`, `invite`, `admin`, `config`, `telemetry`, `report`, `doctor`, `health`, `changelog`, `docs`, `mcp`,
 `completion`.
@@ -192,13 +194,33 @@ When adding several keys, `uploads gallery add` processes them sequentially and
 individual failures in `--json` output. Gallery item updates use the API's current version to
 avoid overwriting concurrent changes.
 
+## Change feeds
+
+A feed is a public newest-first page of screenshots already tagged with a GitHub `owner/repo`,
+or with one pull request or issue. Same product — `--pr` / `--issue` / `--github` is one extra
+filter. It is a live query, not a curated gallery. Use a gallery when you pick the files; use
+a repo feed for the latest shots across a repo; use a PR feed when reviewers should see only
+that pull request. The API returns the canonical public URL.
+
+```bash
+uploads feed create --repo owner/repo
+uploads feed create --repo owner/repo --pr 123
+uploads feed create --github owner/repo#123
+uploads feed create --repo owner/repo --path /settings
+```
+
+Creating the same scope again returns the existing URL. Anyone who knows that URL can
+view the feed. Each shot also has `/c/<id>/<item>` with previous / next. Syncing a
+managed PR comment creates the PR feed if needed and points image clicks at that pager.
+MCP: `feed_create` (`repo`, plus `pr` / `issue` / `github` / `path`) and `feed_get`.
+
 Link a gallery to a GitHub issue or pull request with `gallery link --github`. Run `uploads comment --pr <number>` to refresh that target’s one managed comment with every linked gallery and loose attachment. Coordinates and strict `https://github.com/<owner>/<repo>/issues|pull/<number>` URLs are accepted; `gallery list --github` performs the authenticated reverse lookup. Links never change gallery identity, and GitHub repository visibility does not make the public gallery private.
 
 Config layers (first match wins): CLI flags → env vars → `--env-file` → `~/.config/buildinternet/config`. See `config.example` for keys.
 
 ## MCP server
 
-`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows: `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`. Gallery tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `get_metadata`, `set_metadata`, `find_files`, `usage`, `reconcile`, `purge_expired`, `comment`, `whoami`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. `put` and `attach` accept a `metadata` param (same `gh.*` auto-injection as the CLI's `attach`); `get_metadata`, `set_metadata`, and `find_files` mirror `uploads meta get` / `meta set` / `find`. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`whoami` needs no auth).
+`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows (`gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, `gallery_find_by_reference`) and change feeds (`feed_create`, `feed_get` — pass `pr` or `github` to scope a feed to one pull request). Gallery and feed tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `get_metadata`, `set_metadata`, `find_files`, `usage`, `reconcile`, `purge_expired`, `comment`, `whoami`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. `put` and `attach` accept a `metadata` param (same `gh.*` auto-injection as the CLI's `attach`); `get_metadata`, `set_metadata`, and `find_files` mirror `uploads meta get` / `meta set` / `find`. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`whoami` needs no auth).
 
 ```json
 { "command": "uploads", "args": ["--env-file", "/path/to/.env", "mcp"] }
@@ -208,7 +230,7 @@ Or with `UPLOADS_TOKEN`/`UPLOADS_WORKSPACE` in the environment or user config. C
 
 The MCP Registry lists this server as `sh.uploads/mcp`.
 
-For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations (including `get_metadata` / `set_metadata` / `find_files`) plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. The hosted `put` also accepts a `metadata` param. `uploads install` registers the skills + hosted MCP with whichever of Claude Code, Codex, and Grok are on PATH (a missing CLI is skipped) + Grok/Cursor hooks (short progress; `--verbose` for underlying output). Claude and Codex use their plugins for the same pre-PR screenshot reminder (`uploads hook pre-pr-screenshot`). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
+For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations (including `get_metadata` / `set_metadata` / `find_files`) plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, `gallery_find_by_reference`, `feed_create`, and `feed_get`; all use the same bearer-token workspace scopes and gallery/feed URLs come from the API — see `apps/mcp` in the repo. The hosted `put` also accepts a `metadata` param. `uploads install` registers the skills + hosted MCP with whichever of Claude Code, Codex, and Grok are on PATH (a missing CLI is skipped) + Grok/Cursor hooks (short progress; `--verbose` for underlying output). Claude and Codex use their plugins for the same pre-PR screenshot reminder (`uploads hook pre-pr-screenshot`). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
 
 ## Programmatic use
 

package/dist/cli-catalog.js

@@ -156,6 +156,16 @@ export const ROOT_COMMANDS = [
             { name: "unlink", summary: "Unlink a gallery from GitHub" },
         ],
     },
+    {
+        name: "feed",
+        summary: "Create a public newest-first screenshot feed for a GitHub repo or pull request",
+        subcommands: [
+            { name: "create", summary: "Create or reuse a repo or PR change feed" },
+            { name: "show", summary: "Show a feed" },
+            { name: "list", summary: "List feeds" },
+            { name: "delete", summary: "Delete a feed record" },
+        ],
+    },
     {
         name: "comment",
         summary: "Create/update a PR/issue attachments comment (via gh)",

package/dist/cli-help.js

@@ -165,6 +165,7 @@ ${section(style, "Examples:")}
   ${style.command("uploads attach")} ./artifact.zip --issue 45 --no-comment
   ${style.command("uploads attach")} ./shot.png --meta path=/settings --state after
   ${style.command("uploads gallery")} create --title "Release screenshots"
+  ${style.command("uploads feed")} create --repo owner/repo
   ${style.command("uploads doctor")}
   ${style.command("uploads logout")}
   ${style.command("uploads --version")}

package/dist/cli.js

@@ -7,6 +7,7 @@ import { commandSummary, suggestCommand } from "./cli-suggest.js";
 import { writeJson } from "./io.js";
 import { colorEnabled, createStyle } from "./cli-style.js";
 import { runPut, runAttach, runStaged, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runGithub, runIngest, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
+import { runFeed } from "./commands/feed.js";
 import { runConfig } from "./commands/config.js";
 import { runSetup } from "./commands/setup.js";
 import { runLogin } from "./commands/login.js";
@@ -309,6 +310,7 @@ export async function runCli(argv) {
             case "staged":
             case "screenshot":
             case "gallery":
+            case "feed":
             case "list":
             case "find":
             case "meta":
@@ -337,6 +339,9 @@ export async function runCli(argv) {
                     case "gallery":
                         code = await runGallery(ctx, cmdArgs, showHelp);
                         break;
+                    case "feed":
+                        code = await runFeed(ctx, cmdArgs, showHelp);
+                        break;
                     case "comment":
                         code = await runComment(ctx, cmdArgs, showHelp);
                         break;
@@ -397,7 +402,7 @@ export async function runCli(argv) {
                 return 2;
             }
         }
-        // Best-effort; skipped for mcp, --quiet/--json, and opt-out env vars.
+        // Best-effort; skipped for mcp, update, --quiet/--json, and opt-out env vars.
         if (code === 0 && !showHelp) {
             await maybeHintUpdate({ quiet: quiet || json, command: parsed.command });
         }

package/dist/client.d.ts

@@ -257,6 +257,59 @@ export interface FindGalleriesByReferenceOptions {
     limit?: number;
     cursor?: string;
 }
+/** A workspace-owned, query-backed public repo change feed. */
+export interface FeedItem {
+    id: string;
+    objectKey: string;
+    filename: string;
+    status: "available" | "missing" | "withheld";
+    url: string | null;
+    embedUrl: string | null;
+    /** Canonical `/c/<id>/<item>` page when the API computed one. */
+    pageUrl?: string;
+    contentType: string | null;
+    size: number | null;
+    uploaded: string | null;
+    modified: string | null;
+    path: string | null;
+    state: string | null;
+    posterUrl?: string;
+    videoDimensions?: {
+        width: number;
+        height: number;
+    };
+}
+export interface Feed {
+    id: string;
+    /** Canonical public URL returned by the API; clients must not construct it. */
+    url: string;
+    workspace: string;
+    repo: string;
+    path: string | null;
+    number: number | null;
+    kind: "pull" | "issue" | null;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    items: FeedItem[];
+}
+export type FeedSummary = Omit<Feed, "items">;
+export interface FeedListOptions {
+    limit?: number;
+    cursor?: string;
+}
+export interface FeedListResult {
+    feeds: FeedSummary[];
+    nextCursor: string | null;
+}
+export interface CreateFeedOptions {
+    repo: string;
+    path?: string | null;
+    number?: number | null;
+    kind?: "pull" | "issue" | null;
+    pr?: number | null;
+    issue?: number | null;
+}
 /**
  * Reasons the bot did not post. The CLI falls back to the local `gh` path
  * for all of these except `not_authorized` (issue #297 baseline control):
@@ -734,6 +787,13 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
         id: string;
     }>;
     findGalleriesByReference(opts: FindGalleriesByReferenceOptions): Promise<GalleryListResult>;
+    createFeed(opts: CreateFeedOptions): Promise<Feed>;
+    getFeed(id: string): Promise<Feed>;
+    listFeeds(opts?: FeedListOptions): Promise<FeedListResult>;
+    deleteFeed(id: string): Promise<{
+        deleted: boolean;
+        id: string;
+    }>;
     /**
      * Upsert the managed attachments comment. `resync: true` marks an
      * explicit "make the comment state correct" call (`uploads comment`), so

package/dist/client.js

@@ -307,6 +307,9 @@ function usageBase(config) {
 function galleriesBase(config) {
     return `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/galleries`;
 }
+function feedsBase(config) {
+    return `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/feeds`;
+}
 function mapApiError(status, error, code, requiredScope, existingUrl) {
     const normalized = error.toLowerCase();
     if (status === 401 || code === "unauthorized" || normalized === "unauthorized") {
@@ -652,6 +655,27 @@ export function createUploadsClient(config) {
                 params.set("cursor", opts.cursor);
             return request("GET", galleriesBase(config) + "/by-reference?" + params);
         },
+        async createFeed(opts) {
+            return request("POST", feedsBase(config), {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        async getFeed(id) {
+            return request("GET", `${feedsBase(config)}/${encodeURIComponent(id)}`);
+        },
+        async listFeeds(opts = {}) {
+            const params = new URLSearchParams();
+            if (opts.limit != null)
+                params.set("limit", String(opts.limit));
+            if (opts.cursor)
+                params.set("cursor", opts.cursor);
+            const qs = params.toString();
+            return request("GET", `${feedsBase(config)}${qs ? `?${qs}` : ""}`);
+        },
+        async deleteFeed(id) {
+            return request("DELETE", `${feedsBase(config)}/${encodeURIComponent(id)}`);
+        },
         /**
          * Upsert the managed attachments comment. `resync: true` marks an
          * explicit "make the comment state correct" call (`uploads comment`), so

package/dist/commands/feed.d.ts

@@ -0,0 +1,2 @@
+import type { CliContext } from "../commands.js";
+export declare function runFeed(ctx: CliContext, args: string[], help?: boolean): Promise<number>;

package/dist/commands/feed.js

@@ -0,0 +1,133 @@
+import { flagInt, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
+import { writeCommandHelp } from "../cli-style.js";
+import { parseGithubIssueRef } from "../github.js";
+import { resolveRepo } from "../github-gh.js";
+import { writeJson, writeStdout } from "../io.js";
+const FEED_HELP = `uploads feed <command> [args]
+
+A public newest-first feed of screenshots tagged with a GitHub owner/repo,
+or one pull request / issue. Same product — pass --pr, --issue, or --github
+to scope it. A gallery is a hand-picked list; a feed is live. Anyone who
+knows the URL can view it. Creating the same scope again returns the
+existing feed.
+
+Commands:
+  create [--repo <owner/repo>] [--pr <n> | --issue <n> | --github <ref>] [--path <page-path>]
+  show <feed-id>
+  list [--limit <n>] [--cursor <c>]
+  delete <feed-id>
+
+Examples:
+  uploads feed create
+  uploads feed create --repo acme/app
+  uploads feed create --repo acme/app --pr 123
+  uploads feed create --github acme/app#123
+  uploads feed create --repo acme/app --path /settings
+  uploads feed show feed_example
+`;
+function resolveCreateOptions(parsed) {
+    const github = flagString(parsed.flags, "--github");
+    const pr = flagInt(parsed.flags, "--pr", "--pr");
+    const issue = flagInt(parsed.flags, "--issue", "--issue");
+    const path = flagString(parsed.flags, "--path");
+    const repoFlag = flagString(parsed.flags, "--repo");
+    if (pr != null && issue != null) {
+        throw new UsageError("--pr and --issue are mutually exclusive", {
+            example: "uploads feed create --repo owner/repo --pr 123",
+        });
+    }
+    if (github && (pr != null || issue != null)) {
+        throw new UsageError("--github cannot be combined with --pr or --issue", {
+            example: "uploads feed create --github owner/repo#123",
+        });
+    }
+    if (github) {
+        const ref = parseGithubIssueRef(github);
+        if (!ref) {
+            throw new UsageError("--github must be owner/repo#number or a GitHub issue/PR URL", {
+                example: "uploads feed create --github owner/repo#123",
+            });
+        }
+        if (repoFlag && repoFlag.trim().toLowerCase() !== ref.repo) {
+            throw new UsageError("--repo does not match --github", {
+                example: "uploads feed create --github owner/repo#123",
+            });
+        }
+        return {
+            repo: ref.repo,
+            path,
+            number: ref.number,
+            kind: ref.kind,
+        };
+    }
+    return {
+        repo: resolveRepo(repoFlag).toLowerCase(),
+        path,
+        ...(pr != null ? { number: pr, kind: "pull" } : {}),
+        ...(issue != null ? { number: issue, kind: "issue" } : {}),
+    };
+}
+export async function runFeed(ctx, args, help = false) {
+    const parsed = parseCommandArgs(args);
+    const action = parsed.positionals[0];
+    if (help || parsed.help) {
+        writeCommandHelp(FEED_HELP);
+        return 0;
+    }
+    if (!action) {
+        throw new UsageError("feed requires a subcommand: create, show, list, or delete", {
+            example: "uploads feed create --repo owner/repo --pr 123",
+        });
+    }
+    switch (action) {
+        case "create": {
+            const feed = await ctx.client.createFeed(resolveCreateOptions(parsed));
+            if (ctx.json)
+                await writeJson(feed);
+            else
+                await writeStdout(`${feed.url}\n`);
+            if (!ctx.quiet && !ctx.json)
+                process.stderr.write("warning: feeds are public to anyone with the URL\n");
+            return 0;
+        }
+        case "show": {
+            const id = parsed.positionals[1];
+            if (!id)
+                throw new UsageError("feed show requires a feed ID");
+            const feed = await ctx.client.getFeed(id);
+            if (ctx.json)
+                await writeJson(feed);
+            else
+                await writeStdout(`${feed.url}\n`);
+            return 0;
+        }
+        case "list": {
+            const page = await ctx.client.listFeeds({
+                limit: flagInt(parsed.flags, "--limit", "--limit"),
+                cursor: flagString(parsed.flags, "--cursor"),
+            });
+            if (ctx.json)
+                await writeJson(page);
+            else {
+                for (const feed of page.feeds)
+                    await writeStdout(`${feed.id}  ${feed.url}  ${feed.title}\n`);
+                if (page.nextCursor)
+                    process.stderr.write(`cursor: ${page.nextCursor}\n`);
+            }
+            return 0;
+        }
+        case "delete": {
+            const id = parsed.positionals[1];
+            if (!id)
+                throw new UsageError("feed delete requires a feed ID");
+            const result = await ctx.client.deleteFeed(id);
+            if (ctx.json)
+                await writeJson(result);
+            else if (!ctx.quiet)
+                process.stderr.write(`deleted feed ${result.id}\n`);
+            return 0;
+        }
+        default:
+            throw new UsageError(`unknown feed command: ${action} (expected create, show, list, or delete)`, { example: "uploads feed create --repo owner/repo --pr 123" });
+    }
+}

package/dist/commands/install.d.ts

@@ -31,6 +31,12 @@ export declare function npmTooOldHint(version: string): string;
  */
 export declare function probeSkillTooling(run: CommandRunner): string | undefined;
 export declare function runStep(run: CommandRunner, command: string[]): StepResult;
+/**
+ * True when `mcp list` output already names this server.
+ * Matches a name token (Claude's `uploads: url` form, tables, JSON) and not
+ * a substring of a host like `agents.uploads.sh`.
+ */
+export declare function mcpListIncludesName(output: string, name: string): boolean;
 export declare function runInstall(args: string[], opts: {
     globals: GlobalFlags;
     json?: boolean;

package/dist/commands/install.js

@@ -1,6 +1,6 @@
 import { flagBool, flagString, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { resolveConfig } from "../config.js";
-import { execRunner } from "../github-gh.js";
+import { execRunner, timedExecRunner } from "../github-gh.js";
 import { writeCommandHelp } from "../cli-style.js";
 import { HOOK_COMMAND, HOOK_INVOCATION, installHookManifests, } from "../hooks-install.js";
 export const DEFAULT_MCP_URL = "https://agents.uploads.sh/mcp";
@@ -36,7 +36,9 @@ export const MCP_CLIENTS = [
         // Codex HTTP MCP has no --header; auth is OAuth on first use (same as the
         // plugin's .mcp.json). Passing --bearer-token-env-var UPLOADS_TOKEN would
         // break machines that signed in via `uploads login` (token lives in the
-        // config file, not the environment).
+        // config file, not the environment). A second `mcp add` re-opens Codex's
+        // localhost callback ("Authentication complete. You may close this
+        // window.") — probe `mcp list` first so a refresh does not do that.
         command: (name, url) => ["codex", "mcp", "add", name, "--url", url],
     },
     {
@@ -58,9 +60,10 @@ workspace from the bearer token, so only the token is needed.
 Claude Code and Codex ship the same reminder via their plugins (same command:
 \`${HOOK_INVOCATION}\`) — install those plugins instead of relying on this step.
 
-Safe to re-run. An MCP server already registered under this name is reported
-as \`already configured\` and left as-is — including the token it was created
-with. To point it at a new token: \`<cli> mcp remove <name>\` first
+Safe to re-run. Before \`mcp add\`, install checks \`mcp list\`. A server that is
+already registered is reported as \`already configured\` and left as-is —
+including the token it was created with — so a refresh does not open a browser
+for OAuth. To point it at a new token: \`<cli> mcp remove <name>\` first
 (e.g. \`claude mcp remove uploads\`).
 
 Usage:
@@ -187,6 +190,28 @@ function skillCommand(skill) {
 function isAlreadyConfigured(error) {
     return /already exists|already (configured|registered|present)|duplicate/i.test(error);
 }
+/**
+ * True when `mcp list` output already names this server.
+ * Matches a name token (Claude's `uploads: url` form, tables, JSON) and not
+ * a substring of a host like `agents.uploads.sh`.
+ */
+export function mcpListIncludesName(output, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const token = new RegExp(`(?:^|[\\s"'\\[{,])${escaped}(?:[:\\s"',\\]}]|$)`, "m");
+    return token.test(output);
+}
+/** Best-effort `mcp list` probe. Never opens a browser; times out on the default runner. */
+const MCP_LIST_TIMEOUT_MS = 8_000;
+function probeMcpAlreadyConfigured(run, client, name) {
+    const probe = run === execRunner ? timedExecRunner(MCP_LIST_TIMEOUT_MS) : run;
+    try {
+        const output = probe(client.id, ["mcp", "list"]);
+        return mcpListIncludesName(output, name) ? "yes" : "no";
+    }
+    catch (err) {
+        return isEnoent(err) ? "missing" : "no";
+    }
+}
 function mcpStepKey(client) {
     return `mcp:${client.id}`;
 }
@@ -215,8 +240,25 @@ function partitionSteps(results) {
     }
     return { skills, mcp, other };
 }
-/** Run one client's `mcp add`; missing binaries skip, duplicates are already-configured. */
-function runMcpClientStep(run, command) {
+/**
+ * Run one client's `mcp add`. Probe `mcp list` first so a refresh does not
+ * re-run add — Codex (and some other clients) treat a second add as success
+ * and open a localhost OAuth callback even when the server is already there.
+ */
+function runMcpClientStep(run, client, name, url, bearer) {
+    const command = client.command(name, url, bearer);
+    const listed = probeMcpAlreadyConfigured(run, client, name);
+    if (listed === "yes") {
+        return { command, ok: true, skipped: "already-configured" };
+    }
+    if (listed === "missing") {
+        return {
+            command,
+            ok: true,
+            skipped: "missing-cli",
+            error: `${client.id} not found on PATH`,
+        };
+    }
     try {
         const output = run(command[0], command.slice(1)).trim();
         return { command, ok: true, output: output || undefined };
@@ -412,7 +454,7 @@ export async function runInstall(args, opts, help = false) {
                 results[key] = { command, ok: true, skipped: "dry-run" };
             }
             else {
-                results[key] = runMcpClientStep(run, command);
+                results[key] = runMcpClientStep(run, client, name, url, bearer);
             }
         }
     }

package/dist/commands/update.js

@@ -11,9 +11,9 @@ const UPDATE_HELP = `uploads update — update the CLI and refresh agent integra
 Upgrades the globally installed npm package, then re-runs \`uploads install\` so
 the agent skills match the new version. Skills drift on their own, so this
 refreshes them even when the CLI is already current. An MCP server already
-registered is left as-is (\`already configured\`) — \`claude mcp add\` (and the
-Codex/Grok equivalents) never overwrite an existing entry. A missing agent CLI
-is skipped so it does not fail the rest of the refresh.
+registered is left as-is (\`already configured\`) — install checks \`mcp list\`
+first so \`mcp add\` (and Codex's OAuth browser) does not run again. A missing
+agent CLI is skipped so it does not fail the rest of the refresh.
 
 Usage:
   uploads update [options]

package/dist/comment-render.generated.d.ts

@@ -90,7 +90,7 @@ export interface AttachmentItem {
     url: string | null;
     /** Prefer for `<img src>` on GitHub (Camo-friendly host). Falls back to `url`. */
     embedUrl?: string | null;
-    /** Canonical `/f/` file-page URL (server-computed). Preferred click-through target; falls back to `url`. */
+    /** Preferred click-through (PR feed item, `/f/` file page, or equivalent). Falls back to `url`. */
     pageUrl?: string | null;
     /**
      * The only canonical metadata the managed comment renders (issue #365).

package/dist/github.d.ts

@@ -5,9 +5,21 @@ export interface GithubCoordinate {
     coordinate: string;
     canonicalUrl: string;
 }
+/** Parsed `owner/repo#number` or a strict GitHub issue/PR URL. */
+export interface GithubIssueRef {
+    repo: string;
+    number: number;
+    kind?: "pull" | "issue";
+}
 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;
+/**
+ * Parse `owner/repo#number` or a strict
+ * `https://github.com/<owner>/<repo>/issues|pull/<number>` URL. Kind is set
+ * only when the URL path names `/pull/` or `/issues/`.
+ */
+export declare function parseGithubIssueRef(value: string): GithubIssueRef | undefined;
 /** Normalize a GitHub issue or pull-request coordinate for gallery linking. */
 export declare function normalizeGithubCoordinate(value: string): GithubCoordinate | undefined;
 /**

package/dist/github.js

@@ -13,6 +13,46 @@ export function parseRepoFromRemoteUrl(url) {
     const repo = match?.[1];
     return repo && isValidRepo(repo) ? repo : undefined;
 }
+/**
+ * Parse `owner/repo#number` or a strict
+ * `https://github.com/<owner>/<repo>/issues|pull/<number>` URL. Kind is set
+ * only when the URL path names `/pull/` or `/issues/`.
+ */
+export function parseGithubIssueRef(value) {
+    const input = value.trim();
+    const coordinate = /^([^/\s#]+)\/([^/\s#]+)#([1-9][0-9]*)$/.exec(input);
+    if (coordinate)
+        return githubIssueRef(coordinate[1], coordinate[2], coordinate[3]);
+    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;
+        const match = /^\/([^/]+)\/([^/]+)\/(issues|pull)\/([1-9][0-9]*)\/?$/.exec(url.pathname);
+        if (!match)
+            return undefined;
+        return githubIssueRef(match[1], match[2], match[4], match[3] === "issues" ? "issue" : "pull");
+    }
+    catch {
+        return undefined;
+    }
+}
+function githubIssueRef(ownerRaw, repositoryRaw, numberRaw, kind) {
+    const repo = ownerRaw + "/" + repositoryRaw;
+    const number = Number(numberRaw);
+    if (!isValidRepo(repo) || !Number.isSafeInteger(number))
+        return undefined;
+    return {
+        repo: ownerRaw.toLowerCase() + "/" + repositoryRaw.toLowerCase(),
+        number,
+        ...(kind ? { kind } : {}),
+    };
+}
 /** Normalize a GitHub issue or pull-request coordinate for gallery linking. */
 export function normalizeGithubCoordinate(value) {
     const input = value.trim();

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { assertFetchableUploadUrl, fetchUploadSource, filenameFromUploadUrl, res
 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, type FindFilesOptions, type FindFilesItem, type FindFilesResult, type MetadataKeysResult, type MetadataValuesResult, type GetMetadataResult, type PatchMetadataOptions, type ResolveGhPrefixOptions, type ResolveGhPrefixResult, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";
-export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, GH_PRIVATE_ROOT, ghPrivateKeyPrefix, ghPrivateAttachmentKey, ghPrivateBranchKeyPrefix, ghPrivateBranchAttachmentKey, ghAttachmentKeyForMode, ghBranchAttachmentKeyForMode, parseGhKey, parseGhPrivateKey, type AttachmentItem, type GhTarget, type GhTargetKind, type GhKeyMode, } from "./github.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseGithubIssueRef, parseRepoFromRemoteUrl, GH_PRIVATE_ROOT, ghPrivateKeyPrefix, ghPrivateAttachmentKey, ghPrivateBranchKeyPrefix, ghPrivateBranchAttachmentKey, ghAttachmentKeyForMode, ghBranchAttachmentKeyForMode, parseGhKey, parseGhPrivateKey, type AttachmentItem, type GithubIssueRef, type GhTarget, type GhTargetKind, type GhKeyMode, } from "./github.js";
 export { DEFAULT_OPTIMIZE_MAX_EDGE, DEFAULT_OPTIMIZE_QUALITY, optimizeImageForUpload, rewriteKeyExtension, withImageExtension, type OptimizeImageOptions, type OptimizeImageResult, type OptimizeOutputFormat, } from "./optimize.js";
 export { FRAME_PRESETS, applyFrame, listFramePresets, resolveFrameId, type FrameFit, type FrameOptions, type FrameResult, } from "./frame.js";
 export { execRunner, resolveRepo, upsertAttachmentsComment, type CommandRunner, } from "./github-gh.js";

package/dist/index.js

@@ -10,7 +10,7 @@ export { assertFetchableUploadUrl, fetchUploadSource, filenameFromUploadUrl, res
 export { createUploadsClient, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";
-export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, 
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseGithubIssueRef, parseRepoFromRemoteUrl, 
 // Private-repo randomized-prefix builders (issue #631) — needed by the
 // hosted MCP (apps/mcp), which builds keys in-process rather than via
 // the CLI's own commands.ts.

package/dist/mcp/output-schemas.d.ts

@@ -26,6 +26,7 @@ export declare const searchDocsResultSchema: JsonSchema;
 export declare const promoteToolResultSchema: JsonSchema;
 export declare const galleryResultSchema: JsonSchema;
 export declare const galleryFindResultSchema: JsonSchema;
+export declare const feedResultSchema: JsonSchema;
 /** Hosted catalog — every tool must have an entry. */
 export declare const hostedOutputSchemas: Record<string, JsonSchema>;
 /** Shared-shape stdio tools. Hosted-only tools (`promote`, `repo_link_status`) omitted. */

package/dist/mcp/output-schemas.js

@@ -337,6 +337,39 @@ export const galleryFindResultSchema = objectSchema({
     galleries: { type: "array", items: galleryResultSchema },
     nextCursor: nullableString,
 });
+const feedItemSchema = objectSchema({
+    id: { type: "string" },
+    objectKey: { type: "string" },
+    filename: { type: "string" },
+    status: { type: "string" },
+    url: nullableString,
+    embedUrl: nullableString,
+    pageUrl: { type: "string" },
+    contentType: nullableString,
+    size: { type: ["number", "null"] },
+    uploaded: nullableString,
+    modified: nullableString,
+    path: nullableString,
+    state: nullableString,
+    posterUrl: { type: "string" },
+    videoDimensions: {
+        type: "object",
+        additionalProperties: true,
+    },
+});
+export const feedResultSchema = objectSchema({
+    id: { type: "string" },
+    url: { type: "string" },
+    workspace: { type: "string" },
+    repo: { type: "string" },
+    path: nullableString,
+    number: { type: ["number", "null"] },
+    kind: nullableString,
+    title: { type: "string" },
+    createdAt: { type: "string" },
+    updatedAt: { type: "string" },
+    items: { type: "array", items: feedItemSchema },
+});
 /** Hosted catalog — every tool must have an entry. */
 export const hostedOutputSchemas = {
     gallery_create: galleryResultSchema,
@@ -344,6 +377,8 @@ export const hostedOutputSchemas = {
     gallery_add: galleryItemSchema,
     gallery_link: galleryReferenceSchema,
     gallery_find_by_reference: galleryFindResultSchema,
+    feed_create: feedResultSchema,
+    feed_get: feedResultSchema,
     put: putResultSchema,
     list: listResultSchema,
     delete: deleteResultSchema,
@@ -368,6 +403,8 @@ export const stdioOutputSchemas = {
     gallery_add: galleryItemSchema,
     gallery_link: galleryReferenceSchema,
     gallery_find_by_reference: galleryFindResultSchema,
+    feed_create: feedResultSchema,
+    feed_get: feedResultSchema,
     put: putResultSchema,
     list: listResultSchema,
     delete: deleteResultSchema,

package/dist/mcp/tools.js

@@ -4,7 +4,7 @@ import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
 import { fetchUploadSource, resolveUploadFilename } from "../fetch-upload-source.js";
-import { ghKeyPrefix, ghPrivateKeyPrefix } from "../github.js";
+import { ghKeyPrefix, ghPrivateKeyPrefix, parseGithubIssueRef } from "../github.js";
 import { safeCaptureFacts } from "../capture-facts.js";
 import { deriveRepoSlugFromGit } from "../keys.js";
 import { validateMetaMap } from "../metadata.js";
@@ -75,6 +75,12 @@ function galleryId(args) {
         usage("galleryId is required");
     return id;
 }
+function feedId(args) {
+    const id = optString(args, "feedId");
+    if (!id)
+        usage("feedId is required");
+    return id;
+}
 function galleryReference(args) {
     const provider = optString(args, "provider");
     const coordinate = optString(args, "coordinate");
@@ -86,6 +92,33 @@ function galleryReference(args) {
         usage("provider must be github");
     return { provider, coordinate };
 }
+function feedCreateOptions(args) {
+    const github = optString(args, "github");
+    const repo = optString(args, "repo");
+    const path = optString(args, "path");
+    const pr = optPosInt(args, "pr");
+    const issue = optPosInt(args, "issue");
+    if (pr != null && issue != null)
+        usage("pr and issue are mutually exclusive");
+    if (github && (pr != null || issue != null))
+        usage("github cannot be combined with pr or issue");
+    if (github) {
+        const ref = parseGithubIssueRef(github);
+        if (!ref)
+            usage("github must be owner/repo#number or a GitHub issue/PR URL");
+        if (repo && repo.trim().toLowerCase() !== ref.repo)
+            usage("repo does not match github");
+        return { repo: ref.repo, path, number: ref.number, kind: ref.kind };
+    }
+    if (!repo)
+        usage("repo is required");
+    return {
+        repo,
+        path,
+        ...(pr != null ? { number: pr, kind: "pull" } : {}),
+        ...(issue != null ? { number: issue, kind: "issue" } : {}),
+    };
+}
 const workspaceProp = {
     type: "string",
     description: "Override the workspace for this call (like the CLI's --workspace flag).",
@@ -289,6 +322,66 @@ export function createUploadsMcpTools(opts) {
                 });
             },
         },
+        {
+            name: "feed_create",
+            title: "Create change feed",
+            annotations: mcpWritePublic,
+            securitySchemes: mcpOAuthWrite,
+            description: "Create a public newest-first screenshot feed (same product as CLI `uploads feed create`). Pass `repo` alone for the whole GitHub repo. Pass `pr` plus `repo` — or `github` as owner/repo#123 / a GitHub PR URL — to scope that same feed to one pull request. `issue` does the same for an issue. Optional `path` filters by page-path metadata. Creating the same scope again returns the existing URL. This is a live query, not a curated gallery. Anyone who knows the URL can view it.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    repo: {
+                        type: "string",
+                        description: "GitHub owner/repo, for example acme/app. Required unless github is set.",
+                    },
+                    pr: {
+                        type: "integer",
+                        minimum: 1,
+                        description: "Scope the feed to this pull request. Same product as a repo feed — one extra filter. Mutually exclusive with issue and github.",
+                    },
+                    issue: {
+                        type: "integer",
+                        minimum: 1,
+                        description: "Scope the feed to this issue. Mutually exclusive with pr and github.",
+                    },
+                    github: {
+                        type: "string",
+                        description: "Scope via owner/repo#number or a GitHub issue/PR URL. Supplies repo when omitted. Mutually exclusive with pr and issue.",
+                    },
+                    path: {
+                        type: "string",
+                        description: "Optional exact page-path metadata filter, for example /settings.",
+                    },
+                    workspace: workspaceProp,
+                },
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const { client } = await clientFor(args);
+                return client.createFeed(feedCreateOptions(args));
+            },
+        },
+        {
+            name: "feed_get",
+            title: "Get change feed",
+            annotations: mcpRead,
+            securitySchemes: mcpOAuthRead,
+            description: "Get a workspace-owned change feed by ID, including its current newest-first screenshots and the canonical public /c/<id> URL. Each item includes pageUrl (`/c/<id>/<item>`) for the pager. The feed may be repo-wide or scoped to one pull request / issue (see `number` and `kind` on the result). Anyone with the URL can view the media.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    feedId: { type: "string", description: "Opaque feed ID." },
+                    workspace: workspaceProp,
+                },
+                required: ["feedId"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const { client } = await clientFor(args);
+                return client.getFeed(feedId(args));
+            },
+        },
         {
             name: "put",
             title: "Upload file",

package/dist/update-check.d.ts

@@ -6,7 +6,10 @@ export interface UpdateCache {
 }
 export interface UpdateCheckOptions {
     quiet?: boolean;
-    /** mcp is always skipped (stdio purity). */
+    /**
+     * `mcp` is always skipped (stdio purity). `update` is skipped so a successful
+     * upgrade does not immediately hint the old in-process version.
+     */
     command?: string;
     currentVersion?: string;
     cachePath?: string;

package/dist/update-check.js

@@ -3,7 +3,7 @@
  *
  * 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.
+ * `uploads update`, `uploads mcp`, UPLOADS_NO_UPDATE=1, or NO_UPDATE_NOTIFIER=1.
  */
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -75,7 +75,7 @@ export function writeUpdateCache(path, cache) {
 export async function checkForUpdate(opts = {}) {
     const current = opts.currentVersion ?? packageVersion();
     try {
-        if (opts.quiet || opts.command === "mcp") {
+        if (opts.quiet || opts.command === "mcp" || opts.command === "update") {
             return { current, updateAvailable: false };
         }
         if (truthyEnv("UPLOADS_NO_UPDATE") || truthyEnv("NO_UPDATE_NOTIFIER")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.54.0",
+  "version": "0.55.1",
   "mcpName": "sh.uploads/mcp",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",