@buildinternet/uploads 0.14.0 → 0.16.0

package/README.md

@@ -83,6 +83,17 @@ 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.
 
+**Branch staging (pre-PR):** `attach <files> --branch [name]` (also on
+`screenshot`) stages files against a git branch before any PR exists — the
+working mode for coding agents capturing as they go. Staged files live under
+`gh/<owner>/<repo>/branch/<branch>/…` and are promoted into the PR's
+attachments when one opens: automatically via the
+[GitHub App](https://uploads.sh/docs/github-app) webhook, or on the first
+`attach` after the PR exists (`--promote` forces it with no new files,
+`--no-promote` opts out). `uploads github link` inspects or claims the
+workspace↔repo binding the webhook path uses. Promoted staging is cleaned up
+server-side after ~7 days (~30 for branches that never got a PR).
+
 **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`

package/dist/cli-catalog.js

@@ -25,6 +25,7 @@ export const PUT_LIKE_FLAGS = [
     "--ref",
     "--pr",
     "--issue",
+    "--branch",
     "--comment",
     "--no-comment",
     "--format",
@@ -75,6 +76,7 @@ export const SCREENSHOT_FLAGS = [
     "--no-git",
     "--pr",
     "--issue",
+    "--branch",
     "--comment",
     "--gallery",
     "--meta",
@@ -131,6 +133,14 @@ export const ROOT_COMMANDS = [
         name: "comment",
         summary: "Create/update a PR/issue attachments comment (via gh)",
     },
+    {
+        name: "github",
+        summary: "Claim/inspect this workspace's binding to a GitHub repo",
+        subcommands: [
+            { name: "link", summary: "Claim or inspect the repo binding" },
+            { name: "doctor", summary: "Check the GitHub App's webhook event subscriptions" },
+        ],
+    },
     {
         name: "list",
         summary: "List objects (--meta k=v filters by queryable metadata)",

package/dist/cli.js

@@ -4,7 +4,7 @@ import { UploadsError } from "./errors.js";
 import { commandWorkspace, flagString, isHelpFlag, parseArgv, parseCommandArgs, UsageError, } from "./cli-args.js";
 import { formatRootHelp, wantsFullHelp } from "./cli-help.js";
 import { colorEnabled, createStyle } from "./cli-style.js";
-import { runPut, runAttach, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
+import { runPut, runAttach, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runGithub, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
 import { runConfig } from "./commands/config.js";
 import { runSetup } from "./commands/setup.js";
 import { runLogin } from "./commands/login.js";
@@ -278,7 +278,8 @@ export async function runCli(argv) {
             case "reconcile":
             case "purge-expired":
             case "doctor":
-            case "comment": {
+            case "comment":
+            case "github": {
                 const ctx = createContext(parsed.globals, !showHelp, cmdArgs);
                 switch (parsed.command) {
                     case "attach":
@@ -296,6 +297,9 @@ export async function runCli(argv) {
                     case "comment":
                         code = await runComment(ctx, cmdArgs, showHelp);
                         break;
+                    case "github":
+                        code = await runGithub(ctx, cmdArgs, showHelp);
+                        break;
                     case "list":
                         code = await runList(ctx, cmdArgs, showHelp);
                         break;

package/dist/client.d.ts

@@ -73,6 +73,8 @@ export interface ListItem {
     key: string;
     url: string | null;
     embedUrl?: string | null;
+    /** Canonical `/f/` page URL when the API provides it. Absent on older API deployments. */
+    pageUrl?: string;
     size?: number;
     uploaded?: string;
 }
@@ -170,8 +172,16 @@ export interface FindGalleriesByReferenceOptions {
     limit?: number;
     cursor?: string;
 }
-/** Reasons the bot did not post; the CLI treats any of them as "fall back to gh". */
-export type GithubCommentDeclineReason = "app_unconfigured" | "not_installed" | "forbidden" | "unavailable";
+/**
+ * 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):
+ * the target repo is bound to a different workspace (or is unbound and the
+ * caller is the communal `default` workspace, which can't claim new repos).
+ * Falling back to `gh` there would let the human's own credentials post
+ * anyway, defeating the point of the server-side gate, so the CLI surfaces
+ * the decline instead.
+ */
+export type GithubCommentDeclineReason = "app_unconfigured" | "not_installed" | "forbidden" | "not_authorized" | "unavailable";
 export type GithubCommentResult = {
     posted: true;
     action: "created" | "updated" | "skipped";
@@ -180,10 +190,54 @@ export type GithubCommentResult = {
 } | {
     posted: false;
     reason: GithubCommentDeclineReason;
+    message?: string;
+    fixUrl?: string;
+    required?: string[];
 };
+/** `POST /v1/:workspace/github/promote` request/response (server contract, PR #310). */
+export interface PromoteBranchAttachmentsOptions {
+    repo: string;
+    num: number;
+    branch: string;
+}
+export interface PromoteSkip {
+    key: string;
+    reason: string;
+}
+export interface PromoteBranchAttachmentsResult {
+    promoted: string[];
+    skipped: PromoteSkip[];
+}
+/** `GET`/`POST /v1/:workspace/github/link` result (server contract, phase 4b). */
+export interface GithubLinkResult {
+    repo: string;
+    linked: boolean;
+    workspace: string | null;
+    source: string | null;
+    createdAt: string | null;
+}
+/** POST-only: whether THIS call's workspace ended up owning the binding. */
+export interface GithubLinkClaimResult extends GithubLinkResult {
+    claimed: boolean;
+}
+/** `DELETE /v1/:workspace/github/link` result (issue #318, self-serve unlink). */
+export interface GithubLinkUnlinkResult {
+    repo: string;
+    unlinked: boolean;
+    reason?: "not_linked";
+}
 export interface HealthResult {
     ok: boolean;
 }
+/** `GET /v1/:workspace/github/health` result (issue #293 follow-up). */
+export interface GithubHealthResult {
+    configured: boolean;
+    ok: boolean;
+    events: string[] | null;
+    missingEvents: string[];
+    requiredEvents: string[];
+    hint?: string;
+}
 export interface UsageResult {
     workspace: string;
     bytes: number;
@@ -412,6 +466,39 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
         num: number;
         kind: "pull" | "issues";
     }): Promise<GithubCommentResult>;
+    /**
+     * Promote a workspace's branch-staged attachments into a PR's stable
+     * attachment prefix (server contract, PR #310 — degrade-safe callers
+     * treat any failure, including a 404 from an older/self-hosted worker
+     * that doesn't have this route yet, as "nothing promoted").
+     */
+    promoteBranchAttachments(opts: PromoteBranchAttachmentsOptions): Promise<PromoteBranchAttachmentsResult>;
+    /** Current binding for `repo`, or `{ linked: false }` if unclaimed. Throws
+     * `UploadsError` (status 404) on an older/self-hosted server without this
+     * route — callers treat that as "bindings unsupported". */
+    githubLinkStatus(repo: string): Promise<GithubLinkResult>;
+    /**
+     * Explicitly claim `repo` for this workspace (first-claim-wins — see
+     * github-repo-links.ts server-side). `claimed: false` in the result means
+     * the repo is already bound to a DIFFERENT workspace; this call never
+     * steals it. Throws `UploadsError` (status 404) on an older/self-hosted
+     * server without this route.
+     */
+    githubLinkClaim(repo: string): Promise<GithubLinkClaimResult>;
+    /**
+     * GitHub App configuration + webhook event subscription check. Throws
+     * `UploadsError` (status 404) on an older/self-hosted server without
+     * this route — callers treat that as "unknown", not "broken".
+     */
+    githubHealth(): Promise<GithubHealthResult>;
+    /**
+     * Self-serve unlink (issue #318): removes `repo`'s binding, but only if
+     * this workspace currently owns it. Throws `UploadsError` (status 403)
+     * when a different workspace owns the binding — never steals or
+     * overwrites another workspace's claim. Throws (status 404) on an
+     * older/self-hosted server without this route.
+     */
+    githubLinkUnlink(repo: string): Promise<GithubLinkUnlinkResult>;
     health(): Promise<HealthResult>;
     /** Workspace storage / upload counters (+ limits when configured). */
     usage(): Promise<UsageResult>;

package/dist/client.js

@@ -458,6 +458,55 @@ export function createUploadsClient(config) {
                 headers: { "Content-Type": "application/json" },
             });
         },
+        /**
+         * Promote a workspace's branch-staged attachments into a PR's stable
+         * attachment prefix (server contract, PR #310 — degrade-safe callers
+         * treat any failure, including a 404 from an older/self-hosted worker
+         * that doesn't have this route yet, as "nothing promoted").
+         */
+        async promoteBranchAttachments(opts) {
+            return request("POST", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/promote`, {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        /** Current binding for `repo`, or `{ linked: false }` if unclaimed. Throws
+         * `UploadsError` (status 404) on an older/self-hosted server without this
+         * route — callers treat that as "bindings unsupported". */
+        async githubLinkStatus(repo) {
+            return request("GET", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/link?repo=${encodeURIComponent(repo)}`);
+        },
+        /**
+         * Explicitly claim `repo` for this workspace (first-claim-wins — see
+         * github-repo-links.ts server-side). `claimed: false` in the result means
+         * the repo is already bound to a DIFFERENT workspace; this call never
+         * steals it. Throws `UploadsError` (status 404) on an older/self-hosted
+         * server without this route.
+         */
+        async githubLinkClaim(repo) {
+            return request("POST", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/link`, {
+                body: new TextEncoder().encode(JSON.stringify({ repo })),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        /**
+         * GitHub App configuration + webhook event subscription check. Throws
+         * `UploadsError` (status 404) on an older/self-hosted server without
+         * this route — callers treat that as "unknown", not "broken".
+         */
+        async githubHealth() {
+            return request("GET", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/health`);
+        },
+        /**
+         * Self-serve unlink (issue #318): removes `repo`'s binding, but only if
+         * this workspace currently owns it. Throws `UploadsError` (status 403)
+         * when a different workspace owns the binding — never steals or
+         * overwrites another workspace's claim. Throws (status 404) on an
+         * older/self-hosted server without this route.
+         */
+        async githubLinkUnlink(repo) {
+            return request("DELETE", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/link?repo=${encodeURIComponent(repo)}`);
+        },
         async health() {
             return request("GET", `${config.apiUrl}/health`, { auth: false });
         },

package/dist/commands/screenshot.js

@@ -2,11 +2,12 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { writeCommandHelp } from "../cli-style.js";
-import { frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, } from "../commands.js";
+import { branchFromFlags, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, } from "../commands.js";
 import { resolvePutDefaults } from "../config.js";
 import { loadDefaultsRaw, resolveScreenshotDefaults } from "../config-file.js";
 import { resolvePutPrefix } from "../destinations.js";
-import { execRunner, ghMetadataFromTargetWithTitle } from "../github-gh.js";
+import { execRunner, ghMetadataFromTargetWithTitle, resolveRepo, } from "../github-gh.js";
+import { ghBranchAttachmentKey, ghMetadataForBranch } from "../github.js";
 import { parseMetaFlags, validateMetaMap } from "../metadata.js";
 import { writeJson, writeStdout } from "../io.js";
 import { assertHideSelector, captureScreenshot, parseViewport, parseWaitUntil, } from "../screenshot.js";
@@ -66,6 +67,11 @@ Options:
   --keep-exif               Keep EXIF/XMP/ICC when optimizing
   --pr <num>                Attach to a pull request (stable URL, no hash)
   --issue <num>             Attach to an issue
+  --branch [name]           Stage against a branch, pre-PR (default: current git branch):
+                             key gh/<owner>/<repo>/branch/<branch>/<name>; not with
+                             --pr/--issue/--comment/--key/--ref/--prefix. No managed
+                             comment exists yet — promoting into the PR's comment once
+                             one opens ships in a later phase.
   --comment                 With --pr/--issue: update the managed attachments comment.
                              Posts as uploads-sh[bot] when the GitHub App is installed;
                              otherwise via local gh.
@@ -84,6 +90,7 @@ Examples:
   uploads screenshot http://localhost:3000 --via local --full-page
   uploads screenshot https://uploads.sh --pr 128 --comment
   uploads screenshot ./card.html --no-upload --out ./card.png
+  uploads screenshot https://app.example/settings --branch
 `;
 function colorSchemeFromFlags(flags) {
     const dark = flagBool(flags, "--dark");
@@ -164,9 +171,13 @@ captureImpl = captureScreenshot) {
     const destFlag = flagString(parsed.flags, "--destination");
     const prefixFlag = flagString(parsed.flags, "--prefix");
     const ghTarget = ghTargetFromFlags(parsed.flags, run);
+    const branchArg = branchFromFlags(parsed.flags, run);
     const wantComment = parsed.flags.has("--comment");
     const galleryId = flagString(parsed.flags, "--gallery");
     const dryRun = flagBool(parsed.flags, "--dry-run");
+    if (branchArg !== undefined && ghTarget) {
+        throw new UsageError("--branch cannot be combined with --pr/--issue");
+    }
     if (wantComment && !ghTarget)
         throw new UsageError("--comment requires --pr or --issue");
     if (ghTarget) {
@@ -177,6 +188,16 @@ captureImpl = captureScreenshot) {
         if (prefixFlag)
             throw new UsageError("--prefix cannot be combined with --pr/--issue");
     }
+    if (branchArg !== undefined) {
+        if (wantComment)
+            throw new UsageError("--branch cannot be combined with --comment");
+        if (keyHint)
+            throw new UsageError("--key cannot be combined with --branch");
+        if (flagString(parsed.flags, "--ref"))
+            throw new UsageError("--ref cannot be combined with --branch");
+        if (prefixFlag)
+            throw new UsageError("--prefix cannot be combined with --branch");
+    }
     if (dryRun) {
         if (wantComment)
             throw new UsageError("--dry-run cannot be combined with --comment");
@@ -185,13 +206,14 @@ captureImpl = captureScreenshot) {
         if (noUpload)
             throw new UsageError("--dry-run cannot be combined with --no-upload");
     }
+    const branchRepo = branchArg !== undefined ? resolveRepo(flagString(parsed.flags, "--repo"), run) : undefined;
     let resolvedPrefix;
     try {
         resolvedPrefix = resolvePutPrefix({
             destination: destFlag,
             prefix: prefixFlag,
             key: keyHint,
-            ghAttachment: Boolean(ghTarget),
+            ghAttachment: Boolean(ghTarget) || branchArg !== undefined,
         });
     }
     catch (err) {
@@ -218,6 +240,10 @@ captureImpl = captureScreenshot) {
         metadata = { ...metaExtras, ...ghMetadataFromTargetWithTitle(ghTarget, run) };
         validateMetaMap(metadata);
     }
+    else if (branchArg !== undefined) {
+        metadata = { ...metaExtras, ...ghMetadataForBranch(branchRepo, branchArg) };
+        validateMetaMap(metadata);
+    }
     else if (Object.keys(metaExtras).length > 0) {
         validateMetaMap(metaExtras);
     }
@@ -260,12 +286,15 @@ captureImpl = captureScreenshot) {
     }
     const repo = flagString(parsed.flags, "--repo") ?? putDefaults.repo;
     const ref = flagString(parsed.flags, "--ref") ?? putDefaults.ref;
+    const branchKey = branchArg !== undefined
+        ? ghBranchAttachmentKey(branchRepo, branchArg, captured.filename)
+        : undefined;
     const alt = altFlag ?? basename(captured.filename);
     const { result, prepared, markdown } = await uploadPreparedImage(ctx.client, captured.png, captured.filename, {
         frame: frameOpts,
         optimize: optimizeOpts,
         ghTarget,
-        key: keyHint,
+        key: keyHint ?? branchKey,
         prefix: resolvedPrefix ?? putDefaults.prefix,
         repo,
         ref,
@@ -295,7 +324,7 @@ captureImpl = captureScreenshot) {
     let commentError;
     if (wantComment && ghTarget) {
         try {
-            comment = await syncAttachmentsComment(ctx.client, ghTarget, run);
+            comment = await syncAttachmentsComment(ctx.client, ghTarget, run, ctx.config.workspace);
             if (logHuman)
                 process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         }

package/dist/commands.d.ts

@@ -28,6 +28,17 @@ export declare function readFileArg(fileArg: string): Uint8Array;
 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;
+/**
+ * Reads `--branch [name]` — an optional-value flag: `--branch` alone resolves
+ * the current git branch (`resolveCurrentBranch`); `--branch feature/x` uses
+ * the given name verbatim. Returns undefined when the flag is absent at all
+ * (distinct from an empty/whitespace value, which is rejected). Throws
+ * UsageError if `--branch` is given more than once, or if the value looks
+ * like a filename accidentally swallowed by the optional-value lookahead
+ * (e.g. `uploads attach --branch shot.png` with no other file args) — see
+ * `looksLikeFileNotBranch`.
+ */
+export declare function branchFromFlags(flags: CommandFlags["flags"], run: CommandRunner): string | undefined;
 /** Shared put/attach optimize flags + UPLOADS_NO_OPTIMIZE default. */
 export declare function optimizeOptionsFromFlags(flags: CommandFlags["flags"], defaults: PutDefaults): OptimizeImageOptions;
 export type PreparedUpload = OptimizeImageResult & {
@@ -104,7 +115,18 @@ export interface AttachmentsCommentResult {
 }
 /** Human-mode suffix noting who posted the managed comment. */
 export declare function commentViaSuffix(via: AttachmentsCommentResult["via"]): string;
-export declare function syncAttachmentsComment(client: UploadsClient, target: GhTarget, run: CommandRunner): Promise<AttachmentsCommentResult>;
+/**
+ * Thrown by `syncAttachmentsComment` when the server declines with
+ * `not_authorized` (issue #297 baseline control) — this repo is bound to a
+ * different workspace, or unbound and unclaimable by the communal `default`
+ * workspace. Deliberately not caught by the generic "bot endpoint
+ * unreachable" fallback below: falling back to gh here would let the
+ * human's own credentials post anyway, defeating the point of the
+ * server-side gate.
+ */
+export declare class GithubCommentAuthorizationError extends Error {
+}
+export declare function syncAttachmentsComment(client: UploadsClient, target: GhTarget, run: CommandRunner, workspace?: string): Promise<AttachmentsCommentResult>;
 export type AttachUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -150,6 +172,37 @@ export declare function uploadAttachments(opts: {
     failures: AttachFailure[];
     firstError?: unknown;
 }>;
+/** A branch to stage attachments against pre-PR (`uploads attach --branch`). */
+export interface BranchTarget {
+    repo: string;
+    branch: string;
+}
+/**
+ * Prepare + put each path as a branch-staged attachment (pre-PR) with
+ * bounded concurrency. Same shape as `uploadAttachments`, keyed under
+ * `gh/<owner>/<repo>/branch/<branch>/<filename>` instead of a PR/issue
+ * number. Never syncs the managed comment — callers must not call
+ * `syncAttachmentsComment` for a branch target.
+ */
+export declare function uploadBranchAttachments(opts: {
+    client: UploadsClient;
+    target: BranchTarget;
+    files: readonly string[];
+    contentType?: string;
+    optimize: OptimizeImageOptions;
+    frame: {
+        frameId?: string;
+        frameUrl?: string;
+        frameFit?: "cover" | "contain";
+    };
+    metadata?: Record<string, string>;
+    provenanceClient?: string;
+    concurrency?: number;
+}): Promise<{
+    uploads: AttachUploadItem[];
+    failures: AttachFailure[];
+    firstError?: unknown;
+}>;
 export type PutUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -199,6 +252,7 @@ export declare function runFind(ctx: CliContext, args: string[], help?: boolean)
 export declare function runMeta(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runDelete(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runComment(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
+export declare function runGithub(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runUsage(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runReconcile(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runPurgeExpired(ctx: CliContext, args: string[], help?: boolean): Promise<number>;