@buildinternet/uploads 0.11.1 → 0.12.1

package/dist/screenshot-local.js

@@ -0,0 +1,310 @@
+/**
+ * Local screenshot backend — drives an already-installed Chrome/Chromium via
+ * `playwright-core` (no browser download; ~12 MB of JS).
+ *
+ * IMPORTANT: `playwright-core` must never be statically imported. This module
+ * is Node-only and is itself only ever reached via dynamic `await import()`
+ * from callers (never from index.ts / agent.ts / mcp/server.ts) so the
+ * apps/mcp Cloudflare Worker — which bundles those three entry points — never
+ * pulls this file (or playwright-core) into its bundle.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { UploadsError } from "./errors.js";
+function defaultPlaywrightCacheDir(env, platform) {
+    if (env.PLAYWRIGHT_BROWSERS_PATH)
+        return env.PLAYWRIGHT_BROWSERS_PATH;
+    if (platform === "darwin")
+        return join(homedir(), "Library", "Caches", "ms-playwright");
+    if (platform === "win32")
+        return join(homedir(), "AppData", "Local", "ms-playwright");
+    return join(homedir(), ".cache", "ms-playwright");
+}
+function defaultPuppeteerCacheDir(env, platform) {
+    if (env.PUPPETEER_CACHE_DIR)
+        return env.PUPPETEER_CACHE_DIR;
+    if (platform === "win32")
+        return join(homedir(), "AppData", "Local", "puppeteer", "cache");
+    return join(homedir(), ".cache", "puppeteer");
+}
+function defaultSystemCandidates(platform, env) {
+    if (platform === "darwin") {
+        return [
+            { kind: "chrome", path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" },
+            { kind: "edge", path: "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" },
+            { kind: "chromium", path: "/Applications/Chromium.app/Contents/MacOS/Chromium" },
+            { kind: "brave", path: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" },
+        ];
+    }
+    if (platform === "linux") {
+        return [
+            { kind: "chrome", path: "/usr/bin/google-chrome" },
+            { kind: "chrome", path: "/usr/bin/google-chrome-stable" },
+            { kind: "chromium", path: "/usr/bin/chromium-browser" },
+            { kind: "chromium", path: "/usr/bin/chromium" },
+            { kind: "edge", path: "/usr/bin/microsoft-edge" },
+        ];
+    }
+    if (platform === "win32") {
+        const pf = env.PROGRAMFILES ?? "C:\\Program Files";
+        const pf86 = env["PROGRAMFILES(X86)"] ?? "C:\\Program Files (x86)";
+        return [
+            { kind: "chrome", path: join(pf, "Google", "Chrome", "Application", "chrome.exe") },
+            { kind: "chrome", path: join(pf86, "Google", "Chrome", "Application", "chrome.exe") },
+            { kind: "edge", path: join(pf, "Microsoft", "Edge", "Application", "msedge.exe") },
+            { kind: "edge", path: join(pf86, "Microsoft", "Edge", "Application", "msedge.exe") },
+        ];
+    }
+    return [];
+}
+/** Executable subpath inside a Playwright chromium/chromium_headless_shell revision dir. */
+function playwrightExecutable(revisionDir, kind, platform, exists) {
+    const layouts = kind === "chromium"
+        ? platform === "darwin"
+            ? [
+                join(revisionDir, "chrome-mac-arm64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
+                join(revisionDir, "chrome-mac", "Chromium.app", "Contents", "MacOS", "Chromium"),
+            ]
+            : platform === "linux"
+                ? [join(revisionDir, "chrome-linux", "chrome")]
+                : platform === "win32"
+                    ? [join(revisionDir, "chrome-win", "chrome.exe")]
+                    : []
+        : platform === "darwin"
+            ? [join(revisionDir, "chrome-headless-shell-mac-arm64", "chrome-headless-shell")]
+            : platform === "linux"
+                ? [join(revisionDir, "chrome-headless-shell-linux", "chrome-headless-shell")]
+                : platform === "win32"
+                    ? [join(revisionDir, "chrome-headless-shell-win", "chrome-headless-shell.exe")]
+                    : [];
+    return layouts.find((p) => exists(p));
+}
+function scanPlaywrightCache(dir, platform, exists, readdir) {
+    if (!exists(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const kind of ["chromium", "chromium_headless_shell"]) {
+        const matches = entries
+            .filter((e) => e.startsWith(`${kind}-`))
+            .map((e) => ({ name: e, rev: Number.parseInt(e.slice(kind.length + 1), 10) || 0 }))
+            .toSorted((a, b) => b.rev - a.rev); // newest revision first
+        for (const m of matches) {
+            const exe = playwrightExecutable(join(dir, m.name), kind, platform, exists);
+            if (exe)
+                out.push({
+                    source: "playwright-cache",
+                    kind,
+                    executablePath: exe,
+                    revision: String(m.rev),
+                });
+        }
+    }
+    return out;
+}
+function puppeteerExecutable(buildDir, kind, platform, exists) {
+    let sub;
+    if (platform === "darwin")
+        sub = kind === "chrome" ? "chrome-mac-arm64" : "chrome-headless-shell-mac-arm64";
+    else if (platform === "win32")
+        sub = kind === "chrome" ? "chrome-win64" : "chrome-headless-shell-win64";
+    else
+        sub = kind === "chrome" ? "chrome-linux64" : "chrome-headless-shell-linux64";
+    let exe;
+    if (kind === "chrome") {
+        exe =
+            platform === "darwin"
+                ? join(buildDir, sub, "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing")
+                : platform === "win32"
+                    ? join(buildDir, sub, "chrome.exe")
+                    : join(buildDir, sub, "chrome");
+    }
+    else {
+        exe = join(buildDir, sub, platform === "win32" ? "chrome-headless-shell.exe" : "chrome-headless-shell");
+    }
+    return exists(exe) ? exe : undefined;
+}
+function scanPuppeteerCache(dir, platform, exists, readdir) {
+    const out = [];
+    for (const kind of ["chrome", "chrome-headless-shell"]) {
+        const kindDir = join(dir, kind);
+        if (!exists(kindDir))
+            continue;
+        let builds;
+        try {
+            builds = readdir(kindDir);
+        }
+        catch {
+            continue;
+        }
+        builds = builds
+            .filter((b) => exists(join(kindDir, b)))
+            .sort((a, b) => {
+            const va = (a.match(/[\d.]+$/) ?? ["0"])[0];
+            const vb = (b.match(/[\d.]+$/) ?? ["0"])[0];
+            return vb.localeCompare(va, undefined, { numeric: true });
+        });
+        for (const b of builds) {
+            const exe = puppeteerExecutable(join(kindDir, b), kind, platform, exists);
+            if (exe)
+                out.push({ source: "puppeteer-cache", kind, executablePath: exe, revision: b });
+        }
+    }
+    return out;
+}
+/**
+ * Scan for a usable local Chromium-family executable. Pure fs/env — never
+ * launches a browser. Roots are injectable so tests can fake a cache layout.
+ */
+export function detectLocalBrowser(roots = {}) {
+    const platform = roots.platform ?? process.platform;
+    const env = roots.env ?? process.env;
+    const exists = roots.exists ?? existsSync;
+    const readdir = roots.readdir ?? ((p) => readdirSync(p));
+    const envOverride = env.UPLOADS_CHROME_PATH || env.CHROME_PATH || undefined;
+    const candidates = [];
+    if (envOverride && exists(envOverride)) {
+        candidates.push({ source: "env", kind: "env-override", executablePath: envOverride });
+    }
+    const systemCandidates = roots.systemCandidates ?? defaultSystemCandidates(platform, env);
+    for (const c of systemCandidates) {
+        if (exists(c.path))
+            candidates.push({ source: "system", kind: c.kind, executablePath: c.path });
+    }
+    candidates.push(...scanPlaywrightCache(roots.playwrightCacheDir ?? defaultPlaywrightCacheDir(env, platform), platform, exists, readdir));
+    candidates.push(...scanPuppeteerCache(roots.puppeteerCacheDir ?? defaultPuppeteerCacheDir(env, platform), platform, exists, readdir));
+    // Ranking: env override > system Chrome (channel:'chrome' launch target,
+    // preferred default) > playwright cache chromium > puppeteer cache chrome >
+    // any other system browser > headless-shell builds last (see brief).
+    const rank = (c) => {
+        if (c.source === "env")
+            return 0;
+        if (c.source === "system" && c.kind === "chrome")
+            return 1;
+        if (c.source === "playwright-cache" && c.kind === "chromium")
+            return 2;
+        if (c.source === "puppeteer-cache" && c.kind === "chrome")
+            return 3;
+        if (c.source === "system")
+            return 4;
+        if (c.source === "playwright-cache" && c.kind === "chromium_headless_shell")
+            return 5;
+        if (c.source === "puppeteer-cache" && c.kind === "chrome-headless-shell")
+            return 6;
+        return 9;
+    };
+    const winner = [...candidates].toSorted((a, b) => rank(a) - rank(b))[0];
+    return { envOverride, candidates, winner };
+}
+async function loadPlaywrightCore() {
+    try {
+        // Dynamic import only — never hoist this to a static `import` statement.
+        // eslint-disable-next-line @typescript-eslint/consistent-type-imports
+        return (await import("playwright-core"));
+    }
+    catch (err) {
+        throw new UploadsError(`no local browser runtime available (playwright-core failed to load: ${err instanceof Error ? err.message : String(err)})`, "BROWSER_NOT_FOUND");
+    }
+}
+/** Launch a browser per the documented detection order. Never throws BROWSER_NOT_FOUND for a bad candidate — falls through to the next. */
+async function launchLocalBrowser(chromium, opts) {
+    if (opts.browserPath) {
+        return chromium.launch({ executablePath: opts.browserPath, headless: true });
+    }
+    const detected = opts.detectResult ?? detectLocalBrowser(opts.detectRoots);
+    if (detected.envOverride) {
+        try {
+            return await chromium.launch({ executablePath: detected.envOverride, headless: true });
+        }
+        catch {
+            // fall through
+        }
+    }
+    // Preferred default: let playwright-core resolve system Chrome itself.
+    try {
+        return await chromium.launch({ channel: "chrome", headless: true });
+    }
+    catch {
+        // fall through
+    }
+    try {
+        return await chromium.launch({ channel: "msedge", headless: true });
+    }
+    catch {
+        // fall through
+    }
+    for (const candidate of detected.candidates) {
+        if (candidate.source === "env")
+            continue; // already tried above
+        try {
+            return await chromium.launch({ executablePath: candidate.executablePath, headless: true });
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    throw new UploadsError("no local browser found — install Chrome, or run `npx playwright install chromium`", "BROWSER_NOT_FOUND");
+}
+/** Capture a PNG screenshot using a local (already-installed) browser. */
+export async function captureLocal(opts) {
+    const { chromium } = await loadPlaywrightCore();
+    let browser;
+    let usingCdp = false;
+    if (opts.cdp) {
+        try {
+            browser = await chromium.connectOverCDP(opts.cdp);
+            usingCdp = true;
+        }
+        catch (err) {
+            throw new UploadsError(`could not connect to CDP endpoint ${opts.cdp}: ${err instanceof Error ? err.message : String(err)}`, "BROWSER_NOT_FOUND");
+        }
+    }
+    else {
+        try {
+            browser = await launchLocalBrowser(chromium, opts);
+        }
+        catch (err) {
+            if (err instanceof UploadsError)
+                throw err;
+            throw new UploadsError(`could not launch a local browser: ${err instanceof Error ? err.message : String(err)}`, "BROWSER_NOT_FOUND");
+        }
+    }
+    try {
+        // deviceScaleFactor cannot be set on an existing CDP context — the Chrome
+        // process itself must have been launched with --force-device-scale-factor.
+        const context = usingCdp
+            ? (browser.contexts()[0] ?? (await browser.newContext()))
+            : await browser.newContext({
+                viewport: { width: opts.viewport.width, height: opts.viewport.height },
+                deviceScaleFactor: opts.viewport.deviceScaleFactor,
+                colorScheme: opts.colorScheme,
+            });
+        const page = usingCdp
+            ? await context.newPage()
+            : (context.pages()[0] ?? (await context.newPage()));
+        if (usingCdp) {
+            await page.setViewportSize({ width: opts.viewport.width, height: opts.viewport.height });
+            if (opts.colorScheme)
+                await page.emulateMedia({ colorScheme: opts.colorScheme });
+        }
+        const waitUntil = typeof opts.waitUntil === "string" ? opts.waitUntil : "load";
+        await page.goto(opts.url, { waitUntil, timeout: opts.timeoutMs ?? 30_000 });
+        if (typeof opts.waitUntil === "number")
+            await page.waitForTimeout(opts.waitUntil);
+        const png = opts.selector
+            ? await page.locator(opts.selector).screenshot({ timeout: opts.timeoutMs ?? 30_000 })
+            : await page.screenshot({ fullPage: opts.fullPage === true });
+        // Buffer extends Uint8Array — return it as-is rather than copying.
+        return png;
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/screenshot-remote.d.ts

@@ -0,0 +1,23 @@
+/** Matches the brief's remote-backend cap for inline HTML bodies. */
+export declare const MAX_REMOTE_HTML_BYTES: number;
+export interface RemoteRenderRequest {
+    url?: string;
+    html?: string;
+    viewport: {
+        width: number;
+        height: number;
+        deviceScaleFactor: number;
+    };
+    selector?: string;
+    fullPage?: boolean;
+    colorScheme?: "dark" | "light";
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | number;
+}
+export interface RemoteRenderOptions {
+    apiUrl: string;
+    token: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/** POST the render request; resolves with raw PNG bytes on 200. */
+export declare function captureRemote(body: RemoteRenderRequest, opts: RemoteRenderOptions): Promise<Uint8Array>;

package/dist/screenshot-remote.js

@@ -0,0 +1,79 @@
+/**
+ * Remote screenshot backend — POSTs to the workspace-authed render endpoint
+ * and gets raw PNG bytes back. No local browser required. Network-only; safe
+ * to import statically anywhere (no native/optional deps).
+ */
+import { parseErrorEnvelope } from "./client.js";
+import { UploadsError } from "./errors.js";
+const POST_TIMEOUT_MS = 30_000;
+/** Matches the brief's remote-backend cap for inline HTML bodies. */
+export const MAX_REMOTE_HTML_BYTES = 2 * 1024 * 1024;
+/**
+ * Maps the render endpoint's error codes onto CLI error codes. Mirrors
+ * client.ts's mapApiError conventions: `render_failed` -> RENDER_FAILED;
+ * render-budget denials arrive as the EXISTING `upload_budget_exceeded` code
+ * (renders draw from the monthly upload budget — no separate RENDER_BUDGET
+ * code), so they fall into the shared UPLOAD_BUDGET mapping/hints. The
+ * server's burst limiter reports `rate_limited` explicitly; a bare 429 with
+ * no body code is also treated as a throttle (more likely than a budget
+ * denial), both mapping to RATE_LIMITED — checked before the generic 429
+ * fallback so an explicit `upload_budget_exceeded` on a 429 still wins.
+ */
+function mapRenderError(status, message, code) {
+    if (status === 401 || code === "unauthorized")
+        return new UploadsError(message, "UNAUTHORIZED", status);
+    if (code === "upload_budget_exceeded")
+        return new UploadsError(message, "UPLOAD_BUDGET", status);
+    if (code === "render_failed")
+        return new UploadsError(message, "RENDER_FAILED", status);
+    if (code === "rate_limited")
+        return new UploadsError(message, "RATE_LIMITED", status);
+    if (status === 429)
+        return new UploadsError(message, "RATE_LIMITED", status);
+    return new UploadsError(message, "API_ERROR", status);
+}
+/** POST the render request; resolves with raw PNG bytes on 200. */
+export async function captureRemote(body, opts) {
+    if (body.html !== undefined) {
+        const htmlBytes = new TextEncoder().encode(body.html).byteLength;
+        if (htmlBytes > MAX_REMOTE_HTML_BYTES) {
+            throw new UploadsError(`html body exceeds the remote backend's ${MAX_REMOTE_HTML_BYTES} byte limit (use --via local instead)`, "USAGE");
+        }
+    }
+    const base = opts.apiUrl.replace(/\/$/, "");
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? POST_TIMEOUT_MS);
+    // The body reads stay inside the abort-guarded scope: the timer must cover
+    // the full response (a server stalling mid-stream would otherwise hang
+    // res.arrayBuffer() forever once the headers had arrived).
+    try {
+        const res = await fetchImpl(`${base}/v1/render`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${opts.token}`,
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const { message, code } = await parseErrorEnvelope(res, "render failed");
+            throw mapRenderError(res.status, message, code);
+        }
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        if (bytes.byteLength === 0) {
+            throw new UploadsError("render endpoint returned an empty response", "RENDER_FAILED");
+        }
+        return bytes;
+    }
+    catch (err) {
+        if (err instanceof UploadsError)
+            throw err;
+        const message = err instanceof Error ? err.message : "network request failed";
+        throw new UploadsError(message.includes("abort") ? "render request timed out" : message, "NETWORK");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/screenshot.d.ts

@@ -0,0 +1,74 @@
+import { captureRemote } from "./screenshot-remote.js";
+import type { DetectRoots } from "./screenshot-local.js";
+export type ScreenshotBackend = "auto" | "local" | "remote";
+export type WaitUntil = "load" | "domcontentloaded" | "networkidle" | number;
+export interface ScreenshotViewport {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+}
+export declare const DEFAULT_SCREENSHOT_VIEWPORT: ScreenshotViewport;
+/** Parses `WIDTHxHEIGHT[@SCALEx]`, e.g. "1280x800", "1280x800@2x", "1280x800@2". */
+export declare function parseViewport(raw: string | undefined): ScreenshotViewport;
+/** Parses `--wait`: "load" | "domcontentloaded" | "networkidle" | a millisecond count. */
+export declare function parseWaitUntil(raw: string | undefined): WaitUntil;
+export type ScreenshotTarget = {
+    kind: "url";
+    url: string;
+    localOnly: boolean;
+} | {
+    kind: "html-file";
+    path: string;
+    html: string;
+};
+/**
+ * True for localhost / private-network / link-local hosts — only reachable
+ * by the local backend. Accepts a bare hostname or an IPv6 literal with its
+ * brackets still attached (as returned by `new URL(...).hostname`, e.g.
+ * `"[::1]"`). Mirrors the server's `isPrivateRenderTarget` so `--via remote`
+ * fails fast for the same targets the render endpoint itself would reject.
+ */
+export declare function isPrivateOrLocalHost(hostname: string): boolean;
+/** Classifies a CLI target: http(s) URL, or a path to a local .html file. */
+export declare function classifyTarget(target: string): ScreenshotTarget;
+export interface CaptureScreenshotOptions {
+    target: string;
+    via: ScreenshotBackend;
+    browserPath?: string;
+    cdp?: string;
+    viewport?: ScreenshotViewport;
+    selector?: string;
+    fullPage?: boolean;
+    colorScheme?: "dark" | "light";
+    waitUntil?: WaitUntil;
+    apiUrl: string;
+    token: string;
+    /** Injectable for tests; forwarded to detectLocalBrowser. */
+    detectRoots?: DetectRoots;
+    /** Injectable for tests: replaces the local capture implementation. */
+    captureLocalImpl?: (opts: {
+        url: string;
+        browserPath?: string;
+        cdp?: string;
+        viewport: ScreenshotViewport;
+        selector?: string;
+        fullPage?: boolean;
+        colorScheme?: "dark" | "light";
+        waitUntil: WaitUntil;
+        detectRoots?: DetectRoots;
+        /** Pre-computed detection result from auto-routing, to avoid a second fs scan. */
+        detectResult?: import("./screenshot-local.js").DetectResult;
+    }) => Promise<Uint8Array>;
+    /** Injectable for tests: replaces the remote capture implementation. */
+    captureRemoteImpl?: typeof captureRemote;
+}
+export interface CaptureScreenshotResult {
+    png: Uint8Array;
+    filename: string;
+    backend: "local" | "remote";
+}
+/**
+ * Resolve target + options into PNG bytes via the local or remote backend.
+ * Shared by the CLI `screenshot` command and the MCP `screenshot` tool.
+ */
+export declare function captureScreenshot(opts: CaptureScreenshotOptions): Promise<CaptureScreenshotResult>;