create-ssnode-cli 0.2.5 → 0.2.7

package/templates/web/scripts/compress-src-images.cjs

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+/*
+ * web/src 存量图片批压缩(视觉无损,构建产物瘦身)
+ *
+ * 背景:src 内设计稿类 PNG 大量超展示需求(最大 12.7MB、多张 1-3MB 级),
+ * 上传链已有 compress-image.ts 压缩(2026-10-15)管不到 src 静态资源,本脚本补存量。
+ *
+ * 用法(在 web/ 下运行):
+ *   node scripts/compress-src-images.cjs              # 交互询问是否保留原图(默认保留)
+ *   node scripts/compress-src-images.cjs --dry-run    # 只算不写,预览前后大小
+ *   node scripts/compress-src-images.cjs --no-keep    # 免交互,不留原图备份
+ *   node scripts/compress-src-images.cjs --limit N    # 只处理前 N 张(渐进验证,计实际解码尝试)
+ *   node scripts/compress-src-images.cjs --dir <path> # 换扫描根(默认 src/;沙箱回归用)
+ *
+ * 前提:sharp 为 NATIVE 依赖,禁入 web 依赖(浏览器侧包),隔离安装(同 backend
+ * compress-column-images.cjs 先例):
+ *   npm i --prefix /tmp/compress-libs sharp
+ * 脚本按 node_modules → /tmp/compress-libs 顺序找,找不到打印装法退出。
+ *
+ * 压缩参数与 web/src/utils/compress-image.ts、backend/scripts/compress-column-images.cjs
+ * 同语义,勿单边改:长边钳制 3840 / EXIF 方向烘焙 + 元数据剥离 / WebP q0.92 /
+ * 只有更小(原 95% 以下)才替换。「无损」按仓库既有口径 = 视觉无损(严格数学无损
+ * 对设计稿类位图收益≈0,两条既有链同取舍);编码器是 sharp(本地批处理)非浏览器
+ * canvas——参数一致、观测级等价。
+ *
+ * 换名方案(引用代码零改动):
+ *   压缩结果(WebP 字节)落**原文件名**(BG.png 名不变,import / css url() 全不动;
+ *   <img>/css 背景按内容嗅探渲染,浏览器对图片不按扩展名强制 MIME);
+ *   原图改名 BG.png.orig 同目录保留(幂等标记 + 本机回退件,已 gitignore 勿入库)。
+ *
+ * 幂等 / 跳过规则(跳过只报告不动文件):
+ *   内容已是 WebP(RIFF..WEBP 魔数——不依赖 .orig 标记,--no-keep 模式重跑也安全)
+ *   / 陈旧 .orig 标记(.orig 在但主文件非 WebP,多为 git 还原后残留,提示人工确认)
+ *   / 非静态位图(gif 动图丢帧 / svg 非位图,扫描即过滤)/ 不超尺寸小图(≤300KB 且
+ *   长边 ≤3840)/ 压缩无收益(≥原图 95%)。
+ *
+ * 安全:
+ *   - 开跑交互询问是否保留原图,默认保留;回退单张 = mv xxx.png.orig xxx.png,
+ *     整批走 git checkout(原图入库过,git 历史即真备份);
+ *   - 写入走同目录 .new 临时文件 + 两步 rename(原图先改名、新图后顶上),崩溃不产
+ *     生半张图;开跑前先扫中断残留自修复(.orig 在主文件不在 = 接续换名或回滚原图,
+ *     .new 残留 = 清理陈旧临时件);
+ *   - 每张压缩结果落盘前重新解码校验尺寸一致(防截断/坏写)。
+ */
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const readline = require("node:readline");
+
+// ── 与 compress-image.ts / compress-column-images.cjs 对齐的常量(勿单边改)──
+const MAX_EDGE = 3840;
+const WEBP_QUALITY = 92;
+const SKIP_SIZE = 300 * 1024; // 不超尺寸的小图不重编码
+const ADOPT_RATIO = 0.95; // 压缩结果须小于原图此比例才替换
+const RASTER_RE = /\.(png|jpe?g|webp|bmp)$/i; // gif 动图 / svg 非位图,一律不动
+const ORIG_SUFFIX = ".orig"; // 原图备份后缀(幂等标记 + 回退件)
+const NEW_SUFFIX = ".new"; // 落盘临时后缀(同目录 rename 原子换名)
+const DEFAULT_SCAN_DIR = path.resolve(__dirname, "..", "src");
+
+// ── sharp 隔离加载(不入仓库)──
+function loadSharp() {
+	const candidates = [
+		"sharp", // 万一通过 node_modules 全局可达(如本机 pnpm 已装)
+		path.resolve("/tmp/compress-libs/node_modules/sharp"), // 隔离安装位(同 backend 批迁模式)
+	];
+	for (const candidate of candidates) {
+		try {
+			// eslint-disable-next-line global-require, import/no-dynamic-require
+			return require(candidate);
+		} catch {
+			// 找不到换下一个候选位
+		}
+	}
+	console.error(
+		"缺 sharp(NATIVE 依赖,禁止入 web package.json——浏览器侧包)。隔离安装:\n" +
+			"  npm i --prefix /tmp/compress-libs sharp",
+	);
+	process.exit(1);
+}
+
+/** 内容魔数是否已是 WebP('RIFF'....'WEBP')——幂等判据,不依赖文件名/备份标记 */
+function isWebP(buf) {
+	return (
+		buf.length > 12 &&
+		buf[0] === 0x52 &&
+		buf[1] === 0x49 &&
+		buf[2] === 0x46 &&
+		buf[3] === 0x46 && // RIFF
+		buf[8] === 0x57 &&
+		buf[9] === 0x45 &&
+		buf[10] === 0x42 &&
+		buf[11] === 0x50 // WEBP
+	);
+}
+
+/** 递归收集扫描树内全部文件(位图 / 备份残留 / 临时件分类在调用侧) */
+function walkFiles(dir, out = []) {
+	for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+		const p = path.join(dir, ent.name);
+		if (ent.isDirectory()) walkFiles(p, out);
+		else if (ent.isFile()) out.push(p);
+	}
+	return out;
+}
+
+/**
+ * 开跑前自修复上次中断残留(顺序敏感:先 .orig 后 .new):
+ *   .orig 在主文件不在:.new 在 = 压缩已落盘只差最后换名,接续完成;
+ *                       否则崩在「原图已改名、新图未顶上」,回滚原图。
+ *   .new 残留且主文件在:陈旧临时件,清掉。
+ */
+function repairInterrupted(allFiles) {
+	for (const f of allFiles.filter((x) => x.endsWith(ORIG_SUFFIX))) {
+		const main = f.slice(0, -ORIG_SUFFIX.length);
+		if (fs.existsSync(main)) continue; // 正常已压缩留备份态
+		const staged = main + NEW_SUFFIX;
+		if (fs.existsSync(staged)) {
+			fs.renameSync(staged, main);
+			console.log(`REPAIR 接续换名  ${path.basename(main)}`);
+		} else {
+			fs.renameSync(f, main);
+			console.log(`REPAIR 回滚原图  ${path.basename(main)}`);
+		}
+	}
+	for (const f of allFiles.filter((x) => x.endsWith(NEW_SUFFIX))) {
+		if (!fs.existsSync(f)) continue; // 上一轮修复已消费
+		const main = f.slice(0, -NEW_SUFFIX.length);
+		if (fs.existsSync(main) || fs.existsSync(main + ORIG_SUFFIX)) {
+			fs.unlinkSync(f);
+			console.log(`REPAIR 清理临时件 ${path.basename(f)}`);
+		} else {
+			console.log(
+				`WARN  孤立临时件 ${path.basename(f)}(主文件/备份均不在,人工确认后删)`,
+			);
+		}
+	}
+}
+
+/** 交互询问是否保留原图备份;回车/非 n 均视为保留(默认保留);非 TTY 默认保留 */
+function askKeepOriginal() {
+	return new Promise((resolve) => {
+		if (!process.stdin.isTTY || !process.stdout.isTTY) return resolve(true);
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+		rl.question("是否保留原图备份(同目录 *.orig)?[Y/n] ", (ans) => {
+			rl.close();
+			resolve(!/^\s*n(o)?\s*$/i.test(ans || ""));
+		});
+	});
+}
+
+const argv = process.argv.slice(2);
+const flag = (name) => argv.includes(`--${name}`);
+const opt = (name, def) => {
+	const i = argv.indexOf(`--${name}`);
+	return i >= 0 ? argv[i + 1] : def;
+};
+
+const dryRun = flag("dry-run");
+const limit = parseInt(opt("limit", "0"), 10) || 0;
+const scanDir = path.resolve(opt("dir", DEFAULT_SCAN_DIR));
+
+(async () => {
+	if (!fs.existsSync(scanDir)) {
+		console.error(`扫描目录不存在:${scanDir}`);
+		process.exit(1);
+	}
+	const sharp = loadSharp();
+
+	const allFiles = walkFiles(scanDir);
+	repairInterrupted(allFiles);
+	const images = allFiles.filter((f) => RASTER_RE.test(f));
+
+	let keepOrig = true;
+	if (!dryRun) {
+		if (flag("no-keep")) keepOrig = false;
+		else if (flag("keep")) keepOrig = true;
+		else keepOrig = await askKeepOriginal();
+		if (!process.stdin.isTTY || !process.stdout.isTTY) {
+			console.log(
+				"[src-compress] 非交互环境(非 TTY),按默认保留原图(免交互不留备份用 --no-keep)",
+			);
+		}
+	}
+
+	const rel = (f) => path.relative(scanDir, f);
+	const fmtKB = (n) => `${(n / 1024).toFixed(0)}KB`;
+	console.log(
+		`[src-compress] ${scanDir} 位图 ${images.length} 张  ${
+			dryRun ? "DRY-RUN" : keepOrig ? "保留原图(.orig)" : "不留原图"
+		}${limit ? ` limit=${limit}` : ""}`,
+	);
+
+	const stats = {
+		compressed: 0,
+		noGain: 0,
+		smallSkip: 0,
+		webpDone: 0,
+		staleMark: 0,
+		failed: 0,
+	};
+	let beforeTotal = 0;
+	let saved = 0;
+	let processed = 0;
+
+	for (const file of images) {
+		if (limit && processed >= limit) {
+			console.log(`[src-compress] --limit ${limit} 已处理满,停止(其余未动)`);
+			break;
+		}
+		try {
+			// ── 幂等跳过 ──
+			const buf = fs.readFileSync(file);
+			if (isWebP(buf)) {
+				stats.webpDone += 1;
+				console.log(`SKIP 已压缩      ${fmtKB(buf.length)} ${rel(file)}`);
+				continue;
+			}
+			if (fs.existsSync(file + ORIG_SUFFIX)) {
+				stats.staleMark += 1;
+				console.log(
+					`SKIP 陈旧标记    ${rel(
+						file,
+					)}(.orig 在但主文件非 WebP——git 还原后残留?确认后删 .orig 重跑)`,
+				);
+				continue;
+			}
+			processed += 1;
+
+			// ── 压缩(语义同 compress-image.ts)──
+			const meta = await sharp(buf).metadata();
+			const scale = Math.min(
+				1,
+				MAX_EDGE / Math.max(meta.width || 1, meta.height || 1),
+			);
+			if (scale === 1 && buf.length <= SKIP_SIZE) {
+				stats.smallSkip += 1;
+				console.log(`SKIP 小图        ${fmtKB(buf.length)} ${rel(file)}`);
+				continue;
+			}
+			const width = Math.max(1, Math.round((meta.width || 1) * scale));
+			const height = Math.max(1, Math.round((meta.height || 1) * scale));
+			// rotate() 无参 = 按 EXIF 方向摆正(等效 canvas 管线的 from-image),sharp 输出默认剥元数据
+			const webp = await sharp(buf)
+				.rotate()
+				.resize({
+					width,
+					height,
+					fit: "inside",
+					withoutEnlargement: true,
+					kernel: "lanczos3",
+				})
+				.webp({ quality: WEBP_QUALITY })
+				.toBuffer();
+			if (webp.length >= buf.length * ADOPT_RATIO) {
+				stats.noGain += 1;
+				console.log(
+					`SKIP 无收益      原${fmtKB(buf.length)} → ${fmtKB(
+						webp.length,
+					)} ${rel(file)}`,
+				);
+				continue;
+			}
+
+			// 落盘前自校验:压缩结果能重新解码且长边一致(防截断/坏写;宽高允许 ±4px
+			// 的 WebP 有损重编码舍入误差——除以质量 q 的像素块取整,实测 3840→3836)
+			const verify = await sharp(webp).metadata();
+			const verifyLong = Math.max(verify.width || 0, verify.height || 0);
+			const expectLong = Math.max(width, height);
+			if (
+				!verify.width ||
+				!verify.height ||
+				Math.abs(verifyLong - expectLong) > 4
+			) {
+				throw new Error(
+					`压缩结果自校验失败 ${verify.width}×${verify.height}(期望 ~${width}×${height})`,
+				);
+			}
+
+			const line = `${fmtKB(buf.length)} → ${fmtKB(webp.length)}${
+				scale < 1 ? ` (${meta.width}×${meta.height} → ${width}×${height})` : ""
+			} ${rel(file)}`;
+			if (dryRun) {
+				stats.compressed += 1;
+				beforeTotal += buf.length;
+				saved += buf.length - webp.length;
+				console.log(`DRY  ${line}`);
+				continue;
+			}
+
+			// ── 同目录 .new + 两步 rename 原子换名(崩溃不产生半张图)──
+			fs.writeFileSync(file + NEW_SUFFIX, webp);
+			if (keepOrig) fs.renameSync(file, file + ORIG_SUFFIX);
+			fs.renameSync(file + NEW_SUFFIX, file);
+			stats.compressed += 1;
+			beforeTotal += buf.length;
+			saved += buf.length - webp.length;
+			console.log(
+				`OK   ${line}${
+					keepOrig ? `(原图留 ${path.basename(file)}${ORIG_SUFFIX})` : ""
+				}`,
+			);
+		} catch (err) {
+			stats.failed += 1;
+			console.error(`FAIL ${rel(file)} —— ${err.message}`);
+		}
+	}
+
+	const fmtMB = (n) => `${(n / 1024 / 1024).toFixed(1)}MB`;
+	console.log(`\n[src-compress] 完成:${JSON.stringify(stats)}`);
+	if (stats.compressed) {
+		console.log(
+			`[src-compress] 收益:${fmtMB(beforeTotal)} → ${fmtMB(
+				beforeTotal - saved,
+			)}(省 ${fmtMB(saved)})`,
+		);
+	}
+	if (!dryRun && stats.compressed) {
+		console.log(
+			keepOrig
+				? "[src-compress] 回退:单张 mv xxx.png.orig xxx.png;整批 git checkout -- <目录>。.orig 已 gitignore,勿入库。"
+				: "[src-compress] 未留备份,回退只能走 git checkout -- <目录>。",
+		);
+	}
+	if (stats.failed) process.exitCode = 1;
+})().catch((e) => {
+	console.error("FATAL", e);
+	process.exit(1);
+});

package/templates/web/scripts/lib/interactive.cjs

@@ -0,0 +1,134 @@
+/**
+ * web 发布/回滚共享的终端交互 helper —— node 内置 readline 实现,零新增依赖。
+ * - selectEnvKey:多服务器目标交互选择(server.config.json 的 key 罗列成 `key(host)` 菜单)
+ * - selectVersion:发布前选版本策略(自增默认/维持当前/自定义输入)
+ * - selectRollbackVersion:回滚时罗列服务器归档版本,选中回退目标
+ * - confirm:危险操作前确认
+ * 仅在 TTY 下由调用方调用;非交互(CI/管道)走调用方各自的回落逻辑,不经此文件。
+ */
+const readline = require('readline');
+
+// 不用 rl.question:它的回调只在有挂起问题时消费行,管道/整段粘贴的多行输入会在同一
+// tick 同步 emit 完所有 line 事件、后续 question 还没注册,行被整批丢弃(实测第二个
+// 提问直接 EOF 失败)。这里改为共享一个实例 + line 事件入队,你来我往都稳:
+// 没人提问时到达的行先进 pending 队列,下一次 ask 先吃队列再等新行。
+let rl = null;
+let pendingLines = [];
+let lineWaiter = null; // 挂起中的 ask 的 resolve
+
+function getInterface() {
+  if (rl) return rl;
+  rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.on('line', (line) => {
+    if (lineWaiter) {
+      const resolve = lineWaiter;
+      lineWaiter = null;
+      resolve(line);
+    } else {
+      pendingLines.push(line);
+    }
+  });
+  // stdin EOF/关闭时唤醒挂起的 ask(按空输入处理,走各菜单的默认项),避免死等
+  rl.on('close', () => {
+    if (lineWaiter) {
+      const resolve = lineWaiter;
+      lineWaiter = null;
+      resolve('');
+    }
+  });
+  // Ctrl+C 与终端惯例一致:退出码 130
+  rl.on('SIGINT', () => {
+    process.stdout.write('\n');
+    process.exit(130);
+  });
+  return rl;
+}
+
+// 异步提问 → Promise(答案 trim 后返回)
+function ask(prompt) {
+  getInterface();
+  process.stdout.write(prompt);
+  if (pendingLines.length) {
+    return Promise.resolve(pendingLines.shift().trim());
+  }
+  return new Promise((resolve) => {
+    lineWaiter = (line) => resolve(line.trim());
+  });
+}
+
+// 问答结束调用:关闭实例,释放 stdin 句柄,进程才能自然退出
+function closeInteractive() {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+  pendingLines = [];
+  lineWaiter = null;
+}
+
+// 多服务器目标交互选择:罗列 server.config.json 所有 key,菜单文本 `key(host)`。
+// 回车=默认 key(deploy 优先,缺则第一个)。单目标时直接返回、不交互。
+// 返回选中的 key;无效输入循环重问。
+async function selectEnvKey(serverConfig, { defaultKey = 'deploy' } = {}) {
+  const keys = Object.keys(serverConfig);
+  if (keys.length <= 1) return keys[0] || null;
+
+  console.log('🎯 选择部署目标(server.config.json):');
+  keys.forEach((key, i) => console.log(`  ${i + 1}) ${key}(${serverConfig[key].host})`));
+  const fallback = keys.includes(defaultKey) ? defaultKey : keys[0];
+  const fallbackIndex = keys.indexOf(fallback) + 1;
+
+  while (true) {
+    const input = await ask(`输入序号(回车=默认 ${fallbackIndex} [${fallback}]): `);
+    if (!input) return fallback;
+    const num = Number(input);
+    if (Number.isInteger(num) && num >= 1 && num <= keys.length) return keys[num - 1];
+    console.log(`❌ 无效序号 "${input}",请输入 1~${keys.length}`);
+  }
+}
+
+// 发布版本策略交互:1=自增(默认) 2=维持当前 3=自定义输入。返回最终采用的版本号。
+async function selectVersion(current, next) {
+  console.log(`📌 当前版本: ${current}`);
+  console.log('选择本次发布的版本号:');
+  console.log(`  1) 自增至 ${next}(默认)`);
+  console.log('  2) 维持当前版本');
+  console.log('  3) 自定义输入');
+  while (true) {
+    const input = await ask('输入序号(回车=1 自增): ');
+    if (!input || input === '1') return next;
+    if (input === '2') return current;
+    if (input === '3') {
+      const custom = await ask('输入版本号(形如 1.2.3): ');
+      if (/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(custom)) return custom;
+      console.log(`❌ 版本号格式不对: "${custom}",应为 1.2.3 形式`);
+      continue;
+    }
+    console.log('❌ 无效序号,请输入 1/2/3');
+  }
+}
+
+// 回滚版本选择:releases 为新→旧数组 [{name, version, time}],返回选中的那一项。
+// 默认选第 2 个(上一个版本)——出故障的当前版本通常就是最新归档,选它等于原地不动。
+async function selectRollbackVersion(releases) {
+  console.log('🕰️ 可回退版本(新→旧):');
+  releases.forEach((r, i) => console.log(`  ${i + 1}) ${r.version}  ${r.time}  (${r.name})`));
+  const defaultIndex = releases.length > 1 ? 2 : 1;
+  while (true) {
+    const input = await ask(
+      `输入要回退到的版本序号(回车=${defaultIndex} [${releases[defaultIndex - 1].version}]): `
+    );
+    if (!input) return releases[defaultIndex - 1];
+    const num = Number(input);
+    if (Number.isInteger(num) && num >= 1 && num <= releases.length) return releases[num - 1];
+    console.log(`❌ 无效序号 "${input}",请输入 1~${releases.length}`);
+  }
+}
+
+// 危险操作前的 y/N 确认;非 y(含直接回车)一律视为取消,返回 false。
+async function confirm(prompt) {
+  const input = await ask(`${prompt} (y/N): `);
+  return input === 'y' || input === 'Y';
+}
+
+module.exports = { ask, closeInteractive, selectEnvKey, selectVersion, selectRollbackVersion, confirm };