@buildinternet/uploads 0.13.1 → 0.15.0

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,11 @@ 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: "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,6 +172,46 @@ 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";
+export type GithubCommentResult = {
+    posted: true;
+    action: "created" | "updated" | "skipped";
+    count: number;
+    commentUrl?: string;
+} | {
+    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;
+}
 export interface HealthResult {
     ok: boolean;
 }
@@ -396,6 +438,30 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
         id: string;
     }>;
     findGalleriesByReference(opts: FindGalleriesByReferenceOptions): Promise<GalleryListResult>;
+    upsertGithubComment(opts: {
+        repo: string;
+        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>;
     health(): Promise<HealthResult>;
     /** Workspace storage / upload counters (+ limits when configured). */
     usage(): Promise<UsageResult>;

package/dist/client.js

@@ -452,6 +452,43 @@ export function createUploadsClient(config) {
                 params.set("cursor", opts.cursor);
             return request("GET", galleriesBase(config) + "/by-reference?" + params);
         },
+        async upsertGithubComment(opts) {
+            return request("POST", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/comment`, {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                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" },
+            });
+        },
         async health() {
             return request("GET", `${config.apiUrl}/health`, { auth: false });
         },

package/dist/commands/screenshot.js

@@ -2,12 +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, 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 { ghMetadataFromTarget } from "../github.js";
-import { execRunner } 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";
@@ -67,7 +67,14 @@ 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
-  --comment                 With --pr/--issue: update the managed attachments comment
+  --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.
   --gallery <id>            Add the uploaded object to this public gallery
   --meta <k=v>              Queryable custom metadata (repeatable)
   --workspace, -w <name>    Override workspace
@@ -83,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");
@@ -163,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) {
@@ -176,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");
@@ -184,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) {
@@ -214,7 +237,11 @@ captureImpl = captureScreenshot) {
     const metaExtras = parseMetaFlags(flagValues(parsed.flags, "--meta"));
     let metadata = metaExtras;
     if (ghTarget) {
-        metadata = { ...metaExtras, ...ghMetadataFromTarget(ghTarget) };
+        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) {
@@ -259,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,
@@ -294,9 +324,9 @@ 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}\n`);
+                process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         }
         catch (err) {
             commentError = err instanceof Error ? err.message : String(err);

package/dist/commands.d.ts

@@ -28,6 +28,14 @@ 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.
+ */
+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 & {
@@ -89,13 +97,22 @@ export declare function frameOptionsFromFlags(flags: CommandFlags["flags"]): {
 };
 /**
  * List every attachment under the target's prefix and create/update the
- * managed comment. Throws on gh failure — callers decide whether that is
- * fatal (`comment` command) or a warning (`put --comment`).
+ * managed comment. Prefers the server-side bot endpoint (`uploads-sh[bot]`,
+ * rendered from this workspace's own data); any failure to post that way —
+ * not installed, declined, self-hosted 404, network error — falls through to
+ * the local-`gh` path so self-hosters keep working unchanged. Throws on gh
+ * failure — callers decide whether that is fatal (`comment` command) or a
+ * warning (`put --comment`).
  */
-export declare function syncAttachmentsComment(client: UploadsClient, target: GhTarget, run: CommandRunner): Promise<{
+export interface AttachmentsCommentResult {
     action: "created" | "updated" | "skipped";
     count: number;
-}>;
+    /** Who posted the comment: the GitHub App bot, or the local `gh` fallback. */
+    via: "bot" | "gh";
+}
+/** 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, workspace?: string): Promise<AttachmentsCommentResult>;
 export type AttachUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -141,6 +158,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;
@@ -190,6 +238,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>;