@buildinternet/uploads 0.15.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

@@ -136,7 +136,10 @@ export const ROOT_COMMANDS = [
     {
         name: "github",
         summary: "Claim/inspect this workspace's binding to a GitHub repo",
-        subcommands: [{ name: "link", summary: "Claim or inspect the repo binding" }],
+        subcommands: [
+            { name: "link", summary: "Claim or inspect the repo binding" },
+            { name: "doctor", summary: "Check the GitHub App's webhook event subscriptions" },
+        ],
     },
     {
         name: "list",

package/dist/client.d.ts

@@ -172,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";
@@ -212,9 +220,24 @@ export interface GithubLinkResult {
 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;
@@ -462,6 +485,20 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
      * 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

@@ -489,6 +489,24 @@ export function createUploadsClient(config) {
                 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.d.ts

@@ -33,7 +33,10 @@ export declare function ghTargetFromFlags(flags: CommandFlags["flags"], run: Com
  * 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.
+ * 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. */
@@ -112,6 +115,17 @@ export interface AttachmentsCommentResult {
 }
 /** Human-mode suffix noting who posted the managed comment. */
 export declare function commentViaSuffix(via: AttachmentsCommentResult["via"]): string;
+/**
+ * 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;

package/dist/commands.js

@@ -1,5 +1,5 @@
-import { readFileSync } from "node:fs";
-import { basename } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, extname } from "node:path";
 import { mapBounded } from "./async.js";
 import { createUploadsClient, } from "./client.js";
 import { parseCommandArgs, flagString, flagBool, flagInt, flagValues, UsageError, } from "./cli-args.js";
@@ -130,12 +130,53 @@ export function makeGhTarget(pr, issue, repoArg, run) {
 export function ghTargetFromFlags(flags, run) {
     return makeGhTarget(flagInt(flags, "--pr", "--pr"), flagInt(flags, "--issue", "--issue"), flagString(flags, "--repo"), run);
 }
+/**
+ * Extensions that mark a `--branch` value as almost certainly a filename that
+ * got swallowed by the optional-value lookahead (e.g. `--branch shot.png`
+ * with no other file args). Branch names legitimately contain dots (e.g.
+ * `release/1.2`, `v1.2.3`), so this only matches known media/document
+ * extensions, never bare dotted segments.
+ */
+const BRANCH_LIKE_FILE_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".bmp",
+    ".svg",
+    ".ico",
+    ".tif",
+    ".tiff",
+    ".heic",
+    ".avif",
+    ".mp4",
+    ".mov",
+    ".avi",
+    ".webm",
+    ".mkv",
+    ".pdf",
+]);
+/**
+ * True when `value` looks like a filename that was mistakenly consumed as the
+ * `--branch` value: it names a file that exists on disk, or its extension is
+ * a known media/document type. Ordinary branch names (including dotted ones
+ * like `v1.2` or `release/1.2`) never match either check.
+ */
+function looksLikeFileNotBranch(value) {
+    if (existsSync(value))
+        return true;
+    return BRANCH_LIKE_FILE_EXTENSIONS.has(extname(value).toLowerCase());
+}
 /**
  * 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.
+ * 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 function branchFromFlags(flags, run) {
     if (!flags.has("--branch"))
@@ -145,8 +186,14 @@ export function branchFromFlags(flags, run) {
         throw new UsageError("--branch may only be given once");
     if (raw === true)
         return resolveCurrentBranch(run);
-    if (typeof raw === "string" && raw.trim().length > 0)
+    if (typeof raw === "string" && raw.trim().length > 0) {
+        if (looksLikeFileNotBranch(raw)) {
+            throw new UsageError(`"${raw}" looks like a file, not a branch name — did you mean ` +
+                `"uploads attach ${raw} --branch" (auto-detect the current branch), ` +
+                `or "uploads attach --branch <name> ${raw}" (explicit branch name)?`);
+        }
         return raw;
+    }
     throw new UsageError("--branch requires a non-empty branch name");
 }
 /**
@@ -297,15 +344,39 @@ export function frameOptionsFromFlags(flags) {
 export function commentViaSuffix(via) {
     return via === "bot" ? " (uploads-sh[bot])" : " (via gh)";
 }
+/**
+ * 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 class GithubCommentAuthorizationError extends Error {
+}
 export async function syncAttachmentsComment(client, target, run, workspace) {
+    let bot;
     try {
-        const bot = await client.upsertGithubComment({
+        bot = await client.upsertGithubComment({
             repo: target.repo,
             num: target.num,
             kind: target.kind,
         });
+    }
+    catch {
+        // Endpoint absent/unreachable (self-hosted, network, older worker) — fall
+        // through to the gh path below.
+        bot = undefined;
+    }
+    if (bot) {
         if (bot.posted)
             return { action: bot.action, count: bot.count, via: "bot" };
+        if (bot.reason === "not_authorized") {
+            throw new GithubCommentAuthorizationError(`${bot.message ?? `${target.repo} is not authorized for this workspace.`}\n` +
+                `Run \`uploads github link --status --repo ${target.repo}\` to see who owns the ` +
+                `binding, use that workspace instead, or post the comment manually with gh.`);
+        }
         // Installed-but-unapproved is a fixable misconfiguration, not a silent
         // degrade: tell the user (and how to fix it) before falling back to gh.
         if (bot.reason === "forbidden" && bot.message) {
@@ -313,10 +384,6 @@ export async function syncAttachmentsComment(client, target, run, workspace) {
                 `Posting via local gh in the meantime.\n`);
         }
     }
-    catch {
-        // Endpoint absent/unreachable (self-hosted, network, older worker) — fall
-        // through to the gh path below.
-    }
     // gh fallback: gather from this workspace's own data and post via local `gh`.
     // Note (issue #304): this CLI process has no server-side WorkspaceRecord in
     // scope, so it cannot honor a workspace's githubCommentLinkToFilePage=false
@@ -664,11 +731,15 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
             throw new UsageError("--promote cannot be combined with --no-promote");
         return runAttachPromoteOnly(ctx, parsed, run);
     }
+    // Validate --branch (including the filename-lookahead guard) before the
+    // zero-positionals bailout below — otherwise `uploads attach --branch
+    // shot.png` (where shot.png is swallowed as the branch value, leaving no
+    // file args) would silently print help instead of a clear UsageError.
+    const branchArg = branchFromFlags(parsed.flags, run);
     if (parsed.positionals.length === 0) {
         writeCommandHelp(ATTACH_HELP);
         return 2;
     }
-    const branchArg = branchFromFlags(parsed.flags, run);
     if (branchArg !== undefined) {
         if (parsed.flags.has("--pr"))
             throw new UsageError("--branch cannot be combined with --pr");
@@ -1623,6 +1694,11 @@ App is installed on the repo; otherwise via your local gh auth. Finds its own
 prior comment via a hidden marker and edits it in place; never touches other
 comments or the description.
 
+If this repo is bound to a different workspace (or unbound and you're on the
+communal "default" workspace), the bot post is declined and this command
+fails rather than silently falling back to gh — see \`uploads github link
+--status\`.
+
 Examples:
   uploads --env-file .env comment --pr 123
   uploads comment --issue 45 --repo buildinternet/uploads
@@ -1650,38 +1726,73 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
 }
 // --- github link ---
 const GITHUB_HELP = `uploads github link [--repo <owner/name>] [--status] [--workspace <name>]
+uploads github unlink [--repo <owner/name>] [--workspace <name>]
+uploads github doctor [--workspace <name>]
 
-Claim or inspect this workspace's binding to a GitHub repo (see the managed
-attachments comment / webhook auto-promotion, which use this binding).
-First-claim-wins: claiming an already-bound repo never steals it from
-whichever workspace claimed it first — the command reports who owns it
-instead.
+Claim, inspect, or release this workspace's binding to a GitHub repo (see the
+managed attachments comment / webhook auto-promotion, which use this
+binding). First-claim-wins: claiming an already-bound repo never steals it
+from whichever workspace claimed it first — the command reports who owns it,
+and how to get it released, instead.
 
 --repo defaults the same way as --pr/--issue elsewhere (gh repo view, then
 the git remote). --status only inspects the current binding (files:read);
-without it, the command claims the repo (files:write).
+without it, "link" claims the repo (files:write). "unlink" releases a
+binding this workspace owns — it 403s (via the server) if another workspace
+owns it; an operator can reassign or remove that binding instead.
+
+\`doctor\` checks the GitHub App itself: whether it's configured on the
+server, and whether it's subscribed to the webhook events uploads.sh's
+handler needs (issues, pull_request — see docs/github-app). A missing
+subscription is the classic silent failure: the App's ping stays green
+while webhook auto-promotion and title-cache invalidation quietly do
+nothing.
 
 Examples:
   uploads github link
   uploads github link --repo buildinternet/uploads
   uploads github link --status
+  uploads github unlink --repo buildinternet/uploads
+  uploads github doctor
 `;
+function formatGithubDoctor(result) {
+    if (!result.configured) {
+        return `github app: not configured on this server${result.hint ? ` — ${result.hint}` : ""}\n`;
+    }
+    if (result.events === null) {
+        return `github app: configured, but health check failed${result.hint ? ` — ${result.hint}` : ""}\n`;
+    }
+    if (result.ok) {
+        return `github app: ok — subscribed to ${result.requiredEvents.join(", ")}\n`;
+    }
+    return (`github app: missing webhook event subscription(s): ${result.missingEvents.join(", ")}\n` +
+        (result.hint ? `  ${result.hint}\n` : ""));
+}
 function formatGithubLink(repo, result) {
     return result.workspace
         ? `${repo} is bound to workspace "${result.workspace}"${result.source ? ` (${result.source})` : ""}\n`
         : `${repo} is not bound to any workspace\n`;
 }
-export async function runGithub(ctx, args, help = false, run = execRunner) {
-    const parsed = parseCommandArgs(args);
-    const action = parsed.positionals[0];
-    if (help || parsed.help || !action) {
-        writeCommandHelp(GITHUB_HELP);
-        return help || parsed.help ? 0 : 2;
+async function runGithubDoctor(ctx) {
+    let result;
+    try {
+        result = await ctx.client.githubHealth();
     }
-    if (action !== "link")
-        throw new UsageError(`unknown github subcommand: ${action}`);
-    const repo = resolveRepo(flagString(parsed.flags, "--repo"), run);
-    const statusOnly = flagBool(parsed.flags, "--status");
+    catch (err) {
+        if (err instanceof UploadsError && err.status === 404) {
+            throw new UsageError("server does not support the GitHub App health check yet (404) — upgrade the uploads.sh API/self-hosted worker");
+        }
+        throw err;
+    }
+    if (ctx.json) {
+        await writeJson(result);
+    }
+    else {
+        await writeStdout(formatGithubDoctor(result));
+    }
+    return result.ok ? 0 : 1;
+}
+async function runGithubLink(ctx, repo, statusOnly) {
     let result;
     try {
         result = statusOnly
@@ -1699,11 +1810,52 @@ export async function runGithub(ctx, args, help = false, run = execRunner) {
         return 0;
     }
     if (!statusOnly && result.claimed === false) {
-        process.stderr.write(`note: ${repo} is already bound to a different workspace ("${result.workspace}") — first-claim-wins, not overwritten\n`);
+        process.stderr.write(`note: ${repo} is already bound to a different workspace ("${result.workspace}") — first-claim-wins, not overwritten. Run "uploads github unlink --repo ${repo}" from that workspace, or ask an operator to reassign it.\n`);
     }
     await writeStdout(formatGithubLink(repo, result));
     return 0;
 }
+async function runGithubUnlink(ctx, repo) {
+    let result;
+    try {
+        result = await ctx.client.githubLinkUnlink(repo);
+    }
+    catch (err) {
+        if (err instanceof UploadsError && err.status === 404) {
+            throw new UsageError("server does not support repo bindings yet (404) — upgrade the uploads.sh API/self-hosted worker");
+        }
+        if (err instanceof UploadsError && err.status === 403) {
+            throw new UsageError(`${repo} is bound to a different workspace — ask an operator to reassign or remove it (${err.message})`);
+        }
+        throw err;
+    }
+    if (ctx.json) {
+        await writeJson(result);
+        return 0;
+    }
+    await writeStdout(result.unlinked
+        ? `unlinked ${repo}\n`
+        : `${repo} was not bound to any workspace — nothing to unlink\n`);
+    return 0;
+}
+export async function runGithub(ctx, args, help = false, run = execRunner) {
+    const parsed = parseCommandArgs(args);
+    const action = parsed.positionals[0];
+    if (help || parsed.help || !action) {
+        writeCommandHelp(GITHUB_HELP);
+        return help || parsed.help ? 0 : 2;
+    }
+    if (action !== "link" && action !== "unlink" && action !== "doctor") {
+        throw new UsageError(`unknown github subcommand: ${action}`);
+    }
+    if (action === "doctor")
+        return runGithubDoctor(ctx);
+    const repo = resolveRepo(flagString(parsed.flags, "--repo"), run);
+    if (action === "unlink")
+        return runGithubUnlink(ctx, repo);
+    const statusOnly = flagBool(parsed.flags, "--status");
+    return runGithubLink(ctx, repo, statusOnly);
+}
 // --- usage / reconcile / purge ---
 const USAGE_HELP = `uploads usage [--workspace <name>]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,