snapdiff-cli 0.1.0

package/dist/commands/approve.d.ts

@@ -0,0 +1 @@
+export declare function approveCommand(name: string): Promise<void>;

package/dist/commands/approve.js

@@ -0,0 +1,49 @@
+import pc from "picocolors";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { baselineImagePath, ensureDirs, captureSnapshot, saveBaselineMeta, loadConfig } from "../core/index.js";
+export async function approveCommand(name) {
+    const cwd = process.cwd();
+    const { baselineExists } = await import("@snapdiff/core");
+    if (!(await baselineExists(cwd, name))) {
+        console.log(pc.yellow(`⚠  "${name}" 没有基线截图，无法接受。`));
+        console.log(`  请先运行: ${pc.bold(`npx snapdiff capture <url> --name ${name}`)}`);
+        return;
+    }
+    // Try loading config, fallback to minimal inline config
+    let config = await loadConfig(cwd);
+    let snap = config?.snaps.find((s) => s.name === name);
+    if (!snap) {
+        // Try reading the baseline meta json for URL info
+        const metaPath = join(cwd, ".snapdiff", "baselines", `${name}.json`);
+        let url = "";
+        try {
+            const meta = JSON.parse(await readFile(metaPath, "utf-8"));
+            url = meta.url || "";
+        }
+        catch { }
+        if (!url) {
+            console.log(pc.yellow(`⚠ 未找到 "${name}" 的配置，也无法从基线元数据中恢复 URL。`));
+            console.log(`  请先运行: ${pc.bold(`npx snapdiff capture <url> --name ${name}`)}`);
+            return;
+        }
+        // Reconstruct a minimal snap config from metadata
+        console.log(pc.dim(`  从基线元数据恢复配置: ${url}`));
+        snap = { name, url, viewport: { width: 1440, height: 900 }, threshold: 0.1 };
+    }
+    await ensureDirs(cwd);
+    const viewport = snap.viewport ?? { width: 1440, height: 900 };
+    console.log(pc.cyan(`\n  正在将 "${name}" 的当前状态接受为新基线...`));
+    try {
+        const { imagePath, meta } = await captureSnapshot({
+            config: { ...snap, viewport },
+            outputPath: baselineImagePath(cwd, name),
+        });
+        await saveBaselineMeta(cwd, name, meta);
+        console.log(pc.green(`  ✔ 基线已更新: ${snap.url}`));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.log(pc.red(`  ✗ 接受失败: ${msg}`));
+    }
+}

package/dist/commands/capture.d.ts

@@ -0,0 +1,6 @@
+export declare function captureCommand(url: string | undefined, options: {
+    name?: string;
+    selector?: string;
+    width?: string;
+    height?: string;
+}): Promise<void>;

package/dist/commands/capture.js

@@ -0,0 +1,52 @@
+import { ensureDirs, captureSnapshotsParallel, baselineImagePath, saveBaselineMeta, loadConfig, } from "../core/index.js";
+import pc from "picocolors";
+export async function captureCommand(url, options) {
+    const cwd = process.cwd();
+    const viewport = {
+        width: parseInt(options.width || "1440", 10),
+        height: parseInt(options.height || "900", 10),
+    };
+    // No args → use config file (parallel)
+    if (!url && !options.name) {
+        const config = await loadConfig(cwd);
+        if (!config || config.snaps.length === 0) {
+            console.log(pc.yellow("⚠ 未找到配置，请先运行 snapdiff init 或提供 URL 参数"));
+            console.log(`  用法: ${pc.bold("npx snapdiff capture <url> --name <name>")}`);
+            return;
+        }
+        await ensureDirs(cwd);
+        console.log(pc.cyan(`\n  正在并行截取 ${config.snaps.length} 个页面...`));
+        const tasks = config.snaps.map((snap) => ({
+            config: { ...snap, viewport: snap.viewport ?? viewport, threshold: snap.threshold ?? 0.1 },
+            outputPath: baselineImagePath(cwd, snap.name),
+        }));
+        const results = await captureSnapshotsParallel(tasks, 3);
+        for (let i = 0; i < results.length; i++) {
+            await saveBaselineMeta(cwd, config.snaps[i].name, results[i].meta);
+            console.log(pc.green(`  ✔ ${config.snaps[i].url} ── 基线已保存`));
+        }
+        return;
+    }
+    // Single URL mode
+    if (!url || !options.name) {
+        console.log(pc.yellow("请提供 URL 和名称："));
+        console.log(`  ${pc.bold("npx snapdiff capture <url> --name <name>")}`);
+        return;
+    }
+    await ensureDirs(cwd);
+    const { captureSnapshot } = await import("@snapdiff/core");
+    const snap = {
+        name: options.name,
+        url,
+        selector: options.selector,
+        viewport,
+        threshold: 0.1,
+    };
+    console.log(pc.cyan(`\n  正在截取 ${snap.name}...`));
+    const { imagePath, meta } = await captureSnapshot({
+        config: snap,
+        outputPath: baselineImagePath(cwd, snap.name),
+    });
+    await saveBaselineMeta(cwd, snap.name, meta);
+    console.log(pc.green(`  ✔ ${url} ── 基线已保存`));
+}

package/dist/commands/diff.d.ts

@@ -0,0 +1,4 @@
+export declare function diffCommand(url: string | undefined, options: {
+    name?: string;
+    threshold?: string;
+}): Promise<void>;

package/dist/commands/diff.js

@@ -0,0 +1,130 @@
+import { ensureDirs, captureSnapshot, captureSnapshotsParallel, baselineImagePath, diffImagePath, compareSnapshots, loadConfig, generateReportSummary, generateHtmlReport, baselineExists, } from "../core/index.js";
+import pc from "picocolors";
+import { unlink } from "node:fs/promises";
+export async function diffCommand(url, options) {
+    const cwd = process.cwd();
+    await ensureDirs(cwd);
+    const threshold = parseFloat(options.threshold || "0.1");
+    // No args → run all snaps from config (parallel capture)
+    if (!url && !options.name) {
+        const config = await loadConfig(cwd);
+        if (!config || config.snaps.length === 0) {
+            console.log(pc.yellow("⚠ 未找到配置，请先运行 snapdiff init 或提供参数"));
+            console.log(`  ${pc.bold("npx snapdiff diff <url> --name <name>")}`);
+            return;
+        }
+        // Check which snaps have baselines
+        const validSnaps = [];
+        for (const snap of config.snaps) {
+            if (await baselineExists(cwd, snap.name)) {
+                validSnaps.push(snap);
+            }
+            else {
+                console.log(pc.yellow(`\n  ⚠ "${snap.name}" 还没有基线截图。`));
+                console.log(`     ${pc.bold("npx snapdiff capture " + snap.url + " --name " + snap.name)}`);
+            }
+        }
+        if (validSnaps.length === 0) {
+            console.log(pc.dim("\n  没有需要对比的页面。"));
+            return;
+        }
+        console.log(pc.cyan(`\n  正在并行截取 ${validSnaps.length} 个页面...`));
+        const timestamp = String(Math.floor(Date.now() / 1000));
+        // Phase 1: capture all current states in parallel
+        const captureTasks = validSnaps.map((snap) => ({
+            config: {
+                ...snap,
+                viewport: snap.viewport ?? { width: 1440, height: 900 },
+                threshold: snap.threshold ?? 0.1,
+            },
+            outputPath: baselineImagePath(cwd, "current-" + snap.name),
+        }));
+        const captureResults = await captureSnapshotsParallel(captureTasks, 3);
+        // Phase 2: compare all diffs (sequential, fast operations)
+        const results = [];
+        for (let i = 0; i < validSnaps.length; i++) {
+            const snap = validSnaps[i];
+            const currentPath = captureResults[i].imagePath;
+            const diffOut = diffImagePath(cwd, snap.name, timestamp);
+            const result = await compareSnapshots({
+                baselinePath: baselineImagePath(cwd, snap.name),
+                currentPath,
+                diffOutputPath: diffOut,
+                threshold: threshold / 100,
+            });
+            result.name = snap.name;
+            result.url = snap.url;
+            results.push(result);
+            await unlink(currentPath).catch(() => { });
+            if (result.error) {
+                console.log("  ⚠ " + snap.name + ": " + result.error);
+            }
+            else if (result.passed) {
+                console.log(pc.green("  ✅ " + snap.name + " ── 无变化 (差异 " + result.diffPercent + "%)"));
+            }
+            else {
+                const bar = makeBar(result.diffPercent, 20);
+                console.log("  ❌ " + snap.name);
+                console.log("     " + bar + " " + result.diffPercent + "% (" + result.diffPixels + " 像素)");
+                console.log(pc.dim("     📄 diff 图: " + result.diffImagePath));
+                console.log(pc.cyan("     如果这是预期的变更: " + pc.bold("npx snapdiff approve " + snap.name)));
+            }
+        }
+        if (results.length > 0) {
+            console.log(generateReportSummary(results));
+            const htmlPath = await generateHtmlReport(results, cwd);
+            console.log(pc.cyan("\n  📊 HTML 报告: " + htmlPath));
+        }
+        return;
+    }
+    // Single URL mode
+    if (!url || !options.name) {
+        console.log(pc.yellow("请提供 URL 和名称："));
+        console.log("  " + pc.bold("npx snapdiff diff <url> --name <name>"));
+        return;
+    }
+    const name = options.name;
+    if (!(await baselineExists(cwd, name))) {
+        console.log(pc.yellow('\n  ⚠ "' + name + '" 还没有基线截图。'));
+        console.log("  请先运行: " + pc.bold("npx snapdiff capture " + url + " --name " + name));
+        return;
+    }
+    console.log(pc.cyan("正在对比 " + name + "..."));
+    const viewport = { width: 1440, height: 900 };
+    const t = String(Math.floor(Date.now() / 1000));
+    const currentPath = baselineImagePath(cwd, "current-" + name);
+    const { imagePath: curPath } = await captureSnapshot({
+        config: { name, url, viewport, threshold: threshold / 100 },
+        outputPath: currentPath,
+    });
+    const diffOut = diffImagePath(cwd, name, t);
+    const result = await compareSnapshots({
+        baselinePath: baselineImagePath(cwd, name),
+        currentPath: curPath,
+        diffOutputPath: diffOut,
+        threshold: threshold / 100,
+    });
+    result.name = name;
+    result.url = url;
+    await unlink(curPath).catch(() => { });
+    if (result.error) {
+        console.log("  ⚠ " + result.error);
+    }
+    else if (result.passed) {
+        console.log(pc.green("  ✅ 无变化 (差异 " + result.diffPercent + "%)"));
+    }
+    else {
+        const bar = makeBar(result.diffPercent, 20);
+        console.log("  ❌ " + name);
+        console.log("     " + bar + " " + result.diffPercent + "% (" + result.diffPixels + " 像素)");
+        console.log(pc.dim("     📄 diff 图: " + result.diffImagePath));
+        console.log(pc.cyan("  如果这是预期的变更: " + pc.bold("npx snapdiff approve " + name)));
+    }
+    const htmlPath = await generateHtmlReport([result], cwd);
+    console.log(pc.cyan("\n  📊 HTML 报告: " + htmlPath));
+}
+function makeBar(percent, width) {
+    const filled = Math.min(Math.round((percent / 100) * width), width);
+    const empty = width - filled;
+    return pc.red("█".repeat(filled)) + pc.dim("░".repeat(empty));
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,4 @@
+export declare function initCommand(options: {
+    ci?: boolean;
+    yes?: boolean;
+}): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,135 @@
+import path from "node:path";
+import { writeFile, mkdir, readFile, appendFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import pc from "picocolors";
+export async function initCommand(options) {
+    const cwd = process.cwd();
+    const configPath = path.join(cwd, "snapdiff.config.json");
+    if (existsSync(configPath)) {
+        console.log(pc.yellow("⚠  snapdiff.config.json 已存在，跳过初始化。"));
+        return;
+    }
+    const projectName = path.basename(cwd);
+    if (options.yes) {
+        // Non-interactive mode: use defaults
+        await createConfig(cwd, configPath, {
+            name: projectName,
+            url: "http://localhost:3000",
+            selector: "",
+        });
+        await setupGitignore(cwd);
+        await takeFirstBaseline(cwd, configPath);
+        await maybeSetupCi(cwd, options.ci);
+        printNextSteps(cwd);
+        return;
+    }
+    // Interactive mode
+    console.log(pc.cyan("\n  ⚡ snapdiff 初始化向导\n"));
+    const answers = await askQuestions([
+        { key: "name", question: "? 项目名称", default: projectName },
+        { key: "url", question: "? 要监控的页面 URL", default: "http://localhost:3000" },
+        { key: "selector", question: "? 页面加载完成后的等待元素（可选，留空则等待网络空闲）", default: "" },
+    ]);
+    await createConfig(cwd, configPath, answers);
+    await setupGitignore(cwd);
+    await takeFirstBaseline(cwd, configPath);
+    if (options.ci) {
+        await maybeSetupCi(cwd, true);
+    }
+    printNextSteps(cwd);
+}
+async function askQuestions(questions) {
+    const answers = {};
+    const readline = await import("node:readline/promises");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    for (const q of questions) {
+        const prompt = q.default ? `${pc.dim(q.question)} (${q.default}): ` : `${q.question}: `;
+        const answer = await rl.question(prompt);
+        answers[q.key] = answer || q.default;
+    }
+    rl.close();
+    return answers;
+}
+async function createConfig(cwd, configPath, answers) {
+    const config = {
+        snaps: [
+            {
+                name: answers.name,
+                url: answers.url,
+                ...(answers.selector ? { selector: answers.selector } : {}),
+                viewport: { width: 1440, height: 900 },
+                threshold: 0.1,
+            },
+        ],
+    };
+    await writeFile(configPath, JSON.stringify(config, null, 2), "utf-8");
+    console.log(pc.green(`  ✔ 已创建 ${configPath}`));
+}
+async function setupGitignore(cwd) {
+    const gitignorePath = path.join(cwd, ".gitignore");
+    const diffDirEntry = "\n# snapdiff: 临时 diff 截图（不看 git）\n.snapdiff/diffs/\n.snapdiff/reports/\n";
+    try {
+        if (existsSync(gitignorePath)) {
+            const existing = await readFile(gitignorePath, "utf-8");
+            if (!existing.includes(".snapdiff/diffs/")) {
+                await appendFile(gitignorePath, diffDirEntry);
+                console.log(pc.green("  ✔ 已将 .snapdiff/diffs/ 和 .snapdiff/reports/ 添加到 .gitignore"));
+            }
+        }
+        else {
+            await writeFile(gitignorePath, diffDirEntry, "utf-8");
+            console.log(pc.green("  ✔ 已创建 .gitignore"));
+        }
+    }
+    catch {
+        // .gitignore 不是关键功能，忽略错误
+    }
+}
+async function takeFirstBaseline(cwd, configPath) {
+    const { ensureDirs, captureSnapshot, baselineImagePath, saveBaselineMeta } = await import("@snapdiff/core");
+    const config = JSON.parse(await readFile(configPath, "utf-8"));
+    await ensureDirs(cwd);
+    console.log(pc.cyan("\n  正在截取基线..."));
+    try {
+        const { imagePath, meta } = await captureSnapshot({
+            config: config.snaps[0],
+            outputPath: baselineImagePath(cwd, config.snaps[0].name),
+        });
+        await saveBaselineMeta(cwd, config.snaps[0].name, meta);
+        console.log(pc.green(`  ✔ ${config.snaps[0].url} ── 基线已保存`));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.log(pc.yellow(`  ⚠ 首次截图失败: ${msg}`));
+        console.log(`     稍后可以手动运行 ${pc.bold("npx snapdiff capture")}`);
+    }
+}
+async function maybeSetupCi(cwd, ci) {
+    if (!ci)
+        return;
+    const ciDir = path.join(cwd, ".github", "workflows");
+    if (!existsSync(ciDir)) {
+        await mkdir(ciDir, { recursive: true });
+    }
+    const ciYaml = `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 diff
+`;
+    await writeFile(path.join(ciDir, "snapdiff.yml"), ciYaml, "utf-8");
+    console.log(pc.green("  ✔ 已创建 .github/workflows/snapdiff.yml"));
+}
+function printNextSteps(cwd) {
+    console.log(pc.cyan("\n  下一步："));
+    console.log(`    ▸ 修改代码后运行  ${pc.bold("npx snapdiff diff")}`);
+    console.log(`    ▸ 查看基线状态    ${pc.bold("npx snapdiff status")}`);
+    console.log(`    ▸ 非交互式初始化  ${pc.bold("npx snapdiff init --yes")}`);
+    console.log();
+}

package/dist/commands/status.d.ts

@@ -0,0 +1 @@
+export declare function statusCommand(): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,49 @@
+import pc from "picocolors";
+import { listBaselines, loadConfig } from "../core/index.js";
+export async function statusCommand() {
+    const cwd = process.cwd();
+    const baselines = await listBaselines(cwd);
+    const config = await loadConfig(cwd);
+    console.log(pc.cyan("\n  📸 snapdiff 基线状态\n"));
+    if (baselines.length === 0 && (!config || config.snaps.length === 0)) {
+        console.log("  还没有任何基线截图。");
+        console.log(`  请先运行: ${pc.bold("npx snapdiff init")}`);
+        console.log(`  或: ${pc.bold("npx snapdiff capture <url> --name <name>")}`);
+        console.log();
+        return;
+    }
+    // Build a set of configured snap names
+    const configuredSnaps = new Set(config?.snaps.map((s) => s.name) ?? []);
+    // Header
+    const header = `  ${"名称".padEnd(22)} ${"URL".padEnd(40)} ${"基线时间".padEnd(22)} 状态`;
+    console.log(pc.dim(header));
+    console.log(pc.dim("  " + "─".repeat(90)));
+    // Show configured snaps first
+    if (config) {
+        for (const snap of config.snaps) {
+            const baseline = baselines.find((b) => b.name === snap.name);
+            const timeStr = baseline?.meta
+                ? new Date(baseline.meta.capturedAt).toLocaleString("zh-CN")
+                : "—";
+            const status = baseline
+                ? pc.green("✅ 正常")
+                : pc.yellow("⚠ 未截取");
+            console.log(`  ${snap.name.padEnd(22)} ${snap.url.padEnd(40)} ${timeStr.padEnd(22)} ${status}`);
+        }
+    }
+    // Show uncatalogued baselines
+    const uncatalogued = baselines.filter((b) => !configuredSnaps.has(b.name));
+    if (uncatalogued.length > 0) {
+        console.log();
+        console.log(pc.dim("  未纳入配置的基线："));
+        for (const b of uncatalogued) {
+            const timeStr = b.meta
+                ? new Date(b.meta.capturedAt).toLocaleString("zh-CN")
+                : "—";
+            console.log(`    ${b.name.padEnd(22)} ${timeStr.padEnd(22)} ${pc.dim("(无对应配置)")}`);
+        }
+    }
+    console.log();
+    console.log(pc.dim("  提示: 修改代码后运行 npx snapdiff diff 进行对比"));
+    console.log();
+}

package/dist/core/capture.d.ts

@@ -0,0 +1,14 @@
+import { SnapConfig, BaselineMeta } from "./types.js";
+export interface CaptureOptions {
+    config: SnapConfig;
+    outputPath: string;
+}
+export interface CaptureResult {
+    imagePath: string;
+    meta: BaselineMeta;
+}
+export declare function captureSnapshot(options: CaptureOptions): Promise<CaptureResult>;
+export declare function captureSnapshotsParallel(snaps: Array<{
+    config: SnapConfig;
+    outputPath: string;
+}>, concurrency?: number): Promise<CaptureResult[]>;

package/dist/core/capture.js

@@ -0,0 +1,83 @@
+import { chromium } from "playwright";
+function prefixLines(msg) {
+    return msg.replace(/^/gm, "  ");
+}
+export async function captureSnapshot(options) {
+    const { config, outputPath } = options;
+    const viewport = config.viewport ?? { width: 1440, height: 900 };
+    let browser = null;
+    try {
+        browser = await chromium.launch({ headless: true });
+        const page = await browser.newPage({ viewport });
+        await page.goto(config.url, {
+            waitUntil: "networkidle",
+            timeout: 30_000,
+        });
+        if (config.selector) {
+            await page.waitForSelector(config.selector, { timeout: 15_000 });
+        }
+        await page.waitForTimeout(500);
+        const screenshotBuffer = await page.screenshot({ fullPage: false, type: "png" });
+        const { writeFile } = await import("node:fs/promises");
+        await writeFile(outputPath, screenshotBuffer);
+        const meta = {
+            name: config.name,
+            url: config.url,
+            viewport,
+            selector: config.selector,
+            capturedAt: new Date().toISOString(),
+            contentHash: simpleHash(screenshotBuffer),
+        };
+        return { imagePath: outputPath, meta };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("ERR_CONNECTION_REFUSED") || msg.includes("ENOTFOUND") || msg.includes("ERR_NAME_NOT_RESOLVED")) {
+            throw new Error(`无法访问 ${config.url}，请检查页面是否已启动或 URL 是否正确`);
+        }
+        if (msg.includes("ERR_CONNECTION_TIMEOUT") || msg.includes("ERR_TIMED_OUT") || msg.includes("timeout")) {
+            throw new Error(`访问 ${config.url} 超时（30 秒），页面可能加载过慢`);
+        }
+        if (msg.includes("ERR_ABORTED")) {
+            throw new Error(`对 ${config.url} 的请求被中断，请检查页面是否被重定向或拦截`);
+        }
+        if (msg.includes("waitForSelector") || (msg.includes("Timeout") && config.selector)) {
+            throw new Error(`等待选择器 "${config.selector}" 超时，该元素在页面中未找到`);
+        }
+        if (msg.includes("spawn EACCES") || msg.includes("spawn EPERM") || msg.includes("spawn ENOTDIR")) {
+            throw new Error(`浏览器进程启动失败（权限不足），请重新安装 Chromium:\n  npx playwright install chromium`);
+        }
+        throw new Error(`截图失败: ${msg}`);
+    }
+    finally {
+        if (browser)
+            await browser.close().catch(() => { });
+    }
+}
+export async function captureSnapshotsParallel(snaps, concurrency = 3) {
+    const results = [];
+    const queue = [...snaps];
+    async function worker() {
+        while (queue.length > 0) {
+            const item = queue.shift();
+            try {
+                const result = await captureSnapshot(item);
+                results.push(result);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`  ✗ ${item.config.name}: ${msg}`);
+            }
+        }
+    }
+    const workers = Array.from({ length: Math.min(concurrency, snaps.length) }, () => worker());
+    await Promise.all(workers);
+    return results;
+}
+function simpleHash(buffer) {
+    let hash = 0;
+    for (let i = 0; i < buffer.length; i += 1000) {
+        hash = ((hash << 5) - hash + buffer[i]) | 0;
+    }
+    return Math.abs(hash).toString(16).padStart(8, "0");
+}

package/dist/core/config.d.ts

@@ -0,0 +1,9 @@
+import { SnapConfig } from "./types.js";
+export interface ProjectConfig {
+    snaps: SnapConfig[];
+    ci?: {
+        mode: "strict" | "auto-capture";
+    };
+}
+export declare function loadConfig(cwd: string): Promise<ProjectConfig | null>;
+export declare function defaultConfig(): ProjectConfig;

package/dist/core/config.js

@@ -0,0 +1,41 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+const CONFIG_FILES = [
+    "snapdiff.config.ts",
+    "snapdiff.config.js",
+    "snapdiff.config.json",
+    ".snapdiffrc",
+    ".snapdiffrc.json",
+];
+function stripBom(raw) {
+    return raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+}
+export async function loadConfig(cwd) {
+    for (const file of CONFIG_FILES) {
+        const path = join(cwd, file);
+        if (!existsSync(path))
+            continue;
+        if (file.endsWith(".json") || file === ".snapdiffrc") {
+            try {
+                const raw = await readFile(path, "utf-8");
+                return JSON.parse(stripBom(raw));
+            }
+            catch (err) {
+                const msg = err instanceof SyntaxError
+                    ? `配置文件 ${file} 格式错误，请检查 JSON 语法`
+                    : `读取配置文件 ${file} 失败: ${err instanceof Error ? err.message : err}`;
+                console.error(`  ⚠ ${msg}`);
+                return null;
+            }
+        }
+        if (file.endsWith(".ts") || file.endsWith(".js")) {
+            console.warn("  ⚠ TypeScript/JS 配置文件当前版本暂不支持，请使用 snapdiff.config.json");
+            continue;
+        }
+    }
+    return null;
+}
+export function defaultConfig() {
+    return { snaps: [] };
+}

package/dist/core/diff.d.ts

@@ -0,0 +1,8 @@
+import { DiffResult } from "./types.js";
+export interface DiffOptions {
+    baselinePath: string;
+    currentPath: string;
+    diffOutputPath: string;
+    threshold: number;
+}
+export declare function compareSnapshots(options: DiffOptions): Promise<DiffResult>;

package/dist/core/diff.js

@@ -0,0 +1,35 @@
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import { readFile, writeFile } from "node:fs/promises";
+export async function compareSnapshots(options) {
+    const { baselinePath, currentPath, diffOutputPath, threshold } = options;
+    const baselinePng = PNG.sync.read(await readFile(baselinePath));
+    const currentPng = PNG.sync.read(await readFile(currentPath));
+    if (baselinePng.width !== currentPng.width ||
+        baselinePng.height !== currentPng.height) {
+        return {
+            name: "",
+            url: "",
+            diffPixels: 0,
+            totalPixels: 0,
+            diffPercent: 0,
+            passed: false,
+            error: `尺寸不匹配: baseline ${baselinePng.width}x${baselinePng.height}, current ${currentPng.width}x${currentPng.height}`,
+        };
+    }
+    const diff = new PNG({ width: baselinePng.width, height: baselinePng.height });
+    const diffPixels = pixelmatch(baselinePng.data, currentPng.data, diff.data, baselinePng.width, baselinePng.height, { threshold: 0.1 });
+    const totalPixels = baselinePng.width * baselinePng.height;
+    const diffPercent = (diffPixels / totalPixels) * 100;
+    const passed = diffPercent <= threshold * 100;
+    await writeFile(diffOutputPath, PNG.sync.write(diff));
+    return {
+        name: "",
+        url: "",
+        diffPixels,
+        totalPixels,
+        diffPercent: Math.round(diffPercent * 100) / 100,
+        passed,
+        diffImagePath: diffOutputPath,
+    };
+}

package/dist/core/index.d.ts

@@ -0,0 +1,7 @@
+export type { SnapConfig, BaselineMeta, DiffResult } from "./types.js";
+export type { ProjectConfig } from "./config.js";
+export { loadConfig, defaultConfig } from "./config.js";
+export { captureSnapshot, captureSnapshotsParallel, type CaptureOptions, type CaptureResult } from "./capture.js";
+export { compareSnapshots, type DiffOptions } from "./diff.js";
+export { ensureDirs, baselineImagePath, baselineMetaPath, diffImagePath, saveBaselineMeta, loadBaselineMeta, baselineExists, listBaselines, } from "./storage.js";
+export { generateTextReport, generateReportSummary, generateHtmlReport } from "./reporter.js";

package/dist/core/index.js

@@ -0,0 +1,5 @@
+export { loadConfig, defaultConfig } from "./config.js";
+export { captureSnapshot, captureSnapshotsParallel } from "./capture.js";
+export { compareSnapshots } from "./diff.js";
+export { ensureDirs, baselineImagePath, baselineMetaPath, diffImagePath, saveBaselineMeta, loadBaselineMeta, baselineExists, listBaselines, } from "./storage.js";
+export { generateTextReport, generateReportSummary, generateHtmlReport } from "./reporter.js";

package/dist/core/reporter.d.ts

@@ -0,0 +1,8 @@
+import { DiffResult } from "./types.js";
+export interface ReportOptions {
+    results: DiffResult[];
+    verbose?: boolean;
+}
+export declare function generateTextReport(options: ReportOptions): string;
+export declare function generateReportSummary(results: DiffResult[]): string;
+export declare function generateHtmlReport(results: DiffResult[], cwd: string): Promise<string>;

package/dist/core/reporter.js

@@ -0,0 +1,164 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+export function generateTextReport(options) {
+    const { results } = options;
+    const lines = [];
+    for (const result of results) {
+        if (result.error) {
+            lines.push(`\n  ⚠  ${result.error}`);
+            continue;
+        }
+        if (result.passed) {
+            lines.push(`  ✅ ${result.name} ── 无变化 (差异 ${result.diffPercent}%)`);
+        }
+        else {
+            const bar = makePercentBar(result.diffPercent, 20);
+            lines.push(`  ❌ ${result.name}`);
+            lines.push(`     ${bar} ${result.diffPercent}% (${result.diffPixels} 像素)`);
+            if (result.diffImagePath) {
+                lines.push(`     📄 diff 图: ${result.diffImagePath}`);
+            }
+            lines.push(`     如果这是预期的变更, 请运行: npx snapdiff approve ${result.name}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function generateReportSummary(results) {
+    if (results.length === 0) {
+        return "\n  ℹ 没有页面需要对比。";
+    }
+    const total = results.length;
+    const passed = results.filter((r) => r.passed && !r.error).length;
+    const failed = results.filter((r) => !r.passed && !r.error).length;
+    const errored = results.filter((r) => r.error).length;
+    const summary = `\n  📊 摘要: ${total} 个页面, ${passed} 通过, ${failed} 失败, ${errored} 错误`;
+    return summary + (failed > 0
+        ? `\n  失败页面:\n${results.filter(r => !r.passed && !r.error).map(r => `    ❌ ${r.name} (${r.diffPercent}%)`).join("\n")}`
+        : "");
+}
+export async function generateHtmlReport(results, cwd) {
+    const reportDir = ".snapdiff/reports";
+    const absReportDir = reportDir; // relative to cwd
+    if (!existsSync(absReportDir)) {
+        await mkdir(absReportDir, { recursive: true });
+    }
+    const timestamp = Math.floor(Date.now() / 1000);
+    const reportPath = `${absReportDir}/report-${timestamp}.html`;
+    // Edge case: no results
+    if (results.length === 0) {
+        const html = `<!DOCTYPE html>
+<html lang="zh-CN">
+<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0">
+<title>snapdiff 报告</title>
+<style>body{font-family:-apple-system,sans-serif;background:#f5f5f5;padding:40px;text-align:center;color:#666;}
+h1{font-size:24px;color:#333;}p{font-size:14px;margin-top:8px;}
+</style></head>
+<body><h1>无对比结果</h1><p>没有页面需要对比，请确认基线截图是否存在。</p></body></html>`;
+        await writeFile(reportPath, html, "utf-8");
+        return reportPath;
+    }
+    let cardsHtml = "";
+    let passedCount = 0;
+    let failedCount = 0;
+    for (const r of results) {
+        if (r.error) {
+            cardsHtml += `<div class="card error"><h3>⚠ ${r.name}</h3><p>${r.error}</p></div>`;
+            continue;
+        }
+        const status = r.passed ? "passed" : "failed";
+        if (r.passed)
+            passedCount++;
+        else
+            failedCount++;
+        let diffImgHtml = "";
+        if (r.diffImagePath && !r.passed) {
+            try {
+                const diffBuf = await readFile(r.diffImagePath);
+                const b64 = diffBuf.toString("base64");
+                diffImgHtml = `<img src="data:image/png;base64,${b64}" alt="diff" class="diff-img" />`;
+            }
+            catch {
+                diffImgHtml = `<p class="dim">diff 图不可用</p>`;
+            }
+        }
+        const bar = makePercentBar(r.diffPercent, 30);
+        cardsHtml += `
+<div class="card ${status}">
+  <div class="card-header">
+    <span class="status-badge ${status}">${r.passed ? "✅" : "❌"}</span>
+    <span class="name">${r.name}</span>
+    <span class="url">${r.url}</span>
+  </div>
+  <div class="card-body">
+    <div class="stat-row">
+      <span>差异比例</span>
+      <span class="stat-value">${r.diffPercent}%</span>
+    </div>
+    <div class="stat-row">
+      <span>差异像素</span>
+      <span class="stat-value">${r.diffPixels.toLocaleString()} / ${r.totalPixels.toLocaleString()}</span>
+    </div>
+    <div class="bar-container">${bar}</div>
+    ${diffImgHtml}
+  </div>
+</div>`;
+    }
+    const html = `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>snapdiff 视觉回归报告</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box;}
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:#f5f5f5;color:#1a1a1a;padding:24px;}
+.header{max-width:800px;margin:0 auto 24px;}
+.header h1{font-size:24px;font-weight:600;}
+.header .meta{color:#666;font-size:14px;margin-top:4px;}
+.summary{display:flex;gap:16px;max-width:800px;margin:0 auto 24px;}
+.summary-item{flex:1;background:white;border-radius:8px;padding:16px;text-align:center;box-shadow:0 1px 3px rgba(0,0,0,0.08);}
+.summary-item .num{font-size:32px;font-weight:700;}
+.summary-item .label{font-size:13px;color:#666;margin-top:4px;}
+.summary-item.total .num{color:#333;}
+.summary-item.passed .num{color:#22c55e;}
+.summary-item.failed .num{color:#ef4444;}
+.cards{max-width:800px;margin:0 auto;}
+.card{background:white;border-radius:8px;margin-bottom:16px;box-shadow:0 1px 3px rgba(0,0,0,0.08);overflow:hidden;}
+.card.passed{border-left:4px solid #22c55e;}
+.card.failed{border-left:4px solid #ef4444;}
+.card.error{border-left:4px solid #f59e0b;}
+.card-header{display:flex;align-items:center;gap:8px;padding:12px 16px;border-bottom:1px solid #f0f0f0;}
+.status-badge{font-size:18px;}
+.name{font-weight:600;font-size:15px;}
+.url{color:#666;font-size:13px;margin-left:auto;}
+.card-body{padding:16px;}
+.stat-row{display:flex;justify-content:space-between;padding:4px 0;font-size:14px;}
+.stat-value{font-weight:600;}
+.bar-container{margin:8px 0;font-family:"SF Mono","Fira Code",monospace;font-size:13px;color:#666;}
+.diff-img{width:100%;max-width:600px;margin-top:12px;border:1px solid #e0e0e0;border-radius:4px;}
+.dim{color:#999;font-size:13px;}
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>snapdiff 视觉回归报告</h1>
+  <div class="meta">${new Date().toLocaleString("zh-CN")} · 共 ${results.length} 个页面</div>
+</div>
+<div class="summary">
+  <div class="summary-item total"><div class="num">${results.length}</div><div class="label">总页面</div></div>
+  <div class="summary-item passed"><div class="num">${passedCount}</div><div class="label">通过</div></div>
+  <div class="summary-item failed"><div class="num">${failedCount}</div><div class="label">失败</div></div>
+</div>
+<div class="cards">${cardsHtml}</div>
+</body>
+</html>`;
+    await writeFile(reportPath, html, "utf-8");
+    return reportPath;
+}
+function makePercentBar(percent, width) {
+    const filled = Math.round((percent / 100) * width);
+    const empty = width - filled;
+    const fillChar = "█";
+    const emptyChar = "░";
+    return fillChar.repeat(Math.min(filled, width)) + emptyChar.repeat(Math.max(empty, 0));
+}

package/dist/core/storage.d.ts

@@ -0,0 +1,13 @@
+export { existsSync, mkdirSync } from "node:fs";
+import { BaselineMeta } from "./types.js";
+export declare function ensureDirs(cwd: string): Promise<void>;
+export declare function baselineImagePath(cwd: string, name: string): string;
+export declare function baselineMetaPath(cwd: string, name: string): string;
+export declare function diffImagePath(cwd: string, name: string, timestamp: string): string;
+export declare function saveBaselineMeta(cwd: string, name: string, meta: BaselineMeta): Promise<void>;
+export declare function loadBaselineMeta(cwd: string, name: string): Promise<BaselineMeta | null>;
+export declare function baselineExists(cwd: string, name: string): Promise<boolean>;
+export declare function listBaselines(cwd: string): Promise<Array<{
+    name: string;
+    meta: BaselineMeta | null;
+}>>;

package/dist/core/storage.js

@@ -0,0 +1,69 @@
+export { existsSync, mkdirSync } from "node:fs";
+import { mkdir, readFile, writeFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+const BASELINE_DIR = ".snapdiff/baselines";
+const DIFF_DIR = ".snapdiff/diffs";
+const CONFIG_DIR = ".snapdiff";
+export async function ensureDirs(cwd) {
+    const dirs = [
+        join(cwd, CONFIG_DIR),
+        join(cwd, BASELINE_DIR),
+        join(cwd, DIFF_DIR),
+    ];
+    for (const dir of dirs) {
+        if (!existsSync(dir)) {
+            await mkdir(dir, { recursive: true });
+        }
+    }
+}
+export function baselineImagePath(cwd, name) {
+    return join(cwd, BASELINE_DIR, `${name}.png`);
+}
+export function baselineMetaPath(cwd, name) {
+    return join(cwd, BASELINE_DIR, `${name}.json`);
+}
+export function diffImagePath(cwd, name, timestamp) {
+    return join(cwd, DIFF_DIR, `${name}-${timestamp}-diff.png`);
+}
+export async function saveBaselineMeta(cwd, name, meta) {
+    const dir = join(cwd, BASELINE_DIR);
+    if (!existsSync(dir)) {
+        await mkdir(dir, { recursive: true });
+    }
+    await writeFile(baselineMetaPath(cwd, name), JSON.stringify(meta, null, 2));
+}
+export async function loadBaselineMeta(cwd, name) {
+    const path = baselineMetaPath(cwd, name);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = await readFile(path, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function baselineExists(cwd, name) {
+    return existsSync(baselineImagePath(cwd, name));
+}
+export async function listBaselines(cwd) {
+    const dir = join(cwd, BASELINE_DIR);
+    if (!existsSync(dir))
+        return [];
+    try {
+        const files = await readdir(dir);
+        const pngFiles = files.filter((f) => f.endsWith(".png"));
+        const results = [];
+        for (const file of pngFiles) {
+            const name = file.replace(/\.png$/, "");
+            const meta = await loadBaselineMeta(cwd, name);
+            results.push({ name, meta });
+        }
+        return results;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,37 @@
+export interface SnapConfig {
+    name: string;
+    url: string;
+    selector?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    threshold?: number;
+    maskRegions?: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+}
+export interface BaselineMeta {
+    name: string;
+    url: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    selector?: string;
+    capturedAt: string;
+    contentHash: string;
+}
+export interface DiffResult {
+    name: string;
+    url: string;
+    diffPixels: number;
+    totalPixels: number;
+    diffPercent: number;
+    passed: boolean;
+    diffImagePath?: string;
+    error?: string;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import pc from "picocolors";
+import { initCommand } from "./commands/init.js";
+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
+process.on("unhandledRejection", (err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(pc.red(`\n  ⚠ 意外错误: ${msg}`));
+    console.error(pc.dim(`  如需帮助，请提供以上完整输出来排查问题。`));
+    process.exit(1);
+});
+process.on("uncaughtException", (err) => {
+    console.error(pc.red(`\n  ⚠ 意外错误: ${err.message}`));
+    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");
+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`))
+    .action((opts) => {
+    // If stdin is not a TTY and --yes not given, auto-enable --yes to avoid hanging
+    if (!isInteractive && !opts.yes) {
+        opts.yes = true;
+    }
+    initCommand(opts);
+});
+program
+    .command("capture")
+    .description("截取当前页面作为基线截图")
+    .argument("[url]", "页面 URL")
+    .option("-n, --name <name>", "截图名称")
+    .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`))
+    .action(captureCommand);
+program
+    .command("diff")
+    .description("对比当前页面与基线截图")
+    .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`))
+    .action(diffCommand);
+program
+    .command("approve")
+    .description("接受当前差异为新基线（覆盖旧基线）")
+    .argument("<name>", "截图名称（必填）")
+    .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`))
+    .action(statusCommand);
+program.addHelpText("afterAll", `
+${pc.bold("快速开始")}:
+  $ snapdiff init                    首次运行，走一遍向导
+  $ snapdiff diff                    改完代码后对比变化
+
+${pc.bold("典型工作流")}:
+  1. ${pc.dim("snapdiff init")}             初始化项目，自动截取首张基线
+  2. ${pc.dim("修改代码")}                    改你的 CSS/组件/页面
+  3. ${pc.dim("snapdiff diff")}             对比变化，查看差异
+  4. ${pc.dim("snapdiff approve <name>")}   确认变更，更新基线
+
+${pc.dim("完整文档: https://github.com/your-org/snapdiff")}
+`);
+program.parse(process.argv);

package/dist/test-import.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test-import.js

@@ -0,0 +1,4 @@
+import { baselineImagePath } from "@snapdiff/core";
+// Just test the type
+const x = baselineImagePath("/tmp", "test");
+console.log(x);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "snapdiff-cli",
+  "version": "0.1.0",
+  "description": "?????????????",
+  "type": "module",
+  "bin": {
+    "snapdiff": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "playwright": "^1.52.0",
+    "pixelmatch": "^6.0.0",
+    "pngjs": "^7.0.0",
+    "commander": "^13.0.0",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pngjs": "^6.0.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}