blodemd 0.0.6 → 0.0.8

package/README.md

@@ -23,7 +23,7 @@ Or run without installing:
 npx blodemd
 ```
 
-Requires Node.js 18+.
+Requires Node.js 20.17+ and <25.
 
 ## Quick Start
 
@@ -90,7 +90,7 @@ The CLI looks for a `docs.json` file in the docs directory. Minimal example:
 
 ```json
 {
-  "$schema": "https://mintlify.com/docs.json",
+  "$schema": "https://docs.blode.md/docs.json",
   "name": "my-project",
   "theme": "mint",
   "colors": { "primary": "#0D9373" },

package/dev-server/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/dev-server/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "next dev",
+    "dev": "next dev --webpack",
     "build": "next build",
     "start": "next start",
     "lint": "oxlint .",

package/dev-server/tsconfig.json

@@ -6,7 +6,7 @@
     "esModuleInterop": true,
     "incremental": false,
     "isolatedModules": true,
-    "jsx": "preserve",
+    "jsx": "react-jsx",
     "lib": [
       "es2022",
       "DOM",
@@ -44,6 +44,7 @@
     "**/*.tsx",
     "next-env.d.ts",
     "next.config.js",
-    ".next/types/**/*.ts"
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
   ]
 }

package/dist/cli.mjs

@@ -9,12 +9,14 @@ import { Command } from "commander";
 import open from "open";
 import { homedir } from "node:os";
 import { once } from "node:events";
+import { createServer } from "node:net";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import { createFsSource, loadSiteConfig } from "@repo/previewing";
 import { watch } from "chokidar";
-import { createServer } from "node:http";
+import { createServer as createServer$1 } from "node:http";
 import { createHash, randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
 //#region src/constants.ts
 const CLI_NAME = "blodemd";
 const OAUTH_CLIENT_ID = "6b5f9860-fe96-4a83-b1ad-266260523c91";
@@ -289,9 +291,20 @@ const resolveTokenStatus = (token) => {
 	};
 };
 //#endregion
+//#region src/site-config.ts
+const CONFIG_FILE$2 = "docs.json";
+const loadValidatedSiteConfig = async (root) => {
+	const result = await loadSiteConfig(createFsSource(root));
+	if (!result.ok) throw new CliError(result.errors.join("\n"), EXIT_CODES.VALIDATION, `Make sure ${CONFIG_FILE$2} exists and is valid JSON.`);
+	return {
+		config: result.config,
+		warnings: result.warnings
+	};
+};
+//#endregion
 //#region src/dev/resolve-root.ts
 const CONFIG_FILE$1 = "docs.json";
-const fileExists$2 = async (filePath) => {
+const fileExists$1 = async (filePath) => {
 	try {
 		await fs.access(filePath);
 		return true;
@@ -299,21 +312,17 @@ const fileExists$2 = async (filePath) => {
 		return false;
 	}
 };
-const resolveDocsRoot$1 = async (dir) => {
+const resolveDocsRoot = async (dir) => {
 	if (dir) return path.resolve(process.cwd(), dir);
 	const candidates = [
 		process.cwd(),
 		path.join(process.cwd(), "docs"),
 		path.join(process.cwd(), "apps/docs")
 	];
-	for (const candidate of candidates) if (await fileExists$2(path.join(candidate, CONFIG_FILE$1))) return candidate;
+	for (const candidate of candidates) if (await fileExists$1(path.join(candidate, CONFIG_FILE$1))) return candidate;
 	return process.cwd();
 };
-const validateDocsRoot = async (root) => {
-	const result = await loadSiteConfig(createFsSource(root));
-	if (!result.ok) throw new CliError(result.errors.join("\n"), EXIT_CODES.VALIDATION, `Make sure ${CONFIG_FILE$1} exists and is valid JSON.`);
-	return result;
-};
+const validateDocsRoot = async (root) => await loadValidatedSiteConfig(root);
 //#endregion
 //#region src/dev/watcher.ts
 const INVALIDATE_ENDPOINT = "/blodemd-dev/invalidate";
@@ -376,12 +385,20 @@ const createDevWatcher = ({ port, root }) => {
 //#region src/dev/command.ts
 const DEV_READY_ENDPOINT = "/blodemd-dev/version";
 const DEV_READY_TIMEOUT_MS = 45e3;
+const DEV_PORT_SCAN_LIMIT = 10;
+const DEV_SHUTDOWN_TIMEOUT_MS = 5e3;
+const LOCALHOST = "127.0.0.1";
+const RUNTIME_EXCLUDE_DIRS = new Set([
+	".next",
+	".turbo",
+	"node_modules"
+]);
 const parsePositiveInteger$1 = (value, label) => {
 	const parsed = Number.parseInt(value, 10);
 	if (!Number.isInteger(parsed) || parsed <= 0) throw new CliError(`${label} must be a positive integer.`, EXIT_CODES.VALIDATION);
 	return parsed;
 };
-const fileExists$1 = async (filePath) => {
+const fileExists = async (filePath) => {
 	try {
 		await fs.access(filePath);
 		return true;
@@ -389,11 +406,115 @@ const fileExists$1 = async (filePath) => {
 		return false;
 	}
 };
+const probePortAvailability = async (port) => {
+	const server = createServer();
+	const listening = (async () => {
+		await once(server, "listening");
+		return { kind: "listening" };
+	})();
+	const errored = (async () => {
+		const [error] = await once(server, "error");
+		return {
+			error,
+			kind: "error"
+		};
+	})();
+	server.listen({
+		exclusive: true,
+		host: LOCALHOST,
+		port
+	});
+	const outcome = await Promise.race([listening, errored]);
+	if (outcome.kind === "error") {
+		if (outcome.error.code === "EADDRINUSE" || outcome.error.code === "EACCES") return false;
+		throw outcome.error;
+	}
+	server.close();
+	await once(server, "close");
+	return true;
+};
+const resolveDevPort = async (requestedPort, probePort = probePortAvailability) => {
+	for (let offset = 0; offset < DEV_PORT_SCAN_LIMIT; offset += 1) {
+		const candidate = requestedPort + offset;
+		if (candidate > 65535) break;
+		if (await probePort(candidate)) return candidate;
+	}
+	throw new CliError(`No available port found within ${DEV_PORT_SCAN_LIMIT} attempts starting at ${requestedPort}.`, EXIT_CODES.ERROR, "Close the process using the port or pass a different --port value.");
+};
+const shutdownChildProcess = async (child, timeoutMs = DEV_SHUTDOWN_TIMEOUT_MS) => {
+	if (child.exitCode !== null) return;
+	const timer = setTimeout(() => {
+		if (child.exitCode === null) child.kill("SIGKILL");
+	}, timeoutMs);
+	const exitPromise = once(child, "exit");
+	try {
+		child.kill("SIGTERM");
+	} catch (error) {
+		clearTimeout(timer);
+		if (error.code === "ESRCH") return;
+		throw error;
+	}
+	await exitPromise.finally(() => {
+		clearTimeout(timer);
+	});
+};
 /**
 * Derive the CLI npm package root from the running script path.
 * The CLI entry point is at `<pkg-root>/dist/cli.mjs`.
 */
 const resolveCliPackageRoot = (cliFilePath) => path.dirname(path.dirname(cliFilePath));
+const copyStandaloneTree = async (sourceDir, targetDir) => {
+	await fs.cp(sourceDir, targetDir, {
+		filter: (source) => {
+			const relative = path.relative(sourceDir, source);
+			if (!relative) return true;
+			const topSegment = relative.split(path.sep)[0] ?? "";
+			return !RUNTIME_EXCLUDE_DIRS.has(topSegment);
+		},
+		recursive: true
+	});
+};
+const isStandaloneCliInstall = async (cliPackageRoot) => {
+	try {
+		return (await fs.realpath(cliPackageRoot)).split(path.sep).includes("node_modules");
+	} catch {
+		return cliPackageRoot.split(path.sep).includes("node_modules");
+	}
+};
+const materializeStandaloneRuntime = async (cliPackageRoot) => {
+	const runtimeRoot = path.join(CONFIG_DIR, "standalone-runtime");
+	await fs.rm(runtimeRoot, {
+		force: true,
+		recursive: true
+	});
+	await fs.mkdir(runtimeRoot, { recursive: true });
+	for (const dir of [
+		"dev-server",
+		"docs",
+		"packages"
+	]) await copyStandaloneTree(path.join(cliPackageRoot, dir), path.join(runtimeRoot, dir));
+	await fs.symlink(path.join(cliPackageRoot, "node_modules"), path.join(runtimeRoot, "node_modules"), process.platform === "win32" ? "junction" : "dir");
+	await fs.writeFile(path.join(runtimeRoot, "dev-server", "package.json"), `${JSON.stringify({
+		dependencies: {
+			next: "16.2.1",
+			react: "^19.2.0",
+			"react-dom": "^19.2.0"
+		},
+		devDependencies: {
+			"@types/node": "^22.19.15",
+			"@types/react": "19.2.14",
+			"@types/react-dom": "19.2.3",
+			typescript: "6.0.2"
+		},
+		name: "blodemd-dev-server",
+		private: true,
+		type: "module"
+	}, null, 2)}\n`);
+	return {
+		devServerDir: path.join(runtimeRoot, "dev-server"),
+		packagesDir: path.join(runtimeRoot, "packages")
+	};
+};
 /**
 * Check if a shipped dev-server exists alongside the CLI (npm-installed mode).
 * Verifies both the dev-server directory AND that `next` is resolvable
@@ -401,16 +522,19 @@ const resolveCliPackageRoot = (cliFilePath) => path.dirname(path.dirname(cliFile
 */
 const findStandaloneDevServer = async (cliPackageRoot) => {
 	const devServerDir = path.join(cliPackageRoot, "dev-server");
-	if (!await fileExists$1(path.join(devServerDir, "next.config.js"))) return null;
+	if (!await fileExists(path.join(devServerDir, "next.config.js"))) return null;
+	if (!await isStandaloneCliInstall(cliPackageRoot)) return null;
 	try {
 		createRequire(path.join(cliPackageRoot, "package.json")).resolve("next/package.json");
 	} catch {
 		return null;
 	}
+	const runtime = await materializeStandaloneRuntime(cliPackageRoot);
 	return {
-		devServerDir,
+		devServerDir: runtime.devServerDir,
 		mode: "standalone",
-		packagesDir: path.join(cliPackageRoot, "packages")
+		nextPackageRoot: cliPackageRoot,
+		packagesDir: runtime.packagesDir
 	};
 };
 /**
@@ -424,7 +548,7 @@ const findMonorepoRoot = async (start) => {
 	let current = start;
 	while (true) {
 		const packageJsonPath = path.join(current, "package.json");
-		if (await fileExists$1(packageJsonPath)) {
+		if (await fileExists(packageJsonPath)) {
 			const raw = await fs.readFile(packageJsonPath, "utf8");
 			const workspaces = JSON.parse(raw).workspaces ?? [];
 			if (workspaces.includes("apps/*") && workspaces.includes("packages/*")) return current;
@@ -445,8 +569,12 @@ const resolveDevServer = async (cliFilePath) => {
 };
 const spawnDevServer = (server, { root, port }) => {
 	if (server.mode === "standalone") {
-		const nextBin = resolveNextBin(path.dirname(server.devServerDir));
-		return spawn(process.execPath, [nextBin, "dev"], {
+		const nextBin = resolveNextBin(server.nextPackageRoot);
+		return spawn(process.execPath, [
+			nextBin,
+			"dev",
+			"--webpack"
+		], {
 			cwd: server.devServerDir,
 			env: {
 				...process.env,
@@ -490,14 +618,14 @@ const waitForServer = async ({ child, port }) => {
 const devCommand = async ({ dir, openBrowser, port: portValue }) => {
 	intro(chalk.bold("blodemd dev"));
 	try {
-		const port = parsePositiveInteger$1(portValue, "Port");
-		const root = await resolveDocsRoot$1(dir);
+		const resolvedPort = await resolveDevPort(parsePositiveInteger$1(portValue, "Port"));
+		const root = await resolveDocsRoot(dir);
 		await validateDocsRoot(root);
 		const server = await resolveDevServer(fileURLToPath(import.meta.url));
-		const localUrl = `http://localhost:${port}`;
+		const localUrl = `http://localhost:${resolvedPort}`;
 		log.info(`Docs root: ${chalk.cyan(root)}`);
 		const child = spawnDevServer(server, {
-			port,
+			port: resolvedPort,
 			root
 		});
 		let watcher = null;
@@ -509,17 +637,17 @@ const devCommand = async ({ dir, openBrowser, port: portValue }) => {
 				await watcher.close();
 				watcher = null;
 			}
-			if (child.exitCode === null && !child.killed) child.kill("SIGTERM");
+			await shutdownChildProcess(child);
 		};
 		process.once("SIGINT", closeAll);
 		process.once("SIGTERM", closeAll);
 		try {
 			await waitForServer({
 				child,
-				port
+				port: resolvedPort
 			});
 			watcher = await createDevWatcher({
-				port,
+				port: resolvedPort,
 				root
 			});
 			log.success(`Dev server running at ${chalk.cyan(localUrl)}`);
@@ -562,7 +690,7 @@ const waitForOAuthCode = (options) => {
 			});
 			for (const socket of sockets) socket.destroy();
 		};
-		const httpServer = createServer((request, response) => {
+		const httpServer = createServer$1((request, response) => {
 			if (!request.url) {
 				response.writeHead(400, { "content-type": "text/html; charset=utf-8" });
 				response.end(errorHtml("Missing request URL"));
@@ -619,6 +747,53 @@ const createOAuthState = () => randomBytes(24).toString("hex");
 const createCodeVerifier = () => randomBytes(64).toString("base64url");
 const createCodeChallenge = (verifier) => createHash("sha256").update(verifier).digest().toString("base64url");
 //#endregion
+//#region src/runtime.ts
+const MIN_SUPPORTED_NODE_VERSION = [
+	20,
+	17,
+	0
+];
+const MAX_SUPPORTED_NODE_MAJOR = 25;
+const SUPPORTED_NODE_RANGE = ">=20.17.0 <25";
+const parseVersion = (input) => {
+	const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(input.trim());
+	if (!match) return null;
+	const [, majorText = "", minorText = "", patchText = ""] = match;
+	if (!majorText || !minorText || !patchText) return null;
+	const major = Number.parseInt(majorText, 10);
+	const minor = Number.parseInt(minorText, 10);
+	const patch = Number.parseInt(patchText, 10);
+	if ([
+		major,
+		minor,
+		patch
+	].some((value) => Number.isNaN(value))) return null;
+	return [
+		major,
+		minor,
+		patch
+	];
+};
+const isSupportedNodeVersion = (version) => {
+	const parsed = parseVersion(version);
+	if (!parsed) return false;
+	const [major, minor, patch] = parsed;
+	const [minMajor, minMinor, minPatch] = MIN_SUPPORTED_NODE_VERSION;
+	if (major >= MAX_SUPPORTED_NODE_MAJOR) return false;
+	if (major !== minMajor) return major > minMajor;
+	if (minor !== minMinor) return minor > minMinor;
+	return patch >= minPatch;
+};
+const assertSupportedNodeVersion = (version = process.versions.node) => {
+	if (isSupportedNodeVersion(version)) return;
+	throw new CliError(`blodemd requires Node.js ${SUPPORTED_NODE_RANGE}. Current version: ${version}.`, EXIT_CODES.VALIDATION, "Install a supported Node.js version and try again.");
+};
+const readCliVersion = (moduleUrl) => {
+	const moduleDir = path.dirname(fileURLToPath(moduleUrl));
+	const raw = readFileSync(path.resolve(moduleDir, "..", "package.json"), "utf8");
+	return JSON.parse(raw).version ?? "0.0.0";
+};
+//#endregion
 //#region src/cli.ts
 const CONFIG_FILE = "docs.json";
 const TEXT_CONTENT_TYPES = {
@@ -638,31 +813,6 @@ const ensureFile = async (filePath, content) => {
 		await fs.writeFile(filePath, content, { flag: "wx" });
 	} catch {}
 };
-const fileExists = async (filePath) => {
-	try {
-		await fs.access(filePath);
-		return true;
-	} catch {
-		return false;
-	}
-};
-const readConfig = async (root) => {
-	const raw = await fs.readFile(path.join(root, CONFIG_FILE), "utf8");
-	return {
-		name: JSON.parse(raw).name,
-		raw
-	};
-};
-const resolveDocsRoot = async (dir) => {
-	if (dir) return path.resolve(process.cwd(), dir);
-	const candidates = [
-		process.cwd(),
-		path.join(process.cwd(), "docs"),
-		path.join(process.cwd(), "apps/docs")
-	];
-	for (const candidate of candidates) if (await fileExists(path.join(candidate, CONFIG_FILE))) return candidate;
-	return process.cwd();
-};
 const readGitValue = (gitArgs) => {
 	const result = spawnSync("git", gitArgs, {
 		encoding: "utf8",
@@ -806,7 +956,11 @@ const uploadFiles = async (files, root, apiPath, deploymentId, headers, s) => {
 	s.stop(`Uploaded ${chalk.cyan(String(files.length))} files`);
 };
 const program = new Command();
-program.name("blodemd").description("Blode.md CLI").version("0.0.3");
+const cliVersion = readCliVersion(import.meta.url);
+program.name("blodemd").description("Blode.md CLI").version(cliVersion);
+program.hook("preAction", () => {
+	assertSupportedNodeVersion();
+});
 program.command("login").description("Authenticate with Blode.md").option("--token", "Paste an API key instead of using browser login").option("--port <port>", "Loopback callback port", String(DEFAULT_OAUTH_CALLBACK_PORT)).option("--timeout <seconds>", "OAuth timeout in seconds", String(180)).option("--no-open", "Print URL instead of opening the browser").action(async (options) => {
 	intro(chalk.bold("blodemd login"));
 	try {
@@ -916,7 +1070,7 @@ program.command("init").description("Scaffold a docs folder").argument("[dir]",
 		const root = path.resolve(process.cwd(), dir);
 		await fs.mkdir(root, { recursive: true });
 		await ensureFile(path.join(root, CONFIG_FILE), `${JSON.stringify({
-			$schema: "https://mintlify.com/docs.json",
+			$schema: "https://docs.blode.md/docs.json",
 			colors: { primary: "#0D9373" },
 			name: "my-project",
 			navigation: { groups: [{
@@ -936,7 +1090,8 @@ program.command("init").description("Scaffold a docs folder").argument("[dir]",
 program.command("validate").description("Validate docs.json").argument("[dir]", "docs directory").action(async (dir) => {
 	intro(chalk.bold("blodemd validate"));
 	try {
-		await readConfig(await resolveDocsRoot(dir));
+		const { warnings } = await loadValidatedSiteConfig(await resolveDocsRoot(dir));
+		for (const warning of warnings) log.warn(warning);
 		log.success(`${chalk.cyan(CONFIG_FILE)} is valid.`);
 		log.info("Done");
 	} catch (error) {
@@ -949,8 +1104,9 @@ program.command("push").description("Deploy docs").argument("[dir]", "docs direc
 	try {
 		const root = await resolveDocsRoot(dir);
 		s.start("Validating configuration");
-		const config = await readConfig(root);
+		const { config, warnings } = await loadValidatedSiteConfig(root);
 		s.stop("Configuration valid");
+		for (const warning of warnings) log.warn(warning);
 		const { project, apiUrl, authToken, branch, commitMessage } = await resolvePushConfig(config, options);
 		s.start("Collecting files");
 		const files = await collectFiles(root);