litclaude-ai 0.3.3 → 0.3.6

package/plugins/litclaude/skills/lsp-setup/scripts/verify-lsp.ts

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+// verify-lsp.ts <file> [--timeout=ms] [--config=<path>] — perform a real LSP
+// diagnostics roundtrip for <file>: resolve the server for the file extension
+// (from plugins/litclaude/.lsp.json when present, else the embedded table),
+// spawn it, run the JSON-RPC initialize -> initialized -> didOpen handshake over
+// stdio, wait for textDocument/publishDiagnostics, and report OK / FAIL / SKIP.
+//
+// Dependency-free: uses only node:child_process and node:fs. No monorepo imports.
+//
+// Runtime: Node 22.6+ with `node --experimental-strip-types`, or `bun`.
+//   node --experimental-strip-types scripts/verify-lsp.ts <file>
+//   bun scripts/verify-lsp.ts <file>
+//
+// Exit codes: 0 OK, 1 FAIL (server error / not installed), 2 usage, 3 SKIP
+// (no server known for this extension).
+
+import { spawn } from "node:child_process"
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { extname, isAbsolute, resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import process from "node:process"
+
+import { LANGUAGES, LSP_CONFIG_FILE } from "./lsp-server-table.ts"
+
+const DEFAULT_TIMEOUT_MS = 60_000
+
+interface ResolvedServer {
+	readonly language: string
+	readonly command: readonly string[]
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string")
+}
+
+// Resolve the server command for `ext`, preferring a LitClaude .lsp.json entry
+// whose `extensionToLanguage` maps the extension, then the embedded table.
+function resolveServer(ext: string, configPath: string): ResolvedServer | null {
+	if (existsSync(configPath)) {
+		try {
+			const parsed: unknown = JSON.parse(readFileSync(configPath, "utf-8"))
+			if (isRecord(parsed)) {
+				for (const [language, entry] of Object.entries(parsed)) {
+					if (!isRecord(entry)) continue
+					const map = entry["extensionToLanguage"]
+					const command = entry["command"]
+					if (isRecord(map) && Object.keys(map).includes(ext) && isStringArray(command)) {
+						return { language, command }
+					}
+				}
+			}
+		} catch {
+			// fall through to embedded table
+		}
+	}
+
+	for (const server of LANGUAGES) {
+		if (server.extensions.includes(ext)) {
+			return { language: server.language, command: [...server.command] }
+		}
+	}
+	return null
+}
+
+interface JsonRpcMessage {
+	readonly method?: string
+	readonly id?: number
+	readonly params?: unknown
+	readonly result?: unknown
+	readonly error?: unknown
+}
+
+function encode(message: unknown): Buffer {
+	const body = Buffer.from(JSON.stringify(message), "utf-8")
+	return Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, "ascii"), body])
+}
+
+// Incremental LSP framing parser: pulls complete Content-Length messages off a
+// growing buffer.
+function makeReader(onMessage: (message: JsonRpcMessage) => void): (chunk: Buffer) => void {
+	let buffer = Buffer.alloc(0)
+	return (chunk: Buffer): void => {
+		buffer = Buffer.concat([buffer, chunk])
+		while (true) {
+			const headerEnd = buffer.indexOf("\r\n\r\n")
+			if (headerEnd === -1) return
+			const header = buffer.subarray(0, headerEnd).toString("ascii")
+			const match = /content-length:\s*(\d+)/i.exec(header)
+			if (!match) {
+				buffer = buffer.subarray(headerEnd + 4)
+				continue
+			}
+			const length = Number.parseInt(match[1] ?? "0", 10)
+			const start = headerEnd + 4
+			if (buffer.length < start + length) return
+			const body = buffer.subarray(start, start + length).toString("utf-8")
+			buffer = buffer.subarray(start + length)
+			try {
+				onMessage(JSON.parse(body) as JsonRpcMessage)
+			} catch {
+				// ignore malformed frame
+			}
+		}
+	}
+}
+
+function languageId(ext: string): string {
+	const server = LANGUAGES.find((entry) => entry.extensions.includes(ext))
+	return server?.language ?? ext.replace(/^\./, "")
+}
+
+async function run(filePath: string, timeoutMs: number, configPath: string): Promise<number> {
+	const absolute = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath)
+	const ext = extname(absolute).toLowerCase()
+	const server = resolveServer(ext, configPath)
+
+	if (server === null) {
+		process.stderr.write(`SKIP ${absolute}: no language server known for "${ext}". See references/.\n`)
+		return 3
+	}
+
+	const [bin, ...binArgs] = server.command
+	if (bin === undefined) {
+		process.stderr.write(`SKIP ${absolute}: empty command for ${server.language}.\n`)
+		return 3
+	}
+
+	const text = readFileSync(absolute, "utf-8")
+	const uri = pathToFileURL(absolute).href
+
+	return await new Promise<number>((resolveResult) => {
+		let child
+		try {
+			child = spawn(bin, binArgs, { stdio: ["pipe", "pipe", "pipe"] })
+		} catch {
+			process.stdout.write(`FAIL ${absolute}: language server not installed (${bin})\n`)
+			resolveResult(1)
+			return
+		}
+
+		let settled = false
+		let stderr = ""
+		const finish = (code: number, line: string): void => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			try {
+				child.kill("SIGKILL")
+			} catch {
+				/* already gone */
+			}
+			process.stdout.write(`${line}\n`)
+			resolveResult(code)
+		}
+
+		const timer = setTimeout(() => {
+			finish(1, `FAIL ${absolute}: timed out after ${timeoutMs}ms waiting for diagnostics`)
+		}, timeoutMs)
+
+		child.on("error", (error: NodeJS.ErrnoException) => {
+			if (error.code === "ENOENT") {
+				finish(1, `FAIL ${absolute}: language server not installed (${bin})`)
+			} else {
+				finish(1, `FAIL ${absolute}: ${error.message}`)
+			}
+		})
+		child.on("exit", (code) => {
+			if (!settled) {
+				finish(1, `FAIL ${absolute}: server exited (code ${code ?? "?"})\n${stderr.trim()}`)
+			}
+		})
+		child.stderr.on("data", (chunk: Buffer) => {
+			stderr += chunk.toString("utf-8")
+		})
+
+		const send = (message: unknown): void => {
+			child.stdin.write(encode(message))
+		}
+
+		const read = makeReader((message) => {
+			if (message.id === 1 && message.result !== undefined) {
+				send({ jsonrpc: "2.0", method: "initialized", params: {} })
+				send({
+					jsonrpc: "2.0",
+					method: "textDocument/didOpen",
+					params: { textDocument: { uri, languageId: languageId(ext), version: 1, text } },
+				})
+			}
+			if (message.method === "textDocument/publishDiagnostics" && isRecord(message.params)) {
+				const diagnostics = message.params["diagnostics"]
+				const count = Array.isArray(diagnostics) ? diagnostics.length : 0
+				if (message.params["uri"] === uri) {
+					finish(0, `OK ${absolute}: LSP roundtrip succeeded (${count} diagnostic(s)) via ${server.language}`)
+				}
+			}
+		})
+		child.stdout.on("data", read)
+
+		send({
+			jsonrpc: "2.0",
+			id: 1,
+			method: "initialize",
+			params: {
+				processId: process.pid,
+				rootUri: pathToFileURL(process.cwd()).href,
+				capabilities: { textDocument: { publishDiagnostics: {} } },
+			},
+		})
+	})
+}
+
+function parseTimeout(args: readonly string[]): number {
+	const flag = args.find((arg) => arg.startsWith("--timeout="))
+	if (flag === undefined) return DEFAULT_TIMEOUT_MS
+	const parsed = Number.parseInt(flag.slice("--timeout=".length), 10)
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS
+}
+
+async function main(): Promise<void> {
+	const args = process.argv.slice(2)
+	const configFlag = args.find((arg) => arg.startsWith("--config="))
+	const configPath = configFlag ? configFlag.slice("--config=".length) : LSP_CONFIG_FILE
+	const filePath = args.find((arg) => !arg.startsWith("--"))
+
+	if (filePath === undefined) {
+		process.stderr.write("Usage: verify-lsp.ts <file> [--timeout=ms] [--config=<path>]\n")
+		process.exit(2)
+	}
+	if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+		process.stderr.write(`verify-lsp: not a file: ${filePath}\n`)
+		process.exit(2)
+	}
+
+	const code = await run(filePath, parseTimeout(args), configPath)
+	process.exit(code)
+}
+
+await main()

package/plugins/litclaude/skills/start-work/SKILL.md

@@ -25,19 +25,18 @@ Before the first edit:
 
 ## Native Goal + Dynamic Workflow
 
-Before the first checkbox, use Claude Code's native goal surface when available:
-
-- call `get_goal` if exposed
-- call `create_goal` with the plan objective only when no matching active goal
-  exists
-- call `update_goal` only after all top-level checkboxes and final gates are
-  complete, or when the plan is genuinely blocked
-- if the user invokes `/goal`, respect it as the native session goal
-- do not auto-type or send `/goal` text from a skill
-
-If model-facing goal tools are absent, continue with Boulder/ledger discipline.
-For long plans, ask once for `/goal <plan completion condition>` if that would
-help the user keep the session bounded.
+Before the first checkbox, bind the native goal. Claude Code's `/goal` (v2.1.139+) is a
+**user-typed slash command**, not a model-facing tool, and a hook/skill **cannot invoke it**:
+
+- For a long plan, offer the user one ready-to-paste `/goal <plan completion condition>` line —
+  this is the real way to bind the native session goal — and keep the Boulder/ledger discipline.
+- Forward-compat only: if a future Claude Code build exposes model-facing goal tools, call
+  `get_goal` if exposed, `create_goal` with the plan objective only when no matching active goal
+  exists, and `update_goal` only after all top-level checkboxes and final gates are complete (or
+  when the plan is genuinely blocked). These are not exposed today.
+- Do not auto-type or send `/goal` text from a skill; if the user invokes `/goal`, respect it.
+
+If model-facing goal tools are absent (the case today), continue with Boulder/ledger discipline.
 If goal tools are not exposed, do not print repeated fallback status; just keep
 the plan ledger accurate and continue with verified evidence.
 

package/plugins/litclaude/skills/visual-qa/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: visual-qa
+description: "Rigorous visual QA for any UI you built or changed, across BOTH web/page UIs and TUI/terminal UIs. MUST USE after building or changing any UI to verify it visually before declaring it done. Captures objective reference evidence with a bundled diff script (image-diff for screenshots, tui-check for terminal captures), then runs two parallel read-only oracle passes (design-system and functional integrity; visual fidelity and CJK precision) and synthesizes one good/bad verdict. Triggers: visual QA, visual regression, screenshot diff, pixel diff, image comparison, UI looks wrong, design system check, alpha channel breakage, responsive check, CJK text, Korean/Japanese/Chinese text clipping, glyph drop, TUI alignment, terminal UI, tmux capture, box-drawing border misalignment, wide-character column drift."
+---
+
+# Visual QA - Dual-Oracle Web and TUI Verification
+
+The LitClaude visual specialist for Claude Code. Verify a rendered UI against
+intent using objective script evidence plus two parallel read-only oracle
+passes, then synthesize one good/bad verdict. The script numbers focus the
+reviewers. They are not the verdict.
+
+## Runtime
+
+The bundled scripts are dependency-free TypeScript with zero external packages
+(no install step). Run them with either:
+
+- Node 22.6+: `node --experimental-strip-types "$SKILL_DIR/scripts/cli.ts" ...`
+- bun: `bun "$SKILL_DIR/scripts/cli.ts" ...`
+
+PNG decoding, CRC, deflate/inflate, ANSI stripping, and East-Asian width all use
+only Node built-ins (`node:fs`, `node:zlib`, `node:buffer`). `$SKILL_DIR` is this
+skill's own directory (the folder containing this SKILL.md).
+
+## Purpose and when to use
+
+- Use after you build or change any UI, before calling it done. Covers web/page
+  UIs and TUI/terminal UIs.
+- Use when output must match a mock, a baseline, or a stated design intent; when
+  you suspect a regression; when CJK (Korean/Japanese/Chinese) text may clip,
+  misalign, or wrap awkwardly; when a claimed design system might actually be a
+  flat image; when a terminal layout may overflow or its borders may break.
+- Skip when there is no rendered surface (pure backend or library logic with no
+  visual or terminal output). For broad post-implementation review use
+  review-work; this skill is the visual specialist.
+
+## Step 1 - Detect the surface
+
+- Web/page UI: renders in a browser (HTML/CSS/JS, components, canvas, SVG).
+  Evidence is screenshots.
+- TUI/terminal UI: renders as text in a terminal (box-drawing, panes, status
+  lines, REPL/TUI apps). Evidence is terminal captures.
+
+If the change touches both, run both capture tracks and feed both into the passes.
+
+## Step 2 - Capture objective reference evidence
+
+### Web
+
+1. Capture a REFERENCE image: the user's mock/target, or a known-good baseline.
+   Save as PNG.
+2. Capture the ACTUAL rendered screenshot at the same viewport size using the
+   project's browser tooling (Claude Code's browser/Playwright tooling). Save as
+   PNG.
+3. Run the diff and keep the JSON:
+
+```
+node --experimental-strip-types "$SKILL_DIR/scripts/cli.ts" image-diff <reference.png> <actual.png>
+```
+
+Key fields: `dimensionsMatch`, `diffRatio` (0..1), `similarityScore` (0..100),
+`alphaChannelIntact`, `hotspots[]` (grid regions ranked by `diffRatio`).
+
+### TUI
+
+1. Capture plain text and an ANSI-preserving copy:
+
+```
+tmux capture-pane -p > capture.txt
+tmux capture-pane -e -p > capture-ansi.txt
+```
+
+2. Run the check with the REAL terminal width and keep the JSON:
+
+```
+node --experimental-strip-types "$SKILL_DIR/scripts/cli.ts" tui-check capture.txt --cols <N>
+```
+
+Key fields: `maxWidth`, `overflowLines[]`, `borderMisaligned`,
+`wideCharColumns[]`, `hasAnsi`.
+
+This JSON (diff ratio, similarity score, hotspots or overflow lines, border
+alignment, wide-char columns, alpha) is REFERENCE evidence to aim the reviewers.
+It is not the verdict by itself.
+
+## Step 3 - Dispatch two read-only QA subagents in parallel
+
+Spawn BOTH oracle passes as background subagents in a single message using
+Claude Code's `Task` tool with `run_in_background: true`, so they run
+concurrently. Each oracle is read-only: it reviews and reports, and must not
+modify files. Each returns PASS, REVISE, or FAIL with concrete, located
+findings. Pass A proves the surface is a real design-system implementation, not
+a mock-only or faked-image substitute. Pass B directly opens screenshots and
+inspects source/content for visual and CJK defects. The main session waits for
+both background subagents to finish, then synthesizes the verdict.
+
+Paste evidence directly into each prompt: source code, the plain-text TUI
+captures, the script JSON, and the screenshot paths plus your described
+observations for web. The two passes differ in depth by charter, not by any
+model or effort setting.
+
+### Pass A - Design-system and functional integrity (deeper, strict)
+
+Launch with the `Task` tool, `run_in_background: true`, description
+"Visual QA pass A: design-system and functional integrity", prompt:
+
+```
+REVIEW TYPE: DESIGN-SYSTEM AND FUNCTIONAL INTEGRITY (read-only)
+TIER INTENT: Treat this as the deeper, stricter pass. Reason exhaustively before concluding. Assume a plausible-looking surface may be faked or mock-only until the source proves otherwise. Do not modify any file.
+
+INTENT:
+{What the user asked for, the mock or baseline, and the constraints.}
+
+SURFACE: {web | tui | both}
+
+SOURCE CODE:
+{Full source of the UI: components, styles/tokens, layout, render code. Include neighboring files that show existing patterns.}
+
+CAPTURES:
+{Web: actual screenshot path(s) plus your described observations. TUI: paste capture.txt and capture-ansi.txt inline.}
+
+SHARED SCRIPT EVIDENCE (reference, not verdict):
+{Paste the image-diff or tui-check JSON. Use alphaChannelIntact for the transparency check.}
+
+CHECK EACH:
+1. Real design system vs ad-hoc/mock-only: are styles driven by coherent design tokens and reused primitives, or one-off hardcoded values scattered per element? Treat mock-only screens, static compositions, or one-page hardcoded styling with no reusable system as BLOCKING unless the user explicitly requested a throwaway mock.
+2. Faked-with-an-image anti-pattern: is the UI a real DOM/component tree, or a pasted raster/screenshot or background-image standing in for live elements? For TUI: a real layout that reflows, or hardcoded pre-rendered text at fixed widths?
+3. Alpha and transparency: handled correctly, with no unexpected opaque or black fills and correct PNG/CSS alpha? Cross-check alphaChannelIntact.
+4. Code style and implementation quality.
+5. Responsive and resize behavior across viewport sizes (web) or terminal resize (TUI).
+6. Do the user-intended FEATURES actually work: interactions, states, navigation (web); input handling, resize, scroll (TUI)? Trace the code paths.
+
+OUTPUT:
+VERDICT: PASS | REVISE | FAIL
+CONFIDENCE: HIGH | MEDIUM | LOW
+SUMMARY: 1-3 sentences
+FINDINGS: for each, [dimension] [severity] what is wrong, where (file/line or capture region), and the concrete fix
+WHAT IS GOOD: correct aspects that must not regress
+BLOCKING: items that must be fixed; empty if PASS
+```
+
+### Pass B - Visual fidelity and CJK precision (focused)
+
+Launch with the `Task` tool, `run_in_background: true`, description
+"Visual QA pass B: visual fidelity and CJK precision", prompt:
+
+```
+REVIEW TYPE: VISUAL FIDELITY AND CJK PRECISION (read-only)
+TIER INTENT: Treat this as the focused visual pass. Directly open the screenshots with Claude Code's image-reading tool (the Read tool on the PNG path) before judging. Anchor every claim to the script evidence, source code, and captures. Do not modify any file.
+
+INTENT:
+{What the user requested and the mock or baseline to match.}
+
+SURFACE: {web | tui | both}
+
+CAPTURES:
+{Web: actual and reference screenshot paths plus your described observations. TUI: paste capture.txt and capture-ansi.txt inline.}
+
+SOURCE CODE:
+{For web: include the rendered text/content, components, typography, layout, and style code. For TUI: include render code that controls wrapping, width, and wide-character handling.}
+
+SCRIPT EVIDENCE (required, consume every field):
+{Paste the image-diff or tui-check JSON.}
+
+USE THE EVIDENCE:
+- Web (image-diff): start from diffRatio and similarityScore, then directly open every screenshot path and inspect every hotspots[] entry (gridX, gridY, x, y, width, height, diffRatio). Explain the visual cause of each flagged region from the pixels and source/content together.
+- TUI (tui-check): inspect maxWidth vs expectedColumns, every overflowLines[] entry, borderMisaligned, and wideCharColumns[].
+
+CHECK:
+1. Does the rendered output match what the user requested: layout, spacing, color, type, alignment?
+2. CJK precision:
+   - Web: natural CJK line breaking for display and body text. Flag oversized headings that create orphaned one-character or final-syllable lines, split Korean/Japanese/Chinese semantic phrases unnaturally, detach labels such as `[Image #1]` from their content, clip baselines/descenders, drop glyphs (tofu), or show font metric mismatch.
+   - TUI: wide-character column drift (CJK cells counted as 1 instead of 2), box-drawing border misalignment, content overflowing past the terminal width.
+
+OUTPUT:
+VERDICT: PASS | REVISE | FAIL
+CONFIDENCE: HIGH | MEDIUM | LOW
+SUMMARY: 1-3 sentences
+EVIDENCE TRACE: each hotspot or overflow line mapped to its visual cause
+FINDINGS: for each, [severity] what is wrong, where (hotspot grid or capture line:col), and the concrete fix
+BLOCKING: items that must be fixed; empty if PASS
+```
+
+## Step 4 - Synthesize one verdict
+
+When both background subagents return, merge them into a single report. Per
+dimension, mark good or bad with evidence. For each bad item, state what is
+wrong, where (file/line, hotspot grid, or capture line), and the concrete fix.
+Call out what is genuinely good so it is not regressed later.
+
+Completion gate: do not declare the UI done until both passes are satisfied, OR
+the remaining gaps are explicitly listed and accepted by the user. A high
+`similarityScore` with an open Pass A finding, for example a faked-image layout
+or a broken feature, is still a FAIL.
+
+```markdown
+# Visual QA - Verdict: GOOD | NEEDS WORK
+
+| Dimension | Pass | Verdict | Evidence |
+|---|---|---|---|
+| Design system real vs faked | A | good/bad | ... |
+| Features work | A | good/bad | ... |
+| Responsive / resize | A | good/bad | ... |
+| Alpha / transparency | A+B | good/bad | ... |
+| Visual fidelity to intent | B | good/bad | ... |
+| CJK precision | B | good/bad | ... |
+
+## Must fix
+[Blocking items, each with location and fix, in priority order]
+
+## Good, keep it
+[Correct aspects that must not regress]
+
+## Completion gate
+[Satisfied, or the exact remaining gaps and who accepted them]
+```
+
+## Reference evidence is not the verdict
+
+The script quantifies pixels and columns. It cannot judge whether the result is
+a real design system, whether features work, or whether intent was met. A 99/100
+`similarityScore` can still hide a pasted-image fake, a broken interaction, or
+clipped CJK descenders. Use the numbers to aim the oracles, then trust the
+synthesized review.
+
+Illustrative output (locked field names):
+
+```json
+{
+  "command": "image-diff",
+  "dimensionsMatch": true,
+  "reference": { "width": 1440, "height": 900 },
+  "actual": { "width": 1440, "height": 900 },
+  "totalPixels": 1296000,
+  "diffPixels": 38880,
+  "diffRatio": 0.03,
+  "similarityScore": 97,
+  "alphaChannelIntact": true,
+  "hotspots": [
+    { "gridX": 2, "gridY": 0, "x": 960, "y": 0, "width": 480, "height": 300, "diffRatio": 0.21 }
+  ],
+  "summary": "97/100 similarity; one hotspot in the top-right header region."
+}
+```
+
+```json
+{
+  "command": "tui-check",
+  "expectedColumns": 80,
+  "lineCount": 24,
+  "lineWidths": [80, 80, 82, 80],
+  "maxWidth": 82,
+  "overflowLines": [ { "line": 3, "width": 82 } ],
+  "borderMisaligned": true,
+  "wideCharColumns": [12, 13],
+  "hasAnsi": false,
+  "summary": "Line 3 overflows 80 cols by 2; borders misaligned at wide-char columns 12-13."
+}
+```

package/plugins/litclaude/skills/visual-qa/scripts/ansi.ts

@@ -0,0 +1,17 @@
+const ESC = String.fromCharCode(0x1b)
+const CSI = String.fromCharCode(0x9b)
+
+// Matches CSI/escape sequences (colors, cursor moves) without embedding raw
+// control characters in the regex source.
+const ANSI_PATTERN = new RegExp(
+	`[${ESC}${CSI}][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]`,
+	"g",
+)
+
+export function stripAnsi(input: string): string {
+	return input.replace(ANSI_PATTERN, "")
+}
+
+export function hasAnsi(input: string): boolean {
+	return stripAnsi(input) !== input
+}

package/plugins/litclaude/skills/visual-qa/scripts/cli.ts

@@ -0,0 +1,96 @@
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { resolve } from "node:path"
+import process from "node:process"
+
+import { diffImages } from "./image-diff.ts"
+import { decodePng } from "./png-decode.ts"
+import { checkTui } from "./tui-grid.ts"
+import type { ImageDiffResult, TuiCheckResult } from "./types.ts"
+
+export class CliError extends Error {
+	readonly name = "CliError"
+}
+
+const DEFAULT_COLUMNS = 80
+const COLS_FLAG = "--cols"
+
+export function runImageDiff(args: readonly string[]): ImageDiffResult {
+	const referencePath = args[0]
+	const actualPath = args[1]
+	if (referencePath === undefined || actualPath === undefined) {
+		throw new CliError("usage: image-diff <reference.png> <actual.png>")
+	}
+	const reference = decodePng(readFileSync(referencePath))
+	const actual = decodePng(readFileSync(actualPath))
+	return diffImages(reference, actual)
+}
+
+function parseColumns(args: readonly string[]): number {
+	for (let index = 0; index < args.length; index++) {
+		const arg = args[index] ?? ""
+		if (arg === COLS_FLAG) {
+			const parsed = Number(args[index + 1])
+			if (!Number.isInteger(parsed) || parsed <= 0) {
+				throw new CliError(`${COLS_FLAG} requires a positive integer`)
+			}
+			return parsed
+		}
+		if (arg.startsWith(`${COLS_FLAG}=`)) {
+			const parsed = Number(arg.slice(COLS_FLAG.length + 1))
+			if (!Number.isInteger(parsed) || parsed <= 0) {
+				throw new CliError(`${COLS_FLAG} requires a positive integer`)
+			}
+			return parsed
+		}
+	}
+	return DEFAULT_COLUMNS
+}
+
+export function runTuiCheck(args: readonly string[]): TuiCheckResult {
+	const capturePath = args[0]
+	if (capturePath === undefined || capturePath.startsWith("--")) {
+		throw new CliError("usage: tui-check <capture.txt> [--cols N]")
+	}
+	const text = readFileSync(capturePath, "utf8")
+	return checkTui(text, parseColumns(args.slice(1)))
+}
+
+export function run(argv: readonly string[]): ImageDiffResult | TuiCheckResult {
+	const command = argv[0]
+	const rest = argv.slice(1)
+	switch (command) {
+		case "image-diff":
+			return runImageDiff(rest)
+		case "tui-check":
+			return runTuiCheck(rest)
+		default:
+			throw new CliError(`unknown command "${command ?? ""}"; expected "image-diff" or "tui-check"`)
+	}
+}
+
+function main(argv: readonly string[]): void {
+	try {
+		const result = run(argv)
+		process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error)
+		process.stderr.write(`visual-qa error: ${message}\n`)
+		process.exitCode = 1
+	}
+}
+
+// Entry guard that works under both bun and Node (`--experimental-strip-types`).
+function isMainModule(): boolean {
+	const entry = process.argv[1]
+	if (entry === undefined) return false
+	try {
+		return resolve(fileURLToPath(import.meta.url)) === resolve(entry)
+	} catch {
+		return false
+	}
+}
+
+if (isMainModule()) {
+	main(process.argv.slice(2))
+}