@screenbook/cli 0.0.1

package/dist/index.mjs

@@ -0,0 +1,1262 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { cli, define } from "gunshi";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { createJiti } from "jiti";
+import { glob } from "tinyglobby";
+import { defineConfig } from "@screenbook/core";
+import { execSync, spawn } from "node:child_process";
+import prompts from "prompts";
+import { minimatch } from "minimatch";
+
+//#region src/utils/config.ts
+const CONFIG_FILES = [
+	"screenbook.config.ts",
+	"screenbook.config.js",
+	"screenbook.config.mjs"
+];
+async function loadConfig(configPath) {
+	const cwd = process.cwd();
+	if (configPath) {
+		const absolutePath = resolve(cwd, configPath);
+		if (!existsSync(absolutePath)) throw new Error(`Config file not found: ${configPath}`);
+		return await importConfig(absolutePath, cwd);
+	}
+	for (const configFile of CONFIG_FILES) {
+		const absolutePath = resolve(cwd, configFile);
+		if (existsSync(absolutePath)) return await importConfig(absolutePath, cwd);
+	}
+	return defineConfig();
+}
+async function importConfig(absolutePath, cwd) {
+	const module = await createJiti(cwd).import(absolutePath);
+	if (module.default) return module.default;
+	throw new Error(`Config file must have a default export: ${absolutePath}`);
+}
+
+//#endregion
+//#region src/commands/build.ts
+const buildCommand = define({
+	name: "build",
+	description: "Build screen metadata JSON from screen.meta.ts files",
+	args: {
+		config: {
+			type: "string",
+			short: "c",
+			description: "Path to config file"
+		},
+		outDir: {
+			type: "string",
+			short: "o",
+			description: "Output directory"
+		}
+	},
+	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...");
+		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}`);
+			return;
+		}
+		console.log(`Found ${files.length} screen files`);
+		const jiti = createJiti(cwd);
+		const screens = [];
+		for (const file of files) {
+			const absolutePath = resolve(cwd, file);
+			try {
+				const module = await jiti.import(absolutePath);
+				if (module.screen) {
+					screens.push(module.screen);
+					console.log(`  ✓ ${module.screen.id}`);
+				}
+			} catch (error) {
+				console.error(`  ✗ Failed to load ${file}:`, error);
+			}
+		}
+		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}`);
+		const mermaidPath = join(cwd, outDir, "graph.mmd");
+		writeFileSync(mermaidPath, generateMermaidGraph(screens));
+		console.log(`Generated ${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}%)`);
+	}
+});
+async function generateCoverageData(config, cwd, screens) {
+	let routeFiles = [];
+	if (config.routesPattern) routeFiles = await glob(config.routesPattern, {
+		cwd,
+		ignore: config.ignore
+	});
+	new Set(screens.map((s) => {
+		const parts = s.id.split(".");
+		return parts.slice(0, -1).join("/") || parts[0];
+	}));
+	const missing = [];
+	for (const routeFile of routeFiles) {
+		const routeDir = dirname(routeFile);
+		if (!screens.some((s) => {
+			const screenDir = s.id.replace(/\./g, "/");
+			return routeDir.includes(screenDir) || screenDir.includes(routeDir.replace(/^src\/pages\//, "").replace(/^app\//, ""));
+		})) missing.push({
+			route: routeFile,
+			suggestedPath: join(dirname(routeFile), "screen.meta.ts")
+		});
+	}
+	const total = routeFiles.length > 0 ? routeFiles.length : screens.length;
+	const covered = screens.length;
+	const percentage = total > 0 ? Math.round(covered / total * 100) : 100;
+	const byOwner = {};
+	for (const screen of screens) {
+		const owners = screen.owner || ["unassigned"];
+		for (const owner of owners) {
+			if (!byOwner[owner]) byOwner[owner] = {
+				count: 0,
+				screens: []
+			};
+			byOwner[owner].count++;
+			byOwner[owner].screens.push(screen.id);
+		}
+	}
+	const byTag = {};
+	for (const screen of screens) {
+		const tags = screen.tags || [];
+		for (const tag of tags) byTag[tag] = (byTag[tag] || 0) + 1;
+	}
+	return {
+		total,
+		covered,
+		percentage,
+		missing,
+		byOwner,
+		byTag,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+function generateMermaidGraph(screens) {
+	const lines = ["flowchart TD"];
+	for (const screen of screens) {
+		const label = screen.title.replace(/"/g, "'");
+		lines.push(`    ${sanitizeId(screen.id)}["${label}"]`);
+	}
+	lines.push("");
+	for (const screen of screens) if (screen.next) for (const nextId of screen.next) lines.push(`    ${sanitizeId(screen.id)} --> ${sanitizeId(nextId)}`);
+	return lines.join("\n");
+}
+function sanitizeId(id) {
+	return id.replace(/\./g, "_");
+}
+
+//#endregion
+//#region src/commands/dev.ts
+const devCommand = define({
+	name: "dev",
+	description: "Start the Screenbook development server",
+	args: {
+		config: {
+			type: "string",
+			short: "c",
+			description: "Path to config file"
+		},
+		port: {
+			type: "string",
+			short: "p",
+			description: "Port to run the server on",
+			default: "4321"
+		}
+	},
+	run: async (ctx) => {
+		const config = await loadConfig(ctx.values.config);
+		const port = ctx.values.port ?? "4321";
+		const cwd = process.cwd();
+		console.log("Starting Screenbook development server...");
+		await buildScreens(config, cwd);
+		const uiPackagePath = resolveUiPackage();
+		if (!uiPackagePath) {
+			console.error("Could not find @screenbook/ui package");
+			process.exit(1);
+		}
+		const screensJsonPath = join(cwd, config.outDir, "screens.json");
+		const coverageJsonPath = join(cwd, config.outDir, "coverage.json");
+		const uiScreensDir = join(uiPackagePath, ".screenbook");
+		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}`);
+		const astroProcess = spawn("npx", [
+			"astro",
+			"dev",
+			"--port",
+			port
+		], {
+			cwd: uiPackagePath,
+			stdio: "inherit",
+			shell: true
+		});
+		astroProcess.on("error", (error) => {
+			console.error("Failed to start Astro server:", error);
+			process.exit(1);
+		});
+		astroProcess.on("close", (code) => {
+			process.exit(code ?? 0);
+		});
+		process.on("SIGINT", () => {
+			astroProcess.kill("SIGINT");
+		});
+		process.on("SIGTERM", () => {
+			astroProcess.kill("SIGTERM");
+		});
+	}
+});
+async function buildScreens(config, cwd) {
+	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}`);
+		return;
+	}
+	console.log(`Found ${files.length} screen files`);
+	const jiti = createJiti(cwd);
+	const screens = [];
+	for (const file of files) {
+		const absolutePath = resolve(cwd, file);
+		try {
+			const module = await jiti.import(absolutePath);
+			if (module.screen) {
+				screens.push(module.screen);
+				console.log(`  ✓ ${module.screen.id}`);
+			}
+		} catch (error) {
+			console.error(`  ✗ Failed to load ${file}:`, error);
+		}
+	}
+	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}`);
+}
+function resolveUiPackage() {
+	try {
+		return dirname(createRequire(import.meta.url).resolve("@screenbook/ui/package.json"));
+	} catch {
+		const possiblePaths = [
+			join(process.cwd(), "node_modules", "@screenbook", "ui"),
+			join(process.cwd(), "..", "ui"),
+			join(process.cwd(), "packages", "ui")
+		];
+		for (const p of possiblePaths) if (existsSync(join(p, "package.json"))) return p;
+		return null;
+	}
+}
+
+//#endregion
+//#region src/commands/generate.ts
+const generateCommand = define({
+	name: "generate",
+	description: "Auto-generate screen.meta.ts files from route files",
+	args: {
+		config: {
+			type: "string",
+			short: "c",
+			description: "Path to config file"
+		},
+		dryRun: {
+			type: "boolean",
+			short: "n",
+			description: "Show what would be generated without writing files",
+			default: false
+		},
+		force: {
+			type: "boolean",
+			short: "f",
+			description: "Overwrite existing screen.meta.ts files",
+			default: false
+		}
+	},
+	run: async (ctx) => {
+		const config = await loadConfig(ctx.values.config);
+		const cwd = process.cwd();
+		const dryRun = ctx.values.dryRun ?? false;
+		const force = ctx.values.force ?? 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("");
+			process.exit(1);
+		}
+		console.log("Scanning for route files...");
+		console.log("");
+		const routeFiles = await glob(config.routesPattern, {
+			cwd,
+			ignore: config.ignore
+		});
+		if (routeFiles.length === 0) {
+			console.log(`No route files found matching: ${config.routesPattern}`);
+			return;
+		}
+		console.log(`Found ${routeFiles.length} route files`);
+		console.log("");
+		let created = 0;
+		let skipped = 0;
+		for (const routeFile of routeFiles) {
+			const routeDir = dirname(routeFile);
+			const metaPath = join(routeDir, "screen.meta.ts");
+			const absoluteMetaPath = join(cwd, metaPath);
+			if (!force && existsSync(absoluteMetaPath)) {
+				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("");
+			} else {
+				writeFileSync(absoluteMetaPath, content);
+				console.log(`✓ Created: ${metaPath}`);
+			}
+			created++;
+		}
+		console.log("");
+		if (dryRun) {
+			console.log(`Would create ${created} files (${skipped} already exist)`);
+			console.log("");
+			console.log("Run without --dry-run to create files");
+		} else {
+			console.log(`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");
+			}
+		}
+	}
+});
+/**
+* Infer screen metadata from the route file path
+*/
+function inferScreenMeta(routeDir, routesPattern) {
+	const relativePath = relative(routesPattern.split("*")[0].replace(/\/$/, ""), routeDir);
+	if (!relativePath || relativePath === ".") return {
+		id: "home",
+		title: "Home",
+		route: "/"
+	};
+	const segments = relativePath.split("/").filter((s) => s && !s.startsWith("(") && !s.endsWith(")")).map((s) => s.replace(/^\[\.\.\..*\]$/, "catchall").replace(/^\[(.+)\]$/, "$1"));
+	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) => {
+			if (s.startsWith("[...") && s.endsWith("]")) return "*";
+			if (s.startsWith("[") && s.endsWith("]")) return `:${s.slice(1, -1)}`;
+			return s;
+		}).join("/")
+	};
+}
+/**
+* Generate screen.meta.ts file content
+*/
+function generateScreenMetaContent(meta) {
+	const inferredTag = meta.id.split(".")[0] || "general";
+	return `import { defineScreen } from "@screenbook/core"
+
+export const screen = defineScreen({
+	id: "${meta.id}",
+	title: "${meta.title}",
+	route: "${meta.route}",
+
+	// Team or individual responsible for this screen
+	owner: [],
+
+	// Tags for filtering in the catalog
+	tags: ["${inferredTag}"],
+
+	// APIs/services this screen depends on (for impact analysis)
+	// Example: ["UserAPI.getProfile", "PaymentService.checkout"]
+	dependsOn: [],
+
+	// Screen IDs that can navigate to this screen
+	entryPoints: [],
+
+	// Screen IDs this screen can navigate to
+	next: [],
+})
+`;
+}
+
+//#endregion
+//#region src/utils/impactAnalysis.ts
+/**
+* Check if a screen's dependsOn matches the API name (supports partial matching).
+* - "InvoiceAPI" matches "InvoiceAPI.getDetail"
+* - "InvoiceAPI.getDetail" matches "InvoiceAPI.getDetail"
+*/
+function matchesDependency(dependency, apiName) {
+	if (dependency === apiName) return true;
+	if (dependency.startsWith(`${apiName}.`)) return true;
+	if (apiName.startsWith(`${dependency}.`)) return true;
+	return false;
+}
+/**
+* Find screens that directly depend on the given API.
+*/
+function findDirectDependents(screens, apiName) {
+	return screens.filter((screen) => screen.dependsOn?.some((dep) => matchesDependency(dep, apiName)));
+}
+/**
+* Build a navigation graph from `next` field: screenId -> screens it can navigate to.
+*/
+function buildNavigationGraph(screens) {
+	const graph = /* @__PURE__ */ new Map();
+	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);
+	}
+	return graph;
+}
+/**
+* Find all transitive dependents using BFS.
+* A screen is transitively dependent if it can navigate to a directly dependent screen.
+*/
+function findTransitiveDependents(screens, directDependentIds, maxDepth) {
+	new Map(screens.map((s) => [s.id, s]));
+	const navigationGraph = buildNavigationGraph(screens);
+	const transitive = [];
+	const visited = /* @__PURE__ */ new Set();
+	for (const screen of screens) {
+		if (directDependentIds.has(screen.id)) continue;
+		const path = findPathToDirectDependent(screen.id, directDependentIds, navigationGraph, maxDepth, /* @__PURE__ */ new Set());
+		if (path && !visited.has(screen.id)) {
+			visited.add(screen.id);
+			transitive.push({
+				screen,
+				path
+			});
+		}
+	}
+	return transitive;
+}
+/**
+* Find a path from a screen to any directly dependent screen using BFS.
+*/
+function findPathToDirectDependent(startId, targetIds, graph, maxDepth, visited) {
+	if (visited.has(startId)) return null;
+	const queue = [{
+		id: startId,
+		path: [startId]
+	}];
+	const localVisited = new Set([startId]);
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (current.path.length > maxDepth + 1) continue;
+		const neighbors = graph.get(current.id);
+		if (!neighbors) continue;
+		for (const neighborId of neighbors) {
+			if (localVisited.has(neighborId)) continue;
+			const newPath = [...current.path, neighborId];
+			if (newPath.length > maxDepth + 1) continue;
+			if (targetIds.has(neighborId)) return newPath;
+			localVisited.add(neighborId);
+			queue.push({
+				id: neighborId,
+				path: newPath
+			});
+		}
+	}
+	return null;
+}
+/**
+* Analyze the impact of a change to an API on the screen catalog.
+*/
+function analyzeImpact(screens, apiName, maxDepth = 3) {
+	const direct = findDirectDependents(screens, apiName);
+	const transitive = findTransitiveDependents(screens, new Set(direct.map((s) => s.id)), maxDepth);
+	return {
+		api: apiName,
+		direct,
+		transitive,
+		totalCount: direct.length + transitive.length
+	};
+}
+/**
+* Format the impact result as text output.
+*/
+function formatImpactText(result) {
+	const lines = [];
+	lines.push(`Impact Analysis: ${result.api}`);
+	lines.push("");
+	if (result.direct.length > 0) {
+		lines.push(`Direct (${result.direct.length} screen${result.direct.length > 1 ? "s" : ""}):`);
+		for (const screen of result.direct) {
+			const owner = screen.owner?.length ? ` [${screen.owner.join(", ")}]` : "";
+			lines.push(`  - ${screen.id}  ${screen.route}${owner}`);
+		}
+		lines.push("");
+	}
+	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(" -> ")}`);
+		lines.push("");
+	}
+	if (result.totalCount === 0) {
+		lines.push("No screens depend on this API.");
+		lines.push("");
+	} else lines.push(`Total: ${result.totalCount} screen${result.totalCount > 1 ? "s" : ""} affected`);
+	return lines.join("\n");
+}
+/**
+* Format the impact result as JSON output.
+*/
+function formatImpactJson(result) {
+	return JSON.stringify({
+		api: result.api,
+		summary: {
+			directCount: result.direct.length,
+			transitiveCount: result.transitive.length,
+			totalCount: result.totalCount
+		},
+		direct: result.direct.map((s) => ({
+			id: s.id,
+			title: s.title,
+			route: s.route,
+			owner: s.owner
+		})),
+		transitive: result.transitive.map(({ screen, path }) => ({
+			id: screen.id,
+			title: screen.title,
+			route: screen.route,
+			path
+		}))
+	}, null, 2);
+}
+
+//#endregion
+//#region src/commands/impact.ts
+const impactCommand = define({
+	name: "impact",
+	description: "Analyze which screens depend on a specific API/service",
+	args: {
+		api: {
+			type: "positional",
+			description: "API or service name to analyze (e.g., InvoiceAPI.getDetail)",
+			required: true
+		},
+		config: {
+			type: "string",
+			short: "c",
+			description: "Path to config file"
+		},
+		format: {
+			type: "string",
+			short: "f",
+			description: "Output format: text (default) or json",
+			default: "text"
+		},
+		depth: {
+			type: "number",
+			short: "d",
+			description: "Maximum depth for transitive dependencies",
+			default: 3
+		}
+	},
+	run: async (ctx) => {
+		const config = await loadConfig(ctx.values.config);
+		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");
+			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.");
+			process.exit(1);
+		}
+		let screens;
+		try {
+			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));
+			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.");
+			return;
+		}
+		const result = analyzeImpact(screens, apiName, depth);
+		if (format === "json") console.log(formatImpactJson(result));
+		else console.log(formatImpactText(result));
+	}
+});
+
+//#endregion
+//#region src/utils/detectFramework.ts
+const FRAMEWORKS = [
+	{
+		name: "Next.js (App Router)",
+		packages: ["next"],
+		configFiles: [
+			"next.config.js",
+			"next.config.mjs",
+			"next.config.ts"
+		],
+		routesPattern: "app/**/page.tsx",
+		metaPattern: "app/**/screen.meta.ts",
+		check: (cwd) => existsSync(join(cwd, "app")) || existsSync(join(cwd, "src/app"))
+	},
+	{
+		name: "Next.js (Pages Router)",
+		packages: ["next"],
+		configFiles: [
+			"next.config.js",
+			"next.config.mjs",
+			"next.config.ts"
+		],
+		routesPattern: "pages/**/*.tsx",
+		metaPattern: "pages/**/screen.meta.ts",
+		check: (cwd) => existsSync(join(cwd, "pages")) || existsSync(join(cwd, "src/pages"))
+	},
+	{
+		name: "Remix",
+		packages: ["@remix-run/react", "remix"],
+		configFiles: ["remix.config.js", "vite.config.ts"],
+		routesPattern: "app/routes/**/*.tsx",
+		metaPattern: "app/routes/**/screen.meta.ts"
+	},
+	{
+		name: "Nuxt",
+		packages: ["nuxt"],
+		configFiles: [
+			"nuxt.config.ts",
+			"nuxt.config.js",
+			"nuxt.config.mjs"
+		],
+		routesPattern: "pages/**/*.vue",
+		metaPattern: "pages/**/screen.meta.ts",
+		check: (cwd) => {
+			if (existsSync(join(cwd, "app/pages"))) return false;
+			return existsSync(join(cwd, "pages"));
+		}
+	},
+	{
+		name: "Nuxt 4",
+		packages: ["nuxt"],
+		configFiles: ["nuxt.config.ts", "nuxt.config.js"],
+		routesPattern: "app/pages/**/*.vue",
+		metaPattern: "app/pages/**/screen.meta.ts",
+		check: (cwd) => existsSync(join(cwd, "app/pages"))
+	},
+	{
+		name: "Astro",
+		packages: ["astro"],
+		configFiles: [
+			"astro.config.mjs",
+			"astro.config.js",
+			"astro.config.ts",
+			"astro.config.cjs"
+		],
+		routesPattern: "src/pages/**/*.astro",
+		metaPattern: "src/pages/**/screen.meta.ts"
+	},
+	{
+		name: "Vite + Vue",
+		packages: ["vite", "vue"],
+		configFiles: [
+			"vite.config.ts",
+			"vite.config.js",
+			"vite.config.mjs"
+		],
+		routesPattern: "src/pages/**/*.vue",
+		metaPattern: "src/pages/**/screen.meta.ts",
+		check: (cwd) => {
+			const packageJson = readPackageJson(cwd);
+			if (!packageJson) return false;
+			return !hasPackage(packageJson, "react");
+		}
+	},
+	{
+		name: "Vite + React",
+		packages: ["vite", "react"],
+		configFiles: [
+			"vite.config.ts",
+			"vite.config.js",
+			"vite.config.mjs"
+		],
+		routesPattern: "src/pages/**/*.tsx",
+		metaPattern: "src/pages/**/screen.meta.ts"
+	}
+];
+function readPackageJson(cwd) {
+	const packageJsonPath = join(cwd, "package.json");
+	if (!existsSync(packageJsonPath)) return null;
+	try {
+		const content = readFileSync(packageJsonPath, "utf-8");
+		return JSON.parse(content);
+	} catch {
+		return null;
+	}
+}
+function hasPackage(packageJson, packageName) {
+	return !!(packageJson.dependencies?.[packageName] || packageJson.devDependencies?.[packageName]);
+}
+function hasConfigFile(cwd, configFiles) {
+	return configFiles.some((file) => existsSync(join(cwd, file)));
+}
+/**
+* Auto-detect the frontend framework in a project directory.
+* Returns framework info if detected, null otherwise.
+*/
+function detectFramework(cwd) {
+	const packageJson = readPackageJson(cwd);
+	if (!packageJson) return null;
+	for (const framework of FRAMEWORKS) {
+		if (!framework.packages.some((pkg) => hasPackage(packageJson, pkg))) continue;
+		if (!hasConfigFile(cwd, framework.configFiles)) continue;
+		if (framework.check && !framework.check(cwd)) continue;
+		return {
+			name: framework.name,
+			routesPattern: framework.routesPattern,
+			metaPattern: framework.metaPattern
+		};
+	}
+	return null;
+}
+/**
+* Interactive framework selection when auto-detection fails.
+*/
+async function promptFrameworkSelection() {
+	const choices = FRAMEWORKS.filter((fw, idx, arr) => arr.findIndex((f) => f.routesPattern === fw.routesPattern) === idx).map((fw) => ({
+		title: fw.name,
+		value: fw
+	}));
+	choices.push({
+		title: "Other (manual configuration)",
+		value: null
+	});
+	const response = await prompts({
+		type: "select",
+		name: "framework",
+		message: "Select your frontend framework:",
+		choices
+	});
+	if (!response.framework) return null;
+	return {
+		name: response.framework.name,
+		routesPattern: response.framework.routesPattern,
+		metaPattern: response.framework.metaPattern
+	};
+}
+
+//#endregion
+//#region src/commands/init.ts
+function generateConfigTemplate(framework) {
+	if (framework) return `import { defineConfig } from "@screenbook/core"
+
+export default defineConfig({
+	// Auto-detected: ${framework.name}
+	metaPattern: "${framework.metaPattern}",
+	routesPattern: "${framework.routesPattern}",
+	outDir: ".screenbook",
+})
+`;
+	return `import { defineConfig } from "@screenbook/core"
+
+export default defineConfig({
+	// Glob pattern for screen metadata files
+	metaPattern: "src/**/screen.meta.ts",
+
+	// Glob pattern for route files (uncomment and adjust for your framework):
+	// routesPattern: "src/pages/**/page.tsx",   // Vite/React
+	// routesPattern: "app/**/page.tsx",         // Next.js App Router
+	// routesPattern: "pages/**/*.tsx",          // Next.js Pages Router
+	// routesPattern: "app/routes/**/*.tsx",     // Remix
+	// routesPattern: "pages/**/*.vue",          // Nuxt
+	// routesPattern: "src/pages/**/*.astro",    // Astro
+
+	outDir: ".screenbook",
+})
+`;
+}
+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");
+}
+function printNextSteps(hasRoutesPattern) {
+	console.log("");
+	console.log("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");
+	} 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");
+	}
+	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");
+}
+const initCommand = define({
+	name: "init",
+	description: "Initialize Screenbook in a project",
+	args: {
+		force: {
+			type: "boolean",
+			short: "f",
+			description: "Overwrite existing files",
+			default: false
+		},
+		skipDetect: {
+			type: "boolean",
+			description: "Skip framework auto-detection",
+			default: false
+		}
+	},
+	run: async (ctx) => {
+		const cwd = process.cwd();
+		const force = ctx.values.force ?? false;
+		const skipDetect = ctx.values.skipDetect ?? false;
+		console.log("Initializing Screenbook...");
+		console.log("");
+		let framework = null;
+		if (!skipDetect) {
+			framework = detectFramework(cwd);
+			if (framework) console.log(`  Detected: ${framework.name}`);
+			else {
+				console.log("  Could not auto-detect framework");
+				console.log("");
+				framework = await promptFrameworkSelection();
+				if (framework) {
+					console.log("");
+					console.log(`  Selected: ${framework.name}`);
+				}
+			}
+		}
+		const configPath = join(cwd, "screenbook.config.ts");
+		if (!force && existsSync(configPath)) console.log("  - screenbook.config.ts already exists (skipped)");
+		else {
+			writeFileSync(configPath, generateConfigTemplate(framework));
+			console.log("  + Created screenbook.config.ts");
+		}
+		const gitignorePath = join(cwd, ".gitignore");
+		const screenbookIgnore = ".screenbook";
+		if (existsSync(gitignorePath)) {
+			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)");
+		} else {
+			writeFileSync(gitignorePath, `# Screenbook\n${screenbookIgnore}\n`);
+			console.log("  + Created .gitignore with .screenbook");
+		}
+		console.log("");
+		console.log("Screenbook initialized successfully!");
+		printValueProposition();
+		printNextSteps(framework !== null);
+	}
+});
+
+//#endregion
+//#region src/commands/lint.ts
+const lintCommand = define({
+	name: "lint",
+	description: "Detect routes without screen.meta.ts files",
+	args: { config: {
+		type: "string",
+		short: "c",
+		description: "Path to config file"
+	} },
+	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("");
+			process.exit(1);
+		}
+		console.log("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}%`);
+		}
+		console.log("");
+		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 (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(", ")})`);
+			return;
+		}
+		const metaFiles = await glob(config.metaPattern, {
+			cwd,
+			ignore: config.ignore
+		});
+		const metaDirs = /* @__PURE__ */ new Set();
+		for (const metaFile of metaFiles) metaDirs.add(dirname(metaFile));
+		const missingMeta = [];
+		const covered = [];
+		for (const routeFile of routeFiles) {
+			const routeDir = dirname(routeFile);
+			if (metaDirs.has(routeDir)) covered.push(routeFile);
+			else missingMeta.push(routeFile);
+		}
+		const total = routeFiles.length;
+		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("");
+		const minimumCoverage = adoption.minimumCoverage ?? 100;
+		const passedCoverage = coveragePercent >= minimumCoverage;
+		if (missingCount > 0) {
+			console.log(`Missing screen.meta.ts (${missingCount} files):`);
+			console.log("");
+			for (const file of missingMeta) {
+				const suggestedMetaPath = join(dirname(file), "screen.meta.ts");
+				console.log(`  ✗ ${file}`);
+				console.log(`    → ${suggestedMetaPath}`);
+			}
+			console.log("");
+		}
+		if (!passedCoverage) {
+			console.log(`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");
+		const screensPath = join(cwd, config.outDir, "screens.json");
+		if (existsSync(screensPath)) try {
+			const content = readFileSync(screensPath, "utf-8");
+			const orphans = findOrphanScreens(JSON.parse(content));
+			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.");
+			}
+		} catch {}
+		if (hasWarnings) {
+			console.log("");
+			console.log("Lint completed with warnings.");
+		}
+	}
+});
+/**
+* Find screens that are unreachable (orphans).
+* A screen is an orphan if:
+* - It has no entryPoints defined
+* - AND it's not referenced in any other screen's `next` array
+*/
+function findOrphanScreens(screens) {
+	const referencedIds = /* @__PURE__ */ new Set();
+	for (const screen of screens) if (screen.next) for (const nextId of screen.next) referencedIds.add(nextId);
+	const orphans = [];
+	for (const screen of screens) {
+		const hasEntryPoints = screen.entryPoints && screen.entryPoints.length > 0;
+		const isReferenced = referencedIds.has(screen.id);
+		if (!hasEntryPoints && !isReferenced) orphans.push(screen);
+	}
+	return orphans;
+}
+
+//#endregion
+//#region src/commands/pr-impact.ts
+const prImpactCommand = define({
+	name: "pr-impact",
+	description: "Analyze impact of changed files in a PR",
+	args: {
+		base: {
+			type: "string",
+			short: "b",
+			description: "Base branch to compare against (default: main)",
+			default: "main"
+		},
+		config: {
+			type: "string",
+			short: "c",
+			description: "Path to config file"
+		},
+		format: {
+			type: "string",
+			short: "f",
+			description: "Output format: markdown (default) or json",
+			default: "markdown"
+		},
+		depth: {
+			type: "number",
+			short: "d",
+			description: "Maximum depth for transitive dependencies",
+			default: 3
+		}
+	},
+	run: async (ctx) => {
+		const config = await loadConfig(ctx.values.config);
+		const cwd = process.cwd();
+		const baseBranch = ctx.values.base ?? "main";
+		const format = ctx.values.format ?? "markdown";
+		const depth = ctx.values.depth ?? 3;
+		let changedFiles;
+		try {
+			changedFiles = execSync(`git diff --name-only ${baseBranch}...HEAD 2>/dev/null || git diff --name-only ${baseBranch} HEAD`, {
+				cwd,
+				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}`);
+			process.exit(1);
+		}
+		if (changedFiles.length === 0) {
+			console.log("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({
+				apis: [],
+				results: [],
+				changedFiles
+			}, null, 2));
+			return;
+		}
+		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.");
+			process.exit(1);
+		}
+		let screens;
+		try {
+			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));
+			process.exit(1);
+		}
+		const results = [];
+		for (const apiName of apiNames) {
+			const result = analyzeImpact(screens, apiName, depth);
+			if (result.totalCount > 0) results.push(result);
+		}
+		if (format === "json") console.log(JSON.stringify({
+			changedFiles,
+			detectedApis: apiNames,
+			results: results.map((r) => ({
+				api: r.api,
+				directCount: r.direct.length,
+				transitiveCount: r.transitive.length,
+				totalCount: r.totalCount,
+				direct: r.direct.map((s) => ({
+					id: s.id,
+					title: s.title,
+					route: s.route,
+					owner: s.owner
+				})),
+				transitive: r.transitive.map(({ screen, path }) => ({
+					id: screen.id,
+					title: screen.title,
+					route: screen.route,
+					path
+				}))
+			}))
+		}, null, 2));
+		else console.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
+const mainCommand = define({
+	name: "screenbook",
+	description: "Screen catalog and navigation graph generator",
+	run: () => {
+		console.log("Usage: screenbook <command>");
+		console.log("");
+		console.log("Commands:");
+		console.log("  init       Initialize Screenbook in a project");
+		console.log("  generate   Auto-generate screen.meta.ts from routes");
+		console.log("  build      Build screen metadata JSON");
+		console.log("  dev        Start the development server");
+		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("");
+		console.log("Run 'screenbook <command> --help' for more information");
+	}
+});
+await cli(process.argv.slice(2), mainCommand, {
+	name: "screenbook",
+	version: "0.0.1",
+	subCommands: {
+		init: initCommand,
+		generate: generateCommand,
+		build: buildCommand,
+		dev: devCommand,
+		lint: lintCommand,
+		impact: impactCommand,
+		"pr-impact": prImpactCommand
+	}
+});
+
+//#endregion
+export {  };
+//# sourceMappingURL=index.mjs.map