@buildinternet/uploads 0.22.0 → 0.23.0

package/dist/commands.js

@@ -12,7 +12,8 @@ import { imageFactsFromBytes } from "./image-facts.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./metadata-vocab.js";
 import { ghAttachmentKey, ghBranchAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, normalizeGithubCoordinate, } from "./github.js";
-import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, classifyGhNumber, execRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
+import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, resolveDefaultBranch, classifyGhNumber, execRunner, timedExecRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
+import { deriveRepoFromGit } from "./keys.js";
 import { resolvePutPrefix } from "./destinations.js";
 import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
 import { applyFrame, resolveFrameId } from "./frame.js";
@@ -111,6 +112,10 @@ Options:
   --dry-run             Print key + public URL without uploading; reports if the key would replace
                         (or, on a strict key, be refused). Not with --comment/--gallery
 
+A bare put (no --pr/--issue/--key) on a non-default git branch prints a one-line
+nudge toward --pr/attach --branch (stderr in human mode, a "hint" field in
+--format json). Suppress with --quiet, UPLOADS_NO_NUDGE=1, or config UPLOADS_NO_NUDGE=1.
+
 Exit codes: 0 ok · 2 usage/token/file · 3 auth/policy · 4 network · 1 other (incl. partial multi-file failure).
 Scripted formats (json|url|markdown) also print failures on stdout.
 
@@ -1026,6 +1031,8 @@ async function runAttachBranch(ctx, parsed, branch, run) {
         }
         if (!ctx.quiet && uploads.length > 0) {
             process.stderr.write(`>> find these later: uploads find gh.branch=${branch.toLowerCase()}\n`);
+            process.stderr.write(`>> staged: these auto-attach to this branch's PR when it opens ` +
+                `(or run \`uploads attach --promote\` after opening)\n`);
         }
     }
     return failures.length === 0 ? 0 : 1;
@@ -1077,6 +1084,78 @@ async function runAttachPromoteOnly(ctx, parsed, run) {
     }
     return 0;
 }
+/** Bounds the best-effort `gh pr view` lookup the put nudge (issue #393) makes
+ * on top of the normal put flow — long enough for a real gh call, short
+ * enough to never be felt as a hang. */
+const PUT_NUDGE_GH_TIMEOUT_MS = 3000;
+/**
+ * The bare-put nudge's wording (issue #393): teaches `--pr`/`attach --branch`
+ * as an upgrade from a targetless `put`. `pr` present → names the PR;
+ * otherwise a generic variant that still points at `--pr <num>`. Used
+ * verbatim for both the human-mode stderr line and the JSON `hint` field.
+ */
+function putNudgeText(branch, pr) {
+    const prClause = pr !== undefined ? ` (PR #${pr} open) — rerun with --pr ${pr}` : ` — rerun with --pr <num>`;
+    return (`note: on branch ${branch}${prClause} for a stable key plus a managed comment ` +
+        `that collects this PR's media, or stage pre-PR files with: uploads attach <file> --branch`);
+}
+/**
+ * Best-effort bare-put nudge (issue #393): fires only when `put` has no
+ * targeting flag at all (`--pr`/`--issue`/`--key`; `--branch` too, though
+ * `put` doesn't currently accept it — defensive parity with `attach`), is
+ * inside a git repo (reusing `deriveRepoFromGit`, the same detection the
+ * default screenshot key's repo segment uses), and the current branch isn't
+ * the default one. Never throws — any failure (not a repo, detached HEAD,
+ * `gh` missing/unauthenticated/timed out) degrades to "no nudge" or, once a
+ * branch is already known, to the generic no-PR wording. Must never affect
+ * put's exit code, stdout, or upload behavior.
+ */
+function resolvePutNudge(opts) {
+    const { ctx, flags, ghTarget, keyHint, noGit, defaults, run } = opts;
+    if (ctx.quiet)
+        return undefined;
+    if (defaults.noNudge)
+        return undefined;
+    if (ghTarget || keyHint || noGit)
+        return undefined;
+    if (flags.has("--branch"))
+        return undefined; // not a real put flag today; defensive only
+    try {
+        if (deriveRepoFromGit(run) === undefined)
+            return undefined; // not a (usable) git repo
+        let branch;
+        try {
+            branch = resolveCurrentBranch(run);
+        }
+        catch {
+            return undefined; // detached HEAD, or git unavailable
+        }
+        const defaultBranch = resolveDefaultBranch(run);
+        const onDefaultBranch = defaultBranch
+            ? branch === defaultBranch
+            : branch === "main" || branch === "master"; // undetermined: err toward not nudging
+        if (onDefaultBranch)
+            return undefined;
+        let pr;
+        try {
+            // Only swap in the bounded runner for the real subprocess path — an
+            // injected `run` (tests, or a future caller) is trusted to already be
+            // fast/fake, and execFileSync's `timeout` option is meaningless
+            // against anything that isn't actually shelling out.
+            const timed = run === execRunner ? timedExecRunner(PUT_NUDGE_GH_TIMEOUT_MS) : run;
+            const repoArg = flagString(flags, "--repo") ?? defaults.repo;
+            const repo = resolveRepo(repoArg, timed);
+            pr = resolveCurrentPullRequest(repo, timed).num;
+        }
+        catch {
+            pr = undefined; // gh missing/unauthenticated/timed out/no open PR — generic wording
+        }
+        return putNudgeText(branch, pr);
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function runPut(ctx, args, help = false, run = execRunner) {
     if (help) {
         writeCommandHelp(PUT_HELP);
@@ -1227,6 +1306,18 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             }
         }
     }
+    // Bare-put nudge (issue #393): computed once, used for both the trailing
+    // stderr line (human mode) and the JSON `hint` field below. Best-effort —
+    // see resolvePutNudge; never affects exit code, stdout, or the upload.
+    const nudge = resolvePutNudge({
+        ctx,
+        flags: parsed.flags,
+        ghTarget,
+        keyHint,
+        noGit,
+        defaults,
+        run,
+    });
     const logHuman = !ctx.quiet && format === "human";
     if (logHuman) {
         if (multi) {
@@ -1308,6 +1399,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 failures,
                 comment,
                 commentError,
+                ...(nudge ? { hint: nudge } : {}),
             });
         }
         else {
@@ -1338,6 +1430,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             for (const failure of failures) {
                 process.stderr.write(`warning: could not upload ${failure.file}: ${failure.error.message}\n`);
             }
+            if (nudge)
+                process.stderr.write(`${nudge}\n`);
         }
         return failures.length === 0 && !galleryHadError ? 0 : 1;
     }
@@ -1369,6 +1463,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 frame: result.frame,
                 gallery,
                 ...(dryRun ? { dryRun: true } : {}),
+                ...(nudge ? { hint: nudge } : {}),
             });
             break;
         case "url":
@@ -1388,6 +1483,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     if (gallery?.error) {
         process.stderr.write(`warning: upload succeeded but adding it to gallery ${gallery.id} failed: ${gallery.error.message}\n`);
     }
+    if (nudge && format !== "json")
+        process.stderr.write(`${nudge}\n`);
     return gallery?.error ? 1 : 0;
 }
 // --- galleries ---

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", "UPLOADS_SCREENSHOT_VIA"];
+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", "UPLOADS_NO_NUDGE"];
 export type UploadsConfigKey = (typeof UPLOADS_CONFIG_KEYS)[number];
 export type UploadsConfigValues = Partial<Record<UploadsConfigKey, string>>;
 export interface PutDefaults {
@@ -14,6 +14,8 @@ export interface PutDefaults {
     keepExif?: boolean;
     /** When true, `put` does NOT auto-resolve/stamp gh.* on the default path. */
     noAutoMeta?: boolean;
+    /** When true, `put` never prints the bare-put --pr/attach nudge (issue #393). */
+    noNudge?: boolean;
 }
 declare const PUT_DEFAULT_KEY_MAP: Record<keyof PutDefaults, UploadsConfigKey>;
 export declare function putDefaultsToConfigValues(defaults: PutDefaults): UploadsConfigValues;

package/dist/config-file.js

@@ -14,6 +14,7 @@ export const UPLOADS_CONFIG_KEYS = [
     "UPLOADS_KEEP_EXIF",
     "UPLOADS_NO_AUTO_META",
     "UPLOADS_SCREENSHOT_VIA",
+    "UPLOADS_NO_NUDGE",
 ];
 const PUT_DEFAULT_KEY_MAP = {
     prefix: "UPLOADS_DEFAULT_PREFIX",
@@ -24,6 +25,7 @@ const PUT_DEFAULT_KEY_MAP = {
     noOptimize: "UPLOADS_NO_OPTIMIZE",
     keepExif: "UPLOADS_KEEP_EXIF",
     noAutoMeta: "UPLOADS_NO_AUTO_META",
+    noNudge: "UPLOADS_NO_NUDGE",
 };
 function isTruthyConfigFlag(value) {
     if (!value)
@@ -49,6 +51,8 @@ export function putDefaultsToConfigValues(defaults) {
         out.UPLOADS_KEEP_EXIF = "1";
     if (defaults.noAutoMeta)
         out.UPLOADS_NO_AUTO_META = "1";
+    if (defaults.noNudge)
+        out.UPLOADS_NO_NUDGE = "1";
     return out;
 }
 function parsePutDefaultsFromRaw(raw) {
@@ -72,6 +76,8 @@ function parsePutDefaultsFromRaw(raw) {
         out.keepExif = true;
     if (isTruthyConfigFlag(raw.UPLOADS_NO_AUTO_META))
         out.noAutoMeta = true;
+    if (isTruthyConfigFlag(raw.UPLOADS_NO_NUDGE))
+        out.noNudge = true;
     return out;
 }
 function parsePutDefaultsFromEnv() {
@@ -92,6 +98,8 @@ function parsePutDefaultsFromEnv() {
         raw.UPLOADS_KEEP_EXIF = process.env.UPLOADS_KEEP_EXIF;
     if (process.env.UPLOADS_NO_AUTO_META)
         raw.UPLOADS_NO_AUTO_META = process.env.UPLOADS_NO_AUTO_META;
+    if (process.env.UPLOADS_NO_NUDGE)
+        raw.UPLOADS_NO_NUDGE = process.env.UPLOADS_NO_NUDGE;
     return parsePutDefaultsFromRaw(raw);
 }
 /** XDG default shared across buildinternet skills (github-screenshots, uploads, …). */
@@ -163,6 +171,8 @@ export function mergePutDefaults(...layers) {
             out.keepExif = layer.keepExif;
         if (layer.noAutoMeta != null)
             out.noAutoMeta = layer.noAutoMeta;
+        if (layer.noNudge != null)
+            out.noNudge = layer.noNudge;
     }
     return out;
 }

package/dist/github-gh.d.ts

@@ -2,6 +2,14 @@ import { type GhTarget } from "./github.js";
 /** Runs a command and returns stdout; throws on non-zero exit. Injectable for tests. */
 export type CommandRunner = (cmd: string, args: string[], input?: string) => string;
 export declare const execRunner: CommandRunner;
+/**
+ * A `CommandRunner` bounded by `timeoutMs` (node's native `execFileSync`
+ * `timeout` option). There is no other subprocess-timeout wrapper in this
+ * codebase to reuse, so this is the minimal one: for a best-effort lookup
+ * that must never block its caller for long (e.g. the bare-`put` nudge's `gh
+ * pr view` check, issue #393), pass this instead of the default `execRunner`.
+ */
+export declare const timedExecRunner: (timeoutMs: number) => CommandRunner;
 /**
  * Resolve "owner/name". Order: explicit --repo (validated) → `gh repo view`
  * (fork-aware) → parse the origin remote → UsageError.
@@ -11,6 +19,14 @@ export declare function resolveRepo(explicit: string | undefined, run?: CommandR
 export declare function resolveCurrentPullRequest(repo: string, run?: CommandRunner): GhTarget;
 /** Resolve the current git branch (`--branch` with no value). Throws UsageError on detached HEAD or outside a git repo. */
 export declare function resolveCurrentBranch(run?: CommandRunner): string;
+/**
+ * Best-effort default-branch name via the local `origin/HEAD` ref (no
+ * network call — just reads the ref git already cached from the last
+ * fetch/clone). Returns undefined when it can't be determined (no origin,
+ * `origin/HEAD` never set, not a git repo) — callers should treat that as
+ * "unknown", not "no default branch exists".
+ */
+export declare function resolveDefaultBranch(run?: CommandRunner): string | undefined;
 /**
  * Classify a bare PR/issue number via the GitHub API so the default `put`
  * path can stamp the right `gh.kind`. Returns undefined on any failure (gh

package/dist/github-gh.js

@@ -3,6 +3,19 @@ import { UsageError } from "./cli-args.js";
 import { ATTACHMENTS_MARKER, ghMetadataFromTarget, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
 import { META_VALUE_MAX, isMetaValueSafe } from "./metadata.js";
 export const execRunner = (cmd, args, input) => execFileSync(cmd, args, { encoding: "utf8", input, stdio: ["pipe", "pipe", "pipe"] });
+/**
+ * A `CommandRunner` bounded by `timeoutMs` (node's native `execFileSync`
+ * `timeout` option). There is no other subprocess-timeout wrapper in this
+ * codebase to reuse, so this is the minimal one: for a best-effort lookup
+ * that must never block its caller for long (e.g. the bare-`put` nudge's `gh
+ * pr view` check, issue #393), pass this instead of the default `execRunner`.
+ */
+export const timedExecRunner = (timeoutMs) => (cmd, args, input) => execFileSync(cmd, args, {
+    encoding: "utf8",
+    input,
+    stdio: ["pipe", "pipe", "pipe"],
+    timeout: timeoutMs,
+});
 /**
  * Resolve "owner/name". Order: explicit --repo (validated) → `gh repo view`
  * (fork-aware) → parse the origin remote → UsageError.
@@ -82,6 +95,26 @@ export function resolveCurrentBranch(run = execRunner) {
     }
     return branch;
 }
+/**
+ * Best-effort default-branch name via the local `origin/HEAD` ref (no
+ * network call — just reads the ref git already cached from the last
+ * fetch/clone). Returns undefined when it can't be determined (no origin,
+ * `origin/HEAD` never set, not a git repo) — callers should treat that as
+ * "unknown", not "no default branch exists".
+ */
+export function resolveDefaultBranch(run = execRunner) {
+    try {
+        const out = run("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]).trim();
+        if (!out)
+            return undefined;
+        const slash = out.indexOf("/");
+        const branch = slash === -1 ? out : out.slice(slash + 1);
+        return branch || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Classify a bare PR/issue number via the GitHub API so the default `put`
  * path can stamp the right `gh.kind`. Returns undefined on any failure (gh

package/dist/github.d.ts

@@ -86,6 +86,18 @@ export interface AttachmentItem {
         path?: string;
         state?: string;
     };
+    /**
+     * Poster frame for a video (issue #299), server-computed like `embedUrl` —
+     * never taken from client-settable metadata. Absent means "no poster", and
+     * the renderer falls back to the bullet link.
+     */
+    posterUrl?: string | null;
+    /** Derived video facts used for the caption and display width. */
+    videoMeta?: {
+        durationSeconds?: number;
+        width?: number;
+        height?: number;
+    };
 }
 /** A public gallery linked to the PR or issue whose managed comment is syncing. */
 export interface GalleryCommentItem {

package/dist/github.js

@@ -171,6 +171,34 @@ export function attachmentImageWidth(filename) {
     }
     return ATTACHMENT_IMAGE_WIDTH_DEFAULT;
 }
+/** `m:ss` under an hour, `h:mm:ss` at or above one. */
+function formatDuration(seconds) {
+    const total = Math.floor(seconds);
+    const s = total % 60;
+    const m = Math.floor(total / 60) % 60;
+    const h = Math.floor(total / 3600);
+    const ss = String(s).padStart(2, "0");
+    if (h === 0)
+        return `${m}:${ss}`;
+    return `${h}:${String(m).padStart(2, "0")}:${ss}`;
+}
+/**
+ * Display width for a video poster. Real dimensions only *select* among the
+ * width constants — a raw 1920 would blow out the comment column — and the
+ * result is capped at the real width so a small clip is never upscaled.
+ */
+function posterImageWidth(videoMeta, filename) {
+    const w = videoMeta?.width ?? 0;
+    const h = videoMeta?.height ?? 0;
+    if (w <= 0 || h <= 0)
+        return attachmentImageWidth(filename);
+    const chosen = h > w
+        ? ATTACHMENT_IMAGE_WIDTH_PORTRAIT
+        : w / h >= 16 / 9
+            ? ATTACHMENT_IMAGE_WIDTH_WIDE
+            : ATTACHMENT_IMAGE_WIDTH_DEFAULT;
+    return Math.min(chosen, w);
+}
 function escapeHtmlAttr(s) {
     return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 }
@@ -196,14 +224,19 @@ function escapeMarkdownText(s) {
  * `PATCH /v1/:workspace/files/:key` can set any valid metadata value. A
  * whitespace-only value passes that validation (length-1 printable ASCII), so
  * treat it as absent rather than rendering a dangling separator.
+ *
+ * Bare `/` is stored/searchable but omitted from captions (issue #375) —
+ * alone it is a stray character, and as a prefix next to `state` it is
+ * noise. Only exact `/` after trim is suppressed.
  */
 function metaCaptionParts(meta) {
     const parts = [];
-    for (const value of [meta?.path, meta?.state]) {
-        const trimmed = value?.trim();
-        if (trimmed)
-            parts.push(trimmed);
-    }
+    const path = meta?.path?.trim();
+    if (path && path !== "/")
+        parts.push(path);
+    const state = meta?.state?.trim();
+    if (state)
+        parts.push(state);
     return parts;
 }
 /** `<sub>` caption body for an inline image, or null when there is nothing to say. */
@@ -254,13 +287,29 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
         const src = item.embedUrl ?? item.url;
         const link = item.pageUrl ?? stable; // click-through: file page when known, else raw
         const isImage = Boolean(src) && inferContentType(name).startsWith("image/");
-        if (isImage && inlinedImages >= MAX_INLINE_ATTACHMENT_IMAGES) {
+        const isPosterVideo = Boolean(item.posterUrl) && inferContentType(name).startsWith("video/");
+        const inlines = isImage || isPosterVideo;
+        if (inlines && inlinedImages >= MAX_INLINE_ATTACHMENT_IMAGES) {
             // Cap hit — defer to the collapsed overflow list below rather than
             // embedding every remaining image inline.
             overflowImages.push(item);
             continue;
         }
-        if (isImage) {
+        if (isPosterVideo) {
+            inlinedImages++;
+            const w = posterImageWidth(item.videoMeta, name);
+            const href = escapeHtmlAttr(link ?? item.posterUrl);
+            lines.push(`<a href="${href}"><img width="${w}" alt="${escapeHtmlAttr(name)}" src="${escapeHtmlAttr(item.posterUrl)}"></a>`);
+            // GitHub strips <video>, so a still frame needs an explicit affordance
+            // or it reads as a screenshot.
+            const parts = ["▶ Play video"];
+            if (item.videoMeta?.durationSeconds != null) {
+                parts.push(formatDuration(item.videoMeta.durationSeconds));
+            }
+            parts.push(...metaCaptionParts(item.meta).map(escapeHtmlText));
+            lines.push(`<sub>${parts.join(" · ")}</sub>`, "");
+        }
+        else if (isImage) {
             inlinedImages++;
             // Markdown ![]() has no width control — phone frames become full-column giants.
             // img src uses embed host when available (Camo revalidates); click-through prefers the file page.

package/dist/keys.d.ts

@@ -1,6 +1,13 @@
 export declare function sanitizeKeySegment(s: string): string;
 export declare function sha256Short(bytes: Uint8Array): Promise<string>;
-export declare function deriveRepoFromGit(): string | undefined;
+/**
+ * `run` is optional and structurally matches `CommandRunner` (github-gh.ts)
+ * without importing it — callers that already have an injected runner (e.g.
+ * the put nudge, issue #393) can pass it through for testability; the
+ * default (no `run`) preserves the original direct-`execSync` behavior for
+ * every existing caller.
+ */
+export declare function deriveRepoFromGit(run?: (cmd: string, args: string[], input?: string) => string): string | undefined;
 export declare function buildScreenshotKey(opts: {
     filename: string;
     fileBytes: Uint8Array;

package/dist/keys.js

@@ -9,9 +9,18 @@ export async function sha256Short(bytes) {
         .join("")
         .slice(0, 6);
 }
-export function deriveRepoFromGit() {
+/**
+ * `run` is optional and structurally matches `CommandRunner` (github-gh.ts)
+ * without importing it — callers that already have an injected runner (e.g.
+ * the put nudge, issue #393) can pass it through for testability; the
+ * default (no `run`) preserves the original direct-`execSync` behavior for
+ * every existing caller.
+ */
+export function deriveRepoFromGit(run) {
     try {
-        const url = execSync("git config --get remote.origin.url", { encoding: "utf8" }).trim();
+        const url = run
+            ? run("git", ["config", "--get", "remote.origin.url"]).trim()
+            : execSync("git config --get remote.origin.url", { encoding: "utf8" }).trim();
         const match = url.match(/[/:]([^/]+?)(?:\.git)?$/);
         return match?.[1];
     }

package/package.json

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