@buildinternet/uploads 0.37.2 → 0.38.0

package/dist/commands/screenshot.js

@@ -2,7 +2,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { extractDashValue, flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { writeCommandHelp } from "../cli-style.js";
-import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, } from "../commands.js";
+import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, writeReplacedNote, } from "../commands.js";
 import { resolvePutDefaults } from "../config.js";
 import { loadDefaultsRaw, resolveScreenshotDefaults } from "../config-file.js";
 import { resolvePutPrefix } from "../destinations.js";
@@ -31,6 +31,15 @@ localhost/private-network URLs are reachable only by the
 local backend — with --via remote (or auto falling back to remote) these
 fail fast with a clear error instead of sending a doomed request.
 
+The object name is derived from the target URL (host + path), not chosen by
+you — e.g. https://app.example/settings becomes app.example-settings.png.
+--state folds into that derived name (a -before/-after/... suffix), so
+capturing the same URL with --state before then --state after produces two
+distinct objects instead of the second silently overwriting the first.
+Re-capturing the same URL + --state replaces that object in place — the
+intended idempotency for repeat captures. --key bypasses all of this and
+sets the whole object key verbatim (no folding).
+
 After capture, screenshots share the put upload pipeline: optional --frame,
 optimize-by-default, --pr/--issue attachment + --comment, --gallery, --meta.
 
@@ -381,6 +390,9 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
         reducedMotion,
         evalJs,
         initScript,
+        // Skip folding when an explicit --key was given — --key sets the whole
+        // key, so there's no auto-derived name to fold state into.
+        state: keyHint ? undefined : explicitMeta.state,
         measureSelectors: annotateSelectors.length > 0 ? annotateSelectors : undefined,
         apiUrl: ctx.config.apiUrl,
         token: ctx.config.token,
@@ -497,6 +509,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
         if (prepared.optimized) {
             process.stderr.write(`>> optimized ${prepared.originalBytes} → ${prepared.outputBytes} bytes\n`);
         }
+        writeReplacedNote(result.replaced, ctx.quiet, dryRun, result.wouldRefuse);
         process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n`);
         if (stagingTarget !== undefined) {
             process.stderr.write(`>> find these later: uploads find gh.branch=${stagingTarget.branch.toLowerCase()}\n`);
@@ -514,8 +527,16 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
         process.stderr.write("\n");
     }
     // One JSON `hint` slot (mirrors bare put): the binding warning is more
-    // actionable than the generic staging note, so it wins when both fire.
-    const jsonHint = bindingWarning ?? stagingNote;
+    // actionable than the generic staging note, so it wins when both fire; a
+    // replaced-object note (issue #618) is the lowest priority of the three —
+    // it only surfaces when nothing else already claimed the slot. Since state
+    // folds into the derived key, replaced + state means a same-side re-capture,
+    // which is the intended replace-in-place flow — word it as informational,
+    // not as a problem.
+    const replacedHint = result.replaced && explicitMeta.state
+        ? `re-capture replaced the previous state=${explicitMeta.state} object at ${result.key} — expected for repeat captures of the same URL + state`
+        : undefined;
+    const jsonHint = bindingWarning ?? stagingNote ?? replacedHint;
     switch (format) {
         case "json":
             await writeJson({

package/dist/commands.d.ts

@@ -63,6 +63,7 @@ export declare function warnNearMissMeta(ctx: CliContext, meta: Record<string, s
  * point is `--help` discoverability and `--state` validation.
  */
 export declare function stateAppMetaFromFlags(flags: CommandFlags["flags"]): Record<string, string>;
+export declare function writeReplacedNote(replaced: boolean | undefined, quiet: boolean, dryRun?: boolean, wouldRefuse?: boolean): void;
 export type PreparedUpload = OptimizeImageResult & {
     frame?: Pick<FrameResult, "framed" | "frameId" | "skippedReason">;
 };

package/dist/commands.js

@@ -4,7 +4,7 @@ import { mapBounded } from "./async.js";
 import { createUploadsClient, } from "./client.js";
 import { parseCommandArgs, flagString, flagBool, flagInt, flagValues, UsageError, } from "./cli-args.js";
 import { resolvePutDefaults, workspaceMismatch, workspaceFromToken, } from "./config.js";
-import { buildMarkdown } from "./embed.js";
+import { buildUploadMarkdown } from "./embed.js";
 import { readLocalRepoCommentConfig, resolveCommentOptions } from "./comment-config.js";
 import { urlForGithubEmbed } from "./public-urls.js";
 import { UploadsError } from "./errors.js";
@@ -315,7 +315,7 @@ function formatOptimizeNote(opt) {
     }
     return undefined;
 }
-function writeReplacedNote(replaced, quiet, dryRun = false, wouldRefuse = false) {
+export function writeReplacedNote(replaced, quiet, dryRun = false, wouldRefuse = false) {
     if (quiet)
         return;
     if (dryRun && wouldRefuse) {
@@ -411,9 +411,10 @@ export async function uploadPreparedImage(client, bytes, sourceName, opts) {
         }),
         metadata,
     });
-    const markdown = buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
+    const markdown = buildUploadMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
         alt: opts.alt(prepared),
         width: opts.width,
+        key: result.key,
     });
     return { result, prepared, markdown, sentMetadata: metadata };
 }
@@ -748,8 +749,9 @@ async function uploadAttachmentBatch(opts) {
                 upload: {
                     ...result,
                     file,
-                    markdown: buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
+                    markdown: buildUploadMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
                         alt: sourceName,
+                        key: result.key,
                     }),
                     optimize: {
                         optimized: prepared.optimized,

package/dist/config-file.d.ts

@@ -1,5 +1,7 @@
 import type { UploadsClientConfig } from "./config.js";
-export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", "UPLOADS_SESSION_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 declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", 
+/** Better Auth device-flow session bearer — keeps session.cliVersion fresh. */
+"UPLOADS_SESSION_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 {

package/dist/embed.d.ts

@@ -4,3 +4,13 @@ export declare function buildMarkdown(url: string, opts: {
     alt: string;
     width?: number;
 }): string;
+/**
+ * Null-safe wrapper for upload flows: workspaces with no public base URL
+ * (BYO signed-URLs-only) upload fine but have no embeddable URL, and the
+ * markdown must degrade to honest plain text instead of `![alt](null)`.
+ */
+export declare function buildUploadMarkdown(url: string | null | undefined, opts: {
+    alt: string;
+    width?: number;
+    key: string;
+}): string;

package/dist/embed.js

@@ -28,3 +28,14 @@ export function buildMarkdown(url, opts) {
     }
     return `![${opts.alt}](${url})`;
 }
+/**
+ * Null-safe wrapper for upload flows: workspaces with no public base URL
+ * (BYO signed-URLs-only) upload fine but have no embeddable URL, and the
+ * markdown must degrade to honest plain text instead of `![alt](null)`.
+ */
+export function buildUploadMarkdown(url, opts) {
+    if (!url) {
+        return `\`${opts.key}\` uploaded (no public URL — this workspace serves signed URLs only)`;
+    }
+    return buildMarkdown(url, opts);
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { inferContentType, buildMarkdown } from "./embed.js";
+export { inferContentType, buildMarkdown, buildUploadMarkdown } from "./embed.js";
 export { DEFAULT_EMBED_PUBLIC_BASE_URL, embedBaseUrlFromEnv, embedUrlFromPublic, resolveEmbedBaseUrl, resolveEmbedUrl, urlForGithubEmbed, } from "./public-urls.js";
 export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey } from "./keys.js";
 export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, resolveDestinationRoot, resolvePutPrefix, type BuiltinDestinationId, } from "./destinations.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { inferContentType, buildMarkdown } from "./embed.js";
+export { inferContentType, buildMarkdown, buildUploadMarkdown } from "./embed.js";
 export { DEFAULT_EMBED_PUBLIC_BASE_URL, embedBaseUrlFromEnv, embedUrlFromPublic, resolveEmbedBaseUrl, resolveEmbedUrl, urlForGithubEmbed, } from "./public-urls.js";
 export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey } from "./keys.js";
 export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, resolveDestinationRoot, resolvePutPrefix, } from "./destinations.js";

package/dist/mcp/args.d.ts

@@ -23,7 +23,7 @@ export declare const metadataProp: {
 };
 export declare const stateProp: {
     type: string;
-    enum: ("before" | "after" | "empty" | "error" | "loading")[];
+    enum: ("after" | "before" | "empty" | "error" | "loading")[];
     description: string;
 };
 export declare const appProp: {

package/dist/mcp/tools.js

@@ -761,6 +761,10 @@ export function createUploadsMcpTools(opts) {
                         hide: optStringArray(args, "hide"),
                         hideDevTools: optBool(args, "noHideDevTools") ? false : undefined,
                         reducedMotion: optBool(args, "reducedMotion"),
+                        // Skip folding when an explicit key was given — key sets the
+                        // whole object key, so there's no auto-derived name to fold
+                        // state into.
+                        state: keyArg ? undefined : metadataWithCaptureFacts?.state,
                         apiUrl: config.apiUrl,
                         token: config.token,
                     });

package/dist/metadata-vocab.d.ts

@@ -3,6 +3,8 @@ export type CanonicalMetaKey = (typeof CANONICAL_META_KEYS)[number];
 /** Closed enum for `state` — the highest-value hand-supplied search facet. */
 export declare const META_STATE_VALUES: readonly ["before", "after", "empty", "error", "loading"];
 export type MetaStateValue = (typeof META_STATE_VALUES)[number];
+/** True when `value` is exactly one of the canonical state values. */
+export declare function isMetaStateValue(value: string): value is MetaStateValue;
 /**
  * Validate a `--state` value. Fails fast with a suggestion when the value is a
  * recognized near-miss, otherwise lists the valid set.

package/dist/metadata-vocab.js

@@ -23,6 +23,10 @@ const CANONICAL_KEY_SET = new Set(CANONICAL_META_KEYS);
 /** Closed enum for `state` — the highest-value hand-supplied search facet. */
 export const META_STATE_VALUES = ["before", "after", "empty", "error", "loading"];
 const STATE_VALUE_SET = new Set(META_STATE_VALUES);
+/** True when `value` is exactly one of the canonical state values. */
+export function isMetaStateValue(value) {
+    return STATE_VALUE_SET.has(value);
+}
 /** Common spellings agents reach for, mapped to the canonical `state` value. */
 const STATE_ALIASES = {
     pre: "before",

package/dist/screenshot.d.ts

@@ -65,6 +65,14 @@ export interface CaptureScreenshotOptions {
     fullPage?: boolean;
     colorScheme?: "dark" | "light";
     waitUntil?: WaitUntil;
+    /**
+     * Folded into the auto-derived filename's stem (e.g. `-before`) so a
+     * before/after pair of the same URL yields two distinct object names
+     * instead of silently overwriting each other. Callers must omit this when
+     * the caller also gave an explicit object key/name — folding only applies
+     * to the auto-derived name.
+     */
+    state?: string;
     /** Extra CSS selectors to hide (display:none) before capture. */
     hide?: string[];
     /**
@@ -120,6 +128,26 @@ export interface CaptureScreenshotResult {
     /** Present when `measureSelectors` was given and the local backend ran. */
     measures?: Record<string, MeasuredBox>;
 }
+/**
+ * Folds a `--state` value into an auto-derived filename's stem, e.g.
+ * `localhost-docs-mcp.png` + "before" → `localhost-docs-mcp-before.png`. This
+ * is what keeps a before/after pair (same URL, two states) from colliding on
+ * the same object key (issue #618) — without it, the second capture silently
+ * overwrote the first.
+ *
+ * No-op when `state` is undefined, and idempotent: re-folding a filename that
+ * already ends with `-<state>` (e.g. re-deriving from a stored filename)
+ * doesn't double-append.
+ *
+ * Only the canonical state values fold. Callers pass the merged metadata bag's
+ * `state`, which a free-form `--meta state=…` can populate with any printable
+ * ASCII (validateMetaMap allows `/` and spaces) — that stays metadata-only
+ * rather than entering the object key.
+ *
+ * Callers must skip this entirely when the caller gave an explicit key/name
+ * (e.g. `--key`) — this only applies to the auto-derived filename.
+ */
+export declare function foldStateIntoFilename(filename: string, state: string | undefined): string;
 /**
  * Resolve target + options into PNG bytes via the local or remote backend.
  * Shared by the CLI `screenshot` command and the MCP `screenshot` tool.

package/dist/screenshot.js

@@ -12,6 +12,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, resolve as resolvePath } from "node:path";
 import { pathToFileURL } from "node:url";
 import { UploadsError } from "./errors.js";
+import { isMetaStateValue } from "./metadata-vocab.js";
 import { captureRemote, MAX_REMOTE_HTML_BYTES } from "./screenshot-remote.js";
 /**
  * Host selectors for framework dev toolbars/overlays that otherwise pollute a
@@ -159,6 +160,35 @@ function deriveFilename(target) {
     const stem = [url.hostname, pathPart].filter(Boolean).join("-");
     return `${stem || "screenshot"}.png`;
 }
+/**
+ * Folds a `--state` value into an auto-derived filename's stem, e.g.
+ * `localhost-docs-mcp.png` + "before" → `localhost-docs-mcp-before.png`. This
+ * is what keeps a before/after pair (same URL, two states) from colliding on
+ * the same object key (issue #618) — without it, the second capture silently
+ * overwrote the first.
+ *
+ * No-op when `state` is undefined, and idempotent: re-folding a filename that
+ * already ends with `-<state>` (e.g. re-deriving from a stored filename)
+ * doesn't double-append.
+ *
+ * Only the canonical state values fold. Callers pass the merged metadata bag's
+ * `state`, which a free-form `--meta state=…` can populate with any printable
+ * ASCII (validateMetaMap allows `/` and spaces) — that stays metadata-only
+ * rather than entering the object key.
+ *
+ * Callers must skip this entirely when the caller gave an explicit key/name
+ * (e.g. `--key`) — this only applies to the auto-derived filename.
+ */
+export function foldStateIntoFilename(filename, state) {
+    if (!state || !isMetaStateValue(state))
+        return filename;
+    const match = /^(.*?)(\.[^./]+)?$/.exec(filename);
+    const stem = match?.[1] ?? filename;
+    const ext = match?.[2] ?? "";
+    if (stem.endsWith(`-${state}`))
+        return filename;
+    return `${stem}-${state}${ext}`;
+}
 /**
  * Best-effort local-browser probe used only to decide `auto` routing. Never
  * throws — any failure (e.g. optional playwright-core not installed) means
@@ -183,7 +213,7 @@ export async function captureScreenshot(opts) {
     const target = classifyTarget(opts.target);
     const viewport = opts.viewport ?? DEFAULT_SCREENSHOT_VIEWPORT;
     const waitUntil = opts.waitUntil ?? "load";
-    const filename = deriveFilename(target);
+    const filename = foldStateIntoFilename(deriveFilename(target), opts.state);
     // Only private-network URLs are truly unreachable remotely; an .html file
     // is sent to the remote backend as an inline `html` body (though anything
     // it references via file:// or relative paths won't resolve there).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.37.2",
+  "version": "0.38.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,
@@ -49,7 +49,7 @@
     "@types/node": "^26.1.0",
     "ai": "^6.0.0",
     "files-sdk": "^2.1.0",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   },
   "publishConfig": {