@screenbook/cli 0.0.1 → 1.0.0

package/dist/index.mjs

@@ -6,12 +6,13 @@ import { basename, dirname, join, relative, resolve } from "node:path";
 import { createJiti } from "jiti";
 import { glob } from "tinyglobby";
 import { defineConfig } from "@screenbook/core";
+import pc from "picocolors";
 import { execSync, spawn } from "node:child_process";
 import prompts from "prompts";
 import { minimatch } from "minimatch";
 
 //#region src/utils/config.ts
-const CONFIG_FILES = [
+const CONFIG_FILES$1 = [
 	"screenbook.config.ts",
 	"screenbook.config.js",
 	"screenbook.config.mjs"
@@ -23,7 +24,7 @@ async function loadConfig(configPath) {
 		if (!existsSync(absolutePath)) throw new Error(`Config file not found: ${configPath}`);
 		return await importConfig(absolutePath, cwd);
 	}
-	for (const configFile of CONFIG_FILES) {
+	for (const configFile of CONFIG_FILES$1) {
 		const absolutePath = resolve(cwd, configFile);
 		if (existsSync(absolutePath)) return await importConfig(absolutePath, cwd);
 	}
@@ -35,6 +36,361 @@ async function importConfig(absolutePath, cwd) {
 	throw new Error(`Config file must have a default export: ${absolutePath}`);
 }
 
+//#endregion
+//#region src/utils/cycleDetection.ts
+var Color = /* @__PURE__ */ function(Color$1) {
+	Color$1[Color$1["White"] = 0] = "White";
+	Color$1[Color$1["Gray"] = 1] = "Gray";
+	Color$1[Color$1["Black"] = 2] = "Black";
+	return Color$1;
+}(Color || {});
+/**
+* Detect circular navigation dependencies in screen definitions.
+* Uses DFS with coloring algorithm: O(V + E) complexity.
+*
+* @example
+* ```ts
+* const screens = [
+*   { id: "A", next: ["B"] },
+*   { id: "B", next: ["C"] },
+*   { id: "C", next: ["A"] }, // Creates cycle A → B → C → A
+* ]
+* const result = detectCycles(screens)
+* // result.hasCycles === true
+* // result.cycles[0].cycle === ["A", "B", "C", "A"]
+* ```
+*/
+function detectCycles(screens) {
+	const screenMap = /* @__PURE__ */ new Map();
+	const duplicateIds = [];
+	for (const screen of screens) {
+		if (!screen.id || typeof screen.id !== "string") continue;
+		if (screenMap.has(screen.id)) duplicateIds.push(screen.id);
+		screenMap.set(screen.id, screen);
+	}
+	const color = /* @__PURE__ */ new Map();
+	const parent = /* @__PURE__ */ new Map();
+	const cycles = [];
+	for (const id of screenMap.keys()) color.set(id, Color.White);
+	for (const id of screenMap.keys()) if (color.get(id) === Color.White) dfs(id, null);
+	function dfs(nodeId, parentId) {
+		color.set(nodeId, Color.Gray);
+		parent.set(nodeId, parentId);
+		const neighbors = screenMap.get(nodeId)?.next ?? [];
+		for (const neighborId of neighbors) {
+			const neighborColor = color.get(neighborId);
+			if (neighborColor === Color.Gray) {
+				const cyclePath = reconstructCycle(nodeId, neighborId);
+				const allowed = isCycleAllowed(cyclePath, screenMap);
+				cycles.push({
+					cycle: cyclePath,
+					allowed
+				});
+			} else if (neighborColor === Color.White) {
+				if (screenMap.has(neighborId)) dfs(neighborId, nodeId);
+			}
+		}
+		color.set(nodeId, Color.Black);
+	}
+	/**
+	* Reconstruct cycle path from back edge
+	*/
+	function reconstructCycle(from, to) {
+		const path = [];
+		let current = from;
+		const visited = /* @__PURE__ */ new Set();
+		const maxIterations = screenMap.size + 1;
+		while (current && current !== to && !visited.has(current) && path.length < maxIterations) {
+			visited.add(current);
+			path.unshift(current);
+			current = parent.get(current);
+		}
+		path.unshift(to);
+		path.push(to);
+		return path;
+	}
+	const disallowedCycles = cycles.filter((c) => !c.allowed);
+	return {
+		hasCycles: cycles.length > 0,
+		cycles,
+		disallowedCycles,
+		duplicateIds
+	};
+}
+/**
+* Check if any screen in the cycle has allowCycles: true
+*/
+function isCycleAllowed(cyclePath, screenMap) {
+	const uniqueNodes = cyclePath.slice(0, -1);
+	for (const nodeId of uniqueNodes) if (screenMap.get(nodeId)?.allowCycles === true) return true;
+	return false;
+}
+/**
+* Format cycle information for console output
+*
+* @example
+* ```
+*   Cycle 1: A → B → C → A
+*   Cycle 2 (allowed): D → E → D
+* ```
+*/
+function formatCycleWarnings(cycles) {
+	if (cycles.length === 0) return "";
+	const lines = [];
+	for (let i = 0; i < cycles.length; i++) {
+		const cycle = cycles[i];
+		if (!cycle) continue;
+		const cycleStr = cycle.cycle.join(" → ");
+		const allowedSuffix = cycle.allowed ? " (allowed)" : "";
+		lines.push(`  Cycle ${i + 1}${allowedSuffix}: ${cycleStr}`);
+	}
+	return lines.join("\n");
+}
+/**
+* Get a summary of cycle detection results
+*/
+function getCycleSummary(result) {
+	if (!result.hasCycles) return "No circular navigation detected";
+	const total = result.cycles.length;
+	const disallowed = result.disallowedCycles.length;
+	const allowed = total - disallowed;
+	if (disallowed === 0) return `${total} circular navigation${total > 1 ? "s" : ""} detected (all allowed)`;
+	if (allowed === 0) return `${total} circular navigation${total > 1 ? "s" : ""} detected`;
+	return `${total} circular navigation${total > 1 ? "s" : ""} detected (${disallowed} not allowed, ${allowed} allowed)`;
+}
+
+//#endregion
+//#region src/utils/errors.ts
+/**
+* Centralized error definitions for consistent error messages across CLI commands
+*/
+const ERRORS = {
+	ROUTES_PATTERN_MISSING: {
+		title: "routesPattern not configured",
+		suggestion: "Add routesPattern to your screenbook.config.ts to specify where your route files are located.",
+		example: `import { defineConfig } from "@screenbook/core"
+
+export default defineConfig({
+  routesPattern: "src/pages/**/page.tsx",  // Adjust for your framework
+})`
+	},
+	CONFIG_NOT_FOUND: {
+		title: "Configuration file not found",
+		suggestion: "Run 'screenbook init' to create a screenbook.config.ts file, or create one manually.",
+		example: `import { defineConfig } from "@screenbook/core"
+
+export default defineConfig({
+  metaPattern: "src/**/screen.meta.ts",
+})`
+	},
+	SCREENS_NOT_FOUND: {
+		title: "screens.json not found",
+		suggestion: "Run 'screenbook build' first to generate the screen catalog.",
+		message: "If you haven't set up Screenbook yet, run 'screenbook init' to get started."
+	},
+	SCREENS_PARSE_ERROR: {
+		title: "Failed to parse screens.json",
+		suggestion: "The screens.json file may be corrupted. Try running 'screenbook build' to regenerate it."
+	},
+	META_FILE_LOAD_ERROR: (filePath) => ({
+		title: `Failed to load ${filePath}`,
+		suggestion: "Check the file for syntax errors or missing exports. The file should export a 'screen' object.",
+		example: `import { defineScreen } from "@screenbook/core"
+
+export const screen = defineScreen({
+  id: "example.screen",
+  title: "Example Screen",
+  route: "/example",
+})`
+	}),
+	API_NAME_REQUIRED: {
+		title: "API name is required",
+		suggestion: "Provide the API name as an argument.",
+		example: `screenbook impact UserAPI.getProfile
+screenbook impact "PaymentAPI.*"  # Use quotes for patterns`
+	},
+	GIT_CHANGED_FILES_ERROR: (baseBranch) => ({
+		title: "Failed to get changed files from git",
+		message: `Make sure you are in a git repository and the base branch '${baseBranch}' exists.`,
+		suggestion: `Verify the base branch exists with: git branch -a | grep ${baseBranch}`
+	}),
+	GIT_NOT_REPOSITORY: {
+		title: "Not a git repository",
+		suggestion: "This command requires a git repository. Initialize one with 'git init' or navigate to an existing repository."
+	},
+	SERVER_START_FAILED: (error) => ({
+		title: "Failed to start development server",
+		message: error,
+		suggestion: "Check if the port is already in use or if there are any dependency issues."
+	}),
+	VALIDATION_FAILED: (errorCount) => ({
+		title: `Validation failed with ${errorCount} error${errorCount === 1 ? "" : "s"}`,
+		suggestion: "Fix the validation errors above. Screen references must point to existing screens."
+	}),
+	LINT_MISSING_META: (missingCount, totalRoutes) => ({
+		title: `${missingCount} route${missingCount === 1 ? "" : "s"} missing screen.meta.ts`,
+		message: `Found ${totalRoutes} route file${totalRoutes === 1 ? "" : "s"}, but ${missingCount} ${missingCount === 1 ? "is" : "are"} missing colocated screen.meta.ts.`,
+		suggestion: "Add screen.meta.ts files next to your route files, or run 'screenbook generate' to create them."
+	}),
+	CYCLES_DETECTED: (cycleCount) => ({
+		title: `${cycleCount} circular navigation${cycleCount === 1 ? "" : "s"} detected`,
+		suggestion: "Review the navigation flow. Use 'allowCycles: true' in screen.meta.ts to allow intentional cycles, or use --allow-cycles to suppress all warnings.",
+		example: `// Allow a specific screen to be part of cycles
+export const screen = defineScreen({
+  id: "billing.invoice.detail",
+  next: ["billing.invoices"],
+  allowCycles: true,  // This cycle is intentional
+})`
+	})
+};
+
+//#endregion
+//#region src/utils/logger.ts
+/**
+* Logger utility for consistent, color-coded CLI output
+*/
+const logger = {
+	success: (msg) => {
+		console.log(`${pc.green("✓")} ${msg}`);
+	},
+	error: (msg) => {
+		console.error(`${pc.red("✗")} ${pc.red(`Error: ${msg}`)}`);
+	},
+	warn: (msg) => {
+		console.log(`${pc.yellow("⚠")} ${pc.yellow(`Warning: ${msg}`)}`);
+	},
+	info: (msg) => {
+		console.log(`${pc.cyan("ℹ")} ${msg}`);
+	},
+	errorWithHelp: (options) => {
+		const { title, message, suggestion, example } = options;
+		console.error();
+		console.error(`${pc.red("✗")} ${pc.red(`Error: ${title}`)}`);
+		if (message) {
+			console.error();
+			console.error(`  ${message}`);
+		}
+		if (suggestion) {
+			console.error();
+			console.error(`  ${pc.cyan("Suggestion:")} ${suggestion}`);
+		}
+		if (example) {
+			console.error();
+			console.error(`  ${pc.dim("Example:")}`);
+			for (const line of example.split("\n")) console.error(`  ${pc.dim(line)}`);
+		}
+		console.error();
+	},
+	step: (msg) => {
+		console.log(`${pc.dim("→")} ${msg}`);
+	},
+	done: (msg) => {
+		console.log(`${pc.green("✓")} ${pc.green(msg)}`);
+	},
+	itemSuccess: (msg) => {
+		console.log(`  ${pc.green("✓")} ${msg}`);
+	},
+	itemError: (msg) => {
+		console.log(`  ${pc.red("✗")} ${msg}`);
+	},
+	itemWarn: (msg) => {
+		console.log(`  ${pc.yellow("⚠")} ${msg}`);
+	},
+	log: (msg) => {
+		console.log(msg);
+	},
+	blank: () => {
+		console.log();
+	},
+	bold: (msg) => pc.bold(msg),
+	dim: (msg) => pc.dim(msg),
+	code: (msg) => pc.cyan(msg),
+	path: (msg) => pc.underline(msg),
+	highlight: (msg) => pc.cyan(pc.bold(msg)),
+	green: (msg) => pc.green(msg),
+	red: (msg) => pc.red(msg),
+	yellow: (msg) => pc.yellow(msg)
+};
+
+//#endregion
+//#region src/utils/validation.ts
+/**
+* Validate screen references (next and entryPoints)
+*/
+function validateScreenReferences(screens) {
+	const screenIds = new Set(screens.map((s) => s.id));
+	const errors = [];
+	for (const screen of screens) {
+		if (screen.next) {
+			for (const nextId of screen.next) if (!screenIds.has(nextId)) errors.push({
+				screenId: screen.id,
+				field: "next",
+				invalidRef: nextId,
+				suggestion: findSimilar(nextId, screenIds)
+			});
+		}
+		if (screen.entryPoints) {
+			for (const entryId of screen.entryPoints) if (!screenIds.has(entryId)) errors.push({
+				screenId: screen.id,
+				field: "entryPoints",
+				invalidRef: entryId,
+				suggestion: findSimilar(entryId, screenIds)
+			});
+		}
+	}
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+/**
+* Find similar screen ID using Levenshtein distance
+*/
+function findSimilar(target, candidates) {
+	let bestMatch;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	const maxDistance = Math.ceil(target.length * .4);
+	for (const candidate of candidates) {
+		const distance = levenshteinDistance(target, candidate);
+		if (distance < bestDistance && distance <= maxDistance) {
+			bestDistance = distance;
+			bestMatch = candidate;
+		}
+	}
+	return bestMatch;
+}
+/**
+* Calculate Levenshtein distance between two strings
+*/
+function levenshteinDistance(a, b) {
+	const matrix = Array.from({ length: a.length + 1 }, () => Array.from({ length: b.length + 1 }, () => 0));
+	const get = (i, j) => matrix[i]?.[j] ?? 0;
+	const set = (i, j, value) => {
+		const row = matrix[i];
+		if (row) row[j] = value;
+	};
+	for (let i = 0; i <= a.length; i++) set(i, 0, i);
+	for (let j = 0; j <= b.length; j++) set(0, j, j);
+	for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) {
+		const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+		set(i, j, Math.min(get(i - 1, j) + 1, get(i, j - 1) + 1, get(i - 1, j - 1) + cost));
+	}
+	return get(a.length, b.length);
+}
+/**
+* Format validation errors for console output
+*/
+function formatValidationErrors(errors) {
+	const lines = [];
+	for (const error of errors) {
+		lines.push(`  Screen "${error.screenId}"`);
+		lines.push(`    → ${error.field} references non-existent screen "${error.invalidRef}"`);
+		if (error.suggestion) lines.push(`    Did you mean "${error.suggestion}"?`);
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+
 //#endregion
 //#region src/commands/build.ts
 const buildCommand = define({
@@ -50,22 +406,33 @@ const buildCommand = define({
 			type: "string",
 			short: "o",
 			description: "Output directory"
+		},
+		strict: {
+			type: "boolean",
+			short: "s",
+			description: "Fail on validation errors and disallowed cycles",
+			default: false
+		},
+		allowCycles: {
+			type: "boolean",
+			description: "Suppress all circular navigation warnings",
+			default: false
 		}
 	},
 	run: async (ctx) => {
 		const config = await loadConfig(ctx.values.config);
 		const outDir = ctx.values.outDir ?? config.outDir;
 		const cwd = process.cwd();
-		console.log("Building screen metadata...");
+		logger.info("Building screen metadata...");
 		const files = await glob(config.metaPattern, {
 			cwd,
 			ignore: config.ignore
 		});
 		if (files.length === 0) {
-			console.log(`No screen.meta.ts files found matching: ${config.metaPattern}`);
+			logger.warn(`No screen.meta.ts files found matching: ${config.metaPattern}`);
 			return;
 		}
-		console.log(`Found ${files.length} screen files`);
+		logger.info(`Found ${files.length} screen files`);
 		const jiti = createJiti(cwd);
 		const screens = [];
 		for (const file of files) {
@@ -74,25 +441,51 @@ const buildCommand = define({
 				const module = await jiti.import(absolutePath);
 				if (module.screen) {
 					screens.push(module.screen);
-					console.log(`  ✓ ${module.screen.id}`);
+					logger.itemSuccess(module.screen.id);
 				}
 			} catch (error) {
-				console.error(`  ✗ Failed to load ${file}:`, error);
+				logger.itemError(`Failed to load ${file}`);
+				if (error instanceof Error) logger.log(`    ${logger.dim(error.message)}`);
+			}
+		}
+		const validation = validateScreenReferences(screens);
+		if (!validation.valid) {
+			logger.blank();
+			logger.warn("Invalid screen references found:");
+			logger.log(formatValidationErrors(validation.errors));
+			if (ctx.values.strict) {
+				logger.errorWithHelp(ERRORS.VALIDATION_FAILED(validation.errors.length));
+				process.exit(1);
+			}
+		}
+		if (!ctx.values.allowCycles) {
+			const cycleResult = detectCycles(screens);
+			if (cycleResult.hasCycles) {
+				logger.blank();
+				logger.warn(getCycleSummary(cycleResult));
+				logger.log(formatCycleWarnings(cycleResult.cycles));
+				if (ctx.values.strict && cycleResult.disallowedCycles.length > 0) {
+					logger.blank();
+					logger.errorWithHelp(ERRORS.CYCLES_DETECTED(cycleResult.disallowedCycles.length));
+					process.exit(1);
+				}
 			}
 		}
 		const outputPath = join(cwd, outDir, "screens.json");
 		const outputDir = dirname(outputPath);
 		if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
 		writeFileSync(outputPath, JSON.stringify(screens, null, 2));
-		console.log(`\nGenerated ${outputPath}`);
+		logger.blank();
+		logger.success(`Generated ${logger.path(outputPath)}`);
 		const mermaidPath = join(cwd, outDir, "graph.mmd");
 		writeFileSync(mermaidPath, generateMermaidGraph(screens));
-		console.log(`Generated ${mermaidPath}`);
+		logger.success(`Generated ${logger.path(mermaidPath)}`);
 		const coverage = await generateCoverageData(config, cwd, screens);
 		const coveragePath = join(cwd, outDir, "coverage.json");
 		writeFileSync(coveragePath, JSON.stringify(coverage, null, 2));
-		console.log(`Generated ${coveragePath}`);
-		console.log(`\nCoverage: ${coverage.covered}/${coverage.total} (${coverage.percentage}%)`);
+		logger.success(`Generated ${logger.path(coveragePath)}`);
+		logger.blank();
+		logger.done(`Coverage: ${coverage.covered}/${coverage.total} (${coverage.percentage}%)`);
 	}
 });
 async function generateCoverageData(config, cwd, screens) {
@@ -182,11 +575,14 @@ const devCommand = define({
 		const config = await loadConfig(ctx.values.config);
 		const port = ctx.values.port ?? "4321";
 		const cwd = process.cwd();
-		console.log("Starting Screenbook development server...");
+		logger.info("Starting Screenbook development server...");
 		await buildScreens(config, cwd);
 		const uiPackagePath = resolveUiPackage();
 		if (!uiPackagePath) {
-			console.error("Could not find @screenbook/ui package");
+			logger.errorWithHelp({
+				title: "Could not find @screenbook/ui package",
+				suggestion: "Make sure @screenbook/ui is installed. Run 'npm install @screenbook/ui' or 'pnpm add @screenbook/ui'."
+			});
 			process.exit(1);
 		}
 		const screensJsonPath = join(cwd, config.outDir, "screens.json");
@@ -195,7 +591,8 @@ const devCommand = define({
 		if (!existsSync(uiScreensDir)) mkdirSync(uiScreensDir, { recursive: true });
 		if (existsSync(screensJsonPath)) copyFileSync(screensJsonPath, join(uiScreensDir, "screens.json"));
 		if (existsSync(coverageJsonPath)) copyFileSync(coverageJsonPath, join(uiScreensDir, "coverage.json"));
-		console.log(`\nStarting UI server on http://localhost:${port}`);
+		logger.blank();
+		logger.info(`Starting UI server on ${logger.highlight(`http://localhost:${port}`)}`);
 		const astroProcess = spawn("npx", [
 			"astro",
 			"dev",
@@ -207,7 +604,7 @@ const devCommand = define({
 			shell: true
 		});
 		astroProcess.on("error", (error) => {
-			console.error("Failed to start Astro server:", error);
+			logger.errorWithHelp(ERRORS.SERVER_START_FAILED(error.message));
 			process.exit(1);
 		});
 		astroProcess.on("close", (code) => {
@@ -227,10 +624,10 @@ async function buildScreens(config, cwd) {
 		ignore: config.ignore
 	});
 	if (files.length === 0) {
-		console.log(`No screen.meta.ts files found matching: ${config.metaPattern}`);
+		logger.warn(`No screen.meta.ts files found matching: ${config.metaPattern}`);
 		return;
 	}
-	console.log(`Found ${files.length} screen files`);
+	logger.info(`Found ${files.length} screen files`);
 	const jiti = createJiti(cwd);
 	const screens = [];
 	for (const file of files) {
@@ -239,17 +636,19 @@ async function buildScreens(config, cwd) {
 			const module = await jiti.import(absolutePath);
 			if (module.screen) {
 				screens.push(module.screen);
-				console.log(`  ✓ ${module.screen.id}`);
+				logger.itemSuccess(module.screen.id);
 			}
 		} catch (error) {
-			console.error(`  ✗ Failed to load ${file}:`, error);
+			logger.itemError(`Failed to load ${file}`);
+			if (error instanceof Error) logger.log(`    ${logger.dim(error.message)}`);
 		}
 	}
 	const outputPath = join(cwd, config.outDir, "screens.json");
 	const outputDir = dirname(outputPath);
 	if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
 	writeFileSync(outputPath, JSON.stringify(screens, null, 2));
-	console.log(`\nGenerated ${outputPath}`);
+	logger.blank();
+	logger.success(`Generated ${logger.path(outputPath)}`);
 }
 function resolveUiPackage() {
 	try {
@@ -265,6 +664,267 @@ function resolveUiPackage() {
 	}
 }
 
+//#endregion
+//#region src/commands/doctor.ts
+const CONFIG_FILES = [
+	"screenbook.config.ts",
+	"screenbook.config.js",
+	"screenbook.config.mjs"
+];
+const doctorCommand = define({
+	name: "doctor",
+	description: "Diagnose common issues with Screenbook setup",
+	args: { verbose: {
+		type: "boolean",
+		short: "v",
+		description: "Show detailed output",
+		default: false
+	} },
+	run: async (ctx) => {
+		const cwd = process.cwd();
+		const verbose = ctx.values.verbose;
+		logger.log("");
+		logger.log(logger.bold("Screenbook Doctor"));
+		logger.log("─────────────────");
+		logger.log("");
+		const results = [];
+		results.push(await checkConfigFile(cwd));
+		results.push(await checkDependencies(cwd));
+		const config = await loadConfig();
+		results.push(await checkMetaPattern(cwd, config.metaPattern, config.ignore));
+		results.push(await checkRoutesPattern(cwd, config.routesPattern, config.ignore));
+		results.push(await checkBuildOutput(cwd, config.outDir));
+		results.push(await checkVersionCompatibility(cwd));
+		results.push(await checkGitRepository(cwd));
+		displayResults(results, verbose);
+	}
+});
+async function checkConfigFile(cwd) {
+	for (const configFile of CONFIG_FILES) if (existsSync(resolve(cwd, configFile))) return {
+		name: "Config file",
+		status: "pass",
+		message: `Found: ${configFile}`
+	};
+	return {
+		name: "Config file",
+		status: "warn",
+		message: "No config file found (using defaults)",
+		suggestion: "Run 'screenbook init' to create a config file"
+	};
+}
+async function checkDependencies(cwd) {
+	const packageJsonPath = join(cwd, "package.json");
+	if (!existsSync(packageJsonPath)) return {
+		name: "Dependencies",
+		status: "fail",
+		message: "package.json not found",
+		suggestion: "Run 'npm init' or 'pnpm init' to create package.json"
+	};
+	try {
+		const content = readFileSync(packageJsonPath, "utf-8");
+		const pkg = JSON.parse(content);
+		const allDeps = {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+		const coreVersion = allDeps["@screenbook/core"];
+		const cliVersion = allDeps["@screenbook/cli"];
+		if (!coreVersion && !cliVersion) return {
+			name: "Dependencies",
+			status: "fail",
+			message: "Screenbook packages not installed",
+			suggestion: "Run 'pnpm add -D @screenbook/core @screenbook/cli' to install"
+		};
+		if (!coreVersion) return {
+			name: "Dependencies",
+			status: "warn",
+			message: "@screenbook/core not found in dependencies",
+			suggestion: "Run 'pnpm add -D @screenbook/core' to install"
+		};
+		if (!cliVersion) return {
+			name: "Dependencies",
+			status: "warn",
+			message: "@screenbook/cli not found in dependencies",
+			suggestion: "Run 'pnpm add -D @screenbook/cli' to install"
+		};
+		return {
+			name: "Dependencies",
+			status: "pass",
+			message: `@screenbook/core@${coreVersion}, @screenbook/cli@${cliVersion}`
+		};
+	} catch {
+		return {
+			name: "Dependencies",
+			status: "fail",
+			message: "Failed to read package.json",
+			suggestion: "Ensure package.json is valid JSON"
+		};
+	}
+}
+async function checkMetaPattern(cwd, metaPattern, ignore) {
+	try {
+		const files = await glob(metaPattern, {
+			cwd,
+			ignore
+		});
+		if (files.length === 0) return {
+			name: "Screen meta files",
+			status: "warn",
+			message: `No files matching: ${metaPattern}`,
+			suggestion: "Run 'screenbook generate' to create screen.meta.ts files"
+		};
+		return {
+			name: "Screen meta files",
+			status: "pass",
+			message: `Found ${files.length} screen.meta.ts file${files.length > 1 ? "s" : ""}`
+		};
+	} catch {
+		return {
+			name: "Screen meta files",
+			status: "fail",
+			message: `Invalid pattern: ${metaPattern}`,
+			suggestion: "Check metaPattern in your config file"
+		};
+	}
+}
+async function checkRoutesPattern(cwd, routesPattern, ignore) {
+	if (!routesPattern) return {
+		name: "Routes pattern",
+		status: "warn",
+		message: "routesPattern not configured",
+		suggestion: "Set routesPattern in config to enable 'lint' and 'generate' commands"
+	};
+	try {
+		const files = await glob(routesPattern, {
+			cwd,
+			ignore
+		});
+		if (files.length === 0) return {
+			name: "Routes pattern",
+			status: "warn",
+			message: `No files matching: ${routesPattern}`,
+			suggestion: "Check routesPattern in your config file"
+		};
+		return {
+			name: "Routes pattern",
+			status: "pass",
+			message: `Found ${files.length} route file${files.length > 1 ? "s" : ""}`
+		};
+	} catch {
+		return {
+			name: "Routes pattern",
+			status: "fail",
+			message: `Invalid pattern: ${routesPattern}`,
+			suggestion: "Check routesPattern in your config file"
+		};
+	}
+}
+async function checkBuildOutput(cwd, outDir) {
+	const screensJsonPath = join(cwd, outDir, "screens.json");
+	if (!existsSync(screensJsonPath)) return {
+		name: "Build output",
+		status: "fail",
+		message: `screens.json not found in ${outDir}/`,
+		suggestion: "Run 'screenbook build' to generate metadata"
+	};
+	try {
+		const content = readFileSync(screensJsonPath, "utf-8");
+		const screens = JSON.parse(content);
+		return {
+			name: "Build output",
+			status: "pass",
+			message: `screens.json contains ${screens.length} screen${screens.length > 1 ? "s" : ""}`
+		};
+	} catch {
+		return {
+			name: "Build output",
+			status: "fail",
+			message: "screens.json is corrupted",
+			suggestion: "Run 'screenbook build' to regenerate"
+		};
+	}
+}
+async function checkVersionCompatibility(cwd) {
+	const packageJsonPath = join(cwd, "package.json");
+	if (!existsSync(packageJsonPath)) return {
+		name: "Version compatibility",
+		status: "warn",
+		message: "Cannot check - package.json not found"
+	};
+	try {
+		const content = readFileSync(packageJsonPath, "utf-8");
+		const pkg = JSON.parse(content);
+		const allDeps = {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+		const coreVersion = allDeps["@screenbook/core"];
+		const cliVersion = allDeps["@screenbook/cli"];
+		if (!coreVersion || !cliVersion) return {
+			name: "Version compatibility",
+			status: "warn",
+			message: "Cannot check - packages not installed"
+		};
+		const extractMajor = (version) => {
+			return version.replace(/^[\^~>=<]+/, "").split(".")[0] ?? "0";
+		};
+		if (extractMajor(coreVersion) !== extractMajor(cliVersion)) return {
+			name: "Version compatibility",
+			status: "warn",
+			message: `Major version mismatch: core@${coreVersion} vs cli@${cliVersion}`,
+			suggestion: "Update packages to matching major versions"
+		};
+		return {
+			name: "Version compatibility",
+			status: "pass",
+			message: "Package versions are compatible"
+		};
+	} catch {
+		return {
+			name: "Version compatibility",
+			status: "fail",
+			message: "Failed to read package.json"
+		};
+	}
+}
+async function checkGitRepository(cwd) {
+	if (!existsSync(join(cwd, ".git"))) return {
+		name: "Git repository",
+		status: "warn",
+		message: "Not a git repository",
+		suggestion: "Run 'git init' to enable 'pr-impact' command for PR analysis"
+	};
+	return {
+		name: "Git repository",
+		status: "pass",
+		message: "Git repository detected"
+	};
+}
+function displayResults(results, verbose) {
+	let passCount = 0;
+	let failCount = 0;
+	let warnCount = 0;
+	for (const result of results) {
+		const icon = result.status === "pass" ? logger.green("✓") : result.status === "fail" ? logger.red("✗") : logger.yellow("⚠");
+		const statusColor = result.status === "pass" ? logger.green : result.status === "fail" ? logger.red : logger.yellow;
+		logger.log(`${icon} ${statusColor(result.name)}: ${result.message}`);
+		if (result.suggestion && (result.status !== "pass" || verbose)) logger.log(`  ${logger.dim("→")} ${result.suggestion}`);
+		if (result.status === "pass") passCount++;
+		else if (result.status === "fail") failCount++;
+		else warnCount++;
+	}
+	logger.log("");
+	const summary = [];
+	if (passCount > 0) summary.push(logger.green(`${passCount} passed`));
+	if (failCount > 0) summary.push(logger.red(`${failCount} failed`));
+	if (warnCount > 0) summary.push(logger.yellow(`${warnCount} warnings`));
+	logger.log(`Summary: ${summary.join(", ")}`);
+	if (failCount > 0) {
+		logger.log("");
+		logger.log(logger.dim("Run the suggested commands above to fix the issues."));
+	}
+}
+
 //#endregion
 //#region src/commands/generate.ts
 const generateCommand = define({
@@ -287,6 +947,12 @@ const generateCommand = define({
 			short: "f",
 			description: "Overwrite existing screen.meta.ts files",
 			default: false
+		},
+		interactive: {
+			type: "boolean",
+			short: "i",
+			description: "Interactively confirm or modify each screen",
+			default: false
 		}
 	},
 	run: async (ctx) => {
@@ -294,29 +960,23 @@ const generateCommand = define({
 		const cwd = process.cwd();
 		const dryRun = ctx.values.dryRun ?? false;
 		const force = ctx.values.force ?? false;
+		const interactive = ctx.values.interactive ?? false;
 		if (!config.routesPattern) {
-			console.log("Error: routesPattern not configured");
-			console.log("");
-			console.log("Add routesPattern to your screenbook.config.ts:");
-			console.log("");
-			console.log("  routesPattern: \"src/pages/**/page.tsx\",   // Vite/React");
-			console.log("  routesPattern: \"app/**/page.tsx\",         // Next.js App Router");
-			console.log("  routesPattern: \"src/pages/**/*.vue\",      // Vue/Nuxt");
-			console.log("");
+			logger.errorWithHelp(ERRORS.ROUTES_PATTERN_MISSING);
 			process.exit(1);
 		}
-		console.log("Scanning for route files...");
-		console.log("");
+		logger.info("Scanning for route files...");
+		logger.blank();
 		const routeFiles = await glob(config.routesPattern, {
 			cwd,
 			ignore: config.ignore
 		});
 		if (routeFiles.length === 0) {
-			console.log(`No route files found matching: ${config.routesPattern}`);
+			logger.warn(`No route files found matching: ${config.routesPattern}`);
 			return;
 		}
-		console.log(`Found ${routeFiles.length} route files`);
-		console.log("");
+		logger.log(`Found ${routeFiles.length} route files`);
+		logger.blank();
 		let created = 0;
 		let skipped = 0;
 		for (const routeFile of routeFiles) {
@@ -324,44 +984,141 @@ const generateCommand = define({
 			const metaPath = join(routeDir, "screen.meta.ts");
 			const absoluteMetaPath = join(cwd, metaPath);
 			if (!force && existsSync(absoluteMetaPath)) {
+				if (!interactive) {
+					skipped++;
+					continue;
+				}
+				logger.itemWarn(`Exists: ${logger.path(metaPath)} (use --force to overwrite)`);
 				skipped++;
 				continue;
 			}
 			const screenMeta = inferScreenMeta(routeDir, config.routesPattern);
-			const content = generateScreenMetaContent(screenMeta);
-			if (dryRun) {
-				console.log(`Would create: ${metaPath}`);
-				console.log(`  id: "${screenMeta.id}"`);
-				console.log(`  title: "${screenMeta.title}"`);
-				console.log(`  route: "${screenMeta.route}"`);
-				console.log("");
+			if (interactive) {
+				const result = await promptForScreen(routeFile, screenMeta);
+				if (result.skip) {
+					logger.itemWarn(`Skipped: ${logger.path(metaPath)}`);
+					skipped++;
+					continue;
+				}
+				const content = generateScreenMetaContent(result.meta, {
+					owner: result.owner,
+					tags: result.tags
+				});
+				if (dryRun) {
+					logger.step(`Would create: ${logger.path(metaPath)}`);
+					logger.log(`    ${logger.dim(`id: "${result.meta.id}"`)}`);
+					logger.log(`    ${logger.dim(`title: "${result.meta.title}"`)}`);
+					logger.log(`    ${logger.dim(`route: "${result.meta.route}"`)}`);
+					if (result.owner.length > 0) logger.log(`    ${logger.dim(`owner: [${result.owner.map((o) => `"${o}"`).join(", ")}]`)}`);
+					if (result.tags.length > 0) logger.log(`    ${logger.dim(`tags: [${result.tags.map((t) => `"${t}"`).join(", ")}]`)}`);
+					logger.blank();
+				} else {
+					writeFileSync(absoluteMetaPath, content);
+					logger.itemSuccess(`Created: ${logger.path(metaPath)}`);
+				}
 			} else {
-				writeFileSync(absoluteMetaPath, content);
-				console.log(`✓ Created: ${metaPath}`);
+				const content = generateScreenMetaContent(screenMeta);
+				if (dryRun) {
+					logger.step(`Would create: ${logger.path(metaPath)}`);
+					logger.log(`    ${logger.dim(`id: "${screenMeta.id}"`)}`);
+					logger.log(`    ${logger.dim(`title: "${screenMeta.title}"`)}`);
+					logger.log(`    ${logger.dim(`route: "${screenMeta.route}"`)}`);
+					logger.blank();
+				} else {
+					writeFileSync(absoluteMetaPath, content);
+					logger.itemSuccess(`Created: ${logger.path(metaPath)}`);
+				}
 			}
 			created++;
 		}
-		console.log("");
+		logger.blank();
 		if (dryRun) {
-			console.log(`Would create ${created} files (${skipped} already exist)`);
-			console.log("");
-			console.log("Run without --dry-run to create files");
+			logger.info(`Would create ${created} files (${skipped} already exist)`);
+			logger.blank();
+			logger.log(`Run without ${logger.code("--dry-run")} to create files`);
 		} else {
-			console.log(`Created ${created} files (${skipped} skipped)`);
+			logger.done(`Created ${created} files (${skipped} skipped)`);
 			if (created > 0) {
-				console.log("");
-				console.log("Next steps:");
-				console.log("  1. Review and customize the generated screen.meta.ts files");
-				console.log("  2. Run 'screenbook dev' to view your screen catalog");
+				logger.blank();
+				logger.log(logger.bold("Next steps:"));
+				logger.log("  1. Review and customize the generated screen.meta.ts files");
+				logger.log(`  2. Run ${logger.code("screenbook dev")} to view your screen catalog`);
 			}
 		}
 	}
 });
 /**
+* Parse comma-separated string into array
+*/
+function parseCommaSeparated(input) {
+	if (!input.trim()) return [];
+	return input.split(",").map((s) => s.trim()).filter(Boolean);
+}
+/**
+* Prompt user for screen metadata in interactive mode
+*/
+async function promptForScreen(routeFile, inferred) {
+	logger.blank();
+	logger.info(`Found: ${logger.path(routeFile)}`);
+	logger.blank();
+	logger.log(`  ${logger.dim("ID:")} ${inferred.id} ${logger.dim("(inferred)")}`);
+	logger.log(`  ${logger.dim("Title:")} ${inferred.title} ${logger.dim("(inferred)")}`);
+	logger.log(`  ${logger.dim("Route:")} ${inferred.route} ${logger.dim("(inferred)")}`);
+	logger.blank();
+	const response = await prompts([
+		{
+			type: "confirm",
+			name: "proceed",
+			message: "Generate this screen?",
+			initial: true
+		},
+		{
+			type: (prev) => prev ? "text" : null,
+			name: "id",
+			message: "ID",
+			initial: inferred.id
+		},
+		{
+			type: (_prev, values) => values.proceed ? "text" : null,
+			name: "title",
+			message: "Title",
+			initial: inferred.title
+		},
+		{
+			type: (_prev, values) => values.proceed ? "text" : null,
+			name: "owner",
+			message: "Owner (comma-separated)",
+			initial: ""
+		},
+		{
+			type: (_prev, values) => values.proceed ? "text" : null,
+			name: "tags",
+			message: "Tags (comma-separated)",
+			initial: inferred.id.split(".")[0] || ""
+		}
+	]);
+	if (!response.proceed) return {
+		skip: true,
+		meta: inferred,
+		owner: [],
+		tags: []
+	};
+	return {
+		skip: false,
+		meta: {
+			id: response.id || inferred.id,
+			title: response.title || inferred.title,
+			route: inferred.route
+		},
+		owner: parseCommaSeparated(response.owner || ""),
+		tags: parseCommaSeparated(response.tags || "")
+	};
+}
+/**
 * Infer screen metadata from the route file path
 */
 function inferScreenMeta(routeDir, routesPattern) {
-	const relativePath = relative(routesPattern.split("*")[0].replace(/\/$/, ""), routeDir);
+	const relativePath = relative(routesPattern.split("*")[0]?.replace(/\/$/, "") ?? "", routeDir);
 	if (!relativePath || relativePath === ".") return {
 		id: "home",
 		title: "Home",
@@ -371,18 +1128,21 @@ function inferScreenMeta(routeDir, routesPattern) {
 	return {
 		id: segments.join("."),
 		title: (segments[segments.length - 1] || "home").split(/[-_]/).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" "),
-		route: "/" + relativePath.split("/").filter((s) => s && !s.startsWith("(") && !s.endsWith(")")).map((s) => {
+		route: `/${relativePath.split("/").filter((s) => s && !s.startsWith("(") && !s.endsWith(")")).map((s) => {
 			if (s.startsWith("[...") && s.endsWith("]")) return "*";
 			if (s.startsWith("[") && s.endsWith("]")) return `:${s.slice(1, -1)}`;
 			return s;
-		}).join("/")
+		}).join("/")}`
 	};
 }
 /**
 * Generate screen.meta.ts file content
 */
-function generateScreenMetaContent(meta) {
-	const inferredTag = meta.id.split(".")[0] || "general";
+function generateScreenMetaContent(meta, options) {
+	const owner = options?.owner ?? [];
+	const tags = options?.tags && options.tags.length > 0 ? options.tags : [meta.id.split(".")[0] || "general"];
+	const ownerStr = owner.length > 0 ? `[${owner.map((o) => `"${o}"`).join(", ")}]` : "[]";
+	const tagsStr = `[${tags.map((t) => `"${t}"`).join(", ")}]`;
 	return `import { defineScreen } from "@screenbook/core"
 
 export const screen = defineScreen({
@@ -391,10 +1151,10 @@ export const screen = defineScreen({
 	route: "${meta.route}",
 
 	// Team or individual responsible for this screen
-	owner: [],
+	owner: ${ownerStr},
 
 	// Tags for filtering in the catalog
-	tags: ["${inferredTag}"],
+	tags: ${tagsStr},
 
 	// APIs/services this screen depends on (for impact analysis)
 	// Example: ["UserAPI.getProfile", "PaymentService.checkout"]
@@ -436,7 +1196,7 @@ function buildNavigationGraph(screens) {
 	for (const screen of screens) {
 		if (!screen.next) continue;
 		if (!graph.has(screen.id)) graph.set(screen.id, /* @__PURE__ */ new Set());
-		for (const nextId of screen.next) graph.get(screen.id).add(nextId);
+		for (const nextId of screen.next) graph.get(screen.id)?.add(nextId);
 	}
 	return graph;
 }
@@ -474,6 +1234,7 @@ function findPathToDirectDependent(startId, targetIds, graph, maxDepth, visited)
 	const localVisited = new Set([startId]);
 	while (queue.length > 0) {
 		const current = queue.shift();
+		if (!current) break;
 		if (current.path.length > maxDepth + 1) continue;
 		const neighbors = graph.get(current.id);
 		if (!neighbors) continue;
@@ -521,7 +1282,7 @@ function formatImpactText(result) {
 	}
 	if (result.transitive.length > 0) {
 		lines.push(`Transitive (${result.transitive.length} screen${result.transitive.length > 1 ? "s" : ""}):`);
-		for (const { screen, path } of result.transitive) lines.push(`  - ${path.join(" -> ")}`);
+		for (const { path } of result.transitive) lines.push(`  - ${path.join(" -> ")}`);
 		lines.push("");
 	}
 	if (result.totalCount === 0) {
@@ -590,22 +1351,14 @@ const impactCommand = define({
 		const cwd = process.cwd();
 		const apiName = ctx.values.api;
 		if (!apiName) {
-			console.error("Error: API name is required");
-			console.error("");
-			console.error("Usage: screenbook impact <api-name>");
-			console.error("");
-			console.error("Examples:");
-			console.error("  screenbook impact InvoiceAPI.getDetail");
-			console.error("  screenbook impact PaymentService");
+			logger.errorWithHelp(ERRORS.API_NAME_REQUIRED);
 			process.exit(1);
 		}
 		const format = ctx.values.format ?? "text";
 		const depth = ctx.values.depth ?? 3;
 		const screensPath = join(cwd, config.outDir, "screens.json");
 		if (!existsSync(screensPath)) {
-			console.error("Error: screens.json not found");
-			console.error("");
-			console.error("Run 'screenbook build' first to generate the screen catalog.");
+			logger.errorWithHelp(ERRORS.SCREENS_NOT_FOUND);
 			process.exit(1);
 		}
 		let screens;
@@ -613,20 +1366,22 @@ const impactCommand = define({
 			const content = readFileSync(screensPath, "utf-8");
 			screens = JSON.parse(content);
 		} catch (error) {
-			console.error("Error: Failed to read screens.json");
-			console.error(error instanceof Error ? error.message : String(error));
+			logger.errorWithHelp({
+				...ERRORS.SCREENS_PARSE_ERROR,
+				message: error instanceof Error ? error.message : String(error)
+			});
 			process.exit(1);
 		}
 		if (screens.length === 0) {
-			console.log("No screens found in the catalog.");
-			console.log("");
-			console.log("Run 'screenbook generate' to create screen.meta.ts files,");
-			console.log("then 'screenbook build' to generate the catalog.");
+			logger.warn("No screens found in the catalog.");
+			logger.blank();
+			logger.log("Run 'screenbook generate' to create screen.meta.ts files,");
+			logger.log("then 'screenbook build' to generate the catalog.");
 			return;
 		}
 		const result = analyzeImpact(screens, apiName, depth);
-		if (format === "json") console.log(formatImpactJson(result));
-		else console.log(formatImpactText(result));
+		if (format === "json") logger.log(formatImpactJson(result));
+		else logger.log(formatImpactText(result));
 	}
 });
 
@@ -819,30 +1574,30 @@ export default defineConfig({
 `;
 }
 function printValueProposition() {
-	console.log("");
-	console.log("What Screenbook gives you:");
-	console.log("  - Screen catalog with search & filter");
-	console.log("  - Navigation graph visualization");
-	console.log("  - Impact analysis (API -> affected screens)");
-	console.log("  - CI lint for documentation coverage");
+	logger.blank();
+	logger.log(logger.bold("What Screenbook gives you:"));
+	logger.log("  - Screen catalog with search & filter");
+	logger.log("  - Navigation graph visualization");
+	logger.log("  - Impact analysis (API -> affected screens)");
+	logger.log("  - CI lint for documentation coverage");
 }
 function printNextSteps(hasRoutesPattern) {
-	console.log("");
-	console.log("Next steps:");
+	logger.blank();
+	logger.log(logger.bold("Next steps:"));
 	if (hasRoutesPattern) {
-		console.log("  1. Run 'screenbook generate' to auto-create screen.meta.ts files");
-		console.log("  2. Run 'screenbook dev' to start the UI server");
+		logger.log(`  1. Run ${logger.code("screenbook generate")} to auto-create screen.meta.ts files`);
+		logger.log(`  2. Run ${logger.code("screenbook dev")} to start the UI server`);
 	} else {
-		console.log("  1. Configure routesPattern in screenbook.config.ts");
-		console.log("  2. Run 'screenbook generate' to auto-create screen.meta.ts files");
-		console.log("  3. Run 'screenbook dev' to start the UI server");
+		logger.log("  1. Configure routesPattern in screenbook.config.ts");
+		logger.log(`  2. Run ${logger.code("screenbook generate")} to auto-create screen.meta.ts files`);
+		logger.log(`  3. Run ${logger.code("screenbook dev")} to start the UI server`);
 	}
-	console.log("");
-	console.log("screen.meta.ts files are created alongside your route files:");
-	console.log("");
-	console.log("  src/pages/dashboard/");
-	console.log("    page.tsx          # Your route file");
-	console.log("    screen.meta.ts    # Auto-generated, customize as needed");
+	logger.blank();
+	logger.log("screen.meta.ts files are created alongside your route files:");
+	logger.blank();
+	logger.log(logger.dim("  src/pages/dashboard/"));
+	logger.log(logger.dim("    page.tsx          # Your route file"));
+	logger.log(logger.dim("    screen.meta.ts    # Auto-generated, customize as needed"));
 }
 const initCommand = define({
 	name: "init",
@@ -864,27 +1619,27 @@ const initCommand = define({
 		const cwd = process.cwd();
 		const force = ctx.values.force ?? false;
 		const skipDetect = ctx.values.skipDetect ?? false;
-		console.log("Initializing Screenbook...");
-		console.log("");
+		logger.info("Initializing Screenbook...");
+		logger.blank();
 		let framework = null;
 		if (!skipDetect) {
 			framework = detectFramework(cwd);
-			if (framework) console.log(`  Detected: ${framework.name}`);
+			if (framework) logger.itemSuccess(`Detected: ${framework.name}`);
 			else {
-				console.log("  Could not auto-detect framework");
-				console.log("");
+				logger.log("  Could not auto-detect framework");
+				logger.blank();
 				framework = await promptFrameworkSelection();
 				if (framework) {
-					console.log("");
-					console.log(`  Selected: ${framework.name}`);
+					logger.blank();
+					logger.itemSuccess(`Selected: ${framework.name}`);
 				}
 			}
 		}
 		const configPath = join(cwd, "screenbook.config.ts");
-		if (!force && existsSync(configPath)) console.log("  - screenbook.config.ts already exists (skipped)");
+		if (!force && existsSync(configPath)) logger.log(`  ${logger.dim("-")} screenbook.config.ts already exists ${logger.dim("(skipped)")}`);
 		else {
 			writeFileSync(configPath, generateConfigTemplate(framework));
-			console.log("  + Created screenbook.config.ts");
+			logger.itemSuccess("Created screenbook.config.ts");
 		}
 		const gitignorePath = join(cwd, ".gitignore");
 		const screenbookIgnore = ".screenbook";
@@ -892,14 +1647,14 @@ const initCommand = define({
 			const gitignoreContent = readFileSync(gitignorePath, "utf-8");
 			if (!gitignoreContent.includes(screenbookIgnore)) {
 				writeFileSync(gitignorePath, `${gitignoreContent.trimEnd()}\n\n# Screenbook\n${screenbookIgnore}\n`);
-				console.log("  + Added .screenbook to .gitignore");
-			} else console.log("  - .screenbook already in .gitignore (skipped)");
+				logger.itemSuccess("Added .screenbook to .gitignore");
+			} else logger.log(`  ${logger.dim("-")} .screenbook already in .gitignore ${logger.dim("(skipped)")}`);
 		} else {
 			writeFileSync(gitignorePath, `# Screenbook\n${screenbookIgnore}\n`);
-			console.log("  + Created .gitignore with .screenbook");
+			logger.itemSuccess("Created .gitignore with .screenbook");
 		}
-		console.log("");
-		console.log("Screenbook initialized successfully!");
+		logger.blank();
+		logger.done("Screenbook initialized successfully!");
 		printValueProposition();
 		printNextSteps(framework !== null);
 	}
@@ -910,42 +1665,48 @@ const initCommand = define({
 const lintCommand = define({
 	name: "lint",
 	description: "Detect routes without screen.meta.ts files",
-	args: { config: {
-		type: "string",
-		short: "c",
-		description: "Path to config file"
-	} },
+	args: {
+		config: {
+			type: "string",
+			short: "c",
+			description: "Path to config file"
+		},
+		allowCycles: {
+			type: "boolean",
+			description: "Suppress circular navigation warnings",
+			default: false
+		},
+		strict: {
+			type: "boolean",
+			short: "s",
+			description: "Fail on disallowed cycles",
+			default: false
+		}
+	},
 	run: async (ctx) => {
 		const config = await loadConfig(ctx.values.config);
 		const cwd = process.cwd();
 		const adoption = config.adoption ?? { mode: "full" };
 		let hasWarnings = false;
 		if (!config.routesPattern) {
-			console.log("Error: routesPattern not configured");
-			console.log("");
-			console.log("Add routesPattern to your screenbook.config.ts:");
-			console.log("");
-			console.log("  routesPattern: \"src/pages/**/page.tsx\",   // Vite/React");
-			console.log("  routesPattern: \"app/**/page.tsx\",         // Next.js App Router");
-			console.log("  routesPattern: \"src/pages/**/*.vue\",      // Vue/Nuxt");
-			console.log("");
+			logger.errorWithHelp(ERRORS.ROUTES_PATTERN_MISSING);
 			process.exit(1);
 		}
-		console.log("Linting screen metadata coverage...");
+		logger.info("Linting screen metadata coverage...");
 		if (adoption.mode === "progressive") {
-			console.log(`Mode: Progressive adoption`);
-			if (adoption.includePatterns?.length) console.log(`Checking: ${adoption.includePatterns.join(", ")}`);
-			if (adoption.minimumCoverage != null) console.log(`Minimum coverage: ${adoption.minimumCoverage}%`);
+			logger.log(`Mode: Progressive adoption`);
+			if (adoption.includePatterns?.length) logger.log(`Checking: ${adoption.includePatterns.join(", ")}`);
+			if (adoption.minimumCoverage != null) logger.log(`Minimum coverage: ${adoption.minimumCoverage}%`);
 		}
-		console.log("");
+		logger.blank();
 		let routeFiles = await glob(config.routesPattern, {
 			cwd,
 			ignore: config.ignore
 		});
-		if (adoption.mode === "progressive" && adoption.includePatterns?.length) routeFiles = routeFiles.filter((file) => adoption.includePatterns.some((pattern) => minimatch(file, pattern)));
+		if (adoption.mode === "progressive" && adoption.includePatterns?.length) routeFiles = routeFiles.filter((file) => adoption.includePatterns?.some((pattern) => minimatch(file, pattern)));
 		if (routeFiles.length === 0) {
-			console.log(`No route files found matching: ${config.routesPattern}`);
-			if (adoption.mode === "progressive" && adoption.includePatterns?.length) console.log(`(filtered by includePatterns: ${adoption.includePatterns.join(", ")})`);
+			logger.warn(`No route files found matching: ${config.routesPattern}`);
+			if (adoption.mode === "progressive" && adoption.includePatterns?.length) logger.log(`  ${logger.dim(`(filtered by includePatterns: ${adoption.includePatterns.join(", ")})`)}`);
 			return;
 		}
 		const metaFiles = await glob(config.metaPattern, {
@@ -965,48 +1726,76 @@ const lintCommand = define({
 		const coveredCount = covered.length;
 		const missingCount = missingMeta.length;
 		const coveragePercent = Math.round(coveredCount / total * 100);
-		console.log(`Found ${total} route files`);
-		console.log(`Coverage: ${coveredCount}/${total} (${coveragePercent}%)`);
-		console.log("");
+		logger.log(`Found ${total} route files`);
+		logger.log(`Coverage: ${coveredCount}/${total} (${coveragePercent}%)`);
+		logger.blank();
 		const minimumCoverage = adoption.minimumCoverage ?? 100;
 		const passedCoverage = coveragePercent >= minimumCoverage;
 		if (missingCount > 0) {
-			console.log(`Missing screen.meta.ts (${missingCount} files):`);
-			console.log("");
+			logger.log(`Missing screen.meta.ts (${missingCount} files):`);
+			logger.blank();
 			for (const file of missingMeta) {
 				const suggestedMetaPath = join(dirname(file), "screen.meta.ts");
-				console.log(`  ✗ ${file}`);
-				console.log(`    → ${suggestedMetaPath}`);
+				logger.itemError(file);
+				logger.log(`    ${logger.dim("→")} ${logger.path(suggestedMetaPath)}`);
 			}
-			console.log("");
+			logger.blank();
 		}
 		if (!passedCoverage) {
-			console.log(`Lint failed: Coverage ${coveragePercent}% is below minimum ${minimumCoverage}%`);
+			logger.error(`Lint failed: Coverage ${coveragePercent}% is below minimum ${minimumCoverage}%`);
 			process.exit(1);
 		} else if (missingCount > 0) {
-			console.log(`✓ Coverage ${coveragePercent}% meets minimum ${minimumCoverage}%`);
-			if (adoption.mode === "progressive") console.log(`  Tip: Increase minimumCoverage in config to gradually improve coverage`);
-		} else console.log("✓ All routes have screen.meta.ts files");
+			logger.success(`Coverage ${coveragePercent}% meets minimum ${minimumCoverage}%`);
+			if (adoption.mode === "progressive") logger.log(`  ${logger.dim("Tip:")} Increase minimumCoverage in config to gradually improve coverage`);
+		} else logger.done("All routes have screen.meta.ts files");
 		const screensPath = join(cwd, config.outDir, "screens.json");
 		if (existsSync(screensPath)) try {
 			const content = readFileSync(screensPath, "utf-8");
-			const orphans = findOrphanScreens(JSON.parse(content));
+			const screens = JSON.parse(content);
+			const orphans = findOrphanScreens(screens);
 			if (orphans.length > 0) {
 				hasWarnings = true;
-				console.log("");
-				console.log(`⚠ Orphan screens detected (${orphans.length}):`);
-				console.log("");
-				console.log("  These screens have no entryPoints and are not");
-				console.log("  referenced in any other screen's 'next' array.");
-				console.log("");
-				for (const orphan of orphans) console.log(`  ⚠ ${orphan.id}  ${orphan.route}`);
-				console.log("");
-				console.log("  Consider adding entryPoints or removing these screens.");
+				logger.blank();
+				logger.warn(`Orphan screens detected (${orphans.length}):`);
+				logger.blank();
+				logger.log("  These screens have no entryPoints and are not");
+				logger.log("  referenced in any other screen's 'next' array.");
+				logger.blank();
+				for (const orphan of orphans) logger.itemWarn(`${orphan.id}  ${logger.dim(orphan.route)}`);
+				logger.blank();
+				logger.log(`  ${logger.dim("Consider adding entryPoints or removing these screens.")}`);
+			}
+			if (!ctx.values.allowCycles) {
+				const cycleResult = detectCycles(screens);
+				if (cycleResult.hasCycles) {
+					hasWarnings = true;
+					logger.blank();
+					logger.warn(getCycleSummary(cycleResult));
+					logger.log(formatCycleWarnings(cycleResult.cycles));
+					logger.blank();
+					if (cycleResult.disallowedCycles.length > 0) {
+						logger.log(`  ${logger.dim("Use 'allowCycles: true' in screen.meta.ts to allow intentional cycles.")}`);
+						if (ctx.values.strict) {
+							logger.blank();
+							logger.errorWithHelp(ERRORS.CYCLES_DETECTED(cycleResult.disallowedCycles.length));
+							process.exit(1);
+						}
+					}
+				}
 			}
-		} catch {}
+		} catch (error) {
+			if (error instanceof SyntaxError) {
+				logger.warn("Failed to parse screens.json - file may be corrupted");
+				logger.log(`  ${logger.dim("Run 'screenbook build' to regenerate.")}`);
+				hasWarnings = true;
+			} else if (error instanceof Error) {
+				logger.warn(`Failed to analyze screens.json: ${error.message}`);
+				hasWarnings = true;
+			}
+		}
 		if (hasWarnings) {
-			console.log("");
-			console.log("Lint completed with warnings.");
+			logger.blank();
+			logger.warn("Lint completed with warnings.");
 		}
 	}
 });
@@ -1028,6 +1817,89 @@ function findOrphanScreens(screens) {
 	return orphans;
 }
 
+//#endregion
+//#region src/utils/prImpact.ts
+/**
+* Extract potential API names from changed file paths.
+* Looks for common API file patterns.
+*/
+function extractApiNames(files) {
+	const apis = /* @__PURE__ */ new Set();
+	for (const file of files) {
+		const fileName = basename(file, ".ts").replace(/\.tsx?$/, "").replace(/\.js$/, "").replace(/\.jsx?$/, "");
+		const dirName = basename(dirname(file));
+		if (file.includes("/api/") || file.includes("/apis/") || file.includes("/services/")) {
+			if (fileName.endsWith("API") || fileName.endsWith("Api") || fileName.endsWith("Service")) apis.add(fileName);
+		}
+		if (file.includes("/services/") && (fileName === "index" || fileName === dirName)) {
+			const serviceName = `${capitalize(dirName)}Service`;
+			apis.add(serviceName);
+		}
+		if (file.includes("/api/") || file.includes("/apis/")) {
+			if (!fileName.endsWith("API") && !fileName.endsWith("Api")) {
+				const apiName = `${capitalize(fileName)}API`;
+				apis.add(apiName);
+			}
+		}
+		if (fileName.toLowerCase().includes("api") || fileName.toLowerCase().includes("service")) apis.add(fileName);
+	}
+	return Array.from(apis).sort();
+}
+function capitalize(str) {
+	return str.charAt(0).toUpperCase() + str.slice(1);
+}
+/**
+* Format the results as Markdown for PR comments.
+*/
+function formatMarkdown(changedFiles, detectedApis, results) {
+	const lines = [];
+	lines.push("## Screenbook Impact Analysis");
+	lines.push("");
+	if (results.length === 0) {
+		lines.push("No screen impacts detected from the API changes in this PR.");
+		lines.push("");
+		lines.push("<details>");
+		lines.push("<summary>Detected APIs (no screen dependencies)</summary>");
+		lines.push("");
+		for (const api of detectedApis) lines.push(`- \`${api}\``);
+		lines.push("");
+		lines.push("</details>");
+		return lines.join("\n");
+	}
+	const totalScreens = results.reduce((sum, r) => sum + r.direct.length, 0) + results.reduce((sum, r) => sum + r.transitive.length, 0);
+	lines.push(`**${totalScreens} screen${totalScreens > 1 ? "s" : ""} affected** by changes to ${results.length} API${results.length > 1 ? "s" : ""}`);
+	lines.push("");
+	for (const result of results) {
+		lines.push(`### ${result.api}`);
+		lines.push("");
+		if (result.direct.length > 0) {
+			lines.push(`**Direct dependencies** (${result.direct.length}):`);
+			lines.push("");
+			lines.push("| Screen | Route | Owner |");
+			lines.push("|--------|-------|-------|");
+			for (const screen of result.direct) {
+				const owner = screen.owner?.join(", ") ?? "-";
+				lines.push(`| ${screen.id} | \`${screen.route}\` | ${owner} |`);
+			}
+			lines.push("");
+		}
+		if (result.transitive.length > 0) {
+			lines.push(`**Transitive dependencies** (${result.transitive.length}):`);
+			lines.push("");
+			for (const { path } of result.transitive) lines.push(`- ${path.join(" → ")}`);
+			lines.push("");
+		}
+	}
+	lines.push("<details>");
+	lines.push(`<summary>Changed files (${changedFiles.length})</summary>`);
+	lines.push("");
+	for (const file of changedFiles.slice(0, 20)) lines.push(`- \`${file}\``);
+	if (changedFiles.length > 20) lines.push(`- ... and ${changedFiles.length - 20} more`);
+	lines.push("");
+	lines.push("</details>");
+	return lines.join("\n");
+}
+
 //#endregion
 //#region src/commands/pr-impact.ts
 const prImpactCommand = define({
@@ -1071,25 +1943,22 @@ const prImpactCommand = define({
 				encoding: "utf-8"
 			}).split("\n").map((f) => f.trim()).filter((f) => f.length > 0);
 		} catch {
-			console.error("Error: Failed to get changed files from git");
-			console.error("");
-			console.error("Make sure you are in a git repository and the base branch exists.");
-			console.error(`Base branch: ${baseBranch}`);
+			logger.errorWithHelp(ERRORS.GIT_CHANGED_FILES_ERROR(baseBranch));
 			process.exit(1);
 		}
 		if (changedFiles.length === 0) {
-			console.log("No changed files found.");
+			logger.info("No changed files found.");
 			return;
 		}
 		const apiNames = extractApiNames(changedFiles);
 		if (apiNames.length === 0) {
 			if (format === "markdown") {
-				console.log("## Screenbook Impact Analysis");
-				console.log("");
-				console.log("No API-related changes detected in this PR.");
-				console.log("");
-				console.log(`Changed files: ${changedFiles.length}`);
-			} else console.log(JSON.stringify({
+				logger.log("## Screenbook Impact Analysis");
+				logger.blank();
+				logger.log("No API-related changes detected in this PR.");
+				logger.blank();
+				logger.log(`Changed files: ${changedFiles.length}`);
+			} else logger.log(JSON.stringify({
 				apis: [],
 				results: [],
 				changedFiles
@@ -1098,9 +1967,7 @@ const prImpactCommand = define({
 		}
 		const screensPath = join(cwd, config.outDir, "screens.json");
 		if (!existsSync(screensPath)) {
-			console.error("Error: screens.json not found");
-			console.error("");
-			console.error("Run 'screenbook build' first to generate the screen catalog.");
+			logger.errorWithHelp(ERRORS.SCREENS_NOT_FOUND);
 			process.exit(1);
 		}
 		let screens;
@@ -1108,8 +1975,10 @@ const prImpactCommand = define({
 			const content = readFileSync(screensPath, "utf-8");
 			screens = JSON.parse(content);
 		} catch (error) {
-			console.error("Error: Failed to read screens.json");
-			console.error(error instanceof Error ? error.message : String(error));
+			logger.errorWithHelp({
+				...ERRORS.SCREENS_PARSE_ERROR,
+				message: error instanceof Error ? error.message : String(error)
+			});
 			process.exit(1);
 		}
 		const results = [];
@@ -1117,7 +1986,7 @@ const prImpactCommand = define({
 			const result = analyzeImpact(screens, apiName, depth);
 			if (result.totalCount > 0) results.push(result);
 		}
-		if (format === "json") console.log(JSON.stringify({
+		if (format === "json") logger.log(JSON.stringify({
 			changedFiles,
 			detectedApis: apiNames,
 			results: results.map((r) => ({
@@ -1139,89 +2008,9 @@ const prImpactCommand = define({
 				}))
 			}))
 		}, null, 2));
-		else console.log(formatMarkdown(changedFiles, apiNames, results));
+		else logger.log(formatMarkdown(changedFiles, apiNames, results));
 	}
 });
-/**
-* Extract potential API names from changed file paths.
-* Looks for common API file patterns.
-*/
-function extractApiNames(files) {
-	const apis = /* @__PURE__ */ new Set();
-	for (const file of files) {
-		const fileName = basename(file, ".ts").replace(/\.tsx?$/, "").replace(/\.js$/, "").replace(/\.jsx?$/, "");
-		const dirName = basename(dirname(file));
-		if (file.includes("/api/") || file.includes("/apis/") || file.includes("/services/")) {
-			if (fileName.endsWith("API") || fileName.endsWith("Api") || fileName.endsWith("Service")) apis.add(fileName);
-		}
-		if (file.includes("/services/") && (fileName === "index" || fileName === dirName)) {
-			const serviceName = capitalize(dirName) + "Service";
-			apis.add(serviceName);
-		}
-		if (file.includes("/api/") || file.includes("/apis/")) {
-			if (!fileName.endsWith("API") && !fileName.endsWith("Api")) {
-				const apiName = capitalize(fileName) + "API";
-				apis.add(apiName);
-			}
-		}
-		if (fileName.toLowerCase().includes("api") || fileName.toLowerCase().includes("service")) apis.add(fileName);
-	}
-	return Array.from(apis).sort();
-}
-function capitalize(str) {
-	return str.charAt(0).toUpperCase() + str.slice(1);
-}
-/**
-* Format the results as Markdown for PR comments.
-*/
-function formatMarkdown(changedFiles, detectedApis, results) {
-	const lines = [];
-	lines.push("## Screenbook Impact Analysis");
-	lines.push("");
-	if (results.length === 0) {
-		lines.push("No screen impacts detected from the API changes in this PR.");
-		lines.push("");
-		lines.push("<details>");
-		lines.push("<summary>Detected APIs (no screen dependencies)</summary>");
-		lines.push("");
-		for (const api of detectedApis) lines.push(`- \`${api}\``);
-		lines.push("");
-		lines.push("</details>");
-		return lines.join("\n");
-	}
-	const totalScreens = results.reduce((sum, r) => sum + r.direct.length, 0) + results.reduce((sum, r) => sum + r.transitive.length, 0);
-	lines.push(`**${totalScreens} screen${totalScreens > 1 ? "s" : ""} affected** by changes to ${results.length} API${results.length > 1 ? "s" : ""}`);
-	lines.push("");
-	for (const result of results) {
-		lines.push(`### ${result.api}`);
-		lines.push("");
-		if (result.direct.length > 0) {
-			lines.push(`**Direct dependencies** (${result.direct.length}):`);
-			lines.push("");
-			lines.push("| Screen | Route | Owner |");
-			lines.push("|--------|-------|-------|");
-			for (const screen of result.direct) {
-				const owner = screen.owner?.join(", ") ?? "-";
-				lines.push(`| ${screen.id} | \`${screen.route}\` | ${owner} |`);
-			}
-			lines.push("");
-		}
-		if (result.transitive.length > 0) {
-			lines.push(`**Transitive dependencies** (${result.transitive.length}):`);
-			lines.push("");
-			for (const { screen, path } of result.transitive) lines.push(`- ${path.join(" → ")}`);
-			lines.push("");
-		}
-	}
-	lines.push("<details>");
-	lines.push(`<summary>Changed files (${changedFiles.length})</summary>`);
-	lines.push("");
-	for (const file of changedFiles.slice(0, 20)) lines.push(`- \`${file}\``);
-	if (changedFiles.length > 20) lines.push(`- ... and ${changedFiles.length - 20} more`);
-	lines.push("");
-	lines.push("</details>");
-	return lines.join("\n");
-}
 
 //#endregion
 //#region src/index.ts
@@ -1239,6 +2028,7 @@ const mainCommand = define({
 		console.log("  lint       Detect routes without screen.meta");
 		console.log("  impact     Analyze API dependency impact");
 		console.log("  pr-impact  Analyze PR changes impact");
+		console.log("  doctor     Diagnose common setup issues");
 		console.log("");
 		console.log("Run 'screenbook <command> --help' for more information");
 	}
@@ -1253,7 +2043,8 @@ await cli(process.argv.slice(2), mainCommand, {
 		dev: devCommand,
 		lint: lintCommand,
 		impact: impactCommand,
-		"pr-impact": prImpactCommand
+		"pr-impact": prImpactCommand,
+		doctor: doctorCommand
 	}
 });