frameshot-mcp 0.3.0 → 0.7.0

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+import {
+  BrowserPool,
+  CatalogUseCase,
+  DiffUseCase,
+  EXT_TO_FRAMEWORK,
+  HtmlBuilder,
+  ImageComparator,
+  RenderUseCase,
+  ViteBundler
+} from "./chunk-Q7A3DLED.js";
+
+// src/cli.ts
+import { execFileSync, execSync } from "child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { basename, extname, relative, resolve } from "path";
+var c = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  italic: "\x1B[3m",
+  purple: "\x1B[38;2;139;92;246m",
+  violet: "\x1B[38;2;167;139;250m",
+  blue: "\x1B[38;2;96;165;250m",
+  cyan: "\x1B[38;2;103;232;249m",
+  green: "\x1B[38;2;74;222;128m",
+  red: "\x1B[38;2;248;113;113m",
+  yellow: "\x1B[38;2;250;204;21m",
+  gray: "\x1B[38;2;113;113;122m",
+  white: "\x1B[38;2;250;250;250m",
+  bgPurple: "\x1B[48;2;139;92;246m"
+};
+var FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+function brand() {
+  return `${c.purple}${c.bold}\u25C6${c.reset} ${c.purple}${c.bold}frameshot${c.reset}`;
+}
+function log(msg) {
+  process.stderr.write(`${msg}
+`);
+}
+function error(msg) {
+  log(`
+  ${c.red}${c.bold}\u2716${c.reset} ${c.red}${msg}${c.reset}
+`);
+  process.exit(1);
+}
+function info(label, value) {
+  log(`  ${c.gray}${label.padEnd(6)}${c.reset} ${value}`);
+}
+function spinner(text) {
+  let i = 0;
+  const interval = setInterval(() => {
+    process.stderr.write(
+      `\r  ${c.purple}${FRAMES[i % FRAMES.length]}${c.reset} ${c.dim}${text}${c.reset}`
+    );
+    i++;
+  }, 80);
+  return {
+    stop(finalText) {
+      clearInterval(interval);
+      process.stderr.write(`\r  ${c.green}\u2713${c.reset} ${finalText}\x1B[K
+`);
+    }
+  };
+}
+function separator() {
+  log(`  ${c.gray}${"\u2500".repeat(48)}${c.reset}`);
+}
+function supportsItermImage() {
+  const term = process.env.TERM_PROGRAM ?? "";
+  return term === "iTerm.app" || term === "WezTerm" || !!process.env.TERM_PROGRAM_VERSION?.includes("iTerm") || term === "vscode";
+}
+function supportsKitty() {
+  const term = process.env.TERM ?? "";
+  return term.includes("kitty") || !!process.env.KITTY_PID;
+}
+function centerPad(imageWidthCols) {
+  const termWidth = process.stdout.columns ?? 80;
+  const leftPad = Math.max(0, Math.floor((termWidth - imageWidthCols) / 2));
+  return " ".repeat(leftPad);
+}
+function displayImage(base64, filePath) {
+  if (process.env.FRAMESHOT_NO_IMAGE) return;
+  const IMAGE_COLS = 40;
+  const pad = centerPad(IMAGE_COLS);
+  if (supportsItermImage()) {
+    const osc = `\x1B]1337;File=inline=1;width=${IMAGE_COLS};preserveAspectRatio=1:${base64}\x07`;
+    process.stdout.write(`${pad}${osc}
+`);
+    return;
+  }
+  if (supportsKitty()) {
+    try {
+      const output = execFileSync(
+        "chafa",
+        ["--format=kitty", "--size=40x", filePath],
+        { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
+      );
+      const indented = output.split("\n").map((l) => l ? pad + l : l).join("\n");
+      process.stdout.write(`${indented}
+`);
+      return;
+    } catch {
+    }
+  }
+  try {
+    const output = execFileSync(
+      "chafa",
+      ["--format=sixels", "--size=40x", filePath],
+      { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
+    );
+    const indented = output.split("\n").map((l) => l ? pad + l : l).join("\n");
+    process.stdout.write(`${indented}
+`);
+    return;
+  } catch {
+  }
+  try {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    execFileSync(cmd, [filePath], { stdio: "pipe" });
+  } catch {
+  }
+}
+function parseArgs(args) {
+  const command = args[0] ?? "help";
+  const positional = args[1] ?? "";
+  const flags = {
+    out: ".frameshot",
+    recursive: false
+  };
+  for (let i = 2; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case "--props":
+        try {
+          flags.props = JSON.parse(args[++i]);
+        } catch {
+          error("Invalid --props JSON");
+        }
+        break;
+      case "--out":
+      case "-o":
+        flags.out = args[++i];
+        break;
+      case "--recursive":
+      case "-r":
+        flags.recursive = true;
+        break;
+      case "--width":
+        flags.width = Number.parseInt(args[++i], 10);
+        break;
+      case "--height":
+        flags.height = Number.parseInt(args[++i], 10);
+        break;
+    }
+  }
+  return { command, positional, flags };
+}
+var HELP = `
+  ${brand()} ${c.dim}v0.7.0${c.reset}
+  ${c.dim}Zero-config component screenshots \u2014 Vite + Playwright${c.reset}
+
+  ${c.white}${c.bold}Commands${c.reset}
+    ${c.blue}render${c.reset} ${c.dim}<file>${c.reset}          Render a component to PNG
+    ${c.blue}catalog${c.reset} ${c.dim}<dir>${c.reset}          Render all components in a directory
+    ${c.blue}diff${c.reset} ${c.dim}<file>${c.reset}             Visual diff against git HEAD
+
+  ${c.white}${c.bold}Options${c.reset}
+    ${c.purple}--props${c.reset} ${c.dim}'{...}'${c.reset}            Component props (JSON)
+    ${c.purple}--out${c.reset}, ${c.purple}-o${c.reset} ${c.dim}<dir>${c.reset}            Output directory ${c.gray}[.frameshot]${c.reset}
+    ${c.purple}--recursive${c.reset}, ${c.purple}-r${c.reset}            Scan subdirectories
+    ${c.purple}--width${c.reset} ${c.dim}<px>${c.reset}                Viewport width ${c.gray}[auto]${c.reset}
+    ${c.purple}--height${c.reset} ${c.dim}<px>${c.reset}               Viewport height ${c.gray}[auto]${c.reset}
+
+  ${c.white}${c.bold}Examples${c.reset}
+    ${c.gray}$${c.reset} frameshot render src/Button.tsx
+    ${c.gray}$${c.reset} frameshot render src/Card.tsx ${c.purple}--props${c.reset} '{"title":"Hi"}'
+    ${c.gray}$${c.reset} frameshot catalog src/components/ ${c.purple}-r${c.reset}
+    ${c.gray}$${c.reset} frameshot diff src/Header.tsx
+
+  ${c.dim}Supports: React \xB7 Vue \xB7 Svelte \xB7 Tailwind \xB7 CSS Modules${c.reset}
+  ${c.dim}Display:  iTerm2 \xB7 Kitty \xB7 Sixel \xB7 fallback to open${c.reset}
+
+`;
+async function main() {
+  const { command, positional, flags } = parseArgs(process.argv.slice(2));
+  if (command === "help" || command === "--help" || command === "-h") {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (!positional) {
+    error(
+      `Missing argument. Run ${c.dim}frameshot --help${c.reset} for usage.`
+    );
+  }
+  log(`
+  ${brand()} ${c.dim}v0.7.0${c.reset}
+`);
+  const pool = new BrowserPool();
+  const htmlBuilder = new HtmlBuilder();
+  const imageComparator = new ImageComparator();
+  const viteBundler = new ViteBundler();
+  const renderUseCase = new RenderUseCase(
+    pool,
+    htmlBuilder,
+    imageComparator,
+    viteBundler
+  );
+  const catalogUseCase = new CatalogUseCase(renderUseCase);
+  const diffUseCase = new DiffUseCase(renderUseCase, imageComparator);
+  const outDir = resolve(flags.out);
+  mkdirSync(outDir, { recursive: true });
+  try {
+    await pool.warmup(["chromium"]);
+    switch (command) {
+      case "render":
+        await cmdRender(renderUseCase, positional, flags, outDir);
+        break;
+      case "catalog":
+        await cmdCatalog(catalogUseCase, positional, flags, outDir);
+        break;
+      case "diff":
+        await cmdDiff(diffUseCase, positional, flags, outDir);
+        break;
+      default:
+        error(
+          `Unknown command '${command}'. Run ${c.dim}frameshot --help${c.reset} for usage.`
+        );
+    }
+  } finally {
+    await viteBundler.shutdown();
+    await pool.shutdown();
+  }
+  log("");
+}
+async function cmdRender(useCase, filePath, flags, outDir) {
+  const absPath = resolve(filePath);
+  const relPath = relative(process.cwd(), absPath);
+  info("file", `${c.white}${relPath}${c.reset}`);
+  if (flags.width !== void 0 && flags.height !== void 0) {
+    info("size", `${c.cyan}${flags.width}\xD7${flags.height}${c.reset}`);
+  } else {
+    info("size", `${c.dim}auto${c.reset}`);
+  }
+  if (flags.props) {
+    info("props", `${c.dim}${JSON.stringify(flags.props)}${c.reset}`);
+  }
+  log("");
+  separator();
+  log("");
+  const autoFit = flags.width === void 0 || flags.height === void 0;
+  const s = spinner("Bundling with Vite & rendering...");
+  const start = performance.now();
+  const { results, mode } = await useCase.renderFile(absPath, {
+    props: flags.props,
+    viewport: {
+      width: flags.width ?? 1280,
+      height: flags.height ?? 800
+    },
+    autoFit,
+    fullPage: true,
+    engines: ["chromium"]
+  });
+  const result = results[0];
+  const elapsed = Math.round(performance.now() - start);
+  const outFile = resolve(
+    outDir,
+    `${basename(filePath, extname(filePath))}.png`
+  );
+  writeFileSync(outFile, Buffer.from(result.image, "base64"));
+  s.stop(`Rendered in ${c.white}${c.bold}${elapsed}ms${c.reset}`);
+  log("");
+  displayImage(result.image, outFile);
+  separator();
+  log("");
+  log(
+    `  ${c.green}${c.bold}\u25CF${c.reset} ${c.white}${relative(process.cwd(), outFile)}${c.reset}`
+  );
+  log(
+    `    ${c.dim}${result.width}\xD7${result.height}px \xB7 ${mode} pipeline \xB7 chromium${c.reset}`
+  );
+  const relevantErrors = result.consoleErrors.filter(
+    (e) => !e.includes("Failed to load resource")
+  );
+  if (relevantErrors.length) {
+    log(`
+  ${c.yellow}\u26A0${c.reset}  ${relevantErrors.join(`
+     `)}`);
+  }
+}
+async function cmdCatalog(useCase, dirPath, flags, outDir) {
+  const absDir = resolve(dirPath);
+  const relDir = relative(process.cwd(), absDir);
+  const start = performance.now();
+  info("dir", `${c.white}${relDir}/${c.reset}`);
+  info("mode", `${c.purple}vite${c.reset}`);
+  if (flags.recursive) info("scan", `${c.dim}recursive${c.reset}`);
+  log("");
+  separator();
+  log("");
+  const s = spinner("Scanning & rendering components...");
+  const results = await useCase.renderCatalog(absDir, {
+    recursive: flags.recursive,
+    viewport: { width: flags.width ?? 1280, height: flags.height ?? 800 },
+    autoFit: flags.width === void 0 || flags.height === void 0
+  });
+  if (results.length === 0) {
+    s.stop(`${c.dim}No component files found.${c.reset}`);
+    return;
+  }
+  s.stop(`Found ${c.white}${c.bold}${results.length}${c.reset} components`);
+  log("");
+  let rendered = 0;
+  for (const entry of results) {
+    const name = basename(entry.path, extname(entry.path));
+    if (!entry.image) {
+      log(`  ${c.red}\u2716${c.reset} ${c.dim}${name}${c.reset}`);
+      continue;
+    }
+    const outFile = resolve(outDir, `${name}.png`);
+    writeFileSync(outFile, Buffer.from(entry.image, "base64"));
+    log(`  ${c.green}\u25CF${c.reset} ${c.white}${name}${c.reset}`);
+    rendered++;
+  }
+  const elapsed = Math.round(performance.now() - start);
+  log("");
+  separator();
+  log("");
+  log(
+    `  ${c.green}${c.bold}${rendered}${c.reset}${c.dim}/${results.length} rendered in ${c.white}${elapsed}ms${c.dim} \u2192 ${relative(process.cwd(), outDir)}/${c.reset}`
+  );
+}
+async function cmdDiff(useCase, filePath, flags, outDir) {
+  const absPath = resolve(filePath);
+  const relPath = relative(process.cwd(), absPath);
+  info("file", `${c.white}${relPath}${c.reset}`);
+  info("base", `${c.violet}HEAD${c.reset}`);
+  log("");
+  separator();
+  log("");
+  const s = spinner("Comparing against HEAD...");
+  const start = performance.now();
+  let baseCode;
+  try {
+    const gitRelPath = relative(
+      execSync("git rev-parse --show-toplevel", { encoding: "utf-8" }).trim(),
+      absPath
+    );
+    baseCode = execSync(`git show HEAD:${gitRelPath}`, { encoding: "utf-8" });
+  } catch {
+    s.stop(`${c.red}Failed${c.reset}`);
+    error(
+      `Could not get HEAD version of ${relPath}. Is this file tracked by git?`
+    );
+  }
+  const currentCode = readFileSync(absPath, "utf-8");
+  const ext = extname(filePath).toLowerCase();
+  const framework = EXT_TO_FRAMEWORK[ext] ?? "react";
+  const result = await useCase.diffComponent(baseCode, currentCode, framework, {
+    viewport: { width: flags.width ?? 1280, height: flags.height ?? 800 },
+    autoFit: flags.width === void 0 || flags.height === void 0
+  });
+  const elapsed = Math.round(performance.now() - start);
+  const name = basename(filePath, extname(filePath));
+  writeFileSync(
+    resolve(outDir, `${name}_before.png`),
+    Buffer.from(result.before, "base64")
+  );
+  writeFileSync(
+    resolve(outDir, `${name}_after.png`),
+    Buffer.from(result.after, "base64")
+  );
+  writeFileSync(
+    resolve(outDir, `${name}_diff.png`),
+    Buffer.from(result.diff, "base64")
+  );
+  s.stop(`Compared in ${c.white}${c.bold}${elapsed}ms${c.reset}`);
+  log("");
+  displayImage(result.after, resolve(outDir, `${name}_after.png`));
+  separator();
+  log("");
+  if (result.diffPercentage === 0) {
+    log(
+      `  ${c.green}${c.bold}\u25CF${c.reset} ${c.green}Identical${c.reset} ${c.dim}\u2014 no visual changes detected${c.reset}`
+    );
+  } else {
+    const pct = result.diffPercentage.toFixed(1);
+    const bar = renderBar(result.diffPercentage);
+    log(
+      `  ${c.yellow}${c.bold}\u25CF${c.reset} ${c.yellow}${pct}% changed${c.reset}`
+    );
+    log(`    ${bar}`);
+    log("");
+    log(
+      `    ${c.dim}${name}_before.png \xB7 ${name}_after.png \xB7 ${name}_diff.png${c.reset}`
+    );
+  }
+}
+function renderBar(pct) {
+  const width = 30;
+  const filled = Math.round(pct / 100 * width);
+  const empty = width - filled;
+  return `${c.yellow}${"\u2588".repeat(filled)}${c.gray}${"\u2591".repeat(empty)}${c.reset} ${c.dim}${pct.toFixed(1)}%${c.reset}`;
+}
+main().catch((e) => {
+  error(e.message ?? String(e));
+});