@buildinternet/uploads 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# @buildinternet/uploads
+
+CLI and client for **uploads.sh** — upload files, get public URLs, and produce GitHub-ready markdown. Successor to the R2 scripts in `buildinternet-skills/github-screenshots`.
+
+## CLI
+
+Binary: `uploads` (also `pnpm uploads` from repo root after `pnpm install`).
+
+Install globally or run a pinned version without installing:
+
+```bash
+npm install --global @buildinternet/uploads
+npx @buildinternet/uploads@0.1.0 --help
+```
+
+```bash
+pnpm uploads setup --env-file .env
+pnpm uploads attach ./before.png ./after.png --env-file .env
+pnpm uploads put ./shot.png --env-file .env
+pnpm uploads put ./after.png --pr 123 --comment --env-file .env
+pnpm uploads doctor --env-file .env
+```
+
+Commands: `attach`, `put`, `comment`, `list`, `delete`, `setup`, `config`, `doctor`, `health`.
+
+`attach` is the agent-friendly default for GitHub media. It accepts one or more files,
+infers the pull request for the current branch via `gh`, uploads stable URLs, and creates
+or updates one managed attachments comment. Use `--pr`, `--issue`, and `--repo` to select
+the target explicitly, or `--no-comment` to upload without changing GitHub comments.
+
+Config layers (first match wins): CLI flags → env vars → `--env-file` → `~/.config/buildinternet/config`. See `config.example` for keys.
+
+## Programmatic use
+
+```ts
+import { createUploadsClient } from "@buildinternet/uploads";
+```
+
+Agent/MCP helpers: `@buildinternet/uploads/agent` (`createUploadsWorkerFileTools` for Workers).
+
+## Layout
+
+```
+src/
+  cli.ts            Entry + help
+  commands.ts       put, list, delete, comment, …
+  client.ts         HTTP client for the API
+  github.ts         PR/issue key paths + attachment comments
+  embed.ts          Markdown image output
+bin/uploads.js      Bin shim
+```
+
+## Commands
+
+```bash
+pnpm build        # tsc → dist/
+pnpm typecheck
+pnpm test
+pnpm pack:check   # verify the npm tarball contents
+```
+
+Maintainer release instructions: [`docs/releasing.md`](../../docs/releasing.md).
+
+Agent-oriented usage: [`skills/uploads-cli/SKILL.md`](../../skills/uploads-cli/SKILL.md). REST details: [`docs/api.md`](../../docs/api.md).

package/bin/uploads.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runCli } from "../dist/cli.js";
+
+runCli(process.argv)
+  .then((code) => process.exit(code ?? 0))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

package/dist/agent.d.ts

@@ -0,0 +1,8 @@
+import type { Files } from "files-sdk";
+import { type FileToolsOptions } from "files-sdk/ai-sdk";
+export type { FileReadToolName, FileToolName, FileWriteToolName } from "files-sdk/ai-sdk";
+/**
+ * Worker-side agent tools (Mode A). Pass `Files` from `createStorage()` —
+ * reuses files-sdk tool schemas; do not duplicate MCP tool definitions here.
+ */
+export declare function createUploadsWorkerFileTools(files: Files, opts?: Omit<FileToolsOptions, "files">): import("files-sdk/ai-sdk").FileTools | import("files-sdk/ai-sdk").ReadOnlyFileTools;

package/dist/agent.js

@@ -0,0 +1,24 @@
+import { createFileTools } from "files-sdk/ai-sdk";
+/**
+ * Worker-side agent tools (Mode A). Pass `Files` from `createStorage()` —
+ * reuses files-sdk tool schemas; do not duplicate MCP tool definitions here.
+ */
+export function createUploadsWorkerFileTools(files, opts = {}) {
+    const { overrides, requireApproval, ...rest } = opts;
+    return createFileTools({
+        files,
+        requireApproval: requireApproval ?? {
+            deleteFile: true,
+            uploadFile: false,
+            copyFile: true,
+            signUploadUrl: true,
+        },
+        overrides: {
+            uploadFile: {
+                description: "Upload a file for public hosting (e.g. GitHub embeds). Prefer keys under screenshots/.",
+            },
+            ...overrides,
+        },
+        ...rest,
+    });
+}

package/dist/cli-args.d.ts

@@ -0,0 +1,39 @@
+export interface GlobalFlags {
+    apiUrl?: string;
+    workspace?: string;
+    token?: string;
+    envFile?: string;
+    json?: boolean;
+    quiet?: boolean;
+}
+export interface ParsedArgv {
+    globals: GlobalFlags;
+    help: boolean;
+    command?: string;
+    /** Args starting at the command name (includes command-specific flags). */
+    rest: string[];
+}
+export declare function isHelpFlag(arg: string): boolean;
+/**
+ * Parse global flags that appear before the subcommand. Stops at the first
+ * positional token (the command name) or an unrecognized flag.
+ */
+export declare function parseArgv(argv: string[]): ParsedArgv;
+export declare class UsageError extends Error {
+    constructor(message: string);
+}
+export interface CommandFlags {
+    positionals: string[];
+    flags: Map<string, string | boolean>;
+    help: boolean;
+}
+/**
+ * Parse command-specific args. Supports `--flag value`, `--flag=value`, and
+ * boolean `--flag` flags.
+ */
+export declare function parseCommandArgs(args: string[]): CommandFlags;
+export declare function flagString(flags: CommandFlags["flags"], name: string): string | undefined;
+export declare function flagBool(flags: CommandFlags["flags"], name: string): boolean;
+/** Command-level workspace override (`--workspace` / `-w`). */
+export declare function commandWorkspace(flags: CommandFlags["flags"]): string | undefined;
+export declare function flagInt(flags: CommandFlags["flags"], name: string, label: string): number | undefined;

package/dist/cli-args.js

@@ -0,0 +1,129 @@
+const VALUE_GLOBALS = new Set(["--api-url", "--workspace", "-w", "--token", "--env-file"]);
+export function isHelpFlag(arg) {
+    return arg === "-h" || arg === "--help";
+}
+/**
+ * Parse global flags that appear before the subcommand. Stops at the first
+ * positional token (the command name) or an unrecognized flag.
+ */
+export function parseArgv(argv) {
+    const args = argv.slice(2);
+    const globals = {};
+    let help = false;
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (isHelpFlag(arg)) {
+            help = true;
+            i++;
+            continue;
+        }
+        if (arg === "--json") {
+            globals.json = true;
+            i++;
+            continue;
+        }
+        if (arg === "--quiet") {
+            globals.quiet = true;
+            i++;
+            continue;
+        }
+        if (VALUE_GLOBALS.has(arg)) {
+            const value = args[i + 1];
+            if (!value || value.startsWith("-")) {
+                throw new UsageError(`missing value for ${arg}`);
+            }
+            switch (arg) {
+                case "--api-url":
+                    globals.apiUrl = value;
+                    break;
+                case "--workspace":
+                case "-w":
+                    globals.workspace = value;
+                    break;
+                case "--token":
+                    globals.token = value;
+                    break;
+                case "--env-file":
+                    globals.envFile = value;
+                    break;
+            }
+            i += 2;
+            continue;
+        }
+        if (arg.startsWith("-"))
+            break;
+        break;
+    }
+    const rest = args.slice(i);
+    return { globals, help, command: rest[0], rest };
+}
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UsageError";
+    }
+}
+/**
+ * Parse command-specific args. Supports `--flag value`, `--flag=value`, and
+ * boolean `--flag` flags.
+ */
+export function parseCommandArgs(args) {
+    const positionals = [];
+    const flags = new Map();
+    let help = false;
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (isHelpFlag(arg)) {
+            help = true;
+            i++;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            const eq = arg.indexOf("=");
+            if (eq !== -1) {
+                flags.set(arg.slice(0, eq), arg.slice(eq + 1));
+                i++;
+                continue;
+            }
+            const name = arg;
+            const next = args[i + 1];
+            if (next && !next.startsWith("-")) {
+                flags.set(name, next);
+                i += 2;
+                continue;
+            }
+            flags.set(name, true);
+            i++;
+            continue;
+        }
+        positionals.push(arg);
+        i++;
+    }
+    return { positionals, flags, help };
+}
+export function flagString(flags, name) {
+    const value = flags.get(name);
+    return typeof value === "string" ? value : undefined;
+}
+export function flagBool(flags, name) {
+    return flags.get(name) === true;
+}
+/** Command-level workspace override (`--workspace` / `-w`). */
+export function commandWorkspace(flags) {
+    return flagString(flags, "--workspace") ?? flagString(flags, "-w");
+}
+export function flagInt(flags, name, label) {
+    const raw = flagString(flags, name);
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw)) {
+        throw new UsageError(`invalid ${label}: must be a positive integer (got ${raw})`);
+    }
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new UsageError(`invalid ${label}: must be a positive integer (got ${raw})`);
+    }
+    return n;
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,158 @@
+import { createUploadsClient } from "./client.js";
+import { resolveApiUrl, resolveConfig } from "./config.js";
+import { UploadsError } from "./errors.js";
+import { commandWorkspace, isHelpFlag, parseArgv, parseCommandArgs, UsageError, } from "./cli-args.js";
+import { runPut, runAttach, runList, runDelete, runHealth, runDoctor, runComment, } from "./commands.js";
+import { runConfig } from "./commands/config.js";
+import { runSetup } from "./commands/setup.js";
+const ROOT_HELP = `uploads — CLI for uploads.sh (GitHub image embeds)
+
+Usage:
+  uploads [globals] <command> [args]
+
+Config (first match wins, per key):
+  CLI flags           --api-url, --token, --workspace
+  environment         UPLOADS_API_URL, UPLOADS_TOKEN, UPLOADS_WORKSPACE
+  --env-file <path>
+  $BUILDINTERNET_CONFIG
+  ~/.config/buildinternet/config   (shared with github-screenshots)
+
+Workspace (within config layers):
+  --workspace, -w     override — global (before command) or per-command (after)
+  UPLOADS_WORKSPACE   env / config file
+  (else inferred from token up_<name>_…, else "default")
+
+Other globals (before command):
+  --api-url <url>     default: https://api.uploads.sh
+  --token <token>     or UPLOADS_TOKEN
+  --env-file <path>
+  --json              JSON on stdout
+  --quiet
+
+Commands:
+  attach <file...>     Attach media to the current PR (stable URLs + managed comment)
+  put <file>          Upload (+ URL + markdown for GitHub)
+  comment             Create/update a PR/issue attachments comment (via gh)
+  list                List objects
+  delete <key>        Delete object
+  setup               Guided config + token minting steps
+  config              Show path, init, or set shared config
+  doctor              Health + auth + workspace checks
+  health              API liveness (no auth)
+
+Put/list defaults (config file or env):
+  UPLOADS_DEFAULT_PREFIX, UPLOADS_DEFAULT_REPO, UPLOADS_DEFAULT_REF
+  UPLOADS_DEFAULT_WIDTH, UPLOADS_NO_GIT
+
+Examples:
+  uploads setup
+  uploads setup --token up_default_… --repo myorg/myapp
+  uploads attach ./before.png ./after.png
+  uploads put ./shot.png --ref 42
+  uploads doctor
+
+Agent/MCP: use createUploadsWorkerFileTools() from @buildinternet/uploads/agent on the Worker.
+`;
+function createContext(globals, requireToken, commandArgs) {
+    const cmdWorkspace = commandWorkspace(parseCommandArgs(commandArgs).flags);
+    const config = resolveConfig({
+        apiUrl: globals.apiUrl,
+        workspace: cmdWorkspace ?? globals.workspace,
+        token: globals.token,
+        envFile: globals.envFile,
+        requireToken,
+    });
+    return {
+        config,
+        client: createUploadsClient(config),
+        json: globals.json ?? false,
+        quiet: globals.quiet ?? false,
+        envFile: globals.envFile,
+    };
+}
+function exitCode(err) {
+    if (err instanceof UsageError)
+        return 2;
+    if (err instanceof UploadsError) {
+        switch (err.code) {
+            case "MISSING_TOKEN":
+            case "USAGE":
+                return 2;
+            case "UNAUTHORIZED":
+            case "NOT_FOUND":
+                return 3;
+            case "NETWORK":
+                return 4;
+            default:
+                return 1;
+        }
+    }
+    return 1;
+}
+function errorOut(err, json) {
+    const payload = err instanceof UploadsError
+        ? { error: err.message, code: err.code, status: err.status }
+        : err instanceof UsageError
+            ? { error: err.message, code: "USAGE" }
+            : { error: err instanceof Error ? err.message : String(err) };
+    if (json)
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+    else {
+        const msg = payload.error;
+        if (msg.includes("\n"))
+            process.stderr.write(`${msg}\n`);
+        else
+            process.stderr.write(`error: ${msg}\n`);
+    }
+}
+export async function runCli(argv) {
+    try {
+        const parsed = parseArgv(argv);
+        const json = parsed.globals.json ?? false;
+        if (!parsed.command) {
+            process.stderr.write(ROOT_HELP);
+            return parsed.help ? 0 : 2;
+        }
+        const cmdArgs = parsed.rest.slice(1);
+        const showHelp = parsed.help || cmdArgs.some(isHelpFlag);
+        switch (parsed.command) {
+            case "health":
+                return runHealth({ apiUrl: resolveApiUrl(parsed.globals), json }, cmdArgs, showHelp);
+            case "config":
+                return runConfig(cmdArgs, { json, envFile: parsed.globals.envFile }, showHelp);
+            case "setup":
+                return runSetup(cmdArgs, { json, envFile: parsed.globals.envFile }, showHelp);
+            case "attach":
+            case "put":
+            case "list":
+            case "delete":
+            case "doctor":
+            case "comment": {
+                const ctx = createContext(parsed.globals, !showHelp, cmdArgs);
+                switch (parsed.command) {
+                    case "attach":
+                        return runAttach(ctx, cmdArgs, showHelp);
+                    case "put":
+                        return runPut(ctx, cmdArgs, showHelp);
+                    case "comment":
+                        return runComment(ctx, cmdArgs, showHelp);
+                    case "list":
+                        return runList(ctx, cmdArgs, showHelp);
+                    case "delete":
+                        return runDelete(ctx, cmdArgs, showHelp);
+                    case "doctor":
+                        return runDoctor(ctx, cmdArgs, showHelp);
+                }
+            }
+            default:
+                process.stderr.write(`unknown command: ${parsed.command}\n\n${ROOT_HELP}`);
+                return 2;
+        }
+    }
+    catch (err) {
+        errorOut(err, argv.includes("--json"));
+        if (err instanceof UsageError && !argv.includes("--json"))
+            process.stderr.write(`\n${ROOT_HELP}`);
+        return exitCode(err);
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,55 @@
+import type { UploadsClientConfig } from "./config.js";
+export interface PutOptions {
+    key?: string;
+    contentType?: string;
+    prefix?: string;
+    repo?: string;
+    ref?: string;
+    deriveRepoFromGit?: boolean;
+}
+export interface ListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface PutResult {
+    workspace: string;
+    key: string;
+    url: string;
+    size: number;
+    contentType: string;
+}
+export interface ListItem {
+    key: string;
+    url: string | null;
+    size?: number;
+    uploaded?: string;
+}
+export interface ListResult {
+    items: ListItem[];
+    cursor: string | null;
+}
+export interface HeadResult {
+    key: string;
+    url: string | null;
+    size: number;
+    contentType: string;
+    uploaded?: string;
+}
+export interface DeleteResult {
+    key: string;
+    deleted: boolean;
+}
+export interface HealthResult {
+    ok: boolean;
+}
+export declare function createUploadsClient(config: UploadsClientConfig): {
+    put(body: Uint8Array, opts: PutOptions & {
+        filename: string;
+    }): Promise<PutResult>;
+    list(opts?: ListOptions): Promise<ListResult>;
+    delete(key: string): Promise<DeleteResult>;
+    head(key: string): Promise<HeadResult>;
+    health(): Promise<HealthResult>;
+};
+export type UploadsClient = ReturnType<typeof createUploadsClient>;

package/dist/client.js

@@ -0,0 +1,97 @@
+import { inferContentType } from "./embed.js";
+import { UploadsError } from "./errors.js";
+import { buildScreenshotKey } from "./keys.js";
+function encodeKeyPath(key) {
+    return key.split("/").map(encodeURIComponent).join("/");
+}
+function filesBase(config) {
+    return `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/files`;
+}
+function mapApiError(status, error) {
+    const normalized = error.toLowerCase();
+    if (status === 401 || normalized === "unauthorized") {
+        return new UploadsError(error, "UNAUTHORIZED", status);
+    }
+    if (status === 404 || normalized === "not found") {
+        return new UploadsError(error, "NOT_FOUND", status);
+    }
+    if (status === 400 && normalized === "invalid key") {
+        return new UploadsError(error, "INVALID_KEY", status);
+    }
+    return new UploadsError(error, "API_ERROR", status);
+}
+async function parseErrorResponse(res) {
+    const body = await res.json().catch(() => ({}));
+    const message = typeof body === "object" && body && "error" in body && typeof body.error === "string"
+        ? body.error
+        : res.statusText || "request failed";
+    return mapApiError(res.status, message);
+}
+export function createUploadsClient(config) {
+    async function request(method, path, opts) {
+        const headers = { ...opts?.headers };
+        if (opts?.auth !== false) {
+            headers.Authorization = `Bearer ${config.token}`;
+        }
+        let res;
+        try {
+            res = await fetch(path, {
+                method,
+                headers,
+                body: opts?.body,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "network request failed";
+            throw new UploadsError(message, "NETWORK");
+        }
+        if (!res.ok) {
+            throw await parseErrorResponse(res);
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+    return {
+        async put(body, opts) {
+            const key = opts.key ??
+                (await buildScreenshotKey({
+                    filename: opts.filename,
+                    fileBytes: body,
+                    prefix: opts.prefix,
+                    repo: opts.repo,
+                    ref: opts.ref,
+                    deriveRepoFromGit: opts.deriveRepoFromGit,
+                }));
+            const contentType = opts.contentType ?? inferContentType(opts.filename);
+            const result = await request("PUT", `${filesBase(config)}/${encodeKeyPath(key)}`, {
+                body,
+                headers: { "Content-Type": contentType },
+            });
+            if (result.url == null) {
+                throw new UploadsError("upload succeeded but workspace has no publicBaseUrl", "NO_PUBLIC_URL", 201);
+            }
+            return { ...result, url: result.url };
+        },
+        async list(opts = {}) {
+            const params = new URLSearchParams();
+            if (opts.prefix)
+                params.set("prefix", opts.prefix);
+            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", `${filesBase(config)}${qs ? `?${qs}` : ""}`);
+        },
+        async delete(key) {
+            return request("DELETE", `${filesBase(config)}/${encodeKeyPath(key)}`);
+        },
+        async head(key) {
+            return request("GET", `${filesBase(config)}/${encodeKeyPath(key)}`);
+        },
+        async health() {
+            return request("GET", `${config.apiUrl}/health`, { auth: false });
+        },
+    };
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,4 @@
+export declare function runConfig(args: string[], opts: {
+    json?: boolean;
+    envFile?: string;
+}, help?: boolean): Promise<number>;