@buildinternet/uploads 0.11.0 → 0.12.0

package/README.md

@@ -15,6 +15,8 @@ npx @buildinternet/uploads --help
 uploads setup
 uploads --version
 uploads attach ./before.png ./after.png
+uploads screenshot https://app.example --pr 123 --comment   # capture + host in one step
+uploads screenshot ./report.html --dark --selector "main"
 uploads put ./shot.png
 uploads put ./shot.png --destination screenshots
 uploads put ./shot.png --no-optimize
@@ -37,7 +39,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`, `gallery`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
+Commands: `attach`, `put`, `screenshot`, `gallery`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
 `reconcile`, `purge-expired`, `setup`, `install`, `login`, `whoami` (alias `status`),
 `logout`, `invite`, `admin`, `config`, `telemetry`, `report`, `doctor`, `health`, `mcp`,
 `completion`.
@@ -81,6 +83,15 @@ infers the pull request for the current branch via `gh`, uploads stable URLs, an
 or updates one marker-owned GitHub comment. It keeps loose `gh/...` attachments and linked public galleries in distinct sections, shows up to three available gallery images inline, and updates that same comment in place on every sync. Use `--pr`, `--issue`, and `--repo` to select
 the target explicitly, or `--no-comment` to upload without changing GitHub comments.
 
+**Screenshot capture:** `uploads screenshot <url|file.html>` renders a page to a
+hosted image in one step — no separate browser tooling needed. `--via auto`
+(default) drives a Chrome/Chromium already on the machine (`playwright-core`
+ships no browser; `--browser <path>`, `--cdp <endpoint>`, or the Playwright/
+Puppeteer caches all work), and falls back to server-side rendering when none
+is found. localhost/private URLs are local-only; `.html` files work on both
+backends. After capture it joins the same pipeline as `put` (optimize, frames,
+`--pr`/`--issue` comments, galleries). See `uploads screenshot --help`.
+
 **Keys / destinations:** default put uses the `screenshots` layout. Typed destinations
 (`--destination screenshots|gh|f`, MCP `destination`) set the root; `--pr`/`--issue`
 use `gh/…`. Workspaces may restrict put/sign to those roots via
@@ -128,7 +139,7 @@ Config layers (first match wins): CLI flags → env vars → `--env-file` → `~
 
 ## 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`, `set_metadata`, `find_files`, `usage`, `reconcile`, `purge_expired`, `comment`, `health`, 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`); `set_metadata` and `find_files` mirror `uploads meta set` and `uploads 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 (`health` 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`, 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`, `health`, 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 (`health` needs no auth).
 
 ```json
 { "command": "uploads", "args": ["--env-file", "/path/to/.env", "mcp"] }
@@ -136,7 +147,7 @@ Config layers (first match wins): CLI flags → env vars → `--env-file` → `~
 
 Or with `UPLOADS_TOKEN`/`UPLOADS_WORKSPACE` in the environment or user config. Claude Code: `claude mcp add uploads -- uploads --env-file /path/to/.env 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 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 (short progress; `--verbose` for underlying output). 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`, 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 (short progress; `--verbose` for underlying output). 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/async.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Run `fn` over `values` with bounded concurrency, preserving input order
+ * in the returned array. Used by multi-file attach (and similar fan-outs).
+ */
+export declare function mapBounded<T, R>(values: readonly T[], concurrency: number, fn: (value: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/async.js

@@ -0,0 +1,21 @@
+/**
+ * Run `fn` over `values` with bounded concurrency, preserving input order
+ * in the returned array. Used by multi-file attach (and similar fan-outs).
+ */
+export async function mapBounded(values, concurrency, fn) {
+    if (values.length === 0)
+        return [];
+    const limit = Math.max(1, Math.min(concurrency, values.length));
+    const result = Array.from({ length: values.length });
+    let next = 0;
+    async function worker() {
+        for (;;) {
+            const index = next++;
+            if (index >= values.length)
+                return;
+            result[index] = await fn(values[index], index);
+        }
+    }
+    await Promise.all(Array.from({ length: limit }, worker));
+    return result;
+}

package/dist/cli-catalog.d.ts

@@ -22,6 +22,13 @@ export declare const GLOBAL_FLAGS: readonly {
 }[];
 /** Common flags for put/attach (file-oriented commands). */
 export declare const PUT_LIKE_FLAGS: readonly string[];
+/**
+ * All flags `uploads screenshot` actually reads (verified against
+ * commands/screenshot.ts) — kept as its own explicit list rather than
+ * spreading PUT_LIKE_FLAGS, which includes `--name`/`--no-comment` that
+ * screenshot never parses.
+ */
+export declare const SCREENSHOT_FLAGS: readonly string[];
 export declare const LIST_LIKE_FLAGS: readonly string[];
 export declare const ROOT_COMMANDS: readonly CatalogCommand[];
 export declare const COMPLETION_SHELLS: readonly ["bash", "zsh", "fish"];

package/dist/cli-catalog.js

@@ -40,6 +40,51 @@ export const PUT_LIKE_FLAGS = [
     "--help",
     "-h",
 ];
+/**
+ * All flags `uploads screenshot` actually reads (verified against
+ * commands/screenshot.ts) — kept as its own explicit list rather than
+ * spreading PUT_LIKE_FLAGS, which includes `--name`/`--no-comment` that
+ * screenshot never parses.
+ */
+export const SCREENSHOT_FLAGS = [
+    "--via",
+    "--browser",
+    "--cdp",
+    "--viewport",
+    "--selector",
+    "--full-page",
+    "--dark",
+    "--light",
+    "--wait",
+    "--out",
+    "--no-upload",
+    "--destination",
+    "--prefix",
+    "--repo",
+    "--ref",
+    "--key",
+    "--alt",
+    "--width",
+    "--frame",
+    "--frame-url",
+    "--frame-fit",
+    "--no-optimize",
+    "--optimize-max-edge",
+    "--optimize-quality",
+    "--keep-exif",
+    "--no-git",
+    "--pr",
+    "--issue",
+    "--comment",
+    "--gallery",
+    "--meta",
+    "--dry-run",
+    "--format",
+    "--workspace",
+    "-w",
+    "--help",
+    "-h",
+];
 export const LIST_LIKE_FLAGS = [
     "--prefix",
     "--limit",
@@ -59,10 +104,16 @@ export const ROOT_COMMANDS = [
     },
     {
         name: "put",
-        usage: "put <file>",
+        usage: "put <file...>",
         summary: "Upload (+ URL + markdown for GitHub)",
         essential: true,
     },
+    {
+        name: "screenshot",
+        usage: "screenshot <target>",
+        summary: "Capture a URL or .html file and host it (local browser or remote render)",
+        essential: true,
+    },
     {
         name: "gallery",
         summary: "Create and organize public media galleries",

package/dist/cli.js

@@ -16,6 +16,7 @@ import { runCompletion } from "./commands/completion.js";
 import { runLogout, runWhoami } from "./commands/session.js";
 import { runTelemetry } from "./commands/telemetry.js";
 import { runReport } from "./commands/report.js";
+import { runScreenshot } from "./commands/screenshot.js";
 import { packageVersion } from "./package-version.js";
 import { checkForUpdate, maybeHintUpdate } from "./update-check.js";
 import { errorCodeFromUnknown, maybeShowFirstRunNotice, recordEvent, telemetryCommandName, } from "./telemetry.js";
@@ -75,7 +76,12 @@ function exitCode(err) {
             case "STORAGE_QUOTA":
             case "UPLOAD_BUDGET":
                 return 3;
+            case "BROWSER_NOT_FOUND":
+                return 2;
             case "NETWORK":
+            // Transient — same "retry, don't reconfigure" family as a network
+            // hiccup, not an auth/policy/budget denial (those are exit 3).
+            case "RATE_LIMITED":
                 return 4;
             default:
                 return 1;
@@ -99,6 +105,8 @@ const ERROR_HINTS = {
     UPLOAD_BUDGET: QUOTA_HINT,
     KEY_POLICY: "hint: use a typed destination (`--destination screenshots|gh`) or an allowed prefix; operators set allowlists with `pnpm workspace:limits --allowed-prefixes`\n",
     UNAUTHORIZED: "hint: token rejected — run `uploads login` to sign in again, or check UPLOADS_TOKEN / --token\n",
+    BROWSER_NOT_FOUND: "hint: no local browser found; try --via remote, or install Chrome / npx playwright install chromium\n",
+    RATE_LIMITED: "hint: transient rate limit — wait ~60s and retry\n",
 };
 function errorOut(err, format) {
     const payload = err instanceof UploadsError
@@ -260,6 +268,7 @@ export async function runCli(argv) {
                 break;
             case "attach":
             case "put":
+            case "screenshot":
             case "gallery":
             case "list":
             case "find":
@@ -278,6 +287,9 @@ export async function runCli(argv) {
                     case "put":
                         code = await runPut(ctx, cmdArgs, showHelp);
                         break;
+                    case "screenshot":
+                        code = await runScreenshot(ctx, cmdArgs, showHelp);
+                        break;
                     case "gallery":
                         code = await runGallery(ctx, cmdArgs, showHelp);
                         break;

package/dist/client.d.ts

@@ -336,6 +336,22 @@ export declare function mintWorkspaceToken(apiUrl: string, accessToken: string,
     label?: string;
     ttlSeconds?: number;
 }): Promise<MintTokenResult>;
+/**
+ * Parse API error bodies. Prefers the nested envelope
+ * `{ error: { code, type, message, details? } }`; still accepts the legacy
+ * flat `{ error: string, code?: string }` shape. Exported so other backends
+ * (e.g. the screenshot render endpoint) share this parsing instead of
+ * duplicating it — each caller supplies its own `fallback` message.
+ */
+export declare function extractErrorFields(body: unknown, fallback?: string): {
+    message: string;
+    code?: string;
+};
+/** Fetch + parse an error-response body via {@link extractErrorFields}. */
+export declare function parseErrorEnvelope(res: Response, fallback?: string): Promise<{
+    message: string;
+    code?: string;
+}>;
 export declare function createUploadsClient(config: UploadsClientConfig): {
     put(body: Uint8Array, opts: PutOptions & {
         filename: string;

package/dist/client.js

@@ -210,15 +210,17 @@ function mapApiError(status, error, code) {
 /**
  * Parse API error bodies. Prefers the nested envelope
  * `{ error: { code, type, message, details? } }`; still accepts the legacy
- * flat `{ error: string, code?: string }` shape.
+ * flat `{ error: string, code?: string }` shape. Exported so other backends
+ * (e.g. the screenshot render endpoint) share this parsing instead of
+ * duplicating it — each caller supplies its own `fallback` message.
  */
-function extractErrorFields(body) {
+export function extractErrorFields(body, fallback = "request failed") {
     if (typeof body === "object" && body && "error" in body) {
         const err = body.error;
         if (typeof err === "object" && err && "message" in err) {
             const nested = err;
             return {
-                message: typeof nested.message === "string" ? nested.message : "request failed",
+                message: typeof nested.message === "string" ? nested.message : fallback,
                 code: typeof nested.code === "string" ? nested.code : undefined,
             };
         }
@@ -229,12 +231,16 @@ function extractErrorFields(body) {
             return { message: err, code };
         }
     }
-    return { message: "request failed" };
+    return { message: fallback };
 }
-async function parseErrorResponse(res) {
+/** Fetch + parse an error-response body via {@link extractErrorFields}. */
+export async function parseErrorEnvelope(res, fallback = "request failed") {
     const body = await res.json().catch(() => ({}));
-    const { message, code } = extractErrorFields(body);
-    return mapApiError(res.status, message || res.statusText || "request failed", code);
+    return extractErrorFields(body, fallback);
+}
+async function parseErrorResponse(res) {
+    const { message, code } = await parseErrorEnvelope(res, res.statusText || "request failed");
+    return mapApiError(res.status, message, code);
 }
 export function createUploadsClient(config) {
     async function request(method, path, opts) {

package/dist/commands/completion.js

@@ -1,5 +1,5 @@
 import { parseCommandArgs, UsageError } from "../cli-args.js";
-import { COMPLETION_SHELLS, GLOBAL_FLAGS, LIST_LIKE_FLAGS, PUT_LIKE_FLAGS, ROOT_COMMANDS, isCompletionShell, } from "../cli-catalog.js";
+import { COMPLETION_SHELLS, GLOBAL_FLAGS, LIST_LIKE_FLAGS, PUT_LIKE_FLAGS, SCREENSHOT_FLAGS, ROOT_COMMANDS, isCompletionShell, } from "../cli-catalog.js";
 import { writeCommandHelp } from "../cli-style.js";
 const HELP = `uploads completion <shell>
 
@@ -28,6 +28,7 @@ function bashScript() {
     const globals = GLOBAL_FLAGS.map((g) => g.flag).join(" ");
     const putFlags = PUT_LIKE_FLAGS.join(" ");
     const listFlags = LIST_LIKE_FLAGS.join(" ");
+    const screenshotFlags = SCREENSHOT_FLAGS.join(" ");
     const subMaps = ROOT_COMMANDS.filter((c) => c.subcommands?.length).map((c) => {
         const names = c.subcommands.map((s) => s.name).join(" ");
         return `    ${c.name}) subs="${names}" ;;`;
@@ -52,6 +53,7 @@ _uploads() {
   local -a globals=(${globals})
   local -a put_flags=(${putFlags})
   local -a list_flags=(${listFlags})
+  local -a screenshot_flags=(${screenshotFlags})
 
   # Find the first non-global positional (the subcommand).
   local cmd="" i=1
@@ -102,6 +104,9 @@ ${subMaps.join("\n")}
       put|attach)
         COMPREPLY=( $(compgen -W "\${put_flags[*]}" -- "$cur") )
         ;;
+      screenshot)
+        COMPREPLY=( $(compgen -W "\${screenshot_flags[*]}" -- "$cur") )
+        ;;
       list|find)
         COMPREPLY=( $(compgen -W "\${list_flags[*]}" -- "$cur") )
         ;;
@@ -114,7 +119,7 @@ ${subMaps.join("\n")}
 
   # File paths for upload-style commands.
   case "$cmd" in
-    put|attach)
+    put|attach|screenshot)
       COMPREPLY=( $(compgen -f -- "$cur") )
       ;;
   esac
@@ -194,7 +199,7 @@ ${globalArgs} \\
     args)
       case $line[1] in
 ${subCases}
-      put|attach)
+      put|attach|screenshot)
         _files
         ;;
       esac
@@ -250,13 +255,18 @@ function fishScript() {
             continue;
         lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put attach' -l ${flag.slice(2)}`);
     }
+    for (const flag of SCREENSHOT_FLAGS) {
+        if (!flag.startsWith("--"))
+            continue;
+        lines.push(`complete -c uploads -n '__fish_seen_subcommand_from screenshot' -l ${flag.slice(2)}`);
+    }
     for (const flag of LIST_LIKE_FLAGS) {
         if (!flag.startsWith("--"))
             continue;
         lines.push(`complete -c uploads -n '__fish_seen_subcommand_from list find' -l ${flag.slice(2)}`);
     }
-    // File completion for put/attach
-    lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put attach' -F`);
+    // File completion for put/attach/screenshot
+    lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put attach screenshot' -F`);
     return lines.join("\n") + "\n";
 }
 export function generateCompletionScript(shell) {

package/dist/commands/install.js

@@ -189,6 +189,7 @@ export async function runInstall(args, opts, help = false) {
         .filter(([step]) => step.startsWith("skill:"))
         .map(([, r]) => r);
     const skillsOk = skillResults.length > 0 && skillResults.every((r) => r.ok);
+    const skillsFailed = skillResults.some((r) => !r.ok);
     if (!failed && !dryRun) {
         const stepLabels = [
             ...new Set(Object.keys(results).map((k) => (k.startsWith("skill:") ? "skills" : k))),
@@ -201,5 +202,9 @@ export async function runInstall(args, opts, help = false) {
             : "Fix the MCP step above, then re-run `uploads install mcp`.";
         process.stdout.write(`\nSkills are installed. ${next}\n`);
     }
+    else if (failed && !dryRun && skillsFailed) {
+        // Mixed or total skill failure used to print only per-step lines (#191).
+        process.stdout.write("\nSkill install incomplete. Fix the errors above, then re-run `uploads install skill`.\n");
+    }
     return failed ? 1 : 0;
 }

package/dist/commands/screenshot.d.ts

@@ -0,0 +1,6 @@
+import { type CliContext } from "../commands.js";
+import { type CommandRunner } from "../github-gh.js";
+import { captureScreenshot } from "../screenshot.js";
+export declare function runScreenshot(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner, 
+/** Injectable for tests — avoids launching a real browser or hitting the network. */
+captureImpl?: typeof captureScreenshot): Promise<number>;