@askrjs/cli 0.0.13 → 0.0.15

package/README.md

@@ -49,6 +49,7 @@ unless you opt out with `--no-skills`.
 - `askr skills install [--cwd <dir>] [--force]`
 - `askr skills sync [--cwd <dir>]`
 - `askr ssg --config <path> --output <dir> [--incremental]`
+- `askr verify-hydration [--output ./dist] [--route <path>]...`
 - `askr openapi [--entry ./src/api.ts] [--output ./openapi.yml] [--check]`
 - `askr outdated [packages...] [--workspace <glob>] [--tag <tag>] [--json]`
 - `askr update [packages...] [--workspace <glob>] [--tag <tag>] [--json]`
@@ -140,6 +141,24 @@ owned files so stale chunks and previous output paths are removed. Full and
 incremental builds publish through a sibling staging directory, so route output,
 metadata, assets, and sitemap artifacts change together or not at all.
 
+## Hydration verification
+
+`askr verify-hydration` builds SSG output, serves the generated route set, and
+loads every successful metadata route in a real headless browser both with and
+without JavaScript. It compares normalized tag-and-child topology under `#app`
+after hydration, so text, classes, and mutable ARIA state do not create noise
+while nodes migrating into the wrong sibling container fail with an actionable
+static-versus-hydrated path diff.
+
+```bash
+askr verify-hydration
+askr verify-hydration --route / --route /docs
+askr verify-hydration --no-build --output ./dist
+```
+
+See the [hydration verification reference](./docs/verify-hydration.md) for
+browser installation, timeout, route, and root-selector options.
+
 ## OpenAPI artifacts
 
 `askr openapi` loads a TypeScript module whose default export exposes

package/dist/cli.js

@@ -41,6 +41,7 @@ function printHelp(io = console) {
 	io.log("  openapi    Generate or check an OpenAPI YAML artifact");
 	io.log("  skills     Install or sync Askr agent skills");
 	io.log("  ssg        Run static-site generation");
+	io.log("  verify-hydration  Verify SSG DOM structure in a real browser");
 	io.log("  outdated   List available dependency updates");
 	io.log("  repair     Apply safe fixes and identify remaining semantic work");
 	io.log("  update     Apply safe dependency updates");
@@ -63,6 +64,7 @@ function printHelp(io = console) {
 	io.log("  askr openapi --check");
 	io.log("  askr skills review foundation --cwd ./candidate-app");
 	io.log("  askr ssg --config ./ssg.config.ts --output ./dist/static");
+	io.log("  askr verify-hydration --output ./dist --route /");
 	io.log("  askr outdated");
 	io.log("  askr update");
 	io.log("  askr upgrade");
@@ -101,6 +103,10 @@ async function runCli(args = process.argv.slice(2), io = console) {
 		const { runSsgCli } = await import("./ssg.js");
 		return runSsgCli(args.slice(1), void 0, io);
 	}
+	if (command === "verify-hydration") {
+		const { runVerifyHydrationCli } = await import("./verify-hydration.js");
+		return runVerifyHydrationCli(args.slice(1), void 0, io);
+	}
 	if (command === "openapi") {
 		const { runOpenApiCli } = await import("./openapi.js");
 		return runOpenApiCli(args.slice(1), io);

package/dist/verify-hydration.d.ts

@@ -0,0 +1,35 @@
+import { Browser } from "playwright-core";
+//#region src/bin/verify-hydration.d.ts
+type CliIo = Pick<Console, "error" | "log">;
+interface ParsedVerifyHydrationArgs {
+  cwd: string;
+  outputDir: string;
+  routes: string[];
+  rootSelector: string;
+  buildScript: string;
+  build: boolean;
+  timeoutMs: number;
+  browserChannel?: string;
+  help: boolean;
+  errors: string[];
+}
+interface RouteMetadata {
+  path: string;
+  filePath: string;
+  status?: string;
+}
+interface StaticOutputServer {
+  origin: string;
+  close(): Promise<void>;
+}
+interface VerifyHydrationDeps {
+  runBuild?: (cwd: string, script: string) => Promise<void>;
+  launchBrowser?: (channel?: string) => Promise<Browser>;
+  startServer?: (outputDir: string, routes: readonly RouteMetadata[]) => Promise<StaticOutputServer>;
+}
+declare function parseVerifyHydrationArgs(args: string[], defaultCwd?: string): ParsedVerifyHydrationArgs;
+declare function startStaticOutputServer(outputDir: string, routes: readonly RouteMetadata[]): Promise<StaticOutputServer>;
+declare function verifyHydrationRoutes(browser: Browser, origin: string, routes: readonly RouteMetadata[], rootSelector: string, timeoutMs: number): Promise<string[]>;
+declare function runVerifyHydrationCli(args?: string[], deps?: VerifyHydrationDeps, io?: CliIo): Promise<number>;
+//#endregion
+export { parseVerifyHydrationArgs, runVerifyHydrationCli, startStaticOutputServer, verifyHydrationRoutes };

package/dist/verify-hydration.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+import { t as isDirectExecution } from "./is-direct-execution-Cdlr-ZUl.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import http from "node:http";
+//#region src/bin/verify-hydration.ts
+const helpText = `
+askr verify-hydration - Verify SSG DOM structure in a real browser
+
+Usage:
+  askr verify-hydration [--output <dir>] [--route <path> ...]
+
+Options:
+  --cwd <dir>             Project directory (default: current directory)
+  --output <dir>          Generated SSG output (default: dist)
+  --route <path>          Route to verify; repeat to select a route set
+  --root <selector>       Hydrated application root (default: #app)
+  --build-script <name>   npm script that builds SSG output (default: build)
+  --no-build              Verify existing output without running a build
+  --timeout <ms>          Per-route browser timeout (default: 10000)
+  --browser-channel <id>  Browser channel: chrome, msedge, or playwright
+  --help                  Show this help message
+
+When --route is omitted, routes are read from <output>/metadata.json.
+`;
+function parsePositiveInteger(value, option, errors) {
+	const parsed = Number(value);
+	if (!Number.isSafeInteger(parsed) || parsed < 1) {
+		errors.push(`${option} must be a positive integer`);
+		return;
+	}
+	return parsed;
+}
+function parseVerifyHydrationArgs(args, defaultCwd = process.cwd()) {
+	const parsed = {
+		cwd: defaultCwd,
+		outputDir: "dist",
+		routes: [],
+		rootSelector: "#app",
+		buildScript: "build",
+		build: true,
+		timeoutMs: 1e4,
+		help: false,
+		errors: []
+	};
+	const takeValue = (index, option) => {
+		const value = args[index + 1];
+		if (!value || value.startsWith("-")) {
+			parsed.errors.push(`Missing value for ${option}`);
+			return;
+		}
+		return value;
+	};
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--cwd" || argument === "--output" || argument === "--route" || argument === "--root" || argument === "--build-script" || argument === "--timeout" || argument === "--browser-channel") {
+			const value = takeValue(index, argument);
+			if (!value) continue;
+			index += 1;
+			if (argument === "--cwd") parsed.cwd = value;
+			else if (argument === "--output") parsed.outputDir = value;
+			else if (argument === "--route") parsed.routes.push(value);
+			else if (argument === "--root") parsed.rootSelector = value;
+			else if (argument === "--build-script") parsed.buildScript = value;
+			else if (argument === "--browser-channel") parsed.browserChannel = value;
+			else {
+				const timeout = parsePositiveInteger(value, "--timeout", parsed.errors);
+				if (timeout) parsed.timeoutMs = timeout;
+			}
+		} else if (argument === "--no-build") parsed.build = false;
+		else if (argument === "--help" || argument === "-h") parsed.help = true;
+		else parsed.errors.push(`Unknown option: ${argument}`);
+	}
+	parsed.cwd = path.resolve(defaultCwd, parsed.cwd);
+	parsed.outputDir = path.resolve(parsed.cwd, parsed.outputDir);
+	return parsed;
+}
+function normalizeRoute(route) {
+	const pathname = new URL(route, "http://askr.local").pathname;
+	return pathname === "/" ? pathname : pathname.replace(/\/+$/, "");
+}
+async function readRouteMetadata(outputDir, selectedRoutes) {
+	const metadataPath = path.join(outputDir, "metadata.json");
+	let metadata;
+	try {
+		metadata = JSON.parse(await fs.readFile(metadataPath, "utf8"));
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		throw new Error(`Could not read SSG route metadata at ${metadataPath}: ${detail}`);
+	}
+	const routes = metadata.routes;
+	if (!Array.isArray(routes)) throw new Error(`Invalid SSG route metadata at ${metadataPath}: routes must be an array.`);
+	const valid = routes.filter((entry) => Boolean(entry && typeof entry === "object" && typeof entry.path === "string" && typeof entry.filePath === "string" && entry.status !== "error" && entry.status !== "removed"));
+	const byPath = new Map(valid.map((entry) => [normalizeRoute(entry.path), entry]));
+	if (selectedRoutes.length === 0) return [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+	return [...new Set(selectedRoutes.map(normalizeRoute))].map((route) => {
+		const entry = byPath.get(route);
+		if (!entry) throw new Error(`Route ${route} is not present in ${metadataPath}.`);
+		return entry;
+	});
+}
+function contentType(filePath) {
+	const extension = path.extname(filePath).toLowerCase();
+	if (extension === ".html") return "text/html; charset=utf-8";
+	if (extension === ".js" || extension === ".mjs") return "text/javascript; charset=utf-8";
+	if (extension === ".css") return "text/css; charset=utf-8";
+	if (extension === ".json") return "application/json; charset=utf-8";
+	if (extension === ".svg") return "image/svg+xml";
+	if (extension === ".png") return "image/png";
+	if (extension === ".jpg" || extension === ".jpeg") return "image/jpeg";
+	if (extension === ".webp") return "image/webp";
+	return "application/octet-stream";
+}
+function closeServer(server) {
+	return new Promise((resolve, reject) => {
+		server.close((error) => error ? reject(error) : resolve());
+	});
+}
+async function startStaticOutputServer(outputDir, routes) {
+	const outputRoot = path.resolve(outputDir);
+	const routeFiles = new Map(routes.map((entry) => [normalizeRoute(entry.path), path.resolve(outputRoot, entry.filePath)]));
+	for (const [route, filePath] of routeFiles) {
+		const relative = path.relative(outputRoot, filePath);
+		if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Route ${route} resolves outside the SSG output directory.`);
+	}
+	const server = http.createServer(async (request, response) => {
+		try {
+			const pathname = normalizeRoute(new URL(request.url ?? "/", "http://askr.local").pathname);
+			const candidate = routeFiles.get(pathname) ?? path.resolve(outputRoot, `.${pathname}`);
+			const relative = path.relative(outputRoot, candidate);
+			if (relative.startsWith("..") || path.isAbsolute(relative)) {
+				response.writeHead(404).end("Not found");
+				return;
+			}
+			const filePath = (await fs.stat(candidate).catch(() => null))?.isDirectory() ? path.join(candidate, "index.html") : candidate;
+			const content = await fs.readFile(filePath);
+			response.writeHead(200, {
+				"cache-control": "no-store",
+				"content-type": contentType(filePath)
+			});
+			response.end(content);
+		} catch {
+			response.writeHead(404).end("Not found");
+		}
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", resolve);
+	});
+	const address = server.address();
+	if (!address || typeof address === "string") {
+		await closeServer(server);
+		throw new Error("Hydration verification server did not bind a TCP port.");
+	}
+	return {
+		origin: `http://127.0.0.1:${address.port}`,
+		close: () => closeServer(server)
+	};
+}
+async function runNpmBuild(cwd, script) {
+	await new Promise((resolve, reject) => {
+		const child = spawn(process.platform === "win32" ? "npm.cmd" : "npm", ["run", script], {
+			cwd,
+			stdio: "inherit"
+		});
+		const timer = setTimeout(() => {
+			child.kill("SIGTERM");
+			reject(/* @__PURE__ */ new Error(`npm run ${script} timed out after 300000ms.`));
+		}, 3e5);
+		child.once("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+		child.once("exit", (code, signal) => {
+			clearTimeout(timer);
+			if (code === 0) resolve();
+			else reject(/* @__PURE__ */ new Error(`npm run ${script} failed${signal ? ` with signal ${signal}` : ` with exit code ${code}`}.`));
+		});
+	});
+}
+async function launchChromium(channel) {
+	const { chromium } = await import("playwright-core");
+	const requested = channel ?? process.env.ASKR_BROWSER_CHANNEL ?? "chrome";
+	try {
+		return requested === "playwright" ? await chromium.launch({ headless: true }) : await chromium.launch({
+			channel: requested,
+			headless: true
+		});
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		throw new Error(`Could not launch the ${requested} browser channel. Install Chrome, pass --browser-channel msedge, or run "npx playwright-core install chromium" and pass --browser-channel playwright. ${detail}`);
+	}
+}
+async function snapshotRoot(page, selector) {
+	return page.evaluate((rootSelector) => {
+		const root = globalThis.document.querySelector(rootSelector);
+		if (!root) throw new Error(`Hydration root not found: ${rootSelector}`);
+		const lines = [];
+		const pending = [{
+			node: root,
+			path: rootSelector
+		}];
+		while (pending.length > 0) {
+			const current = pending.pop();
+			if (!current) break;
+			const { node, path: nodePath } = current;
+			if (node.nodeType !== 1) continue;
+			if (node.matches("script, style, link, meta, noscript, template")) continue;
+			lines.push(`${nodePath} <${node.tagName.toLowerCase()}>`);
+			const children = [...node.childNodes].filter((child) => child.nodeType === 1 && !child.matches("script, style, link, meta, noscript, template"));
+			for (let index = children.length - 1; index >= 0; index -= 1) pending.push({
+				node: children[index],
+				path: `${nodePath}/${index}`
+			});
+		}
+		return { lines };
+	}, selector);
+}
+function firstDifference(expected, actual) {
+	const length = Math.max(expected.lines.length, actual.lines.length);
+	for (let index = 0; index < length; index += 1) if (expected.lines[index] !== actual.lines[index]) return {
+		index,
+		expected: expected.lines[index] ?? "<missing>",
+		actual: actual.lines[index] ?? "<missing>"
+	};
+	return null;
+}
+async function loadSnapshot(context, url, selector, timeoutMs, settleHydration) {
+	const page = await context.newPage();
+	const errors = [];
+	page.on("pageerror", (error) => errors.push(error.message));
+	page.on("console", (message) => {
+		if (message.type() === "error") errors.push(`console: ${message.text()}`);
+	});
+	try {
+		page.setDefaultTimeout(timeoutMs);
+		const response = await page.goto(url, {
+			waitUntil: "load",
+			timeout: timeoutMs
+		});
+		if (!response?.ok()) throw new Error(`HTTP ${response?.status() ?? "failure"} loading ${url}`);
+		if (settleHydration) {
+			let timer;
+			try {
+				await Promise.race([page.evaluate(() => {
+					const animationFrame = globalThis.requestAnimationFrame;
+					return new Promise((resolve) => animationFrame(() => animationFrame(() => resolve())));
+				}), new Promise((_resolve, reject) => {
+					timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`Hydration timeout: did not settle within ${timeoutMs}ms.`)), timeoutMs);
+				})]);
+			} finally {
+				if (timer) clearTimeout(timer);
+			}
+		}
+		return {
+			snapshot: await snapshotRoot(page, selector),
+			errors
+		};
+	} finally {
+		await page.close();
+	}
+}
+async function verifyHydrationRoutes(browser, origin, routes, rootSelector, timeoutMs) {
+	const failures = [];
+	const staticContext = await browser.newContext({ javaScriptEnabled: false });
+	const hydratedContext = await browser.newContext({ javaScriptEnabled: true });
+	try {
+		for (const route of routes) {
+			const url = `${origin}${normalizeRoute(route.path)}`;
+			try {
+				const expected = await loadSnapshot(staticContext, url, rootSelector, timeoutMs, false);
+				const actual = await loadSnapshot(hydratedContext, url, rootSelector, timeoutMs, true);
+				const difference = firstDifference(expected.snapshot, actual.snapshot);
+				if (difference) failures.push(`${route.path}: DOM diverged at normalized entry ${difference.index}\n  static:   ${difference.expected}\n  hydrated: ${difference.actual}`);
+				for (const error of actual.errors) failures.push(`${route.path}: browser error: ${error}`);
+			} catch (error) {
+				const detail = error instanceof Error ? error.message : String(error);
+				failures.push(`${route.path}: ${detail}`);
+			}
+		}
+	} finally {
+		await Promise.all([staticContext.close(), hydratedContext.close()]);
+	}
+	return failures;
+}
+async function runVerifyHydrationCli(args = process.argv.slice(2), deps = {}, io = console) {
+	const parsed = parseVerifyHydrationArgs(args);
+	if (parsed.help) {
+		io.log(helpText);
+		return 0;
+	}
+	if (parsed.errors.length > 0) {
+		for (const error of parsed.errors) io.error(`Error: ${error}`);
+		return 1;
+	}
+	let server;
+	let browser;
+	try {
+		if (parsed.build) await (deps.runBuild ?? runNpmBuild)(parsed.cwd, parsed.buildScript);
+		const routes = await readRouteMetadata(parsed.outputDir, parsed.routes);
+		if (routes.length === 0) throw new Error("SSG metadata contains no successful routes to verify.");
+		server = await (deps.startServer ?? startStaticOutputServer)(parsed.outputDir, routes);
+		browser = await (deps.launchBrowser ?? launchChromium)(parsed.browserChannel);
+		const failures = await verifyHydrationRoutes(browser, server.origin, routes, parsed.rootSelector, parsed.timeoutMs);
+		if (failures.length > 0) {
+			for (const failure of failures) io.error(`Hydration verification failed: ${failure}`);
+			return 1;
+		}
+		io.log(`Verified hydration DOM for ${routes.length} route(s).`);
+		return 0;
+	} catch (error) {
+		io.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+		return 1;
+	} finally {
+		await browser?.close().catch(() => void 0);
+		await server?.close().catch(() => void 0);
+	}
+}
+async function main() {
+	process.exit(await runVerifyHydrationCli());
+}
+if (isDirectExecution(import.meta.url)) main();
+//#endregion
+export { parseVerifyHydrationArgs, runVerifyHydrationCli, startStaticOutputServer, verifyHydrationRoutes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askrjs/cli",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Unified CLI for the Askr platform",
   "homepage": "https://github.com/askrjs/askr-cli#readme",
   "bugs": {
@@ -57,6 +57,7 @@
     "js-yaml": "^5.2.1",
     "minimatch": "^10.2.5",
     "npm-registry-fetch": "^19.1.1",
+    "playwright-core": "^1.62.0",
     "semver": "^7.8.5",
     "tsx": "^4.23.1",
     "typescript": "^6.0.3"