snapdiff-cli 0.1.1 → 0.1.3

package/README.md

@@ -1,242 +1,242 @@
-<p align="center">
-  <h1 align="center">snapdiff</h1>
-  <p align="center">一行命令的视觉回归测试工具</p>
-  <p align="center">
-    <a href="https://www.npmjs.com/package/snapdiff-cli"><img src="https://img.shields.io/npm/v/snapdiff-cli" alt="npm"></a>
-    <a href="https://github.com/zixuanlongxi/snapdiff"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license"></a>
-  </p>
-</p>
-
----
-
-## 概述
-
-**snapdiff** 是一个基于 Playwright + pixelmatch 的视觉回归测试工具。你在改代码前截一张基线截图，改完代码后再截一张，它会告诉你**哪些地方变了、变了多少**，并生成可直观对比的 HTML 报告。
-
-适合场景：
-
-- 改 CSS/组件后检查是否有意外的布局变化
-- PR 提交前自动对比视觉差异
-- CI 流水线中集成视觉回归检查
-
----
-
-## 快速开始
-
-```bash
-# 初始化项目（交互式向导，自动完成首次截图）
-npx snapdiff-cli init
-
-# 修改代码后，对比变化
-npx snapdiff-cli diff
-
-# 查看基线状态
-npx snapdiff-cli status
-
-# 确认变更，更新基线
-npx snapdiff-cli approve <name>
-```
-
-第一次运行 `init` 会自动：
-
-1. 创建配置文件 `snapdiff.config.json`
-2. 截取首张基线截图
-3. 将 `.snapdiff/diffs/` 和 `.snapdiff/reports/` 加入 `.gitignore`
-
----
-
-## 命令参考
-
-### `init`
-
-初始化 snapdiff 配置（交互式向导，自动完成首次截图）。
-
-```bash
-npx snapdiff-cli init              # 交互式
-npx snapdiff-cli init --yes         # 非交互式，使用默认值
-npx snapdiff-cli init --yes --ci    # 非交互式 + 生成 CI 配置文件
-```
-
-如果 stdin 不是终端（例如在 CI 环境中），`init` 会自动切换为非交互模式。
-
-### `capture`
-
-截取当前页面作为基线截图。
-
-```bash
-# 从配置文件批量截取
-npx snapdiff-cli capture
-
-# 截取单个页面
-npx snapdiff-cli capture https://example.com --name my-page
-
-# 指定选择器：等待元素出现后再截图
-npx snapdiff-cli capture https://example.com --name home --selector "#app-root"
-
-# 自定义视口大小
-npx snapdiff-cli capture https://example.com --name mobile -w 375 -h 812
-```
-
-多页面模式下自动 **3 并发** 并行截图。
-
-### `diff`
-
-对比当前页面与基线截图。
-
-```bash
-# 对比配置文件中的所有页面（并行截图 + HTML 报告）
-npx snapdiff-cli diff
-
-# 对比单个页面
-npx snapdiff-cli diff https://example.com --name my-page
-
-# 设置更宽松的阈值（允许 0.5% 以内的差异）
-npx snapdiff-cli diff -t 0.5
-```
-
-运行后自动生成 **HTML 报告** 到 `.snapdiff/reports/` 目录，可直接用浏览器打开查看。
-
-### `approve`
-
-接受当前差异为新基线（覆盖旧基线）。
-
-```bash
-npx snapdiff-cli approve my-page
-```
-
-即使配置文件中没有定义该页面，也会尝试从基线元数据中恢复 URL。
-
-### `status`
-
-查看所有基线状态（表格展示）。
-
-```bash
-npx snapdiff-cli status
-```
-
-输出示例：
-
-```
-  📸 snapdiff 基线状态
-
-  名称                     URL                                      基线时间                   状态
-  ──────────────────────────────────────────────────────────────────────────────────────────
-  homepage                 https://example.com                      2026/6/5 10:30      ✅ 正常
-  pricing                  https://example.com/pricing              2026/6/5 10:31      ✅ 正常
-  dashboard                https://example.com/dashboard            —                     ⚠ 未截取
-```
-
----
-
-## 配置文件
-
-在项目根目录创建 `snapdiff.config.json`：
-
-```json
-{
-  "snaps": [
-    {
-      "name": "homepage",
-      "url": "https://example.com",
-      "viewport": { "width": 1440, "height": 900 },
-      "threshold": 0.1
-    },
-    {
-      "name": "pricing",
-      "url": "https://example.com/pricing",
-      "selector": "#app-root",
-      "viewport": { "width": 1440, "height": 900 },
-      "threshold": 0.1
-    }
-  ]
-}
-```
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `name` | string | 是 | 截图名称，用于标识 |
-| `url` | string | 是 | 页面 URL |
-| `selector` | string | 否 | 等待该 CSS 选择器出现后再截图 |
-| `viewport` | object | 否 | 视口大小，默认 `{ width: 1440, height: 900 }` |
-| `threshold` | number | 否 | 差异阈值百分比，默认 `0.1`，超出则判定失败 |
-
----
-
-## 目录结构
-
-```
-项目根目录/
-├── snapdiff.config.json       # 配置文件
-├── .gitignore                 # 自动添加 .snapdiff/diffs/ 和 .snapdiff/reports/
-└── .snapdiff/
-    ├── baselines/              # 基线截图（需纳入 git 管理）
-    │   ├── homepage.png
-    │   └── homepage.json       # 元数据（URL、视口、时间等）
-    ├── diffs/                  # 差异对比图（已加入 .gitignore）
-    │   └── homepage-1234567890-diff.png
-    └── reports/                # HTML 报告（已加入 .gitignore）
-        └── report-1234567890.html
-```
-
-基线截图纳入 git 管理，这样 PR diff 里可以直接看到图片变化。差异图和报告不纳入 git。
-
----
-
-## CI 集成
-
-### GitHub Actions
-
-```yaml
-# .github/workflows/snapdiff.yml
-name: Visual Regression Test
-on: [pull_request]
-jobs:
-  snapdiff:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - run: npx snapdiff-cli diff
-```
-
-也可以通过 `init --ci` 自动生成：
-
-```bash
-npx snapdiff-cli init --yes --ci
-```
-
----
-
-## 技术栈
-
-| 组件 | 用途 |
-|---|---|
-| [Playwright](https://playwright.dev) | 浏览器截图引擎 |
-| [pixelmatch](https://github.com/mapbox/pixelmatch) | 像素级对比 |
-| [pngjs](https://github.com/lukeapage/pngjs) | PNG 图片处理 |
-| [commander](https://github.com/tj/commander.js) | CLI 框架 |
-
----
-
-## 开发
-
-```bash
-git clone <repo>
-cd snapdiff
-
-# 依赖已内置于 CLI 包
-cd packages/cli
-npm install
-npm run build
-
-# 本地测试
-node dist/index.js --help
-```
-
----
-
-## 许可证
-
+<p align="center">
+  <h1 align="center">snapdiff</h1>
+  <p align="center">一行命令的视觉回归测试工具</p>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/snapdiff-cli"><img src="https://img.shields.io/npm/v/snapdiff-cli" alt="npm"></a>
+    <a href="https://github.com/zixuanlongxi/snapdiff"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license"></a>
+  </p>
+</p>
+
+---
+
+## 概述
+
+**snapdiff** 是一个基于 Playwright + pixelmatch 的视觉回归测试工具。你在改代码前截一张基线截图，改完代码后再截一张，它会告诉你**哪些地方变了、变了多少**，并生成可直观对比的 HTML 报告。
+
+适合场景：
+
+- 改 CSS/组件后检查是否有意外的布局变化
+- PR 提交前自动对比视觉差异
+- CI 流水线中集成视觉回归检查
+
+---
+
+## 快速开始
+
+```bash
+# 初始化项目（交互式向导，自动完成首次截图）
+npx snapdiff-cli init
+
+# 修改代码后，对比变化
+npx snapdiff-cli diff
+
+# 查看基线状态
+npx snapdiff-cli status
+
+# 确认变更，更新基线
+npx snapdiff-cli approve <name>
+```
+
+第一次运行 `init` 会自动：
+
+1. 创建配置文件 `snapdiff.config.json`
+2. 截取首张基线截图
+3. 将 `.snapdiff/diffs/` 和 `.snapdiff/reports/` 加入 `.gitignore`
+
+---
+
+## 命令参考
+
+### `init`
+
+初始化 snapdiff 配置（交互式向导，自动完成首次截图）。
+
+```bash
+npx snapdiff-cli init              # 交互式
+npx snapdiff-cli init --yes         # 非交互式，使用默认值
+npx snapdiff-cli init --yes --ci    # 非交互式 + 生成 CI 配置文件
+```
+
+如果 stdin 不是终端（例如在 CI 环境中），`init` 会自动切换为非交互模式。
+
+### `capture`
+
+截取当前页面作为基线截图。
+
+```bash
+# 从配置文件批量截取
+npx snapdiff-cli capture
+
+# 截取单个页面
+npx snapdiff-cli capture https://example.com --name my-page
+
+# 指定选择器：等待元素出现后再截图
+npx snapdiff-cli capture https://example.com --name home --selector "#app-root"
+
+# 自定义视口大小
+npx snapdiff-cli capture https://example.com --name mobile -w 375 -h 812
+```
+
+多页面模式下自动 **3 并发** 并行截图。
+
+### `diff`
+
+对比当前页面与基线截图。
+
+```bash
+# 对比配置文件中的所有页面（并行截图 + HTML 报告）
+npx snapdiff-cli diff
+
+# 对比单个页面
+npx snapdiff-cli diff https://example.com --name my-page
+
+# 设置更宽松的阈值（允许 0.5% 以内的差异）
+npx snapdiff-cli diff -t 0.5
+```
+
+运行后自动生成 **HTML 报告** 到 `.snapdiff/reports/` 目录，可直接用浏览器打开查看。
+
+### `approve`
+
+接受当前差异为新基线（覆盖旧基线）。
+
+```bash
+npx snapdiff-cli approve my-page
+```
+
+即使配置文件中没有定义该页面，也会尝试从基线元数据中恢复 URL。
+
+### `status`
+
+查看所有基线状态（表格展示）。
+
+```bash
+npx snapdiff-cli status
+```
+
+输出示例：
+
+```
+  📸 snapdiff 基线状态
+
+  名称                     URL                                      基线时间                   状态
+  ──────────────────────────────────────────────────────────────────────────────────────────
+  homepage                 https://example.com                      2026/6/5 10:30      ✅ 正常
+  pricing                  https://example.com/pricing              2026/6/5 10:31      ✅ 正常
+  dashboard                https://example.com/dashboard            —                     ⚠ 未截取
+```
+
+---
+
+## 配置文件
+
+在项目根目录创建 `snapdiff.config.json`：
+
+```json
+{
+  "snaps": [
+    {
+      "name": "homepage",
+      "url": "https://example.com",
+      "viewport": { "width": 1440, "height": 900 },
+      "threshold": 0.1
+    },
+    {
+      "name": "pricing",
+      "url": "https://example.com/pricing",
+      "selector": "#app-root",
+      "viewport": { "width": 1440, "height": 900 },
+      "threshold": 0.1
+    }
+  ]
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `name` | string | 是 | 截图名称，用于标识 |
+| `url` | string | 是 | 页面 URL |
+| `selector` | string | 否 | 等待该 CSS 选择器出现后再截图 |
+| `viewport` | object | 否 | 视口大小，默认 `{ width: 1440, height: 900 }` |
+| `threshold` | number | 否 | 差异阈值百分比，默认 `0.1`，超出则判定失败 |
+
+---
+
+## 目录结构
+
+```
+项目根目录/
+├── snapdiff.config.json       # 配置文件
+├── .gitignore                 # 自动添加 .snapdiff/diffs/ 和 .snapdiff/reports/
+└── .snapdiff/
+    ├── baselines/              # 基线截图（需纳入 git 管理）
+    │   ├── homepage.png
+    │   └── homepage.json       # 元数据（URL、视口、时间等）
+    ├── diffs/                  # 差异对比图（已加入 .gitignore）
+    │   └── homepage-1234567890-diff.png
+    └── reports/                # HTML 报告（已加入 .gitignore）
+        └── report-1234567890.html
+```
+
+基线截图纳入 git 管理，这样 PR diff 里可以直接看到图片变化。差异图和报告不纳入 git。
+
+---
+
+## CI 集成
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/snapdiff.yml
+name: Visual Regression Test
+on: [pull_request]
+jobs:
+  snapdiff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npx snapdiff-cli diff
+```
+
+也可以通过 `init --ci` 自动生成：
+
+```bash
+npx snapdiff-cli init --yes --ci
+```
+
+---
+
+## 技术栈
+
+| 组件 | 用途 |
+|---|---|
+| [Playwright](https://playwright.dev) | 浏览器截图引擎 |
+| [pixelmatch](https://github.com/mapbox/pixelmatch) | 像素级对比 |
+| [pngjs](https://github.com/lukeapage/pngjs) | PNG 图片处理 |
+| [commander](https://github.com/tj/commander.js) | CLI 框架 |
+
+---
+
+## 开发
+
+```bash
+git clone <repo>
+cd snapdiff
+
+# 依赖已内置于 CLI 包
+cd packages/cli
+npm install
+npm run build
+
+# 本地测试
+node dist/index.js --help
+```
+
+---
+
+## 许可证
+
 MIT

package/dist/index.d.ts

@@ -1,2 +1 @@
-#!/usr/bin/env node
 export {};

package/dist/index.js

@@ -1,4 +1,6 @@
-#!/usr/bin/env node
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
 import { Command } from "commander";
 import pc from "picocolors";
 import { initCommand } from "./commands/init.js";
@@ -6,36 +8,33 @@ import { captureCommand } from "./commands/capture.js";
 import { diffCommand } from "./commands/diff.js";
 import { approveCommand } from "./commands/approve.js";
 import { statusCommand } from "./commands/status.js";
-// Global error handler — prevent raw stack traces from leaking to users
+// Global error handler
 process.on("unhandledRejection", (err) => {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(pc.red(`\n  ⚠ 意外错误: ${msg}`));
-    console.error(pc.dim(`  如需帮助，请提供以上完整输出来排查问题。`));
+    console.error(pc.dim("  如需帮助，请提供以上完整输出来排查问题。"));
     process.exit(1);
 });
 process.on("uncaughtException", (err) => {
     console.error(pc.red(`\n  ⚠ 意外错误: ${err.message}`));
-    console.error(pc.dim(`  如需帮助，请提供以上完整输出来排查问题。`));
+    console.error(pc.dim("  如需帮助，请提供以上完整输出来排查问题。"));
     process.exit(1);
 });
-// Detect non-TTY stdin early — e.g. piped input in CI
 const isInteractive = process.stdin.isTTY;
 const program = new Command();
 program
     .name("snapdiff")
     .description(pc.cyan("一行命令的视觉回归测试工具"))
-    .version("0.1.0");
+    .version(pkg.version);
 program
     .command("init")
     .description("初始化 snapdiff 配置（交互式向导，自动完成首次截图）")
     .option("--ci", "同时生成 GitHub Action 配置文件")
     .option("--yes", "跳过交互提问，使用默认值")
-    .addHelpText("after", pc.dim(`\n示例:\n  $ snapdiff init\n  $ snapdiff init --yes      非交互式，快速初始化\n  $ snapdiff init --yes --ci  非交互式 + CI 配置\n`))
+    .addHelpText("after", pc.dim("\n示例:\n  $ snapdiff init\n  $ snapdiff init --yes      非交互式，快速初始化\n  $ snapdiff init --yes --ci  非交互式 + CI 配置\n"))
     .action((opts) => {
-    // If stdin is not a TTY and --yes not given, auto-enable --yes to avoid hanging
-    if (!isInteractive && !opts.yes) {
+    if (!isInteractive && !opts.yes)
         opts.yes = true;
-    }
     initCommand(opts);
 });
 program
@@ -46,7 +45,7 @@ program
     .option("-s, --selector <selector>", "等页面中该元素出现后再截图，如 #app-root")
     .option("-w, --width <width>", "视口宽度", "1440")
     .option("-h, --height <height>", "视口高度", "900")
-    .addHelpText("after", pc.dim(`\n示例:\n  $ snapdiff capture                             从配置文件批量截取\n  $ snapdiff capture https://ex.com -n my-page   截取单个页面\n  $ snapdiff capture https://ex.com -n home -s #main\n`))
+    .addHelpText("after", pc.dim("\n示例:\n  $ snapdiff capture                             从配置文件批量截取\n  $ snapdiff capture https://ex.com -n my-page   截取单个页面\n  $ snapdiff capture https://ex.com -n home -s #main\n"))
     .action(captureCommand);
 program
     .command("diff")
@@ -54,18 +53,18 @@ program
     .argument("[url]", "页面 URL")
     .option("-n, --name <name>", "截图名称")
     .option("-t, --threshold <threshold>", "允许的差异阈值百分比，超出即判定为失败", "0.1")
-    .addHelpText("after", pc.dim(`\n示例:\n  $ snapdiff diff                               对比配置文件中的所有页面\n  $ snapdiff diff https://ex.com -n my-page     对比单个页面\n  $ snapdiff diff -t 0.5                        设置更宽松的阈值\n`))
+    .addHelpText("after", pc.dim("\n示例:\n  $ snapdiff diff                               对比配置文件中的所有页面\n  $ snapdiff diff https://ex.com -n my-page     对比单个页面\n  $ snapdiff diff -t 0.5                        设置更宽松的阈值\n"))
     .action(diffCommand);
 program
     .command("approve")
     .description("接受当前差异为新基线（覆盖旧基线）")
     .argument("<name>", "截图名称（必填）")
-    .addHelpText("after", pc.dim(`\n示例:\n  $ snapdiff approve my-page   将我页面的新状态设为基线\n`))
+    .addHelpText("after", pc.dim("\n示例:\n  $ snapdiff approve my-page   将我页面的新状态设为基线\n"))
     .action(approveCommand);
 program
     .command("status")
     .description("查看所有基线状态（表格展示）")
-    .addHelpText("after", pc.dim(`\n示例:\n  $ snapdiff status   查看哪些页面有基线，哪些还未截取\n`))
+    .addHelpText("after", pc.dim("\n示例:\n  $ snapdiff status   查看哪些页面有基线，哪些还未截取\n"))
     .action(statusCommand);
 program.addHelpText("afterAll", `
 ${pc.bold("快速开始")}:

package/package.json

@@ -1,6 +1,6 @@
-{
+{
   "name": "snapdiff-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "????????????????????????? Playwright + pixelmatch",
   "type": "module",
   "bin": {
@@ -47,4 +47,4 @@
     "diff",
     "cli"
   ]
-}
+}