@buildinternet/uploads 0.1.1 → 0.3.0

package/dist/commands.js

@@ -5,29 +5,41 @@ import { parseCommandArgs, flagString, flagBool, flagInt, UsageError, } from "./
 import { resolvePutDefaults, workspaceMismatch, workspaceFromToken, } from "./config.js";
 import { buildMarkdown } from "./embed.js";
 import { UploadsError } from "./errors.js";
+import { writeJson, writeStdout } from "./io.js";
 import { ghAttachmentKey, ghKeyPrefix, attachmentsCommentBody, } from "./github.js";
 import { resolveRepo, resolveCurrentPullRequest, execRunner, upsertAttachmentsComment, } from "./github-gh.js";
-async function writeStdout(text) {
-    if (!process.stdout.write(text)) {
-        await new Promise((resolve) => process.stdout.once("drain", resolve));
-    }
-}
-async function writeJson(value) {
-    await writeStdout(JSON.stringify(value, null, 2) + "\n");
-}
+import { resolvePutPrefix } from "./destinations.js";
+import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
+import { applyFrame, resolveFrameId } from "./frame.js";
 // --- put ---
 const PUT_HELP = `uploads put <file> [options]
 
 Upload an image for GitHub embeds. Use "-" for stdin.
 
+Still images (PNG/JPEG/…) are optimized to WebP by default (long edge capped,
+high quality; EXIF stripped) so GitHub embeds stay lean. Original bytes are kept
+when they are already smaller, animated, or not an image. Use --no-optimize to
+upload as-is, or --keep-exif when image metadata matters for the discussion.
+
+Optional --frame wraps the image in a device/browser chrome before optimize
+(default off). See: uploads put --help frames
+
 Options:
   --key <key>           Object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>)
+  --destination <id>    Typed root: screenshots | gh | f (sets --prefix)
   --prefix <path>       Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX)
   --repo <owner/repo>   Repo segment (default: git remote, or UPLOADS_DEFAULT_REPO)
   --ref <id>            PR/issue/branch segment (default: today, or UPLOADS_DEFAULT_REF)
   --alt <text>          Alt text (default: filename)
   --width <px>          <img width=…> markdown (or UPLOADS_DEFAULT_WIDTH)
-  --content-type <mime> Override Content-Type
+  --content-type <mime> Override Content-Type (ignored when optimize rewrites the body)
+  --frame <id>          Device/browser frame before optimize (phone|browser|iphone-16-pro)
+  --frame-url <url>     Address bar text for --frame browser
+  --frame-fit cover|contain  How the shot fills the screen (default: cover)
+  --no-optimize         Skip client-side image optimization (or UPLOADS_NO_OPTIMIZE=1)
+  --optimize-max-edge <px>  Max long edge when optimizing (default: 2400)
+  --optimize-quality <1-100>  WebP quality (default: 85)
+  --keep-exif           Keep EXIF/XMP/ICC when optimizing (default: strip for privacy)
   --no-git              Don't derive --repo from git (or UPLOADS_NO_GIT=1)
   --workspace, -w <name>  Override workspace (wins over UPLOADS_WORKSPACE and token inference)
   --format human|url|markdown|json
@@ -37,34 +49,110 @@ Options:
 
 Examples:
   uploads put ./shot.png --repo myorg/myapp --ref 1722 --alt "New cards" --width 700
-  uploads --env-file .env put ./shot.png
-  uploads --env-file .env put ./after.png --pr 123 --comment
+  uploads put ./mobile.png --frame phone
+  uploads put ./ui.png --frame browser --frame-url "https://app.example/settings"
+  uploads put ./shot.png --destination screenshots
 `;
-/** Reads --pr/--issue (+ --repo) into a GhTarget; undefined when neither flag is present. */
-function ghTargetFromFlags(flags, run) {
-    const pr = flagInt(flags, "--pr", "--pr");
-    const issue = flagInt(flags, "--issue", "--issue");
+/**
+ * Turns a pr/issue pair (+ optional repo) into a GhTarget; undefined when
+ * neither is present. Shared by the CLI flags and the MCP tool arguments.
+ */
+export function makeGhTarget(pr, issue, repoArg, run) {
     if (pr === undefined && issue === undefined)
         return undefined;
     if (pr !== undefined && issue !== undefined) {
         throw new UsageError("--pr and --issue are mutually exclusive");
     }
-    const repo = resolveRepo(flagString(flags, "--repo"), run);
+    const repo = resolveRepo(repoArg, run);
     return { repo, kind: pr !== undefined ? "pull" : "issues", num: (pr ?? issue) };
 }
+/** Reads --pr/--issue (+ --repo) into a GhTarget; undefined when neither flag is present. */
+function ghTargetFromFlags(flags, run) {
+    return makeGhTarget(flagInt(flags, "--pr", "--pr"), flagInt(flags, "--issue", "--issue"), flagString(flags, "--repo"), run);
+}
+/** Shared put/attach optimize flags + UPLOADS_NO_OPTIMIZE default. */
+export function optimizeOptionsFromFlags(flags, defaults) {
+    if (flags.has("--no-optimize") && typeof flags.get("--no-optimize") === "string") {
+        throw new UsageError("--no-optimize takes no value");
+    }
+    if (flags.has("--keep-exif") && typeof flags.get("--keep-exif") === "string") {
+        throw new UsageError("--keep-exif takes no value");
+    }
+    const quality = flagInt(flags, "--optimize-quality", "--optimize-quality");
+    if (quality !== undefined && quality > 100) {
+        throw new UsageError("invalid --optimize-quality: must be 1–100");
+    }
+    return {
+        enabled: !(flagBool(flags, "--no-optimize") || defaults.noOptimize === true),
+        maxEdge: flagInt(flags, "--optimize-max-edge", "--optimize-max-edge"),
+        quality,
+        keepExif: flagBool(flags, "--keep-exif") || defaults.keepExif === true,
+    };
+}
+function formatOptimizeNote(opt) {
+    if (opt.optimized) {
+        return `optimized ${opt.originalBytes} → ${opt.outputBytes} bytes (${opt.filename})`;
+    }
+    if (opt.skippedReason && opt.skippedReason !== "disabled") {
+        return `optimize skipped (${opt.skippedReason})`;
+    }
+    return undefined;
+}
+/** Frame (optional) then optimize — shared by put/attach/MCP. */
+export async function prepareImageForUpload(bytes, filename, opts) {
+    let currentBytes = bytes;
+    let currentName = filename;
+    let frameMeta;
+    if (opts.frameId) {
+        const framed = await applyFrame(currentBytes, currentName, {
+            id: opts.frameId,
+            browserUrl: opts.frameUrl,
+            fit: opts.frameFit,
+        });
+        frameMeta = {
+            framed: framed.framed,
+            frameId: framed.frameId,
+            skippedReason: framed.skippedReason,
+        };
+        if (framed.framed) {
+            currentBytes = framed.bytes;
+            currentName = framed.filename;
+        }
+    }
+    const optimized = await optimizeImageForUpload(currentBytes, currentName, opts.optimize);
+    return { ...optimized, frame: frameMeta };
+}
+function frameOptionsFromFlags(flags) {
+    const raw = flagString(flags, "--frame");
+    let frameId;
+    try {
+        frameId = resolveFrameId(raw);
+    }
+    catch (err) {
+        throw new UsageError(err instanceof Error ? err.message : String(err));
+    }
+    const fitRaw = flagString(flags, "--frame-fit");
+    let frameFit;
+    if (fitRaw) {
+        if (fitRaw !== "cover" && fitRaw !== "contain") {
+            throw new UsageError(`invalid --frame-fit: ${fitRaw} (use cover or contain)`);
+        }
+        frameFit = fitRaw;
+    }
+    if (frameFit && !frameId)
+        throw new UsageError("--frame-fit requires --frame");
+    const frameUrl = flagString(flags, "--frame-url");
+    if (frameUrl && !frameId)
+        throw new UsageError("--frame-url requires --frame");
+    return { frameId, frameUrl, frameFit };
+}
 /**
  * List every attachment under the target's prefix and create/update the
  * managed comment. Throws on gh failure — callers decide whether that is
  * fatal (`comment` command) or a warning (`put --comment`).
  */
-async function syncAttachmentsComment(ctx, target, run) {
-    const items = [];
-    let cursor;
-    do {
-        const page = await ctx.client.list({ prefix: ghKeyPrefix(target), cursor });
-        items.push(...page.items.map(({ key, url }) => ({ key, url })));
-        cursor = page.cursor ?? undefined;
-    } while (cursor);
+export async function syncAttachmentsComment(client, target, run) {
+    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url }) => ({ key, url }));
     if (items.length === 0)
         return { action: "skipped", count: 0 };
     const body = attachmentsCommentBody(items);
@@ -77,16 +165,27 @@ const ATTACH_HELP = `uploads attach <file...> [options]
 Upload one or more stable PR/issue attachments and maintain a single GitHub
 comment. With no target, uses the pull request for the current branch.
 
+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.
+
 Options:
   --pr <num>            Attach to this pull request
   --issue <num>         Attach to this issue
   --repo <owner/repo>   Repository (default: gh/git inference)
   --no-comment          Upload only; don't create/update the managed comment
-  --content-type <mime> Override Content-Type (applied to every file)
+  --content-type <mime> Override Content-Type (applied to every file; ignored when optimize rewrites)
+  --frame <id>          Device/browser frame before optimize (phone|browser|iphone-16-pro)
+  --frame-url <url>     Address bar text for --frame browser
+  --frame-fit cover|contain  How the shot fills the screen (default: cover)
+  --no-optimize         Skip client-side image optimization (or UPLOADS_NO_OPTIMIZE=1)
+  --optimize-max-edge <px>  Max long edge when optimizing (default: 2400)
+  --optimize-quality <1-100>  WebP quality (default: 85)
+  --keep-exif           Keep EXIF/XMP/ICC when optimizing (default: strip for privacy)
   --workspace, -w <name>  Override workspace
 
 Examples:
   uploads attach ./before.png ./after.png
+  uploads attach ./mobile.png --frame phone
   uploads attach ./shot.png --pr 123 --repo myorg/myapp
   uploads attach ./artifact.zip --issue 45 --no-comment
 `;
@@ -106,25 +205,50 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     const explicitTarget = ghTargetFromFlags(parsed.flags, run);
     const target = explicitTarget ??
         resolveCurrentPullRequest(resolveRepo(flagString(parsed.flags, "--repo"), run), run);
+    const defaults = resolvePutDefaults({ envFile: ctx.envFile });
+    const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
+    const frameOpts = frameOptionsFromFlags(parsed.flags);
+    const contentTypeOverride = flagString(parsed.flags, "--content-type");
     const results = [];
     for (const file of parsed.positionals) {
         if (file === "-")
             throw new UsageError("attach does not support stdin; pass one or more file paths");
-        const filename = basename(file);
+        const sourceName = basename(file);
         if (!ctx.quiet && !ctx.json)
             process.stderr.write(`>> uploading ${file}\n`);
-        const result = await ctx.client.put(new Uint8Array(readFileSync(file)), {
-            filename,
-            key: ghAttachmentKey(target, filename),
-            contentType: flagString(parsed.flags, "--content-type"),
+        const prepared = await prepareImageForUpload(new Uint8Array(readFileSync(file)), sourceName, {
+            ...frameOpts,
+            optimize: optimizeOpts,
+        });
+        if (prepared.frame?.framed && !ctx.quiet && !ctx.json) {
+            process.stderr.write(`>> framed with ${prepared.frame.frameId}\n`);
+        }
+        const note = formatOptimizeNote(prepared);
+        if (note && !ctx.quiet && !ctx.json)
+            process.stderr.write(`>> ${note}\n`);
+        const result = await ctx.client.put(prepared.bytes, {
+            filename: prepared.filename,
+            key: ghAttachmentKey(target, prepared.filename),
+            contentType: prepared.optimized ? prepared.contentType : contentTypeOverride,
+        });
+        results.push({
+            ...result,
+            markdown: buildMarkdown(result.url, { alt: sourceName }),
+            optimize: {
+                optimized: prepared.optimized,
+                skippedReason: prepared.skippedReason,
+                originalBytes: prepared.originalBytes,
+                outputBytes: prepared.outputBytes,
+                filename: prepared.filename,
+            },
+            frame: prepared.frame,
         });
-        results.push({ ...result, markdown: buildMarkdown(result.url, { alt: filename }) });
     }
     let comment;
     let commentError;
     if (!parsed.flags.has("--no-comment")) {
         try {
-            comment = await syncAttachmentsComment(ctx, target, run);
+            comment = await syncAttachmentsComment(ctx.client, target, run);
         }
         catch (err) {
             commentError = err instanceof Error ? err.message : String(err);
@@ -159,6 +283,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         return 2;
     }
     const keyHint = flagString(parsed.flags, "--key");
+    const destFlag = flagString(parsed.flags, "--destination");
+    const prefixFlag = flagString(parsed.flags, "--prefix");
     const ghTarget = ghTargetFromFlags(parsed.flags, run);
     const wantComment = parsed.flags.has("--comment");
     if (wantComment && typeof parsed.flags.get("--comment") === "string") {
@@ -172,12 +298,23 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         if (flagString(parsed.flags, "--ref")) {
             throw new UsageError("--ref cannot be combined with --pr/--issue");
         }
-        if (flagString(parsed.flags, "--prefix")) {
+        if (prefixFlag)
             throw new UsageError("--prefix cannot be combined with --pr/--issue");
-        }
+    }
+    let resolvedPrefix;
+    try {
+        resolvedPrefix = resolvePutPrefix({
+            destination: destFlag,
+            prefix: prefixFlag,
+            key: keyHint,
+            ghAttachment: Boolean(ghTarget),
+        });
+    }
+    catch (err) {
+        throw new UsageError(err instanceof Error ? err.message : String(err));
     }
     const bytes = fileArg === "-" ? new Uint8Array(readFileSync(0)) : new Uint8Array(readFileSync(fileArg));
-    const filename = fileArg === "-" ? (keyHint ? basename(keyHint) : "stdin.bin") : basename(fileArg);
+    const sourceName = fileArg === "-" ? (keyHint ? basename(keyHint) : "stdin.bin") : basename(fileArg);
     const format = ctx.json
         ? "json"
         : (() => {
@@ -189,7 +326,15 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             throw new UsageError(`invalid --format: ${raw}`);
         })();
     const defaults = resolvePutDefaults({ envFile: ctx.envFile });
-    const alt = flagString(parsed.flags, "--alt") ?? basename(filename);
+    const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
+    const frameOpts = frameOptionsFromFlags(parsed.flags);
+    const prepared = await prepareImageForUpload(bytes, sourceName, {
+        ...frameOpts,
+        optimize: optimizeOpts,
+    });
+    const filename = prepared.filename;
+    const contentTypeOverride = flagString(parsed.flags, "--content-type");
+    const alt = flagString(parsed.flags, "--alt") ?? basename(sourceName);
     const widthRaw = flagString(parsed.flags, "--width");
     const width = widthRaw && /^\d+$/.test(widthRaw) && Number(widthRaw) > 0
         ? Number.parseInt(widthRaw, 10)
@@ -200,24 +345,39 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             : defaults.width;
     if (!ctx.quiet && format === "human") {
         process.stderr.write(`>> uploading ${fileArg === "-" ? "stdin" : fileArg}\n`);
+        if (prepared.frame?.framed)
+            process.stderr.write(`>> framed with ${prepared.frame.frameId}\n`);
+        const note = formatOptimizeNote(prepared);
+        if (note)
+            process.stderr.write(`>> ${note}\n`);
     }
     const noGit = flagBool(parsed.flags, "--no-git") || defaults.noGit === true;
-    const result = await ctx.client.put(bytes, {
+    let key = ghTarget ? ghAttachmentKey(ghTarget, filename) : keyHint;
+    if (key && prepared.optimized)
+        key = rewriteKeyExtension(key, filename);
+    const result = await ctx.client.put(prepared.bytes, {
         filename,
-        key: ghTarget ? ghAttachmentKey(ghTarget, filename) : keyHint,
-        prefix: flagString(parsed.flags, "--prefix") ?? defaults.prefix,
+        key,
+        prefix: resolvedPrefix ?? defaults.prefix,
         repo: flagString(parsed.flags, "--repo") ?? defaults.repo,
         ref: flagString(parsed.flags, "--ref") ?? defaults.ref,
-        contentType: flagString(parsed.flags, "--content-type"),
+        contentType: prepared.optimized ? prepared.contentType : contentTypeOverride,
         deriveRepoFromGit: !noGit,
     });
     const markdown = buildMarkdown(result.url, { alt, width });
+    const optimizeMeta = {
+        optimized: prepared.optimized,
+        skippedReason: prepared.skippedReason,
+        originalBytes: prepared.originalBytes,
+        outputBytes: prepared.outputBytes,
+        filename: prepared.filename,
+    };
     if (!ctx.quiet && format === "human") {
         process.stderr.write(`>> key: ${result.key}\n\n`);
     }
     switch (format) {
         case "json":
-            await writeJson({ ...result, markdown });
+            await writeJson({ ...result, markdown, optimize: optimizeMeta, frame: prepared.frame });
             break;
         case "url":
             await writeStdout(`${result.url}\n`);
@@ -230,7 +390,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     }
     if (wantComment && ghTarget) {
         try {
-            const sync = await syncAttachmentsComment(ctx, ghTarget, run);
+            const sync = await syncAttachmentsComment(ctx.client, ghTarget, run);
             if (!ctx.quiet && format === "human") {
                 process.stderr.write(`>> attachments comment ${sync.action}\n`);
             }
@@ -270,13 +430,8 @@ export async function runList(ctx, args, help = false, run = execRunner) {
     const limit = flagInt(parsed.flags, "--limit", "--limit");
     const cursor = flagString(parsed.flags, "--cursor");
     if (flagBool(parsed.flags, "--all")) {
-        const items = [];
-        let next = cursor;
-        do {
-            const page = await ctx.client.list({ prefix, limit, cursor: next ?? undefined });
-            items.push(...page.items);
-            next = page.cursor;
-        } while (next);
+        // --all may start from a caller-provided --cursor and drains from there.
+        const items = await ctx.client.listAll({ prefix, limit, cursor });
         if (ctx.json)
             await writeJson({ items, cursor: null });
         else
@@ -347,7 +502,7 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
     const target = ghTargetFromFlags(parsed.flags, run);
     if (!target)
         throw new UsageError("comment requires --pr or --issue");
-    const result = await syncAttachmentsComment(ctx, target, run);
+    const result = await syncAttachmentsComment(ctx.client, target, run);
     if (ctx.json) {
         await writeJson({ ...target, ...result });
     }
@@ -358,6 +513,83 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
     }
     return 0;
 }
+// --- usage / reconcile / purge ---
+const USAGE_HELP = `uploads usage [--workspace <name>]
+
+Show workspace storage and monthly upload counters (and limits when set).
+
+Examples:
+  uploads --env-file .env usage
+  uploads usage --json
+`;
+export async function runUsage(ctx, args, help = false) {
+    if (help || parseCommandArgs(args).help) {
+        process.stderr.write(USAGE_HELP);
+        return 0;
+    }
+    const result = await ctx.client.usage();
+    if (ctx.json) {
+        await writeJson(result);
+        return 0;
+    }
+    const lines = [
+        `workspace: ${result.workspace}`,
+        `bytes:     ${result.bytes}${result.maxStorageBytes != null ? ` / ${result.maxStorageBytes} (${result.storageRemainingBytes} remaining)` : ""}`,
+        `objects:   ${result.objects}`,
+        `uploads:   ${result.uploadsInPeriod} this period (${result.periodStart})${result.maxUploadsPerPeriod != null ? ` / ${result.maxUploadsPerPeriod} (${result.uploadsRemaining} remaining)` : ""}`,
+        `updated:   ${result.updatedAt}`,
+    ];
+    await writeStdout(lines.join("\n") + "\n");
+    return 0;
+}
+const RECONCILE_HELP = `uploads reconcile [--workspace <name>]
+
+Rebuild ledger bytes/objects from storage (source of truth). Preserves the
+monthly upload counter. Requires files:write.
+
+Examples:
+  uploads --env-file .env reconcile
+`;
+export async function runReconcile(ctx, args, help = false) {
+    if (help || parseCommandArgs(args).help) {
+        process.stderr.write(RECONCILE_HELP);
+        return 0;
+    }
+    const result = await ctx.client.reconcile();
+    if (ctx.json) {
+        await writeJson(result);
+        return 0;
+    }
+    await writeStdout(result.changed
+        ? `reconciled ${result.workspace}: ${result.previous.bytes}→${result.bytes} bytes, ${result.previous.objects}→${result.objects} objects\n`
+        : `reconciled ${result.workspace}: unchanged (${result.bytes} bytes, ${result.objects} objects)\n`);
+    return 0;
+}
+const PURGE_HELP = `uploads purge-expired [--workspace <name>]
+
+Delete objects older than the workspace retentionDays setting, then reconcile.
+Skips if retention is unset. Requires files:delete.
+
+Examples:
+  uploads --env-file .env purge-expired
+`;
+export async function runPurgeExpired(ctx, args, help = false) {
+    if (help || parseCommandArgs(args).help) {
+        process.stderr.write(PURGE_HELP);
+        return 0;
+    }
+    const result = await ctx.client.purgeExpired();
+    if (ctx.json) {
+        await writeJson(result);
+        return 0;
+    }
+    if ("skipped" in result) {
+        await writeStdout(`skipped: ${result.reason}\n`);
+        return 0;
+    }
+    await writeStdout(`purged ${result.deleted} object(s), freed ${result.freedBytes} bytes (retention ${result.retentionDays}d)\n`);
+    return 0;
+}
 // --- health & doctor ---
 const HEALTH_HELP = `uploads health
 
@@ -391,23 +623,20 @@ Examples:
   uploads --env-file .env doctor
   uploads --workspace acme --env-file .env doctor
 `;
-export async function runDoctor(ctx, args, help = false) {
-    if (help || parseCommandArgs(args).help) {
-        process.stderr.write(DOCTOR_HELP);
-        return 0;
-    }
-    const mismatch = workspaceMismatch(ctx.config);
+/** Doctor's health + auth + workspace checks, shared by the CLI and the MCP tool. */
+export async function buildDoctorReport(config, client) {
+    const mismatch = workspaceMismatch(config);
     const hints = [];
     if (mismatch)
         hints.push(mismatch);
-    if (ctx.config.apiUrl.includes("localhost") || ctx.config.apiUrl.includes("127.0.0.1")) {
+    if (config.apiUrl.includes("localhost") || config.apiUrl.includes("127.0.0.1")) {
         hints.push("local API uses dev KV — prod tokens won't work unless minted with --local");
     }
-    const health = await ctx.client.health();
+    const health = await client.health();
     let authOk = false;
     let authError;
     try {
-        await ctx.client.list({ limit: 1 });
+        await client.list({ limit: 1 });
         authOk = true;
     }
     catch (err) {
@@ -416,35 +645,67 @@ export async function runDoctor(ctx, args, help = false) {
             hints.push("if this token works on api.uploads.sh, set UPLOADS_API_URL=https://api.uploads.sh");
         }
     }
-    if (!ctx.config.configExists && !ctx.config.token) {
-        hints.push(`run uploads setup to configure ${ctx.config.configPath}`);
+    let usage;
+    if (authOk) {
+        try {
+            const snap = await client.usage();
+            usage = {
+                ok: true,
+                bytes: snap.bytes,
+                objects: snap.objects,
+                uploadsInPeriod: snap.uploadsInPeriod,
+            };
+        }
+        catch (err) {
+            usage = {
+                ok: false,
+                error: err instanceof UploadsError ? err.message : String(err),
+            };
+        }
+    }
+    if (!config.configExists && !config.token) {
+        hints.push(`run uploads setup to configure ${config.configPath}`);
     }
-    const report = {
+    return {
         ok: health.ok && authOk,
-        apiUrl: ctx.config.apiUrl,
-        workspace: ctx.config.workspace,
-        workspaceSource: ctx.config.workspaceSource,
-        workspaceFromToken: workspaceFromToken(ctx.config.token),
-        configPath: ctx.config.configPath,
-        configExists: ctx.config.configExists,
+        apiUrl: config.apiUrl,
+        workspace: config.workspace,
+        workspaceSource: config.workspaceSource,
+        workspaceFromToken: workspaceFromToken(config.token),
+        configPath: config.configPath,
+        configExists: config.configExists,
         health,
         auth: { ok: authOk, error: authError },
+        usage,
+        warning: mismatch,
         hints,
     };
+}
+export async function runDoctor(ctx, args, help = false) {
+    if (help || parseCommandArgs(args).help) {
+        process.stderr.write(DOCTOR_HELP);
+        return 0;
+    }
+    const report = await buildDoctorReport(ctx.config, ctx.client);
     if (ctx.json) {
         await writeJson(report);
         return report.ok ? 0 : 1;
     }
     const lines = [
-        `config:    ${ctx.config.configPath}${ctx.config.configExists ? "" : " (missing)"}`,
-        `api:       ${ctx.config.apiUrl} (${health.ok ? "ok" : "failed"})`,
-        `workspace: ${ctx.config.workspace}`,
-        `auth:      ${authOk ? "ok" : `failed — ${authError ?? "no token"}`}`,
+        `config:    ${report.configPath}${report.configExists ? "" : " (missing)"}`,
+        `api:       ${report.apiUrl} (${report.health.ok ? "ok" : "failed"})`,
+        `workspace: ${report.workspace}`,
+        `auth:      ${report.auth.ok ? "ok" : `failed — ${report.auth.error ?? "no token"}`}`,
     ];
-    if (mismatch)
-        lines.push(`warning:   ${mismatch}`);
-    for (const h of hints)
-        if (h !== mismatch)
+    if (report.usage) {
+        lines.push(report.usage.ok
+            ? `usage:     ${report.usage.bytes} bytes, ${report.usage.objects} objects, ${report.usage.uploadsInPeriod} uploads this period`
+            : `usage:     failed — ${report.usage.error ?? "unknown"}`);
+    }
+    if (report.warning)
+        lines.push(`warning:   ${report.warning}`);
+    for (const h of report.hints)
+        if (h !== report.warning)
             lines.push(`hint:      ${h}`);
     await writeStdout(lines.join("\n") + "\n");
     return report.ok ? 0 : 1;

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"];
+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"];
 export type UploadsConfigKey = (typeof UPLOADS_CONFIG_KEYS)[number];
 export type UploadsConfigValues = Partial<Record<UploadsConfigKey, string>>;
 export interface PutDefaults {
@@ -8,6 +8,10 @@ export interface PutDefaults {
     ref?: string;
     width?: number;
     noGit?: boolean;
+    /** When true, put/attach skip client-side image optimization. */
+    noOptimize?: boolean;
+    /** When true, optimize keeps EXIF/XMP/ICC (default strips). */
+    keepExif?: boolean;
 }
 declare const PUT_DEFAULT_KEY_MAP: Record<keyof PutDefaults, UploadsConfigKey>;
 export declare function putDefaultsToConfigValues(defaults: PutDefaults): UploadsConfigValues;