@buildinternet/uploads 0.11.1 → 0.12.1

package/dist/commands.d.ts

@@ -6,6 +6,7 @@ import { type CommandRunner } from "./github-gh.js";
 import { type OptimizeImageOptions, type OptimizeImageResult } from "./optimize.js";
 import { type FrameResult } from "./frame.js";
 import type { PutDefaults } from "./config-file.js";
+import type { DetectRoots } from "./screenshot-local.js";
 /** Parallel fan-out for multi-file put/attach (matches files-sdk bulk default). */
 export declare const UPLOAD_BATCH_CONCURRENCY = 8;
 /** @deprecated Use UPLOAD_BATCH_CONCURRENCY. */
@@ -25,6 +26,8 @@ export declare function readFileArg(fileArg: string): Uint8Array;
  * neither is present. Shared by the CLI flags and the MCP tool arguments.
  */
 export declare function makeGhTarget(pr: number | undefined, issue: number | undefined, repoArg: string | undefined, run: CommandRunner): GhTarget | undefined;
+/** Reads --pr/--issue (+ --repo) into a GhTarget; undefined when neither flag is present. */
+export declare function ghTargetFromFlags(flags: CommandFlags["flags"], run: CommandRunner): GhTarget | undefined;
 /** Shared put/attach optimize flags + UPLOADS_NO_OPTIMIZE default. */
 export declare function optimizeOptionsFromFlags(flags: CommandFlags["flags"], defaults: PutDefaults): OptimizeImageOptions;
 export type PreparedUpload = OptimizeImageResult & {
@@ -37,6 +40,53 @@ export declare function prepareImageForUpload(bytes: Uint8Array, filename: strin
     frameFit?: "cover" | "contain";
     optimize: OptimizeImageOptions;
 }): Promise<PreparedUpload>;
+export interface UploadPreparedImageOptions {
+    frame: {
+        frameId?: string;
+        frameUrl?: string;
+        frameFit?: "cover" | "contain";
+    };
+    optimize: OptimizeImageOptions;
+    /** gh attachment key wins over `key` when both are set (matches every call site). */
+    ghTarget?: GhTarget;
+    key?: string;
+    prefix?: string;
+    repo?: string;
+    ref?: string;
+    deriveRepoFromGit?: boolean;
+    contentType?: string;
+    dryRun?: boolean;
+    metadata?: Record<string, string>;
+    provenanceClient?: string;
+    /**
+     * Alt text for the markdown. Takes the prepared result so callers whose
+     * default depends on the post-frame/optimize filename can use it — each
+     * call site's existing default is preserved verbatim (see
+     * .context/2026-07-16-screenshot-command-RESULT.md, "Simplify pass").
+     */
+    alt: (prepared: PreparedUpload) => string;
+    width?: number;
+}
+export interface UploadPreparedImageResult {
+    result: PutResult;
+    prepared: PreparedUpload;
+    markdown: string;
+}
+/**
+ * Shared bytes-oriented upload tail: frame + optimize the bytes, resolve the
+ * object key (gh attachment key wins over an explicit key; extension
+ * rewritten post-optimize), put, and build the GitHub embed markdown. Used by
+ * the screenshot CLI command, the MCP screenshot tool, and the MCP put
+ * tool's contentBase64 path — the three in-memory-bytes call sites.
+ * uploadPuts/uploadAttachments loop over file paths with their own bounded
+ * concurrency and delegate here per item.
+ */
+export declare function uploadPreparedImage(client: UploadsClient, bytes: Uint8Array, sourceName: string, opts: UploadPreparedImageOptions): Promise<UploadPreparedImageResult>;
+export declare function frameOptionsFromFlags(flags: CommandFlags["flags"]): {
+    frameId?: string;
+    frameUrl?: string;
+    frameFit?: "cover" | "contain";
+};
 /**
  * List every attachment under the target's prefix and create/update the
  * managed comment. Throws on gh failure — callers decide whether that is
@@ -174,7 +224,27 @@ export interface DoctorReport {
     /** Workspace/token mismatch warning (also present in hints). */
     warning?: string;
     hints: string[];
+    /** `screenshot`'s local-browser detection (fs scans only — never launches a browser). */
+    browser: {
+        /** false when this runtime has no Node fs/process (e.g. the apps/mcp Worker). */
+        supported: boolean;
+        found: boolean;
+        /** Which backend `uploads screenshot --via auto` would pick right now. */
+        autoBackend: "local" | "remote";
+        candidates: {
+            source: string;
+            kind: string;
+            executablePath: string;
+        }[];
+        /** The best candidate by rank (may differ from candidates[0], which is scan order). */
+        winner?: {
+            source: string;
+            kind: string;
+            executablePath: string;
+        };
+        note?: string;
+    };
 }
 /** Doctor's health + auth + workspace checks, shared by the CLI and the MCP tool. */
-export declare function buildDoctorReport(config: ResolvedConfig, client: UploadsClient): Promise<DoctorReport>;
+export declare function buildDoctorReport(config: ResolvedConfig, client: UploadsClient, detectRoots?: DetectRoots): Promise<DoctorReport>;
 export declare function runDoctor(ctx: CliContext, args: string[], help?: boolean): Promise<number>;

package/dist/commands.js

@@ -125,7 +125,7 @@ export function makeGhTarget(pr, issue, repoArg, run) {
     return { repo, kind: pr !== undefined ? "pull" : "issues", num: (pr ?? issue) };
 }
 /** Reads --pr/--issue (+ --repo) into a GhTarget; undefined when neither flag is present. */
-function ghTargetFromFlags(flags, run) {
+export function ghTargetFromFlags(flags, run) {
     return makeGhTarget(flagInt(flags, "--pr", "--pr"), flagInt(flags, "--issue", "--issue"), flagString(flags, "--repo"), run);
 }
 /**
@@ -205,7 +205,50 @@ export async function prepareImageForUpload(bytes, filename, opts) {
     const optimized = await optimizeImageForUpload(currentBytes, currentName, opts.optimize);
     return { ...optimized, frame: frameMeta };
 }
-function frameOptionsFromFlags(flags) {
+/**
+ * Shared bytes-oriented upload tail: frame + optimize the bytes, resolve the
+ * object key (gh attachment key wins over an explicit key; extension
+ * rewritten post-optimize), put, and build the GitHub embed markdown. Used by
+ * the screenshot CLI command, the MCP screenshot tool, and the MCP put
+ * tool's contentBase64 path — the three in-memory-bytes call sites.
+ * uploadPuts/uploadAttachments loop over file paths with their own bounded
+ * concurrency and delegate here per item.
+ */
+export async function uploadPreparedImage(client, bytes, sourceName, opts) {
+    const prepared = await prepareImageForUpload(bytes, sourceName, {
+        frameId: opts.frame.frameId,
+        frameUrl: opts.frame.frameUrl,
+        frameFit: opts.frame.frameFit,
+        optimize: opts.optimize,
+    });
+    let key = opts.ghTarget ? ghAttachmentKey(opts.ghTarget, prepared.filename) : opts.key;
+    if (key && prepared.optimized)
+        key = rewriteKeyExtension(key, prepared.filename);
+    const result = await client.put(prepared.bytes, {
+        filename: prepared.filename,
+        key,
+        prefix: opts.prefix,
+        repo: opts.repo,
+        ref: opts.ref,
+        contentType: prepared.optimized ? prepared.contentType : opts.contentType,
+        deriveRepoFromGit: opts.deriveRepoFromGit,
+        dryRun: opts.dryRun,
+        provenance: buildCliProvenance({
+            sourceName,
+            client: opts.provenanceClient,
+            optimized: prepared.optimized,
+            frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
+            keepExif: opts.optimize.keepExif === true,
+        }),
+        metadata: opts.metadata,
+    });
+    const markdown = buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
+        alt: opts.alt(prepared),
+        width: opts.width,
+    });
+    return { result, prepared, markdown };
+}
+export function frameOptionsFromFlags(flags) {
     const raw = flagString(flags, "--frame");
     let frameId;
     try {
@@ -415,43 +458,28 @@ export async function uploadPuts(opts) {
                         ? basename(opts.explicitKey)
                         : "stdin.bin"
                     : basename(file));
-            const prepared = await prepareImageForUpload(readFileArg(file), sourceName, {
-                ...opts.frame,
+            const { result, prepared, markdown } = await uploadPreparedImage(opts.client, readFileArg(file), sourceName, {
+                frame: opts.frame,
                 optimize: opts.optimize,
-            });
-            let key = opts.ghTarget
-                ? ghAttachmentKey(opts.ghTarget, prepared.filename)
-                : opts.explicitKey;
-            if (key && prepared.optimized)
-                key = rewriteKeyExtension(key, prepared.filename);
-            const result = await opts.client.put(prepared.bytes, {
-                filename: prepared.filename,
-                key,
+                ghTarget: opts.ghTarget,
+                key: opts.explicitKey,
                 prefix: opts.prefix,
                 repo: opts.repo,
                 ref: opts.ref,
-                contentType: prepared.optimized ? prepared.contentType : opts.contentType,
                 deriveRepoFromGit: opts.deriveRepoFromGit,
+                contentType: opts.contentType,
                 dryRun: opts.dryRun,
-                provenance: buildCliProvenance({
-                    sourceName,
-                    client: opts.provenanceClient,
-                    optimized: prepared.optimized,
-                    frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
-                    keepExif: opts.optimize.keepExif === true,
-                }),
                 metadata: opts.metadata,
+                provenanceClient: opts.provenanceClient,
+                alt: () => opts.alt ?? basename(sourceName),
+                width: opts.width,
             });
-            const alt = opts.alt ?? basename(sourceName);
             return {
                 ok: true,
                 upload: {
                     ...result,
                     file,
-                    markdown: buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
-                        alt,
-                        width: opts.width,
-                    }),
+                    markdown,
                     optimize: {
                         optimized: prepared.optimized,
                         skippedReason: prepared.skippedReason,
@@ -1434,8 +1462,52 @@ Examples:
   uploads --workspace acme --env-file .env doctor
   uploads doctor --json
 `;
+/**
+ * Best-effort local-browser detection for doctor. fs scans only, no browser
+ * launch. Guarded for non-Node runtimes as a precaution for any future
+ * non-Node consumer of this module — apps/mcp today only imports
+ * `buildMarkdown`/`buildScreenshotKey` from the package root, not
+ * `buildDoctorReport`, so this guard isn't exercised on that path currently.
+ */
+async function detectBrowserForDoctor(detectRoots) {
+    if (typeof process === "undefined" || !process.versions?.node) {
+        return {
+            supported: false,
+            found: false,
+            autoBackend: "remote",
+            candidates: [],
+            note: "browser detection is not supported in this runtime",
+        };
+    }
+    try {
+        const { detectLocalBrowser } = await import("./screenshot-local.js");
+        const { candidates, winner } = detectLocalBrowser(detectRoots);
+        return {
+            supported: true,
+            found: Boolean(winner),
+            autoBackend: winner ? "local" : "remote",
+            candidates: candidates.map((c) => ({
+                source: c.source,
+                kind: c.kind,
+                executablePath: c.executablePath,
+            })),
+            winner: winner
+                ? { source: winner.source, kind: winner.kind, executablePath: winner.executablePath }
+                : undefined,
+        };
+    }
+    catch (err) {
+        return {
+            supported: true,
+            found: false,
+            autoBackend: "remote",
+            candidates: [],
+            note: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 /** Doctor's health + auth + workspace checks, shared by the CLI and the MCP tool. */
-export async function buildDoctorReport(config, client) {
+export async function buildDoctorReport(config, client, detectRoots) {
     const mismatch = workspaceMismatch(config);
     const hints = [];
     if (mismatch)
@@ -1443,7 +1515,12 @@ export async function buildDoctorReport(config, client) {
     if (config.apiUrl.includes("localhost") || config.apiUrl.includes("127.0.0.1")) {
         hints.push("local API uses dev KV — prod tokens won't work unless minted with --local");
     }
-    const health = await client.health();
+    // Independent checks — fs-based browser detection doesn't depend on the
+    // network health probe (or vice versa).
+    const [browser, health] = await Promise.all([
+        detectBrowserForDoctor(detectRoots),
+        client.health(),
+    ]);
     let authOk = false;
     let authError;
     try {
@@ -1491,6 +1568,7 @@ export async function buildDoctorReport(config, client) {
         usage,
         warning: mismatch,
         hints,
+        browser,
     };
 }
 export async function runDoctor(ctx, args, help = false) {
@@ -1515,6 +1593,14 @@ export async function runDoctor(ctx, args, help = false) {
             ? `usage:     ${formatByteSize(report.usage.bytes ?? 0)}, ${formatCount(report.usage.objects ?? 0)} objects, ${formatCount(report.usage.uploadsInPeriod ?? 0)} uploads this period`
             : `usage:     failed — ${report.usage.error ?? "unknown"}`);
     }
+    if (report.browser.supported) {
+        lines.push(report.browser.found
+            ? `browser:   found (${report.browser.winner?.source}/${report.browser.winner?.kind}) — screenshot --via auto uses local`
+            : `browser:   none found — screenshot --via auto uses remote`);
+    }
+    else {
+        lines.push(`browser:   ${report.browser.note ?? "not supported in this runtime"}`);
+    }
     if (report.warning)
         lines.push(`warning:   ${report.warning}`);
     for (const h of report.hints)

package/dist/config-file.d.ts

@@ -1,5 +1,5 @@
 import type { UploadsClientConfig } from "./config.js";
-export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", "UPLOADS_DEFAULT_PREFIX", "UPLOADS_DEFAULT_REPO", "UPLOADS_DEFAULT_REF", "UPLOADS_DEFAULT_WIDTH", "UPLOADS_NO_GIT", "UPLOADS_NO_OPTIMIZE", "UPLOADS_KEEP_EXIF", "UPLOADS_NO_AUTO_META"];
+export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", "UPLOADS_DEFAULT_PREFIX", "UPLOADS_DEFAULT_REPO", "UPLOADS_DEFAULT_REF", "UPLOADS_DEFAULT_WIDTH", "UPLOADS_NO_GIT", "UPLOADS_NO_OPTIMIZE", "UPLOADS_KEEP_EXIF", "UPLOADS_NO_AUTO_META", "UPLOADS_SCREENSHOT_VIA"];
 export type UploadsConfigKey = (typeof UPLOADS_CONFIG_KEYS)[number];
 export type UploadsConfigValues = Partial<Record<UploadsConfigKey, string>>;
 export interface PutDefaults {
@@ -26,10 +26,36 @@ export declare function resolveConfigPath(flags?: {
 /** Parse UPLOADS_* keys from a dotenv-style file. Missing file → empty object. */
 export declare function loadConfigFile(path: string): UploadsConfigValues;
 export declare function mergePutDefaults(...layers: PutDefaults[]): PutDefaults;
+/** Raw `--env-file` / user-config-file contents, keyed the way both `resolve*Defaults` need. */
+export interface RawDefaultsConfig {
+    fromEnvFile: UploadsConfigValues;
+    fromUser: UploadsConfigValues;
+}
+/**
+ * Read the on-disk config once (`--env-file` when given, else the user
+ * config file) so callers that need both put-style and screenshot-style
+ * defaults from the same invocation (e.g. `runScreenshot`) don't each read
+ * the file separately. Pass the result to `resolvePutDefaults` /
+ * `resolveScreenshotDefaults` as their second argument.
+ */
+export declare function loadDefaultsRaw(flags?: {
+    envFile?: string;
+}): RawDefaultsConfig;
 /** Put defaults from env, optional env-file, and user config (same precedence as client config). */
 export declare function resolvePutDefaults(flags?: {
     envFile?: string;
-}): PutDefaults;
+}, preloaded?: RawDefaultsConfig): PutDefaults;
+export type ScreenshotBackendPref = "auto" | "local" | "remote";
+export interface ScreenshotDefaults {
+    via?: ScreenshotBackendPref;
+}
+/**
+ * `screenshot --via` default: flag (applied by the caller) > env >
+ * --env-file > user config file > "auto" (the caller's own fallback).
+ */
+export declare function resolveScreenshotDefaults(flags?: {
+    envFile?: string;
+}, preloaded?: RawDefaultsConfig): ScreenshotDefaults;
 export declare function redactToken(token: string | undefined): string;
 /** Create or update UPLOADS_* keys in the shared config file. Preserves other keys. */
 export declare function writeConfigKeys(path: string, keys: UploadsConfigValues, opts?: {

package/dist/config-file.js

@@ -13,6 +13,7 @@ export const UPLOADS_CONFIG_KEYS = [
     "UPLOADS_NO_OPTIMIZE",
     "UPLOADS_KEEP_EXIF",
     "UPLOADS_NO_AUTO_META",
+    "UPLOADS_SCREENSHOT_VIA",
 ];
 const PUT_DEFAULT_KEY_MAP = {
     prefix: "UPLOADS_DEFAULT_PREFIX",
@@ -165,14 +166,51 @@ export function mergePutDefaults(...layers) {
     }
     return out;
 }
+/**
+ * Read the on-disk config once (`--env-file` when given, else the user
+ * config file) so callers that need both put-style and screenshot-style
+ * defaults from the same invocation (e.g. `runScreenshot`) don't each read
+ * the file separately. Pass the result to `resolvePutDefaults` /
+ * `resolveScreenshotDefaults` as their second argument.
+ */
+export function loadDefaultsRaw(flags) {
+    const fromEnvFile = flags?.envFile ? loadConfigFile(flags.envFile) : {};
+    const fromUser = flags?.envFile ? {} : loadConfigFile(resolveConfigPath(flags));
+    return { fromEnvFile, fromUser };
+}
 /** Put defaults from env, optional env-file, and user config (same precedence as client config). */
-export function resolvePutDefaults(flags) {
+export function resolvePutDefaults(flags, preloaded) {
     const fromEnv = parsePutDefaultsFromEnv();
-    const fromEnvFile = flags?.envFile ? parsePutDefaultsFromRaw(loadConfigFile(flags.envFile)) : {};
-    const fromUser = flags?.envFile
-        ? {}
-        : parsePutDefaultsFromRaw(loadConfigFile(resolveConfigPath(flags)));
-    return mergePutDefaults(fromUser, fromEnvFile, fromEnv);
+    const { fromEnvFile, fromUser } = preloaded ?? loadDefaultsRaw(flags);
+    return mergePutDefaults(parsePutDefaultsFromRaw(fromUser), parsePutDefaultsFromRaw(fromEnvFile), fromEnv);
+}
+function isScreenshotBackendPref(value) {
+    return value === "auto" || value === "local" || value === "remote";
+}
+function parseScreenshotDefaultsFromRaw(raw) {
+    const out = {};
+    if (isScreenshotBackendPref(raw.UPLOADS_SCREENSHOT_VIA))
+        out.via = raw.UPLOADS_SCREENSHOT_VIA;
+    return out;
+}
+function parseScreenshotDefaultsFromEnv() {
+    const raw = {};
+    if (process.env.UPLOADS_SCREENSHOT_VIA)
+        raw.UPLOADS_SCREENSHOT_VIA = process.env.UPLOADS_SCREENSHOT_VIA;
+    return parseScreenshotDefaultsFromRaw(raw);
+}
+/**
+ * `screenshot --via` default: flag (applied by the caller) > env >
+ * --env-file > user config file > "auto" (the caller's own fallback).
+ */
+export function resolveScreenshotDefaults(flags, preloaded) {
+    const fromEnv = parseScreenshotDefaultsFromEnv();
+    const { fromEnvFile, fromUser } = preloaded ?? loadDefaultsRaw(flags);
+    return {
+        ...parseScreenshotDefaultsFromRaw(fromUser),
+        ...parseScreenshotDefaultsFromRaw(fromEnvFile),
+        ...fromEnv,
+    };
 }
 export function redactToken(token) {
     if (!token)

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-export { defaultConfigPath, resolveConfigPath, loadConfigFile, redactToken, writeConfigKeys, removeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, UPLOADS_CONFIG_KEYS, type UploadsConfigKey, type UploadsConfigValues, type PutDefaults, } from "./config-file.js";
+export { defaultConfigPath, resolveConfigPath, loadConfigFile, redactToken, writeConfigKeys, removeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, resolveScreenshotDefaults, UPLOADS_CONFIG_KEYS, type UploadsConfigKey, type UploadsConfigValues, type PutDefaults, type ScreenshotDefaults, type ScreenshotBackendPref, } from "./config-file.js";
 export interface UploadsClientConfig {
     apiUrl: string;
     workspace: string;

package/dist/config.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { loadConfigFile, resolveConfigPath } from "./config-file.js";
 import { UploadsError } from "./errors.js";
-export { defaultConfigPath, resolveConfigPath, loadConfigFile, redactToken, writeConfigKeys, removeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, UPLOADS_CONFIG_KEYS, } from "./config-file.js";
+export { defaultConfigPath, resolveConfigPath, loadConfigFile, redactToken, writeConfigKeys, removeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, resolveScreenshotDefaults, UPLOADS_CONFIG_KEYS, } from "./config-file.js";
 export const DEFAULT_API_URL = "https://api.uploads.sh";
 export const DEFAULT_WORKSPACE = "default";
 const TOKEN_WORKSPACE_RE = /^up_([a-z0-9][a-z0-9-]{1,62})_/;

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "FILE_NOT_FOUND" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_KEY" | "KEY_POLICY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "GITHUB_REQUIRED" | "API_ERROR" | "NETWORK" | "USAGE";
+export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "FILE_NOT_FOUND" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_KEY" | "KEY_POLICY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "GITHUB_REQUIRED" | "API_ERROR" | "NETWORK" | "USAGE" | "BROWSER_NOT_FOUND" | "RENDER_FAILED" | "RATE_LIMITED";
 export declare class UploadsError extends Error {
     readonly code: UploadsErrorCode;
     readonly status?: number;

package/dist/github-gh.js

@@ -42,9 +42,15 @@ export function resolveRepo(explicit, run = execRunner) {
 /** Resolve the pull request associated with the current branch. */
 export function resolveCurrentPullRequest(repo, run = execRunner) {
     try {
+        // `gh pr view --repo` requires an explicit selector (it refuses to infer
+        // from the current branch), so pass the branch name as the selector.
+        const branch = run("git", ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+        if (branch === "" || branch === "HEAD")
+            throw new Error("detached HEAD");
         const out = run("gh", [
             "pr",
             "view",
+            branch,
             "--repo",
             repo,
             "--json",

package/dist/mcp/tools.d.ts

@@ -1,3 +1,10 @@
+/**
+ * MCP tool set mirroring the CLI commands (put, attach, list, delete,
+ * usage, reconcile, purge_expired, comment, health, doctor). Config is
+ * resolved fresh per tool call so a
+ * per-call `workspace` argument behaves like the CLI's --workspace flag, and
+ * a missing token surfaces as a tool error rather than a startup failure.
+ */
 import type { GlobalFlags } from "../cli-args.js";
 import { type UploadsClient } from "../client.js";
 import { type UploadsClientConfig } from "../config.js";