@buildinternet/uploads 0.34.1 → 0.35.1

package/README.md

@@ -50,6 +50,13 @@ Commands: `attach`, `put`, `screenshot`, `annotate`, `gallery`, `comment`, `list
 `uploads help --all` (or `--help --all`) for the full command list. Per-command:
 `uploads <cmd> --help`.
 
+**Errors:** every failure prints a short `error:` line on stderr, followed by a
+runnable example when an argument is missing, then a hint — never a help dump,
+so trimmed output (`| tail`) still carries the reason.
+A mistyped command also suggests the closest real one: `uploads set-metadata`
+answers `did you mean: uploads meta set`. With `--json`, an unknown command
+returns `{ "error", "code": "USAGE", "didYouMean" }` on stdout.
+
 **Shell completion:** `uploads completion bash|zsh|fish` prints a script to
 stdout. Example (zsh): `uploads completion zsh > ~/.zsh/completions/_uploads`.
 

package/dist/cli-args.d.ts

@@ -24,7 +24,16 @@ export declare function isHelpFlag(arg: string): boolean;
  */
 export declare function parseArgv(argv: string[]): ParsedArgv;
 export declare class UsageError extends Error {
-    constructor(message: string);
+    /**
+     * A correct invocation to show under the error. Agents pattern-match on a
+     * runnable line far better than on prose, so every "you left out a required
+     * argument" error should carry one — the CLI prints it, and `--json`
+     * callers get it as `example`.
+     */
+    readonly example?: string;
+    constructor(message: string, options?: {
+        example?: string;
+    });
 }
 export interface CommandFlags {
     positionals: string[];

package/dist/cli-args.js

@@ -69,9 +69,17 @@ export function parseArgv(argv) {
     return { globals, help, command: rest[0], rest };
 }
 export class UsageError extends Error {
-    constructor(message) {
+    /**
+     * A correct invocation to show under the error. Agents pattern-match on a
+     * runnable line far better than on prose, so every "you left out a required
+     * argument" error should carry one — the CLI prints it, and `--json`
+     * callers get it as `example`.
+     */
+    example;
+    constructor(message, options = {}) {
         super(message);
         this.name = "UsageError";
+        this.example = options.example;
     }
 }
 /** Records a flag occurrence, turning a repeated string flag into an array. */

package/dist/cli-help.d.ts

@@ -17,6 +17,24 @@ export interface RootHelpOptions {
      */
     needsAuth?: boolean;
 }
+export interface UnknownCommandOptions {
+    /** The command the caller typed. */
+    command: string;
+    /** Suggested command phrase, from `suggestCommand`. */
+    suggestion?: string;
+    /** Catalog summary for the suggestion, shown beside it. */
+    summary?: string;
+    color?: boolean;
+    style?: CliStyle;
+}
+/**
+ * Unknown-command output: deliberately a handful of lines, not the root help
+ * dump (issue #545). Agents trim command output (`| tail -20`), and a 27-line
+ * banner pushed the one line that mattered — the error — out of the window.
+ * Short output survives truncation, and the pointers below still lead to the
+ * full list.
+ */
+export declare function formatUnknownCommand(options: UnknownCommandOptions): string;
 /**
  * Root help text. Default is a short essentials view; pass `full: true` for
  * the complete command + config dump (`uploads help --all`).

package/dist/cli-help.js

@@ -175,6 +175,24 @@ ${style.muted("Tip: uploads help          essentials only")}
 ${style.muted("     uploads help --all    this full listing")}
 `;
 }
+/**
+ * Unknown-command output: deliberately a handful of lines, not the root help
+ * dump (issue #545). Agents trim command output (`| tail -20`), and a 27-line
+ * banner pushed the one line that mattered — the error — out of the window.
+ * Short output survives truncation, and the pointers below still lead to the
+ * full list.
+ */
+export function formatUnknownCommand(options) {
+    const style = options.style ??
+        createStyle(options.color !== undefined ? options.color : colorEnabled(process.stderr));
+    const lines = [style.error(`unknown command: ${options.command}`)];
+    if (options.suggestion) {
+        const summary = options.summary ? `  ${style.body(options.summary)}` : "";
+        lines.push("", `did you mean: ${style.command(`uploads ${options.suggestion}`)}${summary}`);
+    }
+    lines.push("", `  ${padCmd("uploads help --all", CMD_WIDTH, style)}${style.body("Full command list")}`, `  ${padCmd("uploads <cmd> --help", CMD_WIDTH, style)}${style.body("Per-command options and examples")}`);
+    return `${lines.join("\n")}\n`;
+}
 /**
  * Root help text. Default is a short essentials view; pass `full: true` for
  * the complete command + config dump (`uploads help --all`).

package/dist/cli-suggest.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The command phrase a mistyped command most likely meant, or undefined when
+ * nothing is close enough to be worth printing. Aliases win over distance so
+ * `metadata` resolves to `meta set` rather than the bare `meta` group.
+ */
+export declare function suggestCommand(input: string): string | undefined;
+/** Catalog summary for a suggested phrase (`meta set` → the subcommand's). */
+export declare function commandSummary(phrase: string): string | undefined;

package/dist/cli-suggest.js

@@ -0,0 +1,151 @@
+/**
+ * "Did you mean" for a mistyped root command (issue #545).
+ *
+ * The unknown-command path used to answer with the essentials list, which
+ * can't correct a wrong guess for anything outside it — `uploads set-metadata`
+ * printed a help dump that never mentions `meta`. Two sources feed a
+ * suggestion: a table of spellings agents actually reach for, and an edit
+ * distance over the catalog. Same rule as the metadata vocabulary
+ * (metadata-vocab.ts): suggest, never silently rewrite.
+ */
+import { ROOT_COMMANDS } from "./cli-catalog.js";
+/**
+ * Wrong-but-natural spellings, mapped to the command phrase that does the
+ * job. Values are full phrases (`meta set`), not just root names, because the
+ * work an agent wants often lives on a subcommand.
+ */
+const COMMAND_ALIASES = {
+    // metadata — the case in issue #545
+    setmetadata: "meta set",
+    setmeta: "meta set",
+    metadata: "meta set",
+    metaset: "meta set",
+    tag: "meta set",
+    tags: "meta set",
+    label: "meta set",
+    getmetadata: "meta get",
+    getmeta: "meta get",
+    showmetadata: "meta get",
+    metaget: "meta get",
+    // upload
+    upload: "put",
+    uploadfile: "put",
+    cp: "put",
+    copy: "put",
+    send: "put",
+    // listing and search
+    ls: "list",
+    files: "list",
+    objects: "list",
+    search: "find",
+    query: "find",
+    filter: "find",
+    // removal
+    rm: "delete",
+    remove: "delete",
+    del: "delete",
+    destroy: "delete",
+    // capture
+    capture: "screenshot",
+    shot: "screenshot",
+    snap: "screenshot",
+    screengrab: "screenshot",
+    screencapture: "screenshot",
+    // session
+    signin: "login",
+    auth: "login",
+    authenticate: "login",
+    signout: "logout",
+    // github
+    pr: "attach",
+    issue: "attach",
+    upsertcomment: "comment",
+};
+/** Compare on letters and digits only, so `set-metadata` ≡ `set_metadata`. */
+function normalize(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+/** Plain Levenshtein distance (two-row); inputs here are a few characters. */
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + cost);
+        }
+        prev = row;
+    }
+    return prev[b.length];
+}
+/** Crude de-pluralizer, so `galleries` still reaches `gallery`. */
+function singular(value) {
+    if (value.endsWith("ies") && value.length > 4)
+        return `${value.slice(0, -3)}y`;
+    if (value.endsWith("es") && value.length > 3)
+        return value.slice(0, -2);
+    if (value.endsWith("s") && value.length > 3)
+        return value.slice(0, -1);
+    return value;
+}
+/** Short words tolerate one typo, longer ones two. */
+function threshold(length) {
+    if (length <= 3)
+        return 0;
+    if (length <= 5)
+        return 1;
+    return 2;
+}
+/**
+ * The command phrase a mistyped command most likely meant, or undefined when
+ * nothing is close enough to be worth printing. Aliases win over distance so
+ * `metadata` resolves to `meta set` rather than the bare `meta` group.
+ */
+export function suggestCommand(input) {
+    const norm = normalize(input);
+    if (!norm)
+        return undefined;
+    const alias = COMMAND_ALIASES[norm];
+    if (alias)
+        return alias;
+    let best;
+    const consider = (candidate, phrase, allowContainment) => {
+        // A plural or a trailing qualifier (`screenshots`, `put-file`) is the same
+        // intent, not a typo — treat containment as a very strong match.
+        const contained = allowContainment &&
+            candidate.length >= 3 &&
+            (norm.startsWith(candidate) || candidate.startsWith(norm));
+        const distance = contained
+            ? 0
+            : Math.min(editDistance(norm, candidate), editDistance(singular(norm), candidate));
+        if (!contained && distance > threshold(Math.max(norm.length, candidate.length)))
+            return;
+        if (!best || distance < best.distance)
+            best = { phrase, distance };
+    };
+    for (const cmd of ROOT_COMMANDS)
+        consider(normalize(cmd.name), cmd.name, true);
+    // Aliases join the fuzzy pass too, so a typo *of* a synonym (`uplaod`) still
+    // lands. No containment for these — an alias is a whole word, and `tag` as a
+    // prefix would swallow unrelated input.
+    for (const [spelling, phrase] of Object.entries(COMMAND_ALIASES)) {
+        consider(spelling, phrase, false);
+    }
+    return best?.phrase;
+}
+/** Catalog summary for a suggested phrase (`meta set` → the subcommand's). */
+export function commandSummary(phrase) {
+    const [name, sub] = phrase.split(" ");
+    const cmd = ROOT_COMMANDS.find((c) => c.name === name);
+    if (!cmd)
+        return undefined;
+    if (!sub)
+        return cmd.summary;
+    return cmd.subcommands?.find((s) => s.name === sub)?.summary;
+}

package/dist/cli.js

@@ -2,7 +2,9 @@ import { createUploadsClient } from "./client.js";
 import { DEFAULT_API_URL, resolveApiUrl, resolveConfig } from "./config.js";
 import { UploadsError } from "./errors.js";
 import { commandWorkspace, flagString, isHelpFlag, parseArgv, parseCommandArgs, UsageError, } from "./cli-args.js";
-import { formatRootHelp, wantsFullHelp } from "./cli-help.js";
+import { formatRootHelp, formatUnknownCommand, wantsFullHelp } from "./cli-help.js";
+import { commandSummary, suggestCommand } from "./cli-suggest.js";
+import { writeJson } from "./io.js";
 import { colorEnabled, createStyle } from "./cli-style.js";
 import { runPut, runAttach, runStaged, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runGithub, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
 import { runConfig } from "./commands/config.js";
@@ -117,7 +119,7 @@ function errorOut(err, format) {
     const payload = err instanceof UploadsError
         ? { error: err.message, code: err.code, status: err.status }
         : err instanceof UsageError
-            ? { error: err.message, code: "USAGE" }
+            ? { error: err.message, code: "USAGE", ...(err.example ? { example: err.example } : {}) }
             : { error: err instanceof Error ? err.message : String(err) };
     if (format === "json") {
         process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
@@ -136,6 +138,11 @@ function errorOut(err, format) {
         process.stderr.write(`${msg}\n`);
     else
         process.stderr.write(`error: ${msg}\n`);
+    // A runnable line beats prose for both agents and humans; the `--help`
+    // pointer that follows stays for the full option list.
+    if (err instanceof UsageError && err.example) {
+        process.stderr.write(`  ${err.example}\n`);
+    }
     if (err instanceof UploadsError) {
         const hint = ERROR_HINTS[err.code];
         if (hint)
@@ -353,13 +360,25 @@ export async function runCli(argv) {
                 break;
             }
             default: {
-                const style = createStyle(colorEnabled(process.stderr));
-                process.stderr.write(`${style.error(`unknown command: ${parsed.command}`)}\n\n`);
-                await writeRootHelp({
-                    full: false,
-                    token: parsed.globals.token,
-                    envFile: parsed.globals.envFile,
-                });
+                // Short, greppable, and suggestion-first (issue #545) — never the root
+                // help dump, which buried the error when agents piped through `tail`.
+                const suggestion = suggestCommand(parsed.command);
+                const message = `unknown command: ${parsed.command}`;
+                if (json) {
+                    await writeJson({
+                        error: message,
+                        code: "USAGE",
+                        ...(suggestion ? { didYouMean: suggestion } : {}),
+                    });
+                }
+                else {
+                    process.stderr.write(formatUnknownCommand({
+                        command: parsed.command,
+                        suggestion,
+                        summary: suggestion ? commandSummary(suggestion) : undefined,
+                        style: createStyle(colorEnabled(process.stderr)),
+                    }));
+                }
                 flushTelemetry(2);
                 return 2;
             }

package/dist/commands/annotate.js

@@ -48,8 +48,9 @@ readStdinImpl = readStdin) {
     }
     const imagePath = parsed.positionals[0];
     if (!imagePath) {
-        writeCommandHelp(ANNOTATE_HELP);
-        return 2;
+        throw new UsageError("annotate requires an image path", {
+            example: "uploads annotate ./shot.png --spec ./callouts.json",
+        });
     }
     if (parsed.positionals.length > 1) {
         throw new UsageError("annotate takes exactly one image argument");

package/dist/commands/config.js

@@ -59,9 +59,9 @@ export async function runConfig(args, opts, help = false) {
         case "set":
             return runConfigSet(rest, subArgs, opts, help);
         default:
-            process.stderr.write(`unknown config subcommand: ${sub}\n\n`);
-            writeCommandHelp(CONFIG_HELP);
-            return 2;
+            // Short, not a help dump: agents trim output, and a dump pushes the
+            // reason out of the window (issue #545).
+            throw new UsageError(`unknown config subcommand: ${sub} (expected path, show, init, or set)`, { example: "uploads config show" });
     }
 }
 async function runConfigPath(args, opts, help) {
@@ -191,8 +191,9 @@ Examples:
     const key = positionals[0];
     const value = positionals[1];
     if (!key || !value) {
-        writeCommandHelp(`uploads config set <key> <value>\n`);
-        return 2;
+        throw new UsageError("config set requires a key and a value", {
+            example: "uploads config set UPLOADS_WORKSPACE myteam",
+        });
     }
     if (!VALID_KEYS.has(key)) {
         throw new UsageError(`unknown key: ${key} (expected ${[...VALID_KEYS].join(", ")})`);

package/dist/commands/screenshot.js

@@ -156,8 +156,9 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     }
     const target = parsed.positionals[0];
     if (!target) {
-        writeCommandHelp(SCREENSHOT_HELP);
-        return 2;
+        throw new UsageError("screenshot requires a target URL or .html file", {
+            example: "uploads screenshot http://localhost:4321/settings --out settings.png",
+        });
     }
     if (parsed.positionals.length > 1) {
         throw new UsageError("screenshot takes exactly one target");

package/dist/commands.js

@@ -941,8 +941,9 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     // 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;
+        throw new UsageError("attach requires at least one file", {
+            example: "uploads attach ./shot.png --pr 123",
+        });
     }
     if (branchArg !== undefined) {
         if (parsed.flags.has("--pr"))
@@ -1523,8 +1524,9 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     }
     const files = parsed.positionals;
     if (files.length === 0) {
-        writeCommandHelp(PUT_HELP);
-        return 2;
+        throw new UsageError("put requires at least one file", {
+            example: "uploads put ./shot.png --pr 123",
+        });
     }
     const multi = files.length > 1;
     const keyHint = flagString(parsed.flags, "--key");
@@ -1950,15 +1952,21 @@ function githubCoordinateFromFlags(flags) {
 export async function runGallery(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
     const action = parsed.positionals[0];
-    if (help || parsed.help || !action) {
+    if (help || parsed.help) {
         writeCommandHelp(GALLERY_HELP);
-        return help || parsed.help ? 0 : 2;
+        return 0;
+    }
+    if (!action) {
+        throw new UsageError("gallery requires a subcommand: create, show, list, delete, add, link, or unlink", { example: 'uploads gallery create --title "Release screenshots"' });
     }
     switch (action) {
         case "create": {
             const title = flagString(parsed.flags, "--title");
-            if (!title)
-                throw new UsageError("gallery create requires --title");
+            if (!title) {
+                throw new UsageError("gallery create requires --title", {
+                    example: 'uploads gallery create --title "Release screenshots"',
+                });
+            }
             const gallery = await ctx.client.createGallery({
                 title,
                 description: flagString(parsed.flags, "--description"),
@@ -2122,7 +2130,7 @@ export async function runGallery(ctx, args, help = false) {
             return failures.length === 0 ? 0 : 1;
         }
         default:
-            throw new UsageError(`unknown gallery command: ${action}`);
+            throw new UsageError(`unknown gallery command: ${action} (expected create, show, list, delete, add, link, or unlink)`, { example: 'uploads gallery create --title "Release screenshots"' });
     }
 }
 // --- list ---
@@ -2214,11 +2222,12 @@ export async function runList(ctx, args, help = false, run = execRunner) {
 const FIND_HELP = `uploads find k=v [k=v...] [--prefix <p>] [--limit <n>] [--workspace <name>]
 
 Human-friendly alias for \`uploads list --meta k=v...\` — same metadata filter
-(ANDed equality), same output; pairs are positional instead of repeated flags.
+(ANDed equality), same output; pairs are positional, or spelled --meta k=v.
 
 Examples:
   uploads find gh.repo=buildinternet/uploads gh.number=123
   uploads find path=/settings state=after --prefix screenshots/
+  uploads find --meta path=/settings
 `;
 export async function runFind(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
@@ -2226,11 +2235,15 @@ export async function runFind(ctx, args, help = false) {
         writeCommandHelp(FIND_HELP);
         return 0;
     }
-    if (parsed.positionals.length === 0) {
-        writeCommandHelp(FIND_HELP);
-        return 2;
+    // Same flag/positional symmetry as `meta set` (issue #545): `find` is the
+    // alias for `list --meta`, so `find --meta k=v` must not dead-end.
+    const pairs = [...parsed.positionals, ...flagValues(parsed.flags, "--meta")];
+    if (pairs.length === 0) {
+        throw new UsageError("find requires at least one k=v pair (or --meta k=v)", {
+            example: "uploads find path=/settings state=after",
+        });
     }
-    const filters = parseMetaFlags(parsed.positionals);
+    const filters = parseMetaFlags(pairs);
     return runFindFiles(ctx, filters, parsed.flags);
 }
 // --- meta ---
@@ -2243,23 +2256,35 @@ Commands:
   get <key>                            Show metadata for an object
   set <key> k=v [k=v...] [--delete k]...   Merge-set and/or delete pairs
 
+Pairs take either form: positional k=v, or --meta k=v (same spelling as
+put/screenshot/list). Both can appear in one call.
+
 Examples:
   uploads meta get screenshots/myapp/42/shot.png
   uploads meta set screenshots/myapp/42/shot.png path=/settings state=after
+  uploads meta set screenshots/myapp/42/shot.png --meta path=/settings
   uploads meta set screenshots/myapp/42/shot.png --delete path --delete state
 `;
 export async function runMeta(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
     const action = parsed.positionals[0];
-    if (help || parsed.help || !action) {
+    if (help || parsed.help) {
         writeCommandHelp(META_HELP);
-        return help || parsed.help ? 0 : 2;
+        return 0;
+    }
+    if (!action) {
+        throw new UsageError("meta requires a subcommand: get or set", {
+            example: "uploads meta set screenshots/myapp/42/shot.png --meta path=/settings",
+        });
     }
     switch (action) {
         case "get": {
             const key = parsed.positionals[1];
-            if (!key)
-                throw new UsageError("meta get requires an object key");
+            if (!key) {
+                throw new UsageError("meta get requires an object key", {
+                    example: "uploads meta get screenshots/myapp/42/shot.png",
+                });
+            }
             const result = await ctx.client.getMetadata(key);
             if (ctx.json)
                 await writeJson(result);
@@ -2275,12 +2300,22 @@ export async function runMeta(ctx, args, help = false) {
         }
         case "set": {
             const key = parsed.positionals[1];
-            if (!key)
-                throw new UsageError("meta set requires an object key");
-            const pairs = parsed.positionals.slice(2);
+            if (!key) {
+                throw new UsageError("meta set requires an object key", {
+                    example: "uploads meta set screenshots/myapp/42/shot.png --meta path=/settings",
+                });
+            }
+            // `--meta k=v` is accepted alongside the positional form: `put`, `list`,
+            // and `screenshot` all spell metadata that way, and `put`'s own success
+            // tip teaches the flag, so carrying it here is the natural guess
+            // (issue #545). Positionals come first so argument order still reads
+            // left to right when both are used.
+            const pairs = [...parsed.positionals.slice(2), ...flagValues(parsed.flags, "--meta")];
             const del = flagValues(parsed.flags, "--delete");
             if (pairs.length === 0 && del.length === 0) {
-                throw new UsageError("meta set requires k=v pairs and/or --delete <key>");
+                throw new UsageError("meta set requires k=v pairs and/or --delete <key>", {
+                    example: `uploads meta set ${key} --meta path=/settings`,
+                });
             }
             const set = pairs.length > 0 ? parseMetaFlags(pairs) : undefined;
             const result = await ctx.client.patchMetadata(key, {
@@ -2296,7 +2331,9 @@ export async function runMeta(ctx, args, help = false) {
             return 0;
         }
         default:
-            throw new UsageError(`unknown meta command: ${action}`);
+            throw new UsageError(`unknown meta command: ${action} (expected get or set)`, {
+                example: "uploads meta get screenshots/myapp/42/shot.png",
+            });
     }
 }
 /** The metadata keys the managed comment renders (path/state, PR #370). */
@@ -2356,8 +2393,9 @@ export async function runDelete(ctx, args, help = false) {
     }
     const key = parsed.positionals[0];
     if (!key) {
-        writeCommandHelp(DELETE_HELP);
-        return 2;
+        throw new UsageError("delete requires an object key", {
+            example: "uploads delete screenshots/myapp/42/shot.png --dry-run",
+        });
     }
     if (flagBool(parsed.flags, "--dry-run")) {
         if (ctx.json)
@@ -2397,8 +2435,11 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
         return 0;
     }
     const target = ghTargetFromFlags(parsed.flags, run);
-    if (!target)
-        throw new UsageError("comment requires --pr or --issue");
+    if (!target) {
+        throw new UsageError("comment requires --pr or --issue", {
+            example: "uploads comment --pr 123",
+        });
+    }
     const result = await syncAttachmentsComment(ctx.client, target, run, ctx.config.workspace, {
         resync: true,
     });
@@ -2568,7 +2609,9 @@ export async function runGithub(ctx, args, help = false, run = execRunner) {
         return help || parsed.help ? 0 : 2;
     }
     if (action !== "link" && action !== "unlink" && action !== "doctor") {
-        throw new UsageError(`unknown github subcommand: ${action}`);
+        throw new UsageError(`unknown github subcommand: ${action} (expected link or doctor)`, {
+            example: "uploads github link",
+        });
     }
     if (action === "doctor")
         return runGithubDoctor(ctx);

package/dist/github-gh.d.ts

@@ -74,6 +74,13 @@ export declare function ghMetadataFromTargetWithTitle(target: GhTarget, run?: Co
  * deleted best-effort via `gh api -X DELETE`; a failed delete is swallowed
  * and never fails the caller's command, and the next sync retries anyway.
  *
+ * A create additionally re-hunts once it has written (issue #553, mirroring
+ * the bot path): find-or-create is not atomic, so a concurrent writer can
+ * create its own comment in the same window. Both writers independently agree
+ * the OLDEST marker comment wins, fold their body into it and delete the rest
+ * — including their own create — so the race converges instead of leaving a
+ * stale orphan behind for a PR that never syncs again.
+ *
  * On why this duplicates the bot path rather than deferring to it: the gh
  * fallback is a supported path, not a stopgap, so it is held at behavioral
  * parity deliberately. This file already reimplements the hunt, the legacy

package/dist/github-gh.js

@@ -266,6 +266,13 @@ function findManagedComment(target, run, marker) {
  * deleted best-effort via `gh api -X DELETE`; a failed delete is swallowed
  * and never fails the caller's command, and the next sync retries anyway.
  *
+ * A create additionally re-hunts once it has written (issue #553, mirroring
+ * the bot path): find-or-create is not atomic, so a concurrent writer can
+ * create its own comment in the same window. Both writers independently agree
+ * the OLDEST marker comment wins, fold their body into it and delete the rest
+ * — including their own create — so the race converges instead of leaving a
+ * stale orphan behind for a PR that never syncs again.
+ *
  * On why this duplicates the bot path rather than deferring to it: the gh
  * fallback is a supported path, not a stopgap, so it is held at behavioral
  * parity deliberately. This file already reimplements the hunt, the legacy
@@ -281,26 +288,9 @@ function findManagedComment(target, run, marker) {
 export function upsertAttachmentsComment(target, body, run = execRunner, marker = ATTACHMENTS_MARKER, opts = {}) {
     const createIfMissing = opts.createIfMissing ?? true;
     const { comment: existing, extras } = findManagedComment(target, run, marker);
-    const deleteExtras = () => {
-        for (const extra of extras ?? []) {
-            try {
-                run("gh", ["api", `repos/${target.repo}/issues/comments/${extra.id}`, "-X", "DELETE"]);
-            }
-            catch {
-                // Best effort only — a failed delete must never fail the caller's command.
-            }
-        }
-    };
     if (existing) {
-        run("gh", [
-            "api",
-            `repos/${target.repo}/issues/comments/${existing.id}`,
-            "-X",
-            "PATCH",
-            "-F",
-            "body=@-",
-        ], body);
-        deleteExtras();
+        patchComment(target, run, existing.id, body);
+        deleteComments(target, run, extras);
         return { action: "updated" };
     }
     // Patch-only (createIfMissing false, i.e. an empty body) with no existing
@@ -308,7 +298,65 @@ export function upsertAttachmentsComment(target, body, run = execRunner, marker
     if (!createIfMissing)
         return { action: "skipped" };
     // No existing marker hit means `extras` is necessarily empty here (see
-    // `findManagedComment`) — nothing to delete after a create.
-    run("gh", ["api", `repos/${target.repo}/issues/${target.num}/comments`, "-F", "body=@-"], body);
-    return { action: "created" };
+    // `findManagedComment`) — nothing to delete before the create.
+    const created = run("gh", ["api", `repos/${target.repo}/issues/${target.num}/comments`, "-F", "body=@-"], body);
+    return reconcileAfterCreate(target, body, run, marker, created) ?? { action: "created" };
+}
+/**
+ * Re-hunt right after a create and collapse whatever a concurrent writer left
+ * behind (issue #553). Returns `{ action: "updated" }` when this run lost the
+ * race — its body has been folded into the older winning comment and its own
+ * create deleted — or null when nothing needed folding, including every
+ * failure: a verification problem must never fail a successful create.
+ *
+ * The winner is patched BEFORE any delete, so a failed fold leaves both
+ * comments (the next sync's hunt retries) rather than deleting the one that
+ * carries the current body.
+ */
+function reconcileAfterCreate(target, body, run, marker, createdRaw) {
+    let createdId;
+    try {
+        createdId = JSON.parse(createdRaw).id;
+    }
+    catch {
+        // `gh` printed something unparseable — fall through to the hunt, which
+        // identifies the winner on its own.
+    }
+    try {
+        const { comment: winner, extras } = findManagedComment(target, run, marker);
+        // `extras` is undefined in legacy mode, where a second hit may belong to
+        // another workspace — the adopt-only contract holds here too.
+        if (!winner || !extras?.length)
+            return null;
+        if (winner.id === createdId) {
+            // Ours is the oldest and already carries the body we just wrote — only
+            // the other writer's duplicate needs to go.
+            deleteComments(target, run, extras);
+            return null;
+        }
+        patchComment(target, run, winner.id, body);
+        deleteComments(target, run, extras);
+        return { action: "updated" };
+    }
+    catch {
+        // A failed listing or fold leaves the freshly created comment in place —
+        // correct content, one duplicate, healed by the next sync's hunt.
+        return null;
+    }
+}
+/** PATCH one comment's body via stdin, so the body is never shell-interpolated. */
+function patchComment(target, run, id, body) {
+    run("gh", ["api", `repos/${target.repo}/issues/comments/${id}`, "-X", "PATCH", "-F", "body=@-"], body);
+}
+/** Best-effort delete: a failed delete must never fail the caller's command,
+ * and the next sync's hunt retries anyway. */
+function deleteComments(target, run, comments) {
+    for (const c of comments ?? []) {
+        try {
+            run("gh", ["api", `repos/${target.repo}/issues/comments/${c.id}`, "-X", "DELETE"]);
+        }
+        catch {
+            // Best effort only.
+        }
+    }
 }

package/package.json

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