picture-tiny-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jouryjc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# picture-tiny-cli (`ptiny`)
+
+在 agent 中可靠调用的图片压缩 CLI：压到目标文件体积和/或像素尺寸，最小程度影响画质，stdout 始终输出纯 JSON。
+
+> **运行时要求：bun。** `ptiny` 以 bun 执行 TypeScript 源码（依赖原生 `sharp`）。请先安装 [bun](https://bun.sh)。
+
+## 安装 / 使用
+
+```bash
+# 免安装直接用（推荐）
+bunx picture-tiny-cli photo.jpg --max-size 500kb
+
+# 或全局安装后用 ptiny（PATH 上需有 bun）
+bun add -g picture-tiny-cli      # 或 npm i -g picture-tiny-cli
+ptiny photo.jpg --max-size 500kb
+```
+
+## 用法
+
+```bash
+# 压到 500KB 以内，保留原格式
+ptiny photo.jpg --max-size 500kb
+
+# 限制最长边 1600px 并转 webp，输出到目录
+ptiny ./imgs/*.png --max-side 1600 --format webp --out-dir ./out
+
+# 同时限定体积与尺寸
+ptiny photo.jpg --max-size 300kb --max-side 1920
+```
+
+> 从源码运行：`bun install` 后 `bun bin/ptiny …`。
+
+## 选项
+
+见 `bun bin/ptiny --help`。
+
+## 输出（JSON）
+
+```json
+{
+  "ok": true,
+  "summary": { "count": 1, "ok": 1, "failed": 0, "savedPercent": 64.0 },
+  "results": [
+    { "input": "photo.jpg", "output": "photo.min.jpg", "ok": true,
+      "outputBytes": 180000, "quality": 78, "reachedTarget": true, "warnings": [] }
+  ],
+  "errors": []
+}
+```
+
+退出码：全成功 `0`，部分失败 `1`，用法错误 `2`。
+
+## 库用法
+
+```ts
+import { compressImage } from "picture-tiny-cli";
+const out = await compressImage(buffer, { maxSize: 200 * 1024, maxSide: 1600 });
+```

package/bin/ptiny

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+import { main } from "../src/cli";
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    process.stdout.write(JSON.stringify({ ok: false, error: (err as Error).message }) + "\n");
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "picture-tiny-cli",
+  "version": "0.1.0",
+  "description": "Compress images to a target file size and/or pixel dimensions with minimal quality loss — JPEG/PNG/WebP/AVIF, pure-JSON output for agents. Requires the bun runtime.",
+  "type": "module",
+  "bin": {
+    "ptiny": "bin/ptiny"
+  },
+  "module": "src/index.ts",
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "image",
+    "compression",
+    "compress",
+    "optimize",
+    "resize",
+    "sharp",
+    "webp",
+    "avif",
+    "jpeg",
+    "png",
+    "cli",
+    "bun",
+    "agent"
+  ],
+  "license": "MIT",
+  "author": "jouryjc",
+  "scripts": {
+    "test": "bun test",
+    "ptiny": "bun bin/ptiny"
+  },
+  "dependencies": {
+    "sharp": "^0.34.5"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14"
+  }
+}

package/src/args.ts

@@ -0,0 +1,136 @@
+import { parseArgs } from "node:util";
+import { parseSize } from "./size";
+import { normalizeFormat, type TargetFormat } from "./format";
+
+export class UsageError extends Error {}
+
+export interface Options {
+  inputs: string[];
+  maxSize?: number;
+  width?: number;
+  height?: number;
+  maxSide?: number;
+  quality?: number;
+  format?: TargetFormat;
+  output?: string;
+  outDir?: string;
+  suffix: string;
+  inPlace: boolean;
+  recursive: boolean;
+  background: string;
+  minQuality: number;
+  concurrency?: number;
+  dryRun: boolean;
+  help: boolean;
+  version: boolean;
+}
+
+function parseIntStrict(raw: string, name: string): number {
+  if (!/^\d+$/.test(raw.trim())) throw new UsageError(`--${name} must be a positive integer`);
+  const n = parseInt(raw, 10);
+  if (n < 1) throw new UsageError(`--${name} must be a positive integer`);
+  return n;
+}
+
+function parseQuality(raw: string, name: string): number {
+  const q = parseIntStrict(raw, name);
+  if (q > 100) throw new UsageError(`--${name} must be 1-100`);
+  return q;
+}
+
+export function parseCliArgs(argv: string[]): Options {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        "max-size": { type: "string" },
+        width: { type: "string" },
+        height: { type: "string" },
+        "max-side": { type: "string" },
+        quality: { type: "string" },
+        format: { type: "string" },
+        output: { type: "string" },
+        "out-dir": { type: "string" },
+        suffix: { type: "string" },
+        "in-place": { type: "boolean", default: false },
+        recursive: { type: "boolean", default: false },
+        background: { type: "string" },
+        "min-quality": { type: "string" },
+        concurrency: { type: "string" },
+        "dry-run": { type: "boolean", default: false },
+        help: { type: "boolean", default: false },
+        version: { type: "boolean", default: false },
+      },
+    });
+  } catch (err) {
+    throw new UsageError((err as Error).message);
+  }
+
+  const v = parsed.values;
+  const opts: Options = {
+    inputs: parsed.positionals,
+    suffix: v.suffix ?? ".min",
+    inPlace: v["in-place"] ?? false,
+    recursive: v.recursive ?? false,
+    background: v.background ?? "#ffffff",
+    minQuality: v["min-quality"] != null ? parseQuality(v["min-quality"], "min-quality") : 1,
+    dryRun: v["dry-run"] ?? false,
+    help: v.help ?? false,
+    version: v.version ?? false,
+  };
+
+  if (v["max-size"] != null) {
+    try {
+      opts.maxSize = parseSize(v["max-size"]);
+    } catch (err) {
+      throw new UsageError((err as Error).message);
+    }
+  }
+  if (v.width != null) opts.width = parseIntStrict(v.width, "width");
+  if (v.height != null) opts.height = parseIntStrict(v.height, "height");
+  if (v["max-side"] != null) opts.maxSide = parseIntStrict(v["max-side"], "max-side");
+  if (v.quality != null) opts.quality = parseQuality(v.quality, "quality");
+  if (v.format != null) {
+    try {
+      opts.format = normalizeFormat(v.format);
+    } catch (err) {
+      throw new UsageError((err as Error).message);
+    }
+  }
+  if (v.output != null) opts.output = v.output;
+  if (v["out-dir"] != null) opts.outDir = v["out-dir"];
+  if (v.concurrency != null) opts.concurrency = parseIntStrict(v.concurrency, "concurrency");
+
+  if (opts.help || opts.version) return opts;
+
+  validate(opts);
+  return opts;
+}
+
+function validate(opts: Options): void {
+  if (opts.inputs.length === 0) throw new UsageError("no input files given");
+  const hasConstraint =
+    opts.maxSize != null ||
+    opts.width != null ||
+    opts.height != null ||
+    opts.maxSide != null ||
+    opts.quality != null;
+  if (!hasConstraint) {
+    throw new UsageError(
+      "at least one of --max-size, --width, --height, --max-side, --quality is required",
+    );
+  }
+  if (opts.output != null && opts.inputs.length > 1) {
+    throw new UsageError("--output cannot be used with multiple inputs; use --out-dir");
+  }
+  if (opts.inPlace && (opts.output != null || opts.outDir != null)) {
+    throw new UsageError("--in-place cannot be combined with --output or --out-dir");
+  }
+  if (opts.inPlace && opts.format != null) {
+    throw new UsageError(
+      "--in-place cannot be combined with --format (it would change the extension and orphan the original); use --out-dir or --output",
+    );
+  }
+}

package/src/cli.ts

@@ -0,0 +1,105 @@
+import { parseCliArgs, UsageError } from "./args";
+import { expandInputs } from "./inputs";
+import { processAll, type FileResult } from "./run";
+
+const VERSION = "0.1.0";
+
+const HELP = `ptiny - compress images to a target file size and/or pixel size
+
+Usage: ptiny [options] <input...>
+
+Targets (at least one required):
+  --max-size <500kb|1.5mb|N>   target max file size
+  --width <px>                 target width
+  --height <px>                target height
+  --max-side <px>              cap the longest side
+  --quality <1-100>            fixed quality (skip size search)
+Format:
+  --format <jpeg|png|webp|avif>  convert format (default: keep original)
+Output:
+  --output <file>              output path (single input only)
+  --out-dir <dir>              output directory
+  --suffix <.min>              sibling suffix (default .min)
+  --in-place                   overwrite originals
+  --recursive                  recurse into directories
+Behavior:
+  --background <white>         flatten color for alpha->jpeg
+  --min-quality <n>            quality search floor (default 1)
+  --concurrency <n>            parallel workers (default cpu count)
+  --dry-run                    compute without writing
+  --help, --version`;
+
+function sum(ns: number[]): number {
+  return ns.reduce((a, b) => a + b, 0);
+}
+function round1(n: number): number {
+  return Math.round(n * 10) / 10;
+}
+
+function emit(payload: unknown): void {
+  process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+}
+
+/** CLI 主入口，返回退出码。stdout 始终为 JSON，日志走 stderr。 */
+export async function main(argv: string[]): Promise<number> {
+  let opts;
+  try {
+    opts = parseCliArgs(argv);
+  } catch (err) {
+    if (err instanceof UsageError) {
+      emit({ ok: false, error: err.message });
+      return 2;
+    }
+    throw err;
+  }
+
+  if (opts.help) {
+    emit({ ok: true, help: HELP });
+    return 0;
+  }
+  if (opts.version) {
+    emit({ ok: true, version: VERSION });
+    return 0;
+  }
+
+  let files: string[];
+  try {
+    files = await expandInputs(opts.inputs, opts.recursive);
+  } catch (err) {
+    emit({ ok: false, error: (err as Error).message });
+    return 2;
+  }
+  if (files.length === 0) {
+    emit({ ok: false, error: "no image files matched the given inputs" });
+    return 2;
+  }
+
+  const results = await processAll(files, opts);
+  const okResults = results.filter((r) => r.ok);
+  const errorResults = results.filter((r) => !r.ok);
+
+  const originalBytes = sum(okResults.map((r) => r.originalBytes ?? 0));
+  const outputBytes = sum(okResults.map((r) => r.outputBytes ?? 0));
+  const savedBytes = originalBytes - outputBytes;
+
+  const payload = {
+    ok: errorResults.length === 0,
+    summary: {
+      count: results.length,
+      ok: okResults.length,
+      failed: errorResults.length,
+      originalBytes,
+      outputBytes,
+      savedBytes,
+      savedPercent: originalBytes > 0 ? round1((savedBytes / originalBytes) * 100) : 0,
+    },
+    results: okResults,
+    errors: errorResults.map((r: FileResult) => ({
+      input: r.input,
+      ok: false,
+      error: r.error,
+    })),
+  };
+  emit(payload);
+  return errorResults.length === 0 ? 0 : 1;
+}

package/src/compress.ts

@@ -0,0 +1,189 @@
+import sharp from "sharp";
+import type { Sharp, ResizeOptions } from "sharp";
+import {
+  applyEncoder,
+  normalizeFormat,
+  DEFAULT_QUALITY,
+  LOSSY_FORMATS,
+  type TargetFormat,
+} from "./format";
+
+export interface CompressOptions {
+  maxSize?: number; // 目标最大字节数
+  width?: number;
+  height?: number;
+  maxSide?: number;
+  quality?: number; // 固定质量 1-100
+  format?: TargetFormat; // 显式目标格式
+  background?: string; // alpha→jpeg 压平底色
+  minQuality?: number; // 质量搜索下界，默认 1
+}
+
+export interface CompressResult {
+  buffer: Buffer;
+  format: TargetFormat;
+  originalFormat: string;
+  width: number;
+  height: number;
+  originalWidth: number;
+  originalHeight: number;
+  quality: number | null;
+  targetBytes: number | null;
+  reachedTarget: boolean;
+  iterations: number;
+  warnings: string[];
+}
+
+/** 多页（动图）保护：pages>1 抛错。 */
+export function assertStatic(pages: number | undefined): void {
+  if ((pages ?? 1) > 1) throw new Error("animated images are not supported in v1");
+}
+
+function clampQuality(q: number): number {
+  return Math.max(1, Math.min(100, Math.round(q)));
+}
+
+/** 计算 resize 选项；不放大时返回 null 并记录 warning。 */
+function planResize(
+  opts: CompressOptions,
+  ow: number,
+  oh: number,
+  warnings: string[],
+): ResizeOptions | null {
+  let width = opts.width;
+  let height = opts.height;
+  if (opts.maxSide != null) {
+    width = Math.min(width ?? opts.maxSide, opts.maxSide);
+    height = Math.min(height ?? opts.maxSide, opts.maxSide);
+  }
+  if (width == null && height == null) return null;
+  const fitsW = width == null || width >= ow;
+  const fitsH = height == null || height >= oh;
+  if (fitsW && fitsH) {
+    warnings.push("requested size is larger than or equal to original; not upscaling");
+    return null;
+  }
+  return { width, height, fit: "inside", withoutEnlargement: true };
+}
+
+/**
+ * 二分搜索质量：取 ≤target 的最高质量；都不满足时返回最小可得（best effort）。
+ */
+async function searchQuality(
+  encode: (q: number) => Promise<Buffer>,
+  targetBytes: number,
+  minQuality: number,
+): Promise<{ buffer: Buffer; quality: number; iterations: number; reached: boolean }> {
+  let lo = Math.max(1, Math.min(100, Math.round(minQuality)));
+  let hi = 100;
+  let iterations = 0;
+  let bestFit: { buffer: Buffer; quality: number } | null = null;
+  let smallest: { buffer: Buffer; quality: number; size: number } | null = null;
+
+  while (lo <= hi) {
+    const mid = Math.floor((lo + hi) / 2);
+    iterations++;
+    const buf = await encode(mid);
+    if (smallest == null || buf.length < smallest.size) {
+      smallest = { buffer: buf, quality: mid, size: buf.length };
+    }
+    if (buf.length <= targetBytes) {
+      if (bestFit == null || mid > bestFit.quality) bestFit = { buffer: buf, quality: mid };
+      lo = mid + 1; // 体积达标，尝试更高质量
+    } else {
+      hi = mid - 1; // 超标，降质量
+    }
+  }
+
+  if (bestFit) {
+    return { buffer: bestFit.buffer, quality: bestFit.quality, iterations, reached: true };
+  }
+  return { buffer: smallest!.buffer, quality: smallest!.quality, iterations, reached: false };
+}
+
+/** 压缩单张图片：先 resize，再按约束选择固定质量 / 二分搜索 / 尺寸-only 编码。 */
+export async function compressImage(
+  input: Buffer,
+  opts: CompressOptions,
+): Promise<CompressResult> {
+  const meta = await sharp(input, { failOn: "none" }).metadata();
+  assertStatic(meta.pages);
+
+  const originalFormat = meta.format ?? "unknown";
+  const originalWidth = meta.width ?? 0;
+  const originalHeight = meta.height ?? 0;
+  const hasAlpha = meta.hasAlpha ?? false;
+  const targetFormat: TargetFormat = opts.format ?? normalizeFormat(originalFormat);
+  const warnings: string[] = [];
+  const resize = planResize(opts, originalWidth, originalHeight, warnings);
+
+  function buildPipeline(): Sharp {
+    let p = sharp(input, { failOn: "none" });
+    if (resize) p = p.resize(resize);
+    if (targetFormat === "jpeg" && hasAlpha) {
+      p = p.flatten({ background: opts.background ?? "#ffffff" });
+    }
+    return p;
+  }
+
+  const encode = (quality: number | null): Promise<Buffer> =>
+    applyEncoder(buildPipeline(), targetFormat, quality).toBuffer();
+
+  const targetBytes = opts.maxSize ?? null;
+  let resultBuffer: Buffer;
+  let chosenQuality: number | null;
+  let iterations = 0;
+  let reachedTarget = true;
+
+  if (opts.quality != null) {
+    chosenQuality = clampQuality(opts.quality);
+    resultBuffer = await encode(chosenQuality);
+    if (targetBytes != null) {
+      reachedTarget = resultBuffer.length <= targetBytes;
+      if (!reachedTarget) {
+        warnings.push(
+          `fixed --quality ${chosenQuality} produced ${resultBuffer.length} bytes, ` +
+            `exceeding target ${targetBytes}; omit --quality to let size search pick a smaller quality`,
+        );
+      }
+    }
+  } else if (targetBytes != null) {
+    const search = await searchQuality(
+      (q) => encode(q),
+      targetBytes,
+      opts.minQuality ?? 1,
+    );
+    resultBuffer = search.buffer;
+    chosenQuality = search.quality;
+    iterations = search.iterations;
+    reachedTarget = search.reached;
+    if (!reachedTarget) {
+      warnings.push(
+        `could not reach target size; emitted best effort at quality ${chosenQuality}`,
+      );
+      if (targetFormat === "png") {
+        warnings.push("consider --format webp for better compression of this image");
+      }
+    }
+  } else {
+    // 仅尺寸约束：有损用默认质量，png 走无损（quality=null）
+    chosenQuality = LOSSY_FORMATS.has(targetFormat) ? DEFAULT_QUALITY : null;
+    resultBuffer = await encode(chosenQuality);
+  }
+
+  const outMeta = await sharp(resultBuffer, { failOn: "none" }).metadata();
+  return {
+    buffer: resultBuffer,
+    format: targetFormat,
+    originalFormat,
+    width: outMeta.width ?? originalWidth,
+    height: outMeta.height ?? originalHeight,
+    originalWidth,
+    originalHeight,
+    quality: chosenQuality,
+    targetBytes,
+    reachedTarget,
+    iterations,
+    warnings,
+  };
+}

package/src/format.ts

@@ -0,0 +1,40 @@
+import type { Sharp } from "sharp";
+
+export type TargetFormat = "jpeg" | "png" | "webp" | "avif";
+
+export const DEFAULT_QUALITY = 82;
+export const LOSSY_FORMATS = new Set<TargetFormat>(["jpeg", "webp", "avif"]);
+
+/** 把格式字符串归一化为受支持的目标格式，未知格式抛错。 */
+export function normalizeFormat(fmt: string): TargetFormat {
+  const f = fmt.toLowerCase();
+  if (f === "jpg" || f === "jpeg") return "jpeg";
+  if (f === "png") return "png";
+  if (f === "webp") return "webp";
+  if (f === "avif") return "avif";
+  throw new Error(`unsupported format: ${JSON.stringify(fmt)}`);
+}
+
+/**
+ * 给 sharp pipeline 应用目标格式编码器。
+ * - 有损格式：quality 为 null 时用 DEFAULT_QUALITY。
+ * - png：quality 为 null 走无损；为数字走调色板量化。
+ */
+export function applyEncoder(pipeline: Sharp, format: TargetFormat, quality: number | null): Sharp {
+  switch (format) {
+    case "jpeg":
+      return pipeline.jpeg({ quality: quality ?? DEFAULT_QUALITY, mozjpeg: true });
+    case "webp":
+      return pipeline.webp({ quality: quality ?? DEFAULT_QUALITY });
+    case "avif":
+      return pipeline.avif({ quality: quality ?? DEFAULT_QUALITY });
+    case "png":
+      return quality == null
+        ? pipeline.png({ compressionLevel: 9 })
+        : pipeline.png({ quality, palette: true, compressionLevel: 9 });
+    default: {
+      const never: never = format;
+      throw new Error(`unsupported format: ${never}`);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { compressImage, assertStatic } from "./compress";
+export type { CompressOptions, CompressResult } from "./compress";
+export { parseSize, formatBytes } from "./size";
+export { parseCliArgs, UsageError } from "./args";
+export type { Options } from "./args";
+export { main } from "./cli";

package/src/inputs.ts

@@ -0,0 +1,53 @@
+import { Glob } from "bun";
+import { stat, readdir } from "node:fs/promises";
+import { join, extname, resolve } from "node:path";
+
+const IMAGE_EXTS = new Set([".jpg", ".jpeg", ".png", ".webp", ".avif", ".gif", ".tiff", ".tif"]);
+
+function isGlob(s: string): boolean {
+  return /[*?[\]{}]/.test(s);
+}
+
+async function listDir(dir: string, recursive: boolean): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files: string[] = [];
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (recursive) files.push(...(await listDir(full, recursive)));
+    } else {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/** 把输入项（文件/目录/glob）展开为去重、排序后的图片路径列表。 */
+export async function expandInputs(inputs: string[], recursive: boolean): Promise<string[]> {
+  const out = new Set<string>();
+  for (const item of inputs) {
+    if (isGlob(item)) {
+      const glob = new Glob(item);
+      const cwd = process.cwd();
+      for await (const file of glob.scan({ onlyFiles: true, cwd })) {
+        const abs = resolve(cwd, file);
+        if (IMAGE_EXTS.has(extname(abs).toLowerCase())) out.add(abs);
+      }
+      continue;
+    }
+    let st;
+    try {
+      st = await stat(item);
+    } catch {
+      throw new Error(`input not found: ${item}`);
+    }
+    if (st.isDirectory()) {
+      for (const f of await listDir(item, recursive)) {
+        if (IMAGE_EXTS.has(extname(f).toLowerCase())) out.add(resolve(f));
+      }
+    } else {
+      if (IMAGE_EXTS.has(extname(item).toLowerCase())) out.add(resolve(item));
+    }
+  }
+  return [...out].sort();
+}

package/src/output.ts

@@ -0,0 +1,24 @@
+import { dirname, basename, extname, join } from "node:path";
+import type { Options } from "./args";
+import type { TargetFormat } from "./format";
+
+const FORMAT_EXT: Record<TargetFormat, string> = {
+  jpeg: ".jpg",
+  png: ".png",
+  webp: ".webp",
+  avif: ".avif",
+};
+
+function changeExt(p: string, ext: string): string {
+  return join(dirname(p), basename(p, extname(p)) + ext);
+}
+
+/** 依据选项与目标格式解析单个输入文件的输出路径。 */
+export function resolveOutputPath(input: string, format: TargetFormat, opts: Options): string {
+  const ext = FORMAT_EXT[format];
+  if (opts.output) return opts.output;
+  if (opts.inPlace) return changeExt(input, ext);
+  if (opts.outDir) return join(opts.outDir, basename(input, extname(input)) + ext);
+  const stem = basename(input, extname(input));
+  return join(dirname(input), `${stem}${opts.suffix}${ext}`);
+}

package/src/run.ts

@@ -0,0 +1,126 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { cpus } from "node:os";
+import { compressImage } from "./compress";
+import { resolveOutputPath } from "./output";
+import type { Options } from "./args";
+
+export interface FileResult {
+  input: string;
+  output?: string;
+  ok: boolean;
+  error?: string;
+  originalFormat?: string;
+  format?: string;
+  originalWidth?: number;
+  originalHeight?: number;
+  width?: number;
+  height?: number;
+  originalBytes?: number;
+  outputBytes?: number;
+  savedBytes?: number;
+  savedPercent?: number;
+  ratio?: number;
+  quality?: number | null;
+  targetBytes?: number | null;
+  reachedTarget?: boolean;
+  iterations?: number;
+  warnings?: string[];
+}
+
+function round1(n: number): number {
+  return Math.round(n * 10) / 10;
+}
+function round4(n: number): number {
+  return Math.round(n * 10000) / 10000;
+}
+
+/**
+ * 读取→压缩→写出单个文件，捕获错误为结果记录（不抛出）。
+ * `claimed` 跨文件共享，用于检测一次调用内多个输入写到同一输出路径的冲突。
+ */
+export async function processFile(
+  input: string,
+  opts: Options,
+  claimed: Set<string> = new Set(),
+): Promise<FileResult> {
+  try {
+    const buf = await readFile(input);
+    const result = await compressImage(buf, {
+      maxSize: opts.maxSize,
+      width: opts.width,
+      height: opts.height,
+      maxSide: opts.maxSide,
+      quality: opts.quality,
+      format: opts.format,
+      background: opts.background,
+      minQuality: opts.minQuality,
+    });
+    const output = resolveOutputPath(input, result.format, opts);
+    const resolvedOut = resolve(output);
+    // 绝不静默覆盖原图：输出落回输入自身且未显式 --in-place 时拒绝。
+    if (!opts.inPlace && resolvedOut === resolve(input)) {
+      return {
+        input,
+        ok: false,
+        error: `refusing to overwrite the original without --in-place: ${input}`,
+      };
+    }
+    // 同一次调用内多个输入写到同一输出路径会相互覆盖——报错而非静默丢失。
+    if (claimed.has(resolvedOut)) {
+      return {
+        input,
+        ok: false,
+        error: `output path collides with another input: ${output}`,
+      };
+    }
+    claimed.add(resolvedOut);
+    if (!opts.dryRun) {
+      await mkdir(dirname(output), { recursive: true });
+      await writeFile(output, result.buffer);
+    }
+    const originalBytes = buf.length;
+    const outputBytes = result.buffer.length;
+    return {
+      input,
+      output,
+      ok: true,
+      originalFormat: result.originalFormat,
+      format: result.format,
+      originalWidth: result.originalWidth,
+      originalHeight: result.originalHeight,
+      width: result.width,
+      height: result.height,
+      originalBytes,
+      outputBytes,
+      savedBytes: originalBytes - outputBytes,
+      savedPercent: round1((1 - outputBytes / originalBytes) * 100),
+      ratio: round4(outputBytes / originalBytes),
+      quality: result.quality,
+      targetBytes: result.targetBytes,
+      reachedTarget: result.reachedTarget,
+      iterations: result.iterations,
+      warnings: result.warnings,
+    };
+  } catch (err) {
+    return { input, ok: false, error: (err as Error).message };
+  }
+}
+
+/** 以受限并发处理一组文件，结果顺序与输入一致。 */
+export async function processAll(files: string[], opts: Options): Promise<FileResult[]> {
+  const concurrency = Math.max(1, opts.concurrency ?? cpus().length);
+  const results: FileResult[] = new Array(files.length);
+  const claimed = new Set<string>();
+  let next = 0;
+  async function worker(): Promise<void> {
+    while (true) {
+      const i = next++;
+      if (i >= files.length) break;
+      results[i] = await processFile(files[i]!, opts, claimed);
+    }
+  }
+  const workers = Array.from({ length: Math.min(concurrency, files.length) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}

package/src/size.ts

@@ -0,0 +1,37 @@
+const UNITS: Record<string, number> = {
+  "": 1,
+  b: 1,
+  k: 1024,
+  kb: 1024,
+  kib: 1024,
+  m: 1024 ** 2,
+  mb: 1024 ** 2,
+  mib: 1024 ** 2,
+  g: 1024 ** 3,
+  gb: 1024 ** 3,
+  gib: 1024 ** 3,
+};
+
+/** 解析人类可读体积为字节数。纯数字按字节，支持 b/kb/mb/gb（1KB=1024）。 */
+export function parseSize(input: string): number {
+  const m = String(input).trim().toLowerCase().match(/^(\d+(?:\.\d+)?)\s*([a-z]*)$/);
+  if (!m) throw new Error(`invalid size: ${JSON.stringify(input)}`);
+  const value = parseFloat(m[1]!);
+  const unit = m[2]!;
+  const mult = UNITS[unit];
+  if (mult == null) throw new Error(`invalid size unit: ${JSON.stringify(unit)}`);
+  return Math.round(value * mult);
+}
+
+/** 字节数格式化为人类可读字符串。 */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  const units = ["KB", "MB", "GB"];
+  let v = bytes / 1024;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v.toFixed(1)}${units[i]}`;
+}