@buildinternet/uploads 0.9.0 → 0.10.0

package/dist/commands/session.js

@@ -0,0 +1,140 @@
+/**
+ * Session commands: whoami / status (show identity) and logout (clear token).
+ */
+import { describeConfigSources, loadConfigFile, redactToken, removeConfigKeys, resolveConfig, resolveConfigPath, workspaceFromToken, } from "../config.js";
+import { flagBool, flagString, parseCommandArgs } from "../cli-args.js";
+import { writeCommandHelp } from "../cli-style.js";
+import { writeJson } from "../io.js";
+const WHOAMI_HELP = `uploads whoami
+
+Show the active CLI identity: workspace, token (redacted), API URL, and where
+each value came from. Alias: uploads status.
+
+Does not call the API (offline). Use uploads doctor to verify the token works.
+
+Options:
+  --path <file>       Config file to inspect (default: shared buildinternet config)
+  --json              JSON on stdout
+
+Examples:
+  uploads whoami
+  uploads status --json
+  uploads whoami --path ./my.env
+`;
+const LOGOUT_HELP = `uploads logout
+
+Remove the saved UPLOADS_TOKEN from the shared config file so this machine is
+no longer signed in for the CLI. Does not revoke the token on the server.
+
+Environment variables (UPLOADS_TOKEN) are not unset — export them yourself if set.
+
+Options:
+  --path <file>       Config file to edit (default: shared buildinternet config)
+  --json              JSON on stdout
+
+Examples:
+  uploads logout
+  uploads logout --path ./my.env
+`;
+export function buildWhoamiReport(opts) {
+    const flags = {
+        envFile: opts.envFile,
+        token: opts.token,
+        workspace: opts.workspace,
+        apiUrl: opts.apiUrl,
+    };
+    const config = resolveConfig({ ...flags, requireToken: false });
+    const sources = describeConfigSources(flags);
+    const tokenInConfig = Boolean(loadConfigFile(config.configPath).UPLOADS_TOKEN);
+    return {
+        signedIn: Boolean(config.token),
+        workspace: config.workspace,
+        workspaceSource: sources.workspace,
+        workspaceFromToken: config.token ? workspaceFromToken(config.token) : undefined,
+        token: redactToken(config.token || undefined),
+        tokenSource: sources.token,
+        tokenInConfig,
+        apiUrl: config.apiUrl,
+        apiUrlSource: sources.apiUrl,
+        configPath: config.configPath,
+        configExists: config.configExists,
+    };
+}
+function formatWhoami(report) {
+    const cfg = `${report.configPath}${report.configExists ? "" : " (missing)"}`;
+    const lines = [
+        `signed in:  ${report.signedIn ? "yes" : "no"}`,
+        `workspace:  ${report.workspace} (${report.workspaceSource})`,
+    ];
+    if (report.workspaceFromToken && report.workspaceFromToken !== report.workspace) {
+        lines.push(`token ws:   ${report.workspaceFromToken} (encoded in token)`);
+    }
+    if (report.signedIn) {
+        lines.push(`token:      ${report.token} (${report.tokenSource})`);
+    }
+    lines.push(`api:        ${report.apiUrl} (${report.apiUrlSource})`);
+    lines.push(`config:     ${cfg}`);
+    if (!report.signedIn) {
+        lines.push("", "hint: run uploads login to sign in");
+    }
+    else if (report.tokenSource === "env" && !report.tokenInConfig) {
+        lines.push("", "note: token is from the environment, not the config file", "      uploads logout only clears the config file");
+    }
+    return lines.join("\n") + "\n";
+}
+function wantsJson(opts, parsed) {
+    return Boolean(opts.json || flagBool(parsed.flags, "--json"));
+}
+export async function runWhoami(args, opts, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        writeCommandHelp(WHOAMI_HELP);
+        return 0;
+    }
+    const report = buildWhoamiReport({
+        envFile: flagString(parsed.flags, "--path") ?? opts.envFile,
+        token: opts.token,
+        workspace: opts.workspace,
+        apiUrl: opts.apiUrl,
+    });
+    if (wantsJson(opts, parsed))
+        await writeJson(report);
+    else
+        process.stdout.write(formatWhoami(report));
+    return report.signedIn ? 0 : 1;
+}
+export async function runLogout(args, opts, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        writeCommandHelp(LOGOUT_HELP);
+        return 0;
+    }
+    const path = flagString(parsed.flags, "--path") ?? resolveConfigPath({ envFile: opts.envFile });
+    const hadFileToken = Boolean(loadConfigFile(path).UPLOADS_TOKEN);
+    const envTokenStillSet = Boolean(process.env.UPLOADS_TOKEN);
+    const result = removeConfigKeys(path, ["UPLOADS_TOKEN"]);
+    const payload = {
+        path: result.path,
+        removed: result.removed,
+        configExisted: result.existed,
+        hadTokenInConfig: hadFileToken,
+        envTokenStillSet,
+    };
+    if (wantsJson(opts, parsed)) {
+        await writeJson(payload);
+        return 0;
+    }
+    if (result.removed.includes("UPLOADS_TOKEN")) {
+        process.stdout.write(`signed out — removed UPLOADS_TOKEN from ${result.path}\n`);
+    }
+    else if (!result.existed) {
+        process.stdout.write(`no config file at ${result.path} — already signed out\n`);
+    }
+    else {
+        process.stdout.write(`no UPLOADS_TOKEN in ${result.path} — already signed out\n`);
+    }
+    if (envTokenStillSet) {
+        process.stderr.write("note: UPLOADS_TOKEN is still set in the environment; unset it to fully sign out\n");
+    }
+    return 0;
+}

package/dist/commands/setup.js

@@ -2,6 +2,7 @@ import { createUploadsClient } from "../client.js";
 import { DEFAULT_API_URL, DEFAULT_WORKSPACE, describeConfigSources, putDefaultsToConfigValues, redactToken, resolveApiUrl, resolveConfig, resolveConfigPath, resolvePutDefaults, writeConfigKeys, workspaceFromToken, } from "../config.js";
 import { flagBool, flagInt, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
 import { UploadsError } from "../errors.js";
+import { writeCommandHelp } from "../cli-style.js";
 const SETUP_HELP = `uploads setup — guided CLI configuration
 
 Writes UPLOADS_* keys to the shared buildinternet config file and prints
@@ -99,7 +100,7 @@ function formatWizard(status) {
 export async function runSetup(args, opts, help = false) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
-        process.stderr.write(SETUP_HELP);
+        writeCommandHelp(SETUP_HELP);
         return 0;
     }
     const apiUrl = flagString(parsed.flags, "--api-url");

package/dist/commands.js

@@ -14,7 +14,9 @@ import { resolvePutPrefix } from "./destinations.js";
 import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
 import { applyFrame, resolveFrameId } from "./frame.js";
 import { buildCliProvenance } from "./provenance.js";
+import { formatByteSize } from "./format-bytes.js";
 import { packageVersion } from "./package-version.js";
+import { writeCommandHelp } from "./cli-style.js";
 /** Read a local file (or `-` for stdin). Missing path → FILE_NOT_FOUND (exit 2). */
 export function readFileArg(fileArg) {
     try {
@@ -44,6 +46,11 @@ Uploads are public. --pr/--issue keys include the repo, number, and filename and
 remain public even for private/internal GitHub repositories. Upload only media
 that is safe at a predictable public URL.
 
+Re-uploading the same key overwrites in place (no prompt) so embeds hot-swap;
+human mode prints ">> replaced existing object (same URL)" after a real put,
+or ">> would replace existing object (same URL)" on --dry-run when the key
+already exists.
+
 Human/json output includes durable url and (when dual-host applies) embedUrl.
 MARKDOWN prefers embedUrl for GitHub. Override: UPLOADS_EMBED_PUBLIC_BASE_URL.
 
@@ -77,7 +84,7 @@ Options:
                         Re-uploading to an existing key WITH --meta replaces that file's
                         entire metadata set; without --meta the existing metadata is
                         preserved. Use "uploads meta set" to edit individual keys.
-  --dry-run             Print key + public URL without uploading. Not with --comment/--gallery
+  --dry-run             Print key + public URL without uploading; reports if the key would replace an existing object. Not with --comment/--gallery
 
 Exit codes: 0 ok · 2 usage/token/file · 3 auth/policy · 4 network · 1 other.
 Scripted formats (json|url|markdown) also print failures on stdout.
@@ -148,13 +155,20 @@ export function optimizeOptionsFromFlags(flags, defaults) {
 }
 function formatOptimizeNote(opt) {
     if (opt.optimized) {
-        return `optimized ${opt.originalBytes} → ${opt.outputBytes} bytes (${opt.filename})`;
+        return `optimized ${formatByteSize(opt.originalBytes)} → ${formatByteSize(opt.outputBytes)} (${opt.filename})`;
     }
     if (opt.skippedReason && opt.skippedReason !== "disabled") {
         return `optimize skipped (${opt.skippedReason})`;
     }
     return undefined;
 }
+function writeReplacedNote(replaced, quiet, dryRun = false) {
+    if (!quiet && replaced) {
+        process.stderr.write(dryRun
+            ? `>> would replace existing object (same URL)\n`
+            : `>> replaced existing object (same URL)\n`);
+    }
+}
 /** Frame (optional) then optimize — shared by put/attach/MCP. */
 export async function prepareImageForUpload(bytes, filename, opts) {
     let currentBytes = bytes;
@@ -259,6 +273,10 @@ Attachments are public and their repo/number/filename keys are predictable.
 Private/internal GitHub repository visibility does not restrict access; upload
 only media that is safe at a public URL.
 
+Same filename under the same PR/issue overwrites in place (no prompt) so the
+URL and every embed hot-swap. Human mode prints ">> replaced existing object
+(same URL)" when that happens.
+
 Still images are optimized to WebP by default (same as put). Use --no-optimize
 to upload originals. Optional --frame wraps images in device/browser chrome.
 
@@ -293,11 +311,11 @@ Examples:
 export async function runAttach(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
-        process.stderr.write(ATTACH_HELP);
+        writeCommandHelp(ATTACH_HELP);
         return 0;
     }
     if (parsed.positionals.length === 0) {
-        process.stderr.write(ATTACH_HELP);
+        writeCommandHelp(ATTACH_HELP);
         return 2;
     }
     if (parsed.flags.has("--no-comment") && typeof parsed.flags.get("--no-comment") === "string") {
@@ -348,6 +366,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
             }),
             metadata,
         });
+        writeReplacedNote(result.replaced, ctx.quiet || ctx.json);
         const embedSrc = urlForGithubEmbed(result.url, result.embedUrl);
         results.push({
             ...result,
@@ -393,17 +412,17 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
 }
 export async function runPut(ctx, args, help = false, run = execRunner) {
     if (help) {
-        process.stderr.write(PUT_HELP);
+        writeCommandHelp(PUT_HELP);
         return 0;
     }
     const parsed = parseCommandArgs(args);
     if (parsed.help) {
-        process.stderr.write(PUT_HELP);
+        writeCommandHelp(PUT_HELP);
         return 0;
     }
     const fileArg = parsed.positionals[0];
     if (!fileArg) {
-        process.stderr.write(PUT_HELP);
+        writeCommandHelp(PUT_HELP);
         return 2;
     }
     const keyHint = flagString(parsed.flags, "--key");
@@ -562,6 +581,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         }),
         metadata,
     });
+    if (format === "human")
+        writeReplacedNote(result.replaced, ctx.quiet, dryRun);
     const embedSrc = urlForGithubEmbed(result.url, result.embedUrl);
     const markdown = buildMarkdown(embedSrc, { alt, width });
     let gallery;
@@ -673,7 +694,7 @@ export async function runGallery(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
     const action = parsed.positionals[0];
     if (help || parsed.help || !action) {
-        process.stderr.write(GALLERY_HELP);
+        writeCommandHelp(GALLERY_HELP);
         return help || parsed.help ? 0 : 2;
     }
     switch (action) {
@@ -887,7 +908,7 @@ async function runFindFiles(ctx, filters, flags) {
 export async function runList(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
-        process.stderr.write(LIST_HELP);
+        writeCommandHelp(LIST_HELP);
         return 0;
     }
     const metaPairs = flagValues(parsed.flags, "--meta");
@@ -945,11 +966,11 @@ Examples:
 export async function runFind(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
-        process.stderr.write(FIND_HELP);
+        writeCommandHelp(FIND_HELP);
         return 0;
     }
     if (parsed.positionals.length === 0) {
-        process.stderr.write(FIND_HELP);
+        writeCommandHelp(FIND_HELP);
         return 2;
     }
     const filters = parseMetaFlags(parsed.positionals);
@@ -974,7 +995,7 @@ export async function runMeta(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
     const action = parsed.positionals[0];
     if (help || parsed.help || !action) {
-        process.stderr.write(META_HELP);
+        writeCommandHelp(META_HELP);
         return help || parsed.help ? 0 : 2;
     }
     switch (action) {
@@ -1034,12 +1055,12 @@ Examples:
 export async function runDelete(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
-        process.stderr.write(DELETE_HELP);
+        writeCommandHelp(DELETE_HELP);
         return 0;
     }
     const key = parsed.positionals[0];
     if (!key) {
-        process.stderr.write(DELETE_HELP);
+        writeCommandHelp(DELETE_HELP);
         return 2;
     }
     if (flagBool(parsed.flags, "--dry-run")) {
@@ -1071,7 +1092,7 @@ Examples:
 export async function runComment(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
-        process.stderr.write(COMMENT_HELP);
+        writeCommandHelp(COMMENT_HELP);
         return 0;
     }
     const target = ghTargetFromFlags(parsed.flags, run);
@@ -1099,7 +1120,7 @@ Examples:
 `;
 export async function runUsage(ctx, args, help = false) {
     if (help || parseCommandArgs(args).help) {
-        process.stderr.write(USAGE_HELP);
+        writeCommandHelp(USAGE_HELP);
         return 0;
     }
     const result = await ctx.client.usage();
@@ -1127,7 +1148,7 @@ Examples:
 `;
 export async function runReconcile(ctx, args, help = false) {
     if (help || parseCommandArgs(args).help) {
-        process.stderr.write(RECONCILE_HELP);
+        writeCommandHelp(RECONCILE_HELP);
         return 0;
     }
     const result = await ctx.client.reconcile();
@@ -1150,7 +1171,7 @@ Examples:
 `;
 export async function runPurgeExpired(ctx, args, help = false) {
     if (help || parseCommandArgs(args).help) {
-        process.stderr.write(PURGE_HELP);
+        writeCommandHelp(PURGE_HELP);
         return 0;
     }
     const result = await ctx.client.purgeExpired();
@@ -1176,7 +1197,7 @@ Examples:
 `;
 export async function runHealth(ctx, args, help = false) {
     if (help || parseCommandArgs(args).help) {
-        process.stderr.write(HEALTH_HELP);
+        writeCommandHelp(HEALTH_HELP);
         return 0;
     }
     const result = await createUploadsClient({
@@ -1260,7 +1281,7 @@ export async function buildDoctorReport(config, client) {
 }
 export async function runDoctor(ctx, args, help = false) {
     if (help || parseCommandArgs(args).help) {
-        process.stderr.write(DOCTOR_HELP);
+        writeCommandHelp(DOCTOR_HELP);
         return 0;
     }
     const report = await buildDoctorReport(ctx.config, ctx.client);

package/dist/config-file.d.ts

@@ -40,4 +40,13 @@ export declare function writeConfigKeys(path: string, keys: UploadsConfigValues,
     updated: string[];
 };
 export declare function configValuesFromClient(config: Partial<UploadsClientConfig>, defaults?: PutDefaults): UploadsConfigValues;
+/**
+ * Remove keys from the shared config file (e.g. logout clears UPLOADS_TOKEN).
+ * No-op for missing file/keys. Preserves other lines and comments.
+ */
+export declare function removeConfigKeys(path: string, keys: readonly string[]): {
+    path: string;
+    removed: string[];
+    existed: boolean;
+};
 export { PUT_DEFAULT_KEY_MAP };

package/dist/config-file.js

@@ -226,15 +226,7 @@ export function writeConfigKeys(path, keys, opts) {
             updated.push(key);
         }
     }
-    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-    writeFileSync(tmp, lines.join("\n").replace(/\n*$/, "\n"), { encoding: "utf8", mode: 0o600 });
-    renameSync(tmp, path);
-    try {
-        chmodSync(path, 0o600);
-    }
-    catch {
-        /* Windows/filesystems may not support modes. */
-    }
+    writeConfigFileAtomic(path, lines.join("\n"));
     return { path, created: !existed, updated };
 }
 export function configValuesFromClient(config, defaults) {
@@ -248,4 +240,42 @@ export function configValuesFromClient(config, defaults) {
     Object.assign(out, putDefaultsToConfigValues(defaults ?? {}));
     return out;
 }
+/**
+ * Remove keys from the shared config file (e.g. logout clears UPLOADS_TOKEN).
+ * No-op for missing file/keys. Preserves other lines and comments.
+ */
+export function removeConfigKeys(path, keys) {
+    if (!existsSync(path))
+        return { path, removed: [], existed: false };
+    const keySet = new Set(keys);
+    const removed = [];
+    const kept = [];
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+        const parsed = parseEnvLine(line);
+        if (parsed && keySet.has(parsed.key)) {
+            if (!removed.includes(parsed.key))
+                removed.push(parsed.key);
+            continue;
+        }
+        kept.push(line);
+    }
+    if (removed.length === 0)
+        return { path, removed: [], existed: true };
+    // Drop consecutive blank lines left by removals
+    const collapsed = kept.filter((line, i) => !(line === "" && i > 0 && kept[i - 1] === ""));
+    writeConfigFileAtomic(path, collapsed.join("\n"));
+    return { path, removed, existed: true };
+}
+/** Atomic write + mode 0o600 (best-effort on platforms without chmod). */
+function writeConfigFileAtomic(path, body) {
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, body.replace(/\n*$/, "\n"), { encoding: "utf8", mode: 0o600 });
+    renameSync(tmp, path);
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        /* Windows/filesystems may not support modes. */
+    }
+}
 export { PUT_DEFAULT_KEY_MAP };

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-export { defaultConfigPath, resolveConfigPath, loadConfigFile, redactToken, writeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, UPLOADS_CONFIG_KEYS, type UploadsConfigKey, type UploadsConfigValues, type PutDefaults, } from "./config-file.js";
+export { defaultConfigPath, resolveConfigPath, loadConfigFile, redactToken, writeConfigKeys, removeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, UPLOADS_CONFIG_KEYS, type UploadsConfigKey, type UploadsConfigValues, type PutDefaults, } from "./config-file.js";
 export interface UploadsClientConfig {
     apiUrl: string;
     workspace: string;

package/dist/config.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { loadConfigFile, resolveConfigPath } from "./config-file.js";
 import { UploadsError } from "./errors.js";
-export { defaultConfigPath, resolveConfigPath, loadConfigFile, redactToken, writeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, UPLOADS_CONFIG_KEYS, } from "./config-file.js";
+export { defaultConfigPath, resolveConfigPath, loadConfigFile, redactToken, writeConfigKeys, removeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, UPLOADS_CONFIG_KEYS, } from "./config-file.js";
 export const DEFAULT_API_URL = "https://api.uploads.sh";
 export const DEFAULT_WORKSPACE = "default";
 const TOKEN_WORKSPACE_RE = /^up_([a-z0-9][a-z0-9-]{1,62})_/;

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "FILE_NOT_FOUND" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_KEY" | "KEY_POLICY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "API_ERROR" | "NETWORK" | "USAGE";
+export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "FILE_NOT_FOUND" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_KEY" | "KEY_POLICY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "GITHUB_REQUIRED" | "API_ERROR" | "NETWORK" | "USAGE";
 export declare class UploadsError extends Error {
     readonly code: UploadsErrorCode;
     readonly status?: number;

package/dist/format-bytes.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Human-readable size for CLI notes (1024-based).
+ * files-sdk has no size formatter — only raw `size` on head/upload results.
+ */
+export declare function formatByteSize(bytes: number): string;

package/dist/format-bytes.js

@@ -0,0 +1,11 @@
+/**
+ * Human-readable size for CLI notes (1024-based).
+ * files-sdk has no size formatter — only raw `size` on head/upload results.
+ */
+export function formatByteSize(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return "0 B";
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    const exponent = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+    return `${(bytes / 1024 ** exponent).toFixed(exponent === 0 ? 0 : 1)} ${units[exponent]}`;
+}

package/dist/update-check.d.ts

@@ -23,6 +23,16 @@ export declare function parseSemver(version: string): [number, number, number] |
 export declare function isNewerVersion(latest: string, current: string): boolean;
 export declare function readUpdateCache(path: string): UpdateCache | undefined;
 export declare function writeUpdateCache(path: string, cache: UpdateCache): void;
+export interface UpdateStatus {
+    current: string;
+    latest?: string;
+    updateAvailable: boolean;
+}
+/**
+ * Resolve current vs latest published version (cache + optional network).
+ * Always resolves; never throws. Does not print.
+ */
+export declare function checkForUpdate(opts?: UpdateCheckOptions): Promise<UpdateStatus>;
 /**
  * If a newer published version is known (or can be fetched within the timeout),
  * write a one-line stderr hint. Always resolves; never throws.

package/dist/update-check.js

@@ -69,20 +69,21 @@ export function writeUpdateCache(path, cache) {
     }
 }
 /**
- * If a newer published version is known (or can be fetched within the timeout),
- * write a one-line stderr hint. Always resolves; never throws.
+ * Resolve current vs latest published version (cache + optional network).
+ * Always resolves; never throws. Does not print.
  */
-export async function maybeHintUpdate(opts = {}) {
+export async function checkForUpdate(opts = {}) {
+    const current = opts.currentVersion ?? packageVersion();
     try {
-        if (opts.quiet || opts.command === "mcp")
-            return;
-        if (truthyEnv("UPLOADS_NO_UPDATE") || truthyEnv("NO_UPDATE_NOTIFIER"))
-            return;
-        const current = opts.currentVersion ?? packageVersion();
+        if (opts.quiet || opts.command === "mcp") {
+            return { current, updateAvailable: false };
+        }
+        if (truthyEnv("UPLOADS_NO_UPDATE") || truthyEnv("NO_UPDATE_NOTIFIER")) {
+            return { current, updateAvailable: false };
+        }
         const cachePath = opts.cachePath ?? defaultCachePath();
         const now = opts.now ?? Date.now();
         const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
-        const write = opts.write ?? ((text) => process.stderr.write(text));
         const cached = readUpdateCache(cachePath);
         let latest;
         if (cached && now - cached.checkedAt < ttlMs && cached.current === current) {
@@ -98,9 +99,24 @@ export async function maybeHintUpdate(opts = {}) {
                 latest = cached.latest; // stale cache if network failed
             }
         }
-        if (latest && isNewerVersion(latest, current)) {
-            write(`hint: ${PACKAGE_NAME}@${latest} is available (you have ${current}). Update: npm i -g ${PACKAGE_NAME}\n`);
-        }
+        const updateAvailable = Boolean(latest && isNewerVersion(latest, current));
+        return { current, latest, updateAvailable };
+    }
+    catch {
+        return { current, updateAvailable: false };
+    }
+}
+/**
+ * If a newer published version is known (or can be fetched within the timeout),
+ * write a one-line stderr hint. Always resolves; never throws.
+ */
+export async function maybeHintUpdate(opts = {}) {
+    try {
+        const status = await checkForUpdate(opts);
+        if (!status.updateAvailable || !status.latest)
+            return;
+        const write = opts.write ?? ((text) => process.stderr.write(text));
+        write(`hint: ${PACKAGE_NAME}@${status.latest} is available (you have ${status.current}). Update: npm i -g ${PACKAGE_NAME}\n`);
     }
     catch {
         // Never surface update-check failures.

package/package.json

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