lake-cimg 0.0.1

package/README.md

@@ -0,0 +1,138 @@
+# lake-cimg · `cimg`
+
+命令行批量压缩图片，默认输出 **WebP**；支持单文件、目录，以及递归子目录。基于 [sharp](https://sharp.pixelplumbing.com/)，可多任务并行处理。
+
+## 特性
+
+- 默认转为 WebP，可调质量；可选 `--no-webp` 保留原格式仅压缩
+- 可选按最长边缩放（`--size`），不指定则只做编码压缩、不改变像素尺寸
+- 目录批量处理；`-r` 递归子目录；配合 `-o` 时保持相对目录结构
+- 处理过程输出体积对比；失败时非零退出码
+
+## 环境要求
+
+- **Node.js** ≥ 18
+
+## 安装
+
+```bash
+# 全局安装后，任意目录可直接使用 cimg
+npm install -g lake-cimg
+```
+
+```bash
+# 在本项目目录内开发或本地使用时
+cd /path/to/cimg
+npm install
+node bin/cimg.js --help
+```
+
+通过 `npx` 单次运行（无需全局安装）：
+
+```bash
+npx lake-cimg <路径> [选项]
+```
+
+## 快速开始
+
+```bash
+# 查看帮助与版本
+cimg --help
+cimg --version
+
+# 压缩当前目录下支持的图片（见下文「行为说明」：未指定 -o 时会替换源文件）
+cimg .
+
+# 输出到单独目录，并限制最长边 1200px
+cimg ./photos -o ./dist -s 1200
+
+# 递归子目录，质量 80
+cimg ./assets -r -q 80
+```
+
+使用本地 `npm run` 时，**必须在参数前加 `--`**，否则 npm 会吞掉 `--size` 等选项：
+
+```bash
+npm run compress -- ./photo.png --size 100
+```
+
+## 命令说明
+
+### 用法
+
+```text
+cimg [options] [input]
+```
+
+`input` 为**文件或文件夹**路径（相对当前工作目录或绝对路径均可）。未传 `input` 或为空时会打印帮助并以状态码 `1` 退出。
+
+### 选项
+
+| 选项 | 说明 |
+| --- | --- |
+| `-o, --out-dir <dir>` | 输出根目录。指定后**不删除**源文件，结果写入该目录 |
+| `-s, --size <px>` | 最长边像素上限（可选）。不指定则**不缩放**，仅压缩/转码 |
+| `-q, --quality <1-100>` | WebP 质量，默认 `75` |
+| `--no-webp` | 不转为 WebP，在原格式下压缩（jpeg/png/webp/gif 等） |
+| `-r, --recursive` | 输入为目录时，递归处理子目录 |
+| `-h, --help` | 显示帮助 |
+| `-V, --version` | 显示版本 |
+
+### 行为说明
+
+**未指定 `-o` 时**：在源文件所在目录生成 `.webp`（或 `--no-webp` 时覆盖原格式文件），并**删除原始图片**。批量处理前请确认已备份或使用 `-o` 写到单独目录。
+
+**指定 `-o` 且使用 `-r`**：会按源目录的相对路径在输出目录下重建子文件夹，避免不同子目录中的同名文件互相覆盖。
+
+**并发**：按 CPU 核心数限制并行任务数，大目录下可显著快于单线程。
+
+## 支持格式
+
+输入：**jpg / jpeg、png、webp、gif**（gif 含动图，处理时由 sharp 按能力读写）。
+
+输出：默认 **WebP**；`--no-webp` 时尽量保持原容器格式并压缩。
+
+## 退出码
+
+| 码 | 含义 |
+| --- | --- |
+| `0` | 全部成功，或没有可处理文件（目录下无匹配图片时也会以 `0` 退出并提示） |
+| `1` | 存在处理失败、参数非法、输入路径不存在等错误 |
+
+## 在代码中调用
+
+包入口为 `lib/compress.js`（ESM），可导入例如：
+
+- `run(options)` — 批量入口（与 CLI 行为一致）
+- `processOne(inputPath, options)` — 单文件
+- `collectFiles(inputPath, recursive)` — 枚举待处理路径
+
+适合在构建脚本或 Node 服务中复用同一套逻辑。
+
+## 常见问题
+
+- **写权限**：`-o` 指向的目录需可创建/写入；否则 sharp 或 `fs` 会报错。
+- **路径**：Windows 与 Unix 路径均可；建议对含空格的路径加引号。
+- **质量范围**：`--quality` 须为 **1–100** 的整数；`--size` 若提供则须为 **正整数**。
+
+## 发布到 npm（维护者）
+
+仓库通过 [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml) 在发布 GitHub Release 或手动触发 workflow 时执行 `npm publish --provenance`。
+
+### 本地自检（可选）
+
+在项目根目录执行：
+
+```bash
+npm pkg fix
+```
+
+会按 npm 建议整理 `package.json`（例如 `repository` 等字段格式）。执行后用 `git diff` 查看变更，确认无误再提交。
+
+### GitHub Actions Secrets
+
+在 GitHub 仓库 **Settings → Secrets and variables → Actions** 中配置 **`NPM_TOKEN`**：使用 [npm](https://www.npmjs.com/) 帐号的 **Automation** 类型 token（或具备发布权限的 token），与 workflow 里 `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` 对应。未配置或 token 无效时，发布步骤会在认证阶段失败。
+
+## 依赖说明
+
+核心库：[sharp](https://sharp.pixelplumbing.com/)、[commander](https://github.com/tj/commander.js)。项目自身许可证以仓库根目录声明为准（若有）。

package/bin/cimg.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * CLI entry: parse args with Commander, validate, then run lib/compress.run().
+ */
+import { readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { program } from "commander";
+import { run } from "../lib/compress.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(join(__dirname, "..", "package.json"), "utf8")
+);
+
+/**
+ * @param {{ quality: number, size?: number | null }} opts
+ * @returns {{ ok: true } | { ok: false, message: string }}
+ */
+function validateCliOptions(opts) {
+  const { quality, size } = opts;
+  if (Number.isNaN(quality) || quality < 1 || quality > 100) {
+    return { ok: false, message: "错误: --quality 须为 1–100 的整数" };
+  }
+  if (size != null && (Number.isNaN(size) || size < 1)) {
+    return { ok: false, message: "错误: --size 须为正整数" };
+  }
+  return { ok: true };
+}
+
+/** Resolve a user path relative to cwd. */
+function resolveUserPath(relativeOrAbsolute) {
+  return resolve(process.cwd(), relativeOrAbsolute.trim());
+}
+
+program
+  .name("cimg")
+  .description("批量压缩图片为 WebP，支持单文件或文件夹")
+  .version(pkg.version)
+  .argument("[input]", "文件或文件夹路径")
+  .option("-o, --out-dir <dir>", "输出目录（不指定则直接修改源文件：同目录生成 .webp 后删除原图）")
+  .option("-s, --size <px>", "最大边长（可选，不指定则只压缩不缩放）", (v) => parseInt(v, 10))
+  .option("-q, --quality <1-100>", "WebP 质量", (v) => parseInt(v, 10), 75)
+  .option("--no-webp", "不转为 WebP，保留原格式仅压缩（默认会转为 WebP）")
+  .option("-r, --recursive", "递归处理子目录")
+  .action(async (input, opts) => {
+    if (!input || input.trim() === "") {
+      program.outputHelp();
+      process.exit(1);
+    }
+    const validation = validateCliOptions({
+      quality: opts.quality,
+      size: opts.size,
+    });
+    if (!validation.ok) {
+      console.error(validation.message);
+      process.exit(1);
+    }
+    const inputPath = resolveUserPath(input);
+    const outDir = opts.outDir ? resolveUserPath(opts.outDir) : null;
+    try {
+      const { failed } = await run({
+        inputPath,
+        outDir,
+        size: opts.size ?? null,
+        quality: opts.quality,
+        toWebp: opts.webp !== false,
+        recursive: !!opts.recursive,
+      });
+      process.exit(failed > 0 ? 1 : 0);
+    } catch (err) {
+      console.error("错误:", err.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/lib/compress.js

@@ -0,0 +1,234 @@
+/**
+ * Core compression logic: collect files, process one, run batch.
+ * No process.argv dependency — suitable for programmatic use and tests.
+ */
+import { readdir, readFile, writeFile, mkdir, stat } from "fs/promises";
+import { join, extname, dirname, resolve, basename, relative } from "path";
+import { cpus } from "os";
+import sharp from "sharp";
+import {
+  SUPPORTED_EXT,
+  DEFAULT_QUALITY,
+  DEFAULT_EFFORT,
+  supportedFormatsLabel,
+} from "./constants.js";
+
+/** Max concurrent tasks for processing images */
+const MAX_CONCURRENCY = Math.max(1, cpus().length);
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+function formatCompare(before, after) {
+  const saved = before - after;
+  const pct = before > 0 ? ((saved / before) * 100).toFixed(1) : "0";
+  return `${formatSize(before)} → ${formatSize(after)}（节省 ${pct}%）`;
+}
+
+/**
+ * Run tasks with a maximum concurrency limit.
+ * @param {Array<() => Promise<any>>} tasks
+ * @param {number} concurrency
+ * @returns {Promise<{status: string, value?: any, reason?: any}[]>}
+ */
+async function runWithConcurrency(tasks, concurrency) {
+  const results = new Array(tasks.length);
+  let currentIndex = 0;
+
+  async function worker() {
+    while (currentIndex < tasks.length) {
+      const index = currentIndex++;
+      try {
+        const val = await tasks[index]();
+        results[index] = { status: "fulfilled", value: val };
+      } catch (err) {
+        results[index] = { status: "rejected", reason: err };
+      }
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, worker);
+  await Promise.all(workers);
+  return results;
+}
+
+function isSupported(filePath) {
+  return SUPPORTED_EXT.includes(extname(filePath).toLowerCase());
+}
+
+/**
+ * Encode pipeline to WebP buffer with shared sharp options.
+ * @param {import("sharp").Sharp} pipeline
+ * @param {number} quality
+ * @param {{ lossless?: boolean }} [options]
+ */
+async function encodeWebpBuffer(pipeline, quality, { lossless = false } = {}) {
+  return pipeline
+    .webp({
+      quality,
+      effort: DEFAULT_EFFORT,
+      smartSubsample: true,
+      lossless,
+    })
+    .toBuffer();
+}
+
+/**
+ * Recursively collect image paths under dir (or return [dir] if dir is a file).
+ * @param {string} inputPath - Absolute path to file or directory
+ * @param {boolean} recursive - Whether to recurse into subdirectories
+ * @returns {Promise<string[]>} Absolute paths to supported image files
+ */
+export async function collectFiles(inputPath, recursive = false) {
+  const s = await stat(inputPath);
+  if (s.isFile()) {
+    if (!isSupported(inputPath)) return [];
+    return [resolve(inputPath)];
+  }
+  if (s.isDirectory()) {
+    const names = await readdir(inputPath, { withFileTypes: true });
+    const promises = names.map(async (ent) => {
+      const full = join(inputPath, ent.name);
+      if (ent.isDirectory() && recursive) {
+        return collectFiles(full, true);
+      } else if (ent.isFile() && isSupported(ent.name)) {
+        return [resolve(full)];
+      }
+      return [];
+    });
+    const subArrays = await Promise.all(promises);
+    return subArrays.flat();
+  }
+  return [];
+}
+
+/**
+ * Compress one image. Output WebP by default, or keep original format when toWebp is false.
+ * @param {string} inputPath - Absolute path to input image
+ * @param {{ outDir?: string | null, size?: number | null, quality?: number, toWebp?: boolean }} options
+ * @returns {Promise<{ outPath: string, sizeBefore: number, sizeAfter: number }>}
+ */
+export async function processOne(inputPath, options = {}) {
+  const { outDir, size, quality = DEFAULT_QUALITY, toWebp = true } = options;
+  const baseDir = dirname(inputPath);
+  const extRaw = extname(inputPath);
+  const ext = extRaw.toLowerCase();
+  const baseName = basename(inputPath, extRaw);
+  const outBase = outDir ? resolve(outDir) : baseDir;
+  const outExt = toWebp ? ".webp" : ext;
+  const outPath = join(outBase, `${baseName}${outExt}`);
+
+  const inputBuffer = await readFile(inputPath);
+  const sizeBefore = inputBuffer.length;
+  let pipeline = sharp(inputBuffer, { animated: true });
+
+  if (size != null && size > 0) {
+    pipeline = pipeline.resize({
+      width: size,
+      height: size,
+      fit: "inside",
+      withoutEnlargement: true,
+      background: { r: 0, g: 0, b: 0, alpha: 0 },
+    });
+  }
+
+  const outputBuffer = toWebp
+    ? await encodeWebpBuffer(pipeline, quality, { lossless: false })
+    : await toFormatBuffer(pipeline, ext, quality);
+
+  const sizeAfter = outputBuffer.length;
+  await mkdir(outBase, { recursive: true });
+  await writeFile(outPath, outputBuffer);
+  return { outPath, sizeBefore, sizeAfter };
+}
+
+/**
+ * Encode to original format (jpeg/png/webp/gif) for --no-webp.
+ */
+async function toFormatBuffer(pipeline, ext, quality) {
+  switch (ext) {
+    case ".jpg":
+    case ".jpeg":
+      return pipeline.jpeg({ quality, mozjpeg: true }).toBuffer();
+    case ".png":
+      return pipeline.png({ compressionLevel: 9 }).toBuffer();
+    case ".webp":
+      return encodeWebpBuffer(pipeline, quality);
+    case ".gif":
+      return pipeline.gif().toBuffer();
+    default:
+      return encodeWebpBuffer(pipeline, quality);
+  }
+}
+
+/**
+ * Run batch compression.
+ * @param {{ inputPath: string, outDir?: string | null, size?: number | null, quality?: number, recursive?: boolean }} options
+ * @returns {Promise<{ success: number, failed: number }>} success/failed counts; throws if input invalid
+ */
+export async function run(options) {
+  const {
+    inputPath,
+    outDir,
+    size,
+    quality,
+    toWebp = true,
+    recursive = false,
+  } = options;
+  const absoluteInput = resolve(inputPath);
+
+  let inputStat;
+  try {
+    inputStat = await stat(absoluteInput);
+  } catch {
+    throw new Error(`输入路径不存在: ${absoluteInput}`);
+  }
+  const baseDir = inputStat.isDirectory() ? absoluteInput : dirname(absoluteInput);
+
+  const files = await collectFiles(absoluteInput, recursive);
+  if (files.length === 0) {
+    console.log(`未找到支持的图片文件（支持: ${supportedFormatsLabel()}）`);
+    return { success: 0, failed: 0 };
+  }
+
+  console.log(`\n共 ${files.length} 个文件，开始压缩…\n`);
+
+  const tasks = files.map((fp) => async () => {
+    let targetOutDir = outDir;
+    if (outDir && recursive) {
+      const relPath = relative(baseDir, dirname(fp));
+      targetOutDir = join(outDir, relPath);
+    }
+    return processOne(fp, { outDir: targetOutDir, size, quality, toWebp });
+  });
+
+  const results = await runWithConcurrency(tasks, MAX_CONCURRENCY);
+
+  let success = 0;
+  let failed = 0;
+  let totalBefore = 0;
+  let totalAfter = 0;
+  for (let i = 0; i < files.length; i++) {
+    const r = results[i];
+    const fp = files[i];
+    if (r.status === "fulfilled") {
+      const { outPath, sizeBefore, sizeAfter } = r.value;
+      totalBefore += sizeBefore;
+      totalAfter += sizeAfter;
+      console.log(`  ✅ ${fp} → ${basename(outPath)}`);
+      console.log(`     ${formatCompare(sizeBefore, sizeAfter)}`);
+      success++;
+    } else {
+      console.error(`  ❌ ${fp}: ${r.reason?.message ?? r.reason}`);
+      failed++;
+    }
+  }
+  console.log(`\n完成：成功 ${success}，失败 ${failed}。`);
+  if (success > 0 && totalBefore > 0) {
+    console.log(`合计：${formatCompare(totalBefore, totalAfter)}`);
+  }
+  return { success, failed };
+}

package/lib/constants.js

@@ -0,0 +1,13 @@
+/** Supported image extensions for compression */
+export const SUPPORTED_EXT = [".jpg", ".jpeg", ".png", ".webp", ".gif"];
+
+/** Default WebP quality (1–100) */
+export const DEFAULT_QUALITY = 75;
+
+/** Sharp WebP effort (0–6), 6 = smallest size */
+export const DEFAULT_EFFORT = 6;
+
+/** Human-readable list for messages (e.g. "jpg, jpeg, png, webp, gif") */
+export function supportedFormatsLabel() {
+  return SUPPORTED_EXT.map((e) => e.slice(1)).join(", ");
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "lake-cimg",
+  "version": "0.0.1",
+  "description": "Batch image compression to WebP — single file or folder",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lake0090/lake-cimg.git"
+  },
+  "type": "module",
+  "main": "lib/compress.js",
+  "bin": {
+    "cimg": "bin/cimg.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "compress": "node bin/cimg.js",
+    "start": "node bin/cimg.js"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "sharp": "^0.33.0"
+  }
+}