git-shots-cli 0.1.1 → 0.2.0

package/dist/index.js

@@ -216,6 +216,233 @@ async function pullBaselines(config, options) {
   console.log(chalk4.green(`Downloaded ${downloaded} baselines to ${outputDir}`));
 }
 
+// src/review.ts
+import { execSync as execSync2 } from "child_process";
+import { platform } from "os";
+import chalk5 from "chalk";
+function openBrowser(url) {
+  try {
+    const os = platform();
+    if (os === "win32") {
+      execSync2(`start "" "${url}"`, { stdio: "ignore" });
+    } else if (os === "darwin") {
+      execSync2(`open "${url}"`, { stdio: "ignore" });
+    } else {
+      execSync2(`xdg-open "${url}"`, { stdio: "ignore" });
+    }
+  } catch {
+    console.log(chalk5.dim(`Could not open browser. Visit the URL manually.`));
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve5) => setTimeout(resolve5, ms));
+}
+async function review(config, options) {
+  const shouldOpen = options.open ?? true;
+  const shouldPoll = options.poll ?? true;
+  const timeoutSec = options.timeout ?? 300;
+  const branch = options.branch ?? execSync2("git rev-parse --abbrev-ref HEAD", { encoding: "utf-8" }).trim();
+  const sha = options.sha ?? execSync2("git rev-parse HEAD", { encoding: "utf-8" }).trim();
+  console.log(chalk5.dim(`Project: ${config.project}`));
+  console.log(chalk5.dim(`Branch:  ${branch}`));
+  console.log(chalk5.dim(`SHA:     ${sha.slice(0, 7)}`));
+  console.log();
+  console.log(chalk5.dim("Uploading screenshots..."));
+  await upload(config, { branch, sha });
+  console.log();
+  console.log(chalk5.dim("Creating review session..."));
+  const reviewUrl = `${config.server}/api/reviews`;
+  let reviewData;
+  try {
+    const res = await fetch(reviewUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Origin: config.server },
+      body: JSON.stringify({
+        project: config.project,
+        branch,
+        gitSha: sha
+      })
+    });
+    const data = await res.json();
+    if (!res.ok) {
+      console.error(chalk5.red(`Failed to create review: ${JSON.stringify(data)}`));
+      process.exit(1);
+    }
+    reviewData = data;
+  } catch (err) {
+    console.error(chalk5.red(`Request failed: ${err}`));
+    process.exit(1);
+  }
+  const allZero = reviewData.diffs.length === 0 || reviewData.diffs.every((d) => d.mismatchPercentage === 0);
+  if (allZero) {
+    console.log(chalk5.green("No visual changes detected."));
+    process.exit(0);
+  }
+  const sessionUrl = `${config.server}/reviews/${reviewData.review.id}`;
+  console.log();
+  console.log(chalk5.bold("Visual changes detected:"));
+  console.log();
+  for (const d of reviewData.diffs) {
+    const pct = d.mismatchPercentage.toFixed(2) + "%";
+    const color = d.mismatchPercentage > 10 ? chalk5.red : d.mismatchPercentage > 1 ? chalk5.yellow : chalk5.green;
+    console.log(`  ${d.screen.padEnd(30)} ${color(pct)}`);
+  }
+  console.log();
+  console.log(`Review: ${chalk5.cyan(sessionUrl)}`);
+  if (shouldOpen) {
+    openBrowser(sessionUrl);
+  }
+  if (!shouldPoll) {
+    return;
+  }
+  console.log();
+  console.log(chalk5.dim(`Polling for verdict (timeout: ${timeoutSec}s)...`));
+  const pollInterval = 3e3;
+  const startTime = Date.now();
+  const deadline = startTime + timeoutSec * 1e3;
+  while (Date.now() < deadline) {
+    await sleep(pollInterval);
+    try {
+      const res = await fetch(`${config.server}/api/reviews/${reviewData.review.id}`, {
+        headers: { Origin: config.server }
+      });
+      const data = await res.json();
+      if (!res.ok) continue;
+      if (data.review.status === "approved") {
+        console.log();
+        console.log(chalk5.green.bold("Review approved!"));
+        process.exit(0);
+      }
+      if (data.review.status === "rejected") {
+        console.log();
+        console.log(chalk5.red.bold("Review rejected."));
+        const rejected = data.diffs.filter((d) => d.status === "rejected");
+        if (rejected.length > 0) {
+          console.log(chalk5.dim("Rejected screens:"));
+          for (const d of rejected) {
+            console.log(chalk5.red(`  - ${d.base.screen_slug}`));
+          }
+        }
+        process.exit(1);
+      }
+    } catch {
+    }
+  }
+  console.log();
+  console.log(chalk5.yellow(`Review timed out after ${timeoutSec}s.`));
+  console.log(chalk5.dim(`Visit ${sessionUrl} to complete the review.`));
+  process.exit(2);
+}
+
+// src/hook.ts
+import { existsSync as existsSync3, writeFileSync as writeFileSync2, unlinkSync, chmodSync, readFileSync as readFileSync3 } from "fs";
+import { resolve as resolve4, join } from "path";
+import { execSync as execSync3 } from "child_process";
+import chalk6 from "chalk";
+var HOOK_MARKER = "# git-shots-hook";
+var HOOK_SCRIPT = `#!/bin/sh
+${HOOK_MARKER}
+# Pre-push hook: runs git-shots visual review before pushing.
+# Installed by: git-shots hook install
+
+# Skip if no .git-shots.json config
+if [ ! -f ".git-shots.json" ]; then
+  exit 0
+fi
+
+# Read screenshots directory from config (default: docs/screenshots/current)
+SCREENSHOTS_DIR=$(node -e "try{const c=JSON.parse(require('fs').readFileSync('.git-shots.json','utf-8'));console.log(c.directory||'docs/screenshots/current')}catch{console.log('docs/screenshots/current')}" 2>/dev/null)
+
+# Skip if no screenshots directory or no PNGs
+if [ ! -d "$SCREENSHOTS_DIR" ]; then
+  exit 0
+fi
+
+PNG_COUNT=$(find "$SCREENSHOTS_DIR" -name "*.png" 2>/dev/null | head -1)
+if [ -z "$PNG_COUNT" ]; then
+  exit 0
+fi
+
+# Skip on main/master \u2014 no base to diff against
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  exit 0
+fi
+
+echo ""
+echo "git-shots: Running visual review before push..."
+echo ""
+
+git-shots review
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 1 ]; then
+  echo ""
+  echo "git-shots: Visual review rejected. Push blocked."
+  exit 1
+fi
+
+if [ $EXIT_CODE -eq 2 ]; then
+  echo ""
+  echo "git-shots: Visual review timed out. Push allowed (review pending)."
+  exit 0
+fi
+
+exit 0
+`;
+function getGitDir(cwd) {
+  try {
+    return execSync3("git rev-parse --git-dir", { cwd, encoding: "utf-8" }).trim();
+  } catch {
+    throw new Error("Not a git repository");
+  }
+}
+async function hookInstall(cwd = process.cwd()) {
+  const gitDir = getGitDir(cwd);
+  const hooksDir = resolve4(cwd, gitDir, "hooks");
+  const hookPath = join(hooksDir, "pre-push");
+  if (existsSync3(hookPath)) {
+    const existing = readFileSync3(hookPath, "utf-8");
+    if (existing.includes(HOOK_MARKER)) {
+      console.log(chalk6.yellow("git-shots pre-push hook is already installed."));
+      return;
+    }
+    console.error(
+      chalk6.red("A pre-push hook already exists at ") + chalk6.dim(hookPath)
+    );
+    console.error(
+      chalk6.dim("Remove or rename it first, then re-run this command.")
+    );
+    process.exit(1);
+  }
+  writeFileSync2(hookPath, HOOK_SCRIPT, { mode: 493 });
+  try {
+    chmodSync(hookPath, 493);
+  } catch {
+  }
+  console.log(chalk6.green("Installed pre-push hook at ") + chalk6.dim(hookPath));
+  console.log();
+  console.log(chalk6.dim("The hook will run `git-shots review` before every push"));
+  console.log(chalk6.dim("when .git-shots.json is present and screenshots exist."));
+}
+async function hookUninstall(cwd = process.cwd()) {
+  const gitDir = getGitDir(cwd);
+  const hooksDir = resolve4(cwd, gitDir, "hooks");
+  const hookPath = join(hooksDir, "pre-push");
+  if (!existsSync3(hookPath)) {
+    console.log(chalk6.yellow("No pre-push hook found."));
+    return;
+  }
+  const existing = readFileSync3(hookPath, "utf-8");
+  if (!existing.includes(HOOK_MARKER)) {
+    console.error(chalk6.red("Pre-push hook exists but was not installed by git-shots."));
+    console.error(chalk6.dim("Remove it manually if you want: ") + chalk6.dim(hookPath));
+    process.exit(1);
+  }
+  unlinkSync(hookPath);
+  console.log(chalk6.green("Removed git-shots pre-push hook."));
+}
+
 // src/index.ts
 var program = new Command();
 program.name("git-shots").description("CLI for git-shots visual regression platform").version("0.1.0");
@@ -260,4 +487,28 @@ program.command("pull-baselines").description("Download baseline screenshots fro
   }
   await pullBaselines(config, { branch: options.branch, output: options.output });
 });
+program.command("review").description("Upload screenshots, create review session, and poll for verdict").option("-p, --project <slug>", "Project slug").option("-s, --server <url>", "Server URL").option("-d, --directory <path>", "Screenshots directory").option("-b, --branch <name>", "Git branch (auto-detected)").option("--sha <hash>", "Git SHA (auto-detected)").option("--open", "Open review URL in browser", true).option("--no-open", "Do not open review URL in browser").option("--poll", "Poll for verdict and exit with code", true).option("--no-poll", "Do not poll for verdict").option("--timeout <seconds>", "Polling timeout in seconds", parseInt, 300).action(async (options) => {
+  const config = loadConfig();
+  if (options.project) config.project = options.project;
+  if (options.server) config.server = options.server;
+  if (options.directory) config.directory = options.directory;
+  if (!config.project) {
+    console.error("Error: project slug required. Use --project or .git-shots.json");
+    process.exit(1);
+  }
+  await review(config, {
+    branch: options.branch,
+    sha: options.sha,
+    open: options.open,
+    poll: options.poll,
+    timeout: options.timeout
+  });
+});
+var hook = program.command("hook").description("Manage git hooks for automatic visual review");
+hook.command("install").description("Install a pre-push hook that runs git-shots review before each push").action(async () => {
+  await hookInstall();
+});
+hook.command("uninstall").description("Remove the git-shots pre-push hook").action(async () => {
+  await hookUninstall();
+});
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "git-shots-cli",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"description": "CLI for git-shots visual regression platform",
 	"type": "module",
 	"bin": {

package/src/hook.ts

@@ -0,0 +1,124 @@
+import { existsSync, writeFileSync, unlinkSync, chmodSync, readFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { execSync } from 'node:child_process';
+import chalk from 'chalk';
+
+const HOOK_MARKER = '# git-shots-hook';
+
+const HOOK_SCRIPT = `#!/bin/sh
+${HOOK_MARKER}
+# Pre-push hook: runs git-shots visual review before pushing.
+# Installed by: git-shots hook install
+
+# Skip if no .git-shots.json config
+if [ ! -f ".git-shots.json" ]; then
+  exit 0
+fi
+
+# Read screenshots directory from config (default: docs/screenshots/current)
+SCREENSHOTS_DIR=$(node -e "try{const c=JSON.parse(require('fs').readFileSync('.git-shots.json','utf-8'));console.log(c.directory||'docs/screenshots/current')}catch{console.log('docs/screenshots/current')}" 2>/dev/null)
+
+# Skip if no screenshots directory or no PNGs
+if [ ! -d "$SCREENSHOTS_DIR" ]; then
+  exit 0
+fi
+
+PNG_COUNT=$(find "$SCREENSHOTS_DIR" -name "*.png" 2>/dev/null | head -1)
+if [ -z "$PNG_COUNT" ]; then
+  exit 0
+fi
+
+# Skip on main/master — no base to diff against
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  exit 0
+fi
+
+echo ""
+echo "git-shots: Running visual review before push..."
+echo ""
+
+git-shots review
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 1 ]; then
+  echo ""
+  echo "git-shots: Visual review rejected. Push blocked."
+  exit 1
+fi
+
+if [ $EXIT_CODE -eq 2 ]; then
+  echo ""
+  echo "git-shots: Visual review timed out. Push allowed (review pending)."
+  exit 0
+fi
+
+exit 0
+`;
+
+function getGitDir(cwd: string): string {
+	try {
+		return execSync('git rev-parse --git-dir', { cwd, encoding: 'utf-8' }).trim();
+	} catch {
+		throw new Error('Not a git repository');
+	}
+}
+
+export async function hookInstall(cwd: string = process.cwd()) {
+	const gitDir = getGitDir(cwd);
+	const hooksDir = resolve(cwd, gitDir, 'hooks');
+	const hookPath = join(hooksDir, 'pre-push');
+
+	// Check if a pre-push hook already exists
+	if (existsSync(hookPath)) {
+		const existing = readFileSync(hookPath, 'utf-8');
+		if (existing.includes(HOOK_MARKER)) {
+			console.log(chalk.yellow('git-shots pre-push hook is already installed.'));
+			return;
+		}
+
+		// Another hook exists — don't overwrite
+		console.error(
+			chalk.red('A pre-push hook already exists at ') + chalk.dim(hookPath)
+		);
+		console.error(
+			chalk.dim('Remove or rename it first, then re-run this command.')
+		);
+		process.exit(1);
+	}
+
+	writeFileSync(hookPath, HOOK_SCRIPT, { mode: 0o755 });
+
+	// chmod on non-Windows (writeFileSync mode doesn't always stick)
+	try {
+		chmodSync(hookPath, 0o755);
+	} catch {
+		// Windows — mode already set via writeFileSync
+	}
+
+	console.log(chalk.green('Installed pre-push hook at ') + chalk.dim(hookPath));
+	console.log();
+	console.log(chalk.dim('The hook will run `git-shots review` before every push'));
+	console.log(chalk.dim('when .git-shots.json is present and screenshots exist.'));
+}
+
+export async function hookUninstall(cwd: string = process.cwd()) {
+	const gitDir = getGitDir(cwd);
+	const hooksDir = resolve(cwd, gitDir, 'hooks');
+	const hookPath = join(hooksDir, 'pre-push');
+
+	if (!existsSync(hookPath)) {
+		console.log(chalk.yellow('No pre-push hook found.'));
+		return;
+	}
+
+	const existing = readFileSync(hookPath, 'utf-8');
+	if (!existing.includes(HOOK_MARKER)) {
+		console.error(chalk.red('Pre-push hook exists but was not installed by git-shots.'));
+		console.error(chalk.dim('Remove it manually if you want: ') + chalk.dim(hookPath));
+		process.exit(1);
+	}
+
+	unlinkSync(hookPath);
+	console.log(chalk.green('Removed git-shots pre-push hook.'));
+}

package/src/index.ts

@@ -5,6 +5,8 @@ import { upload } from './upload.js';
 import { compare } from './compare.js';
 import { status } from './status.js';
 import { pullBaselines } from './pull-baselines.js';
+import { review } from './review.js';
+import { hookInstall, hookUninstall } from './hook.js';
 
 const program = new Command();
 
@@ -86,4 +88,53 @@ program
 		await pullBaselines(config, { branch: options.branch, output: options.output });
 	});
 
+program
+	.command('review')
+	.description('Upload screenshots, create review session, and poll for verdict')
+	.option('-p, --project <slug>', 'Project slug')
+	.option('-s, --server <url>', 'Server URL')
+	.option('-d, --directory <path>', 'Screenshots directory')
+	.option('-b, --branch <name>', 'Git branch (auto-detected)')
+	.option('--sha <hash>', 'Git SHA (auto-detected)')
+	.option('--open', 'Open review URL in browser', true)
+	.option('--no-open', 'Do not open review URL in browser')
+	.option('--poll', 'Poll for verdict and exit with code', true)
+	.option('--no-poll', 'Do not poll for verdict')
+	.option('--timeout <seconds>', 'Polling timeout in seconds', parseInt, 300)
+	.action(async (options) => {
+		const config = loadConfig();
+		if (options.project) config.project = options.project;
+		if (options.server) config.server = options.server;
+		if (options.directory) config.directory = options.directory;
+		if (!config.project) {
+			console.error('Error: project slug required. Use --project or .git-shots.json');
+			process.exit(1);
+		}
+		await review(config, {
+			branch: options.branch,
+			sha: options.sha,
+			open: options.open,
+			poll: options.poll,
+			timeout: options.timeout
+		});
+	});
+
+const hook = program
+	.command('hook')
+	.description('Manage git hooks for automatic visual review');
+
+hook
+	.command('install')
+	.description('Install a pre-push hook that runs git-shots review before each push')
+	.action(async () => {
+		await hookInstall();
+	});
+
+hook
+	.command('uninstall')
+	.description('Remove the git-shots pre-push hook')
+	.action(async () => {
+		await hookUninstall();
+	});
+
 program.parse();

package/src/review.ts

@@ -0,0 +1,199 @@
+import { execSync } from 'node:child_process';
+import { platform } from 'node:os';
+import chalk from 'chalk';
+import type { GitShotsConfig } from './config.js';
+import { upload } from './upload.js';
+
+interface ReviewOptions {
+	branch?: string;
+	sha?: string;
+	open?: boolean;
+	poll?: boolean;
+	timeout?: number;
+}
+
+interface ReviewResponse {
+	review: {
+		id: number;
+		status: string;
+		url: string;
+	};
+	diffs: Array<{
+		screen: string;
+		mismatchPercentage: number;
+		mismatchPixels: number;
+	}>;
+}
+
+interface ReviewStatusResponse {
+	review: {
+		id: number;
+		status: string;
+	};
+	diffs: Array<{
+		base: { screen_slug: string };
+		mismatch_percentage: number;
+		status: string;
+	}>;
+}
+
+function openBrowser(url: string): void {
+	try {
+		const os = platform();
+		if (os === 'win32') {
+			execSync(`start "" "${url}"`, { stdio: 'ignore' });
+		} else if (os === 'darwin') {
+			execSync(`open "${url}"`, { stdio: 'ignore' });
+		} else {
+			execSync(`xdg-open "${url}"`, { stdio: 'ignore' });
+		}
+	} catch {
+		console.log(chalk.dim(`Could not open browser. Visit the URL manually.`));
+	}
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function review(config: GitShotsConfig, options: ReviewOptions) {
+	const shouldOpen = options.open ?? true;
+	const shouldPoll = options.poll ?? true;
+	const timeoutSec = options.timeout ?? 300;
+
+	// Get git info
+	const branch =
+		options.branch ??
+		execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf-8' }).trim();
+	const sha =
+		options.sha ?? execSync('git rev-parse HEAD', { encoding: 'utf-8' }).trim();
+
+	console.log(chalk.dim(`Project: ${config.project}`));
+	console.log(chalk.dim(`Branch:  ${branch}`));
+	console.log(chalk.dim(`SHA:     ${sha.slice(0, 7)}`));
+	console.log();
+
+	// Step 1: Upload screenshots
+	console.log(chalk.dim('Uploading screenshots...'));
+	await upload(config, { branch, sha });
+	console.log();
+
+	// Step 2: Create review session via POST /api/reviews
+	console.log(chalk.dim('Creating review session...'));
+
+	const reviewUrl = `${config.server}/api/reviews`;
+	let reviewData: ReviewResponse;
+
+	try {
+		const res = await fetch(reviewUrl, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json', Origin: config.server },
+			body: JSON.stringify({
+				project: config.project,
+				branch,
+				gitSha: sha
+			})
+		});
+		const data = await res.json();
+
+		if (!res.ok) {
+			console.error(chalk.red(`Failed to create review: ${JSON.stringify(data)}`));
+			process.exit(1);
+		}
+
+		reviewData = data as ReviewResponse;
+	} catch (err) {
+		console.error(chalk.red(`Request failed: ${err}`));
+		process.exit(1);
+	}
+
+	// Step 3: Check if all diffs are 0% mismatch
+	const allZero =
+		reviewData.diffs.length === 0 ||
+		reviewData.diffs.every((d) => d.mismatchPercentage === 0);
+
+	if (allZero) {
+		console.log(chalk.green('No visual changes detected.'));
+		process.exit(0);
+	}
+
+	// Step 4: Print review URL and diff summary
+	const sessionUrl = `${config.server}/reviews/${reviewData.review.id}`;
+	console.log();
+	console.log(chalk.bold('Visual changes detected:'));
+	console.log();
+
+	for (const d of reviewData.diffs) {
+		const pct = d.mismatchPercentage.toFixed(2) + '%';
+		const color =
+			d.mismatchPercentage > 10
+				? chalk.red
+				: d.mismatchPercentage > 1
+					? chalk.yellow
+					: chalk.green;
+		console.log(`  ${d.screen.padEnd(30)} ${color(pct)}`);
+	}
+
+	console.log();
+	console.log(`Review: ${chalk.cyan(sessionUrl)}`);
+
+	// Step 5: Open in browser
+	if (shouldOpen) {
+		openBrowser(sessionUrl);
+	}
+
+	// Step 6: Poll for verdict
+	if (!shouldPoll) {
+		return;
+	}
+
+	console.log();
+	console.log(chalk.dim(`Polling for verdict (timeout: ${timeoutSec}s)...`));
+
+	const pollInterval = 3000;
+	const startTime = Date.now();
+	const deadline = startTime + timeoutSec * 1000;
+
+	while (Date.now() < deadline) {
+		await sleep(pollInterval);
+
+		try {
+			const res = await fetch(`${config.server}/api/reviews/${reviewData.review.id}`, {
+				headers: { Origin: config.server }
+			});
+			const data = (await res.json()) as ReviewStatusResponse;
+
+			if (!res.ok) continue;
+
+			if (data.review.status === 'approved') {
+				console.log();
+				console.log(chalk.green.bold('Review approved!'));
+				process.exit(0);
+			}
+
+			if (data.review.status === 'rejected') {
+				console.log();
+				console.log(chalk.red.bold('Review rejected.'));
+
+				// Show which screens had issues
+				const rejected = data.diffs.filter((d) => d.status === 'rejected');
+				if (rejected.length > 0) {
+					console.log(chalk.dim('Rejected screens:'));
+					for (const d of rejected) {
+						console.log(chalk.red(`  - ${d.base.screen_slug}`));
+					}
+				}
+
+				process.exit(1);
+			}
+		} catch {
+			// Network error — keep polling
+		}
+	}
+
+	// Timeout
+	console.log();
+	console.log(chalk.yellow(`Review timed out after ${timeoutSec}s.`));
+	console.log(chalk.dim(`Visit ${sessionUrl} to complete the review.`));
+	process.exit(2);
+}