@prudentbird/voxx 1.0.0

package/dist/index.mjs

@@ -0,0 +1,1346 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { access, copyFile, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, extname, join, normalize, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import { DEFAULT_CONFIG, buildNavTree, buildSeo, escapeXml, formatDate, getPosts, humanize, loadConfig, parseVersion, renderLlmsFull, renderLlmsTxtSections, renderRobotsTxt, renderRss, renderSitemap, resolveCollectionDefaults, rssPath, sectionHeading, serializeJsonLd, slugify, splitDatePrefix, splitOrderPrefix } from "@prudentbird/voxx-core";
+import { watch } from "node:fs";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+//#region src/util.ts
+const require = createRequire(import.meta.url);
+const TEMPLATES_DIR = fileURLToPath(new URL("../templates", import.meta.url));
+const useColor = process.stdout.isTTY && !process.env["NO_COLOR"];
+const wrap = (code) => (s) => useColor ? `[${code}m${s}[0m` : s;
+/** ANSI color helpers that degrade gracefully in non-TTY environments. */
+const c = {
+	bold: wrap("1"),
+	dim: wrap("2"),
+	red: wrap("31"),
+	green: wrap("32"),
+	yellow: wrap("33"),
+	cyan: wrap("36")
+};
+/** Prefixed console helpers used throughout the CLI commands. */
+const log = {
+	info: (msg) => console.log(msg),
+	success: (msg) => console.log(`${c.green("✓")} ${msg}`),
+	warn: (msg) => console.log(`${c.yellow("!")} ${msg}`),
+	error: (msg) => console.error(`${c.red("✗")} ${msg}`)
+};
+/**
+* Returns `true` if the path exists and is accessible, `false` otherwise.
+*/
+async function exists(path) {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Reads a scaffold template file by name from the bundled `templates/` directory.
+*
+* @param name - Template filename, e.g. `"shared/data.ts.tpl"`.
+*/
+async function readTemplate(name) {
+	return readFile(join(TEMPLATES_DIR, name), "utf8");
+}
+/**
+* Replaces `{{KEY}}` placeholders in a template string.
+*
+* @param tpl - Template string containing `{{VARIABLE}}` tokens.
+* @param vars - Map of token names to replacement values.
+*/
+function render(tpl, vars = {}) {
+	return tpl.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? "");
+}
+/**
+* Writes `content` to `path`, creating parent directories as needed.
+* Skips the write if the file already exists and `force` is `false`.
+*
+* @param path - Destination file path.
+* @param content - File content to write.
+* @param force - Overwrite existing files when `true`. Defaults to `false`.
+* @returns `"written"` if the file was created/replaced, `"skipped"` if it already existed.
+*/
+async function writeFileSafe(path, content, force = false) {
+	await mkdir(dirname(path), { recursive: true });
+	if (!force && await exists(path)) return "skipped";
+	await writeFile(path, content);
+	return "written";
+}
+/**
+* Resolves the path to a sub-asset of the installed `@prudentbird/voxx-core` package.
+*
+* @param subpath - Package-relative path, e.g. `"theme/voxx.css"`.
+*/
+function resolveCoreAsset(subpath) {
+	return require.resolve(`@prudentbird/voxx-core/${subpath}`);
+}
+/**
+* Converts a package name or slug to Title Case.
+*
+* Strips any npm scope prefix (`@scope/`) before converting.
+*/
+function titleCase(name) {
+	return name.replace(/^@[^/]+\//, "").replace(/[-_]+/g, " ").replace(/\b\w/g, (m) => m.toUpperCase()).trim();
+}
+/**
+* Returns `true` if the path is a safe relative path that stays within the
+* project root (no absolute paths, no `..` traversal, no null bytes).
+*/
+function isSafeRelPath(p) {
+	if (p === "") return true;
+	if (p.includes("\0")) return false;
+	if (p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p)) return false;
+	return p.split(/[\\/]/).every((seg) => seg !== "..");
+}
+/**
+* Normalizes a URL base path to always have a leading slash and no trailing slash.
+*
+* @param base - Raw base path, e.g. `"blog/"` or `"/blog"`.
+* @returns Normalized path, e.g. `"/blog"`.
+*/
+function normalizeBase(base) {
+	const withLead = base.startsWith("/") ? base : `/${base}`;
+	return withLead.length > 1 ? withLead.replace(/\/+$/, "") : withLead;
+}
+const YAML_PLAIN_RE = /^[A-Za-z0-9](?:[A-Za-z0-9 ._/()-]*[A-Za-z0-9._/()-])?$/;
+/**
+* Returns a YAML-safe representation of `value`.
+*
+* Plain strings that match the safe character set are returned as-is;
+* everything else is JSON-quoted.
+*/
+function yamlValue(value) {
+	return YAML_PLAIN_RE.test(value) ? value : JSON.stringify(value);
+}
+//#endregion
+//#region src/commands/init.ts
+const APP_DIR_CANDIDATES = ["app", "src/app"];
+const GLOBALS_CANDIDATES = [
+	"app/globals.css",
+	"src/app/globals.css",
+	"styles/globals.css",
+	"src/styles/globals.css",
+	"app/global.css"
+];
+const PRESETS = [
+	"blog",
+	"docs",
+	"changelog"
+];
+const PRESET_DEFAULTS = {
+	blog: {
+		title: "My Blog",
+		description: "A blog built with Voxx."
+	},
+	docs: {
+		title: "My Docs",
+		description: "Documentation built with Voxx."
+	},
+	changelog: {
+		title: "Changelog",
+		description: "Release notes built with Voxx."
+	}
+};
+async function readPkg(cwd) {
+	if (await exists(join(cwd, "package.json"))) return JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+	return {};
+}
+function pkgHasNext(pkg) {
+	return Boolean(pkg.dependencies?.["next"] ?? pkg.devDependencies?.["next"]);
+}
+async function detectAppDir(cwd) {
+	for (const dir of APP_DIR_CANDIDATES) if (await exists(join(cwd, dir))) return dir;
+	return null;
+}
+async function detectTokens(cwd) {
+	for (const rel of GLOBALS_CANDIDATES) {
+		const path = join(cwd, rel);
+		if (await exists(path)) {
+			const css = await readFile(path, "utf8");
+			if (css.includes("--background") || css.includes("--foreground")) return true;
+		}
+	}
+	return false;
+}
+async function copyAsset(subpath, target, force) {
+	if (!force && await exists(target)) return "skipped";
+	await mkdir(dirname(target), { recursive: true });
+	await copyFile(resolveCoreAsset(subpath), target);
+	return "written";
+}
+function run(cmd, args, cwd) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(cmd, args, {
+			cwd,
+			stdio: "inherit"
+		});
+		child.on("error", reject);
+		child.on("close", (code) => resolve(code ?? 1));
+	});
+}
+async function chooseSetup() {
+	if (!process.stdin.isTTY) return "static";
+	log.warn("No Next.js app detected here.");
+	log.info(`  ${c.cyan("1.")} Static site — markdown in, HTML/CSS out via ${c.cyan("voxx build")}`);
+	log.info(`  ${c.cyan("2.")} New Next.js app — runs ${c.cyan("create-next-app")}, then scaffolds`);
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		for (;;) {
+			const answer = (await rl.question(`Choose [1/2] (default 1): `)).trim();
+			if (answer === "" || answer === "1") return "static";
+			if (answer === "2") return "next";
+			log.warn("Please answer 1 or 2.");
+		}
+	} finally {
+		rl.close();
+	}
+}
+async function createNextApp(cwd) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	let dir;
+	try {
+		dir = (await rl.question(`Directory for the new app (default ${c.cyan("my-app")}): `)).trim() || "my-app";
+	} finally {
+		rl.close();
+	}
+	log.info("");
+	if (await run("npx", ["create-next-app@latest", dir], cwd) !== 0) {
+		log.error("create-next-app failed — nothing scaffolded.");
+		return null;
+	}
+	return join(cwd, dir);
+}
+async function isolateCreatedApp(cwd, appDir) {
+	const siteDir = join(cwd, appDir, "(site)");
+	const moved = [];
+	for (const file of [
+		"layout.tsx",
+		"layout.js",
+		"page.tsx",
+		"page.js",
+		"page.module.css"
+	]) {
+		const from = join(cwd, appDir, file);
+		if (!await exists(from)) continue;
+		await mkdir(siteDir, { recursive: true });
+		await rename(from, join(siteDir, file));
+		moved.push(file);
+	}
+	if (!moved.some((f) => f.startsWith("layout."))) return false;
+	for (const file of ["layout.tsx", "layout.js"]) {
+		const path = join(siteDir, file);
+		if (!await exists(path)) continue;
+		await writeFile(path, (await readFile(path, "utf8")).replace("\"./globals.css\"", "\"../globals.css\""));
+	}
+	return true;
+}
+const NEXT_CONFIG_FILES = [
+	"next.config.ts",
+	"next.config.mjs",
+	"next.config.js",
+	"next.config.cjs"
+];
+function nextMajor(pkg) {
+	const range = pkg.dependencies?.["next"] ?? pkg.devDependencies?.["next"] ?? "";
+	const m = /(\d+)/.exec(range);
+	return m ? Number(m[1]) : null;
+}
+const MINIMAL_NEXT_CONFIG = `import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,
+};
+
+export default nextConfig;
+`;
+async function enableCacheComponents(cwd, pkg) {
+	const major = nextMajor(pkg);
+	if (major !== null && major < 16) return { kind: "unsupported" };
+	let file = null;
+	for (const name of NEXT_CONFIG_FILES) if (await exists(join(cwd, name))) {
+		file = name;
+		break;
+	}
+	if (!file) {
+		if (major === null) return { kind: "manual" };
+		await writeFile(join(cwd, "next.config.ts"), MINIMAL_NEXT_CONFIG);
+		return {
+			kind: "created",
+			file: "next.config.ts"
+		};
+	}
+	const source = await readFile(join(cwd, file), "utf8");
+	if (/\bcacheComponents\b/.test(source)) return {
+		kind: "already",
+		file
+	};
+	const m = /(const\s+nextConfig\s*(?::\s*[\w.]+)?\s*=\s*|export\s+default\s+|module\.exports\s*=\s*)\{/.exec(source);
+	if (!m) return { kind: "manual" };
+	const at = m.index + m[0].length;
+	const rest = source.slice(at);
+	const insert = rest.trimStart().startsWith("}") ? "\n  cacheComponents: true,\n" : "\n  cacheComponents: true,";
+	await writeFile(join(cwd, file), source.slice(0, at) + insert + rest);
+	return {
+		kind: "enabled",
+		file
+	};
+}
+function planAdd(raw, preset, values) {
+	const rawCollections = Array.isArray(raw["collections"]) ? raw["collections"] : [];
+	const rawContent = raw["content"] ?? void 0;
+	const existing = rawCollections.length > 0 ? rawCollections.map(resolveCollectionDefaults) : [{
+		name: rawContent?.type ?? DEFAULT_CONFIG.content.type,
+		type: rawContent?.type ?? DEFAULT_CONFIG.content.type,
+		dir: rawContent?.dir ?? DEFAULT_CONFIG.content.dir,
+		basePath: rawContent?.basePath ?? DEFAULT_CONFIG.content.basePath,
+		drafts: rawContent?.drafts ?? false
+	}];
+	const first = existing[0];
+	const name = values.name ?? preset;
+	const dir = values.dir ?? `content/${name}`;
+	const basePath = normalizeBase(values.base ?? `/${name}`);
+	if (existing.some((c) => c.name === name)) return {
+		ok: false,
+		message: `Collection "${name}" already exists — defined: ${existing.map((c) => c.name).join(", ")}. Pass --name <other>.`
+	};
+	const dupBase = existing.find((c) => c.basePath === basePath);
+	if (dupBase) return {
+		ok: false,
+		message: `Base path "${basePath}" is already used by collection "${dupBase.name}" — pass --base <path>.`
+	};
+	const dupDir = existing.find((c) => c.dir === dir);
+	if (dupDir) return {
+		ok: false,
+		message: `Content dir "${dir}" is already used by collection "${dupDir.name}" — pass --dir <dir>.`
+	};
+	const next = {
+		name,
+		type: preset,
+		dir,
+		basePath,
+		drafts: false
+	};
+	if (rawCollections.length > 0) return {
+		ok: true,
+		out: {
+			...raw,
+			collections: [...rawCollections, next]
+		},
+		name,
+		dir,
+		basePath
+	};
+	const migrated = {
+		name: first.name,
+		...rawContent ?? {}
+	};
+	const reResolved = resolveCollectionDefaults(migrated);
+	if (reResolved.dir !== first.dir) migrated["dir"] = first.dir;
+	if (reResolved.basePath !== first.basePath) migrated["basePath"] = first.basePath;
+	const collections = [migrated, next];
+	const out = {};
+	let inserted = false;
+	for (const [key, value] of Object.entries(raw)) {
+		if (key === "content" || key === "collections") {
+			if (!inserted) {
+				out["collections"] = collections;
+				inserted = true;
+			}
+			continue;
+		}
+		out[key] = value;
+	}
+	if (!inserted) out["collections"] = collections;
+	return {
+		ok: true,
+		out,
+		name,
+		dir,
+		basePath
+	};
+}
+async function init(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		options: {
+			dir: { type: "string" },
+			base: { type: "string" },
+			app: { type: "string" },
+			name: { type: "string" },
+			add: { type: "boolean" },
+			force: { type: "boolean" }
+		},
+		allowPositionals: true
+	});
+	const presetArg = positionals[0] ?? "blog";
+	if (!PRESETS.includes(presetArg)) {
+		log.error(`Unknown preset "${presetArg}" — expected one of: ${PRESETS.join(", ")}.`);
+		process.exitCode = 1;
+		return;
+	}
+	const preset = presetArg;
+	const add = Boolean(values.add);
+	const force = Boolean(values.force);
+	if (add && force) {
+		log.error("--add and --force cannot be combined — --add never overwrites. Delete the collection's files and re-run if you need a clean re-scaffold.");
+		process.exitCode = 1;
+		return;
+	}
+	if (!add && values.name !== void 0) {
+		log.error("--name only applies with --add.");
+		process.exitCode = 1;
+		return;
+	}
+	if (values.dir !== void 0 && !isSafeRelPath(values.dir)) {
+		log.error(`Invalid --dir "${values.dir}" — must stay within the project (no "..").`);
+		process.exitCode = 1;
+		return;
+	}
+	if (values.app !== void 0 && !isSafeRelPath(values.app)) {
+		log.error(`Invalid --app "${values.app}" — must stay within the project (no "..").`);
+		process.exitCode = 1;
+		return;
+	}
+	if (values.base !== void 0 && values.base.split(/[\\/]/).includes("..")) {
+		log.error(`Invalid --base "${values.base}" — must not contain "..".`);
+		process.exitCode = 1;
+		return;
+	}
+	let cwd = process.cwd();
+	let contentDir = values.dir ?? "content";
+	let basePath = normalizeBase(values.base ?? `/${preset}`);
+	let collectionName = preset;
+	let pkg = await readPkg(cwd);
+	let hasNext = pkgHasNext(pkg);
+	let createdAppDir = null;
+	let staticChoice = false;
+	const results = [];
+	if (add) {
+		const cfgPath = join(cwd, "voxx.json");
+		if (!await exists(cfgPath)) {
+			log.error(`--add requires an existing voxx.json — run ${c.cyan(`voxx init ${preset}`)} first.`);
+			process.exitCode = 1;
+			return;
+		}
+		let raw;
+		try {
+			raw = JSON.parse(await readFile(cfgPath, "utf8"));
+		} catch {
+			log.error("voxx.json is not valid JSON — fix it before running --add.");
+			process.exitCode = 1;
+			return;
+		}
+		const plan = planAdd(raw, preset, values);
+		if (!plan.ok) {
+			log.error(plan.message);
+			process.exitCode = 1;
+			return;
+		}
+		collectionName = plan.name;
+		contentDir = plan.dir;
+		basePath = plan.basePath;
+		await writeFile(cfgPath, `${JSON.stringify(plan.out, null, 2)}\n`);
+		results.push([`voxx.json (added collection "${collectionName}")`, "written"]);
+	} else if (!hasNext) if (await chooseSetup() === "next") {
+		createdAppDir = await createNextApp(cwd);
+		if (!createdAppDir) {
+			process.exitCode = 1;
+			return;
+		}
+		cwd = createdAppDir;
+		pkg = await readPkg(cwd);
+		hasNext = pkgHasNext(pkg);
+	} else staticChoice = true;
+	const baseSegment = basePath.slice(1);
+	const appDir = values.app ?? await detectAppDir(cwd);
+	const siteTitle = pkg.name ? titleCase(pkg.name) : PRESET_DEFAULTS[preset].title;
+	if (!add) results.push(["voxx.json", await writeFileSafe(join(cwd, "voxx.json"), render(await readTemplate("shared/voxx.json.tpl"), {
+		SITE_TITLE: siteTitle,
+		SITE_DESCRIPTION: PRESET_DEFAULTS[preset].description,
+		SITE_URL: "https://example.com",
+		TYPE: preset,
+		CONTENT_DIR: contentDir,
+		BASE_PATH: basePath
+	}), force)]);
+	const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+	const samples = preset === "docs" ? [
+		["docs/index.md.tpl", "index.md"],
+		["docs/getting-started-index.md.tpl", join("01-getting-started", "index.md")],
+		["docs/installation.md.tpl", join("01-getting-started", "01-installation.md")]
+	] : preset === "changelog" ? [[
+		"changelog/release.md.tpl",
+		"0.1.0.md",
+		{ DATE: today }
+	]] : [[
+		"blog/hello-world.md.tpl",
+		"hello-world.md",
+		{ DATE: today }
+	]];
+	for (const [tpl, rel, vars] of samples) results.push([join(contentDir, rel), await writeFileSafe(join(cwd, contentDir, rel), render(await readTemplate(tpl), vars ?? {}), force)]);
+	let wroteGlobals = false;
+	let cache = null;
+	if (hasNext && appDir) {
+		const blogDir = join(cwd, appDir, baseSegment);
+		const voxxDir = join(blogDir, "_voxx");
+		const hasTokens = await detectTokens(cwd);
+		wroteGlobals = !hasTokens;
+		const globalsImport = hasTokens ? "" : "import \"./_voxx/voxx-globals.css\";";
+		const isolated = preset === "docs" && !add && createdAppDir !== null && baseSegment !== "" && await isolateCreatedApp(cwd, appDir);
+		if (isolated) results.push([`${join(appDir, "(site)")}/ (app layout moved — docs has its own root layout)`, "written"]);
+		const dataFromAppRoot = baseSegment ? `./${baseSegment}/_voxx/data` : "./_voxx/data";
+		const dataFromRouteDir = baseSegment ? `../${baseSegment}/_voxx/data` : "../_voxx/data";
+		results.push([relative(cwd, join(voxxDir, "voxx.css")), await copyAsset("theme/voxx.css", join(voxxDir, "voxx.css"), force)]);
+		if (wroteGlobals) results.push([relative(cwd, join(voxxDir, "voxx-globals.css")), await copyAsset("theme/demo-globals.css", join(voxxDir, "voxx-globals.css"), force)]);
+		const templated = [
+			[
+				preset === "docs" ? isolated ? "docs/layout-root.tsx.tpl" : "docs/layout.tsx.tpl" : `${preset}/layout.tsx.tpl`,
+				join(blogDir, "layout.tsx"),
+				{
+					GLOBALS_IMPORT: isolated && hasTokens ? "import \"../globals.css\";" : globalsImport,
+					BASE_PATH: basePath,
+					RSS_PATH: basePath === "/" ? "/rss.xml" : `${basePath}/rss.xml`
+				}
+			],
+			[
+				"shared/data.ts.tpl",
+				join(voxxDir, "data.ts"),
+				{ COLLECTION_ARG: `{ collection: ${JSON.stringify(collectionName)} }` }
+			],
+			["shared/content-version.ts.tpl", join(voxxDir, "content-version.ts")],
+			[
+				"shared/instrumentation.ts.tpl",
+				join(dirname(join(cwd, appDir)), "instrumentation.ts"),
+				void 0,
+				true
+			]
+		];
+		if (preset !== "changelog") templated.push(["shared/on-this-page.tsx.tpl", join(voxxDir, "on-this-page.tsx")], ["shared/metadata.ts.tpl", join(voxxDir, "metadata.ts")], [
+			"shared/sitemap.ts.tpl",
+			join(cwd, appDir, "sitemap.ts"),
+			{ DATA_IMPORT: dataFromAppRoot },
+			true
+		], [
+			"shared/robots.ts.tpl",
+			join(cwd, appDir, "robots.ts"),
+			{ DATA_IMPORT: dataFromAppRoot },
+			true
+		]);
+		templated.push([
+			"shared/llms-route.ts.tpl",
+			join(cwd, appDir, "llms.txt", "route.ts"),
+			{ DATA_IMPORT: dataFromRouteDir },
+			true
+		], [
+			"shared/llms-full-route.ts.tpl",
+			join(cwd, appDir, "llms-full.txt", "route.ts"),
+			{ DATA_IMPORT: dataFromRouteDir },
+			true
+		]);
+		if (preset !== "docs") templated.push([
+			"shared/rss-route.ts.tpl",
+			join(blogDir, "rss.xml", "route.ts"),
+			{ DATA_IMPORT: "../_voxx/data" }
+		]);
+		if (preset === "docs") templated.push(["docs/page.tsx.tpl", join(blogDir, "[[...slug]]", "page.tsx")], ["docs/doc-page.tsx.tpl", join(voxxDir, "doc-page.tsx")], ["docs/sidebar-nav.tsx.tpl", join(voxxDir, "sidebar-nav.tsx")], ["docs/mobile-nav.tsx.tpl", join(voxxDir, "mobile-nav.tsx")], ["shared/theme-toggle.tsx.tpl", join(voxxDir, "theme-toggle.tsx")]);
+		else if (preset === "changelog") templated.push(["changelog/page.tsx.tpl", join(blogDir, "page.tsx")], ["changelog/release-list.tsx.tpl", join(voxxDir, "release-list.tsx")], ["shared/theme-toggle.tsx.tpl", join(voxxDir, "theme-toggle.tsx")]);
+		else templated.push(["blog/page.tsx.tpl", join(blogDir, "page.tsx")], ["blog/slug-page.tsx.tpl", join(blogDir, "[slug]", "page.tsx")], ["blog/post-page.tsx.tpl", join(voxxDir, "post-page.tsx")], ["blog/post-list.tsx.tpl", join(voxxDir, "post-list.tsx")], ["shared/theme-toggle.tsx.tpl", join(voxxDir, "theme-toggle.tsx")]);
+		for (const [tpl, target, vars, siteWide] of templated) {
+			const content = render(await readTemplate(tpl), vars ?? {});
+			results.push([
+				relative(cwd, target),
+				await writeFileSafe(target, content, force),
+				siteWide
+			]);
+		}
+		cache = await enableCacheComponents(cwd, pkg);
+		if (cache.kind === "enabled" || cache.kind === "created") results.push([`${cache.file} (cacheComponents: true)`, "written"]);
+	}
+	log.info("");
+	log.info(c.bold(add ? "voxx init --add" : "voxx init"));
+	for (const [label, status, siteWide] of results) {
+		const mark = status === "written" ? c.green("+") : c.dim("•");
+		const note = status === "skipped" ? add && siteWide ? c.dim(" (site-wide, already present)") : c.dim(" (exists, skipped)") : "";
+		const prefix = createdAppDir ? `${relative(process.cwd(), cwd)}/` : "";
+		log.info(`  ${mark} ${prefix}${label}${note}`);
+	}
+	log.info("");
+	log.info(c.bold("Next steps:"));
+	if (add) {
+		log.info(`  1. Write content in ${c.cyan(`${contentDir}/`)} (try ${c.cyan(`voxx new "Title" --collection ${collectionName}`)}).`);
+		if (hasNext && appDir) log.info(`  2. Run your dev server and open ${c.cyan(basePath)}.`);
+		else if (hasNext) log.warn("Next.js found but no app/ directory — pass --app <dir> to scaffold routes.");
+		else log.info(`  2. Run ${c.cyan("voxx build")} to render static HTML to ${c.cyan("./dist")}.`);
+		log.info(`  ${c.dim("(Feature defaults like rss/toc follow the first collection's type — review \"features\" in voxx.json.)")}`);
+		log.info("");
+		return;
+	}
+	if (staticChoice) {
+		const writeHint = preset === "docs" ? `Write pages in ${c.cyan(`${contentDir}/`)} — folders become sections.` : preset === "changelog" ? `Add releases in ${c.cyan(`${contentDir}/`)} (try ${c.cyan("voxx new \"0.2.0\"")}).` : `Write posts in ${c.cyan(`${contentDir}/`)} (try ${c.cyan("voxx new \"My post\"")}).`;
+		log.info(`  1. ${writeHint}`);
+		log.info(`  2. Set ${c.cyan("site.url")} in ${c.cyan("voxx.json")}.`);
+		log.info(`  3. Run ${c.cyan("voxx build")} to render static HTML to ${c.cyan("./dist")}.`);
+	} else if (!hasNext) {
+		log.warn("No Next.js detected — wrote voxx.json + sample content only.");
+		log.info(`  Install the engine:  ${c.cyan("npm i @prudentbird/voxx-core")}`);
+		log.info(`  Or build static HTML: ${c.cyan("npx voxx build")}`);
+	} else if (!appDir) log.warn("Next.js found but no app/ directory — pass --app <dir> to scaffold routes.");
+	else {
+		let step = 1;
+		if (createdAppDir) log.info(`  ${step++}. ${c.cyan(`cd ${relative(process.cwd(), createdAppDir)}`)}`);
+		log.info(`  ${step++}. Install the engine:  ${c.cyan("npm i @prudentbird/voxx-core")}`);
+		if (cache?.kind === "manual") log.info(`  ${step++}. Enable Cache Components — add ${c.cyan("cacheComponents: true")} to next.config.`);
+		else if (cache?.kind === "unsupported") log.info(`  ${step++}. Upgrade to Next 16+ and add ${c.cyan("cacheComponents: true")} to next.config.`);
+		log.info(`  ${step++}. Set ${c.cyan("site.url")} in ${c.cyan("voxx.json")}.`);
+		log.info(`  ${step}. Run your dev server and open ${c.cyan(basePath)}.`);
+		if (cache?.kind === "already") log.info(`  ${c.dim(`(Cache Components already enabled in ${cache.file}.)`)}`);
+		if (wroteGlobals) log.info(`  ${c.dim("(No design tokens found — added voxx-globals.css so it looks good out of the box.)")}`);
+		if (preset === "docs" && !createdAppDir && appDir) log.info(`  ${c.dim(`(Heads up: your root layout wraps ${basePath} — its navbar/footer will show there too. To isolate the docs, see https://voxx.prudentbird.com/docs/reference/layouts.)`)}`);
+	}
+	log.info("");
+}
+//#endregion
+//#region src/commands/build.ts
+function stripLead(path) {
+	return path.replace(/^\/+/, "");
+}
+function headTags(seo, config) {
+	const tags = [`<meta name="description" content="${escapeXml(seo.description)}">`, `<link rel="canonical" href="${escapeXml(seo.canonical)}">`];
+	const og = seo.openGraph;
+	if (og) tags.push(`<meta property="og:type" content="article">`, `<meta property="og:title" content="${escapeXml(og.title)}">`, `<meta property="og:description" content="${escapeXml(og.description)}">`, `<meta property="og:url" content="${escapeXml(og.url)}">`, `<meta property="og:site_name" content="${escapeXml(og.siteName)}">`, ...og.images.map((src) => `<meta property="og:image" content="${escapeXml(src)}">`));
+	if (seo.twitter) tags.push(`<meta name="twitter:card" content="summary_large_image">`, `<meta name="twitter:title" content="${escapeXml(seo.twitter.title)}">`, `<meta name="twitter:description" content="${escapeXml(seo.twitter.description)}">`);
+	if (config.seo.jsonLd && seo.jsonLd) tags.push(`<script type="application/ld+json">${serializeJsonLd(seo.jsonLd)}<\/script>`);
+	return tags.join("\n    ");
+}
+function shell(opts) {
+	return `<!doctype html>
+<html lang="${escapeXml(opts.lang)}">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>${escapeXml(opts.title)}</title>
+    <link rel="stylesheet" href="/_voxx/voxx-globals.css">
+    <link rel="stylesheet" href="/_voxx/voxx.css">
+    ${opts.head}
+  </head>
+  <body>
+${opts.body}
+  </body>
+</html>
+`;
+}
+function siteHeader(config) {
+	const base = config.content.basePath || "/";
+	const rss = config.features.rss ? `<div class="voxx-header__actions"><a class="voxx-icon-button" href="${escapeXml(rssPath(config))}" aria-label="RSS feed"><svg viewBox="0 0 24 24" fill="none" aria-hidden="true"><path d="M4 11a9 9 0 0 1 9 9M4 4a16 16 0 0 1 16 16" stroke="currentColor" stroke-width="2" stroke-linecap="round"/><circle cx="5" cy="19" r="1" fill="currentColor"/></svg></a></div>` : "";
+	return `    <header class="voxx voxx-header">
+      <a class="voxx-header__title" href="${escapeXml(base)}">${escapeXml(config.site.title)}</a>
+      ${rss}
+    </header>`;
+}
+function metaLine(post, config) {
+	const rt = config.features.readingTime ? ` · ${post.readingTimeMinutes} min read` : "";
+	return `<time datetime="${escapeXml(post.date)}">${escapeXml(formatDate(post.date, config.site.locale))}</time>${escapeXml(rt)}`;
+}
+function tocAside(post) {
+	if (post.toc.length === 0) return "";
+	return `      <aside class="voxx-aside"><div class="voxx-aside__inner">
+        <nav class="voxx-toc" aria-label="On this page">
+          <p class="voxx-toc__title"><svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M2.5 4h7M2.5 8h11M2.5 12h7" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>On this page</p>
+          <ul class="voxx-toc__list">
+${post.toc.map((t) => `          <li class="voxx-toc__item" data-depth="${t.depth}"><a href="#${escapeXml(t.id)}">${escapeXml(t.text)}</a></li>`).join("\n")}
+          </ul>
+        </nav>
+      </div></aside>`;
+}
+function indexBody(posts, config) {
+	const cards = posts.length === 0 ? `<p class="voxx-empty">No posts yet.</p>` : `<ul class="voxx-postlist">
+${posts.map((post) => {
+		const tags = config.features.tags && post.tags.length ? `<ul class="voxx-tags">${post.tags.map((t) => `<li class="voxx-tag">${escapeXml(t)}</li>`).join("")}</ul>` : "";
+		const excerpt = post.excerpt ? `<p class="voxx-postcard__excerpt">${escapeXml(post.excerpt)}</p>` : "";
+		return `      <li class="voxx-postcard"><a class="voxx-postcard__link" href="${escapeXml(post.url)}">
+        <h2 class="voxx-postcard__title">${escapeXml(post.title)}</h2>
+        <p class="voxx-postcard__meta">${metaLine(post, config)}</p>
+        ${excerpt}
+        ${tags}
+      </a></li>`;
+	}).join("\n")}
+    </ul>`;
+	return `    <main class="voxx voxx-index">
+      <header class="voxx-index__header">
+        <h1>${escapeXml(config.site.title)}</h1>
+        ${config.site.description ? `<p class="voxx-index__desc">${escapeXml(config.site.description)}</p>` : ""}
+      </header>
+      ${cards}
+    </main>`;
+}
+function postBody(post, config) {
+	const aside = config.features.toc ? tocAside(post) : "";
+	return `    <main class="voxx voxx-layout">
+      <article class="voxx-article">
+        <header class="voxx-article__header">
+          <h1>${escapeXml(post.title)}</h1>
+          <p class="voxx-article__meta">${metaLine(post, config)}</p>
+        </header>
+        <div class="voxx-prose">${post.html}</div>
+      </article>
+${aside}
+    </main>`;
+}
+function navHtml(items, activeUrl) {
+	if (items.length === 0) return "";
+	return `<ul class="voxx-nav__list">\n${items.map((item) => {
+		return `<li>${item.url ? `<a class="voxx-nav__link" href="${escapeXml(item.url)}"${item.url === activeUrl ? " data-active=\"true\"" : ""}>${escapeXml(item.title)}</a>` : `<span class="voxx-nav__section">${escapeXml(item.title)}</span>`}${navHtml(item.children, activeUrl)}</li>`;
+	}).join("\n")}\n</ul>`;
+}
+function pagerHtml(prev, next) {
+	if (!prev && !next) return "";
+	const link = (post, label, cls) => `<a class="voxx-pager__link${cls}" href="${escapeXml(post.url)}"><span class="voxx-pager__label">${label}</span><span class="voxx-pager__title">${escapeXml(post.title)}</span></a>`;
+	return `        <nav class="voxx-pager">
+          ${prev ? link(prev, "Previous", "") : "<span></span>"}
+          ${next ? link(next, "Next", " voxx-pager__link--next") : "<span></span>"}
+        </nav>`;
+}
+function docsSidebar(nav, activeUrl, config) {
+	const base = config.content.basePath || "/";
+	return `<aside class="voxx-docs__nav"><div class="voxx-docs__nav-inner">
+        <div class="voxx-docs__nav-header">
+          <details class="voxx-docs__menu"><summary aria-label="Navigation"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect width="18" height="18" x="3" y="3" rx="2"/><path d="M9 3v18"/></svg></summary>
+            <div class="voxx-docs__menu-panel"><nav class="voxx-nav">${navHtml(nav, activeUrl)}</nav></div>
+          </details>
+          <a class="voxx-docs__title" href="${escapeXml(base)}">${escapeXml(config.site.title)}</a>
+        </div>
+        <nav class="voxx-nav">${navHtml(nav, activeUrl)}</nav>
+      </div></aside>`;
+}
+function docBody(post, posts, index, nav, config) {
+	const prev = index > 0 ? posts[index - 1] : void 0;
+	const next = posts[index + 1];
+	const aside = config.features.toc ? tocAside(post) : "";
+	const desc = post.description ? `<p class="voxx-article__meta">${escapeXml(post.description)}</p>` : "";
+	return `    <div class="voxx voxx-docs">
+      ${docsSidebar(nav, post.url, config)}
+      <main class="voxx-layout">
+        <article class="voxx-article">
+          <header class="voxx-article__header">
+            <h1>${escapeXml(post.title)}</h1>
+            ${desc}
+          </header>
+          <div class="voxx-prose">${post.html}</div>
+${pagerHtml(prev, next)}
+        </article>
+${aside}
+      </main>
+    </div>`;
+}
+function docsIndexBody(nav, config) {
+	return `    <div class="voxx voxx-docs">
+      ${docsSidebar(nav, "", config)}
+      <main class="voxx-layout">
+        <article class="voxx-article">
+          <header class="voxx-article__header">
+            <h1>${escapeXml(config.site.title)}</h1>
+            ${config.site.description ? `<p class="voxx-article__meta">${escapeXml(config.site.description)}</p>` : ""}
+          </header>
+          <div class="voxx-prose">${navHtml(nav, "")}</div>
+        </article>
+      </main>
+    </div>`;
+}
+function changelogBody(posts, config) {
+	const releases = posts.length === 0 ? `<p class="voxx-empty">No releases yet.</p>` : `<div class="voxx-releases">
+${posts.map((post) => `      <section class="voxx-release" id="${escapeXml(post.slug)}">
+        <header class="voxx-release__header">
+          <h2 class="voxx-release__version"><a href="#${escapeXml(post.slug)}">${escapeXml(post.version ? `v${post.version}` : post.title)}</a></h2>
+          <time datetime="${escapeXml(post.date)}">${escapeXml(formatDate(post.date, config.site.locale))}</time>
+        </header>
+        <div class="voxx-prose">${post.html}</div>
+      </section>`).join("\n")}
+    </div>`;
+	return `    <main class="voxx voxx-index">
+      <header class="voxx-index__header">
+        <h1>${escapeXml(config.site.title)}</h1>
+        ${config.site.description ? `<p class="voxx-index__desc">${escapeXml(config.site.description)}</p>` : ""}
+      </header>
+      ${releases}
+    </main>`;
+}
+/**
+* Rewrite root-absolute internal links (`href`/`src` beginning with a single
+* `/`) to paths relative to the page's own location. This keeps navigation and
+* asset links working whether the generated site is served from the domain
+* root, a subpath, or opened directly from the filesystem. Protocol-relative
+* (`//host`) and external URLs are left untouched.
+*/
+function relativizeLinks(html, fromDir, outDir) {
+	const prefix = relative(fromDir, outDir).split(sep).join("/") || ".";
+	return html.replace(/\b(href|src)="\/(?!\/)([^"]*)"/g, `$1="${prefix}/$2"`);
+}
+async function writePage(path, html, outDir) {
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, path.endsWith(".html") ? relativizeLinks(html, dirname(path), outDir) : html);
+}
+const SOURCE_RE = /\.mdx?$/;
+async function copyContentAssets(contentDir, targetDir) {
+	let copied = 0;
+	let entries;
+	try {
+		entries = await readdir(contentDir, {
+			recursive: true,
+			withFileTypes: true
+		});
+	} catch {
+		return 0;
+	}
+	for (const entry of entries) {
+		if (!entry.isFile()) continue;
+		const name = entry.name;
+		if (SOURCE_RE.test(name) || name.startsWith(".")) continue;
+		const rel = relative(contentDir, join(entry.parentPath, name));
+		const source = join(contentDir, rel);
+		const target = join(targetDir, rel);
+		await mkdir(dirname(target), { recursive: true });
+		await copyFile(source, target);
+		copied++;
+	}
+	return copied;
+}
+async function buildCollection(config, posts, outDir) {
+	const type = config.content.type;
+	const indexPath = join(outDir, stripLead(config.content.basePath), "index.html");
+	if (type === "changelog") await writePage(indexPath, shell({
+		title: config.site.title,
+		lang: config.site.locale,
+		head: `<meta name="description" content="${escapeXml(config.site.description)}">`,
+		body: `${siteHeader(config)}\n${changelogBody(posts, config)}`
+	}), outDir);
+	else if (type === "docs") {
+		const nav = buildNavTree(posts);
+		for (let i = 0; i < posts.length; i++) {
+			const post = posts[i];
+			const seo = buildSeo(post, config);
+			await writePage(join(outDir, stripLead(post.url), "index.html"), shell({
+				title: `${post.title} — ${config.site.title}`,
+				lang: config.site.locale,
+				head: headTags(seo, config),
+				body: docBody(post, posts, i, nav, config)
+			}), outDir);
+		}
+		if (!posts.some((p) => p.path.length === 0)) await writePage(indexPath, shell({
+			title: config.site.title,
+			lang: config.site.locale,
+			head: `<meta name="description" content="${escapeXml(config.site.description)}">`,
+			body: docsIndexBody(nav, config)
+		}), outDir);
+	} else {
+		await writePage(indexPath, shell({
+			title: config.site.title,
+			lang: config.site.locale,
+			head: `<meta name="description" content="${escapeXml(config.site.description)}">`,
+			body: `${siteHeader(config)}\n${indexBody(posts, config)}`
+		}), outDir);
+		for (const post of posts) {
+			const seo = buildSeo(post, config);
+			await writePage(join(outDir, stripLead(post.url), "index.html"), shell({
+				title: `${post.title} — ${config.site.title}`,
+				lang: config.site.locale,
+				head: headTags(seo, config),
+				body: `${siteHeader(config)}\n${postBody(post, config)}`
+			}), outDir);
+		}
+	}
+}
+async function buildSite(opts) {
+	const { cwd, outDir } = opts;
+	const config = await loadConfig({ cwd });
+	const collections = config.collections;
+	const multi = collections.length > 1;
+	await mkdir(join(outDir, "_voxx"), { recursive: true });
+	await copyFile(resolveCoreAsset("theme/voxx.css"), join(outDir, "_voxx", "voxx.css"));
+	await copyFile(resolveCoreAsset("theme/demo-globals.css"), join(outDir, "_voxx", "voxx-globals.css"));
+	const allPosts = [];
+	const sections = [];
+	let pageCount = 0;
+	for (const collection of collections) {
+		const view = {
+			...config,
+			content: { ...collection }
+		};
+		const posts = await getPosts({
+			config: view,
+			includeDrafts: opts.includeDrafts
+		});
+		await buildCollection(view, posts, outDir);
+		const assetTarget = join(outDir, stripLead(collection.basePath));
+		await copyContentAssets(collection.dir, assetTarget);
+		if (config.features.rss && isFeedType(collection)) await writePage(join(outDir, stripLead(rssPath(view))), renderRss(posts, view), outDir);
+		sections.push({
+			heading: multi ? humanize(collection.name) : sectionHeading(collection.type),
+			posts
+		});
+		allPosts.push(...posts);
+		pageCount += posts.length;
+	}
+	if (config.features.sitemap) {
+		await writeFile(join(outDir, "sitemap.xml"), renderSitemap(allPosts, config, { indexPaths: collections.map((col) => col.basePath) }));
+		await writeFile(join(outDir, "robots.txt"), renderRobotsTxt(config));
+	}
+	if (config.features.llmsTxt) {
+		await writeFile(join(outDir, "llms.txt"), renderLlmsTxtSections(sections, config));
+		await writeFile(join(outDir, "llms-full.txt"), renderLlmsFull(allPosts, config));
+	}
+	return {
+		config,
+		pageCount,
+		collectionCount: collections.length,
+		indexRel: join(relative(cwd, outDir), stripLead(collections[0].basePath), "index.html")
+	};
+}
+function isFeedType(collection) {
+	return collection.type === "blog" || collection.type === "changelog";
+}
+async function build(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			out: { type: "string" },
+			drafts: { type: "boolean" }
+		},
+		allowPositionals: true
+	});
+	const cwd = process.cwd();
+	if (!await exists(join(cwd, "voxx.json"))) {
+		log.error("No voxx.json found. Run `voxx init` first.");
+		process.exitCode = 1;
+		return;
+	}
+	const outDir = join(cwd, values.out ?? "dist");
+	const result = await buildSite({
+		cwd,
+		outDir,
+		includeDrafts: values.drafts ? true : void 0
+	});
+	const { config } = result;
+	if (!config.site.url || /example\.com/.test(config.site.url)) log.warn(`site.url is ${config.site.url ? `"${config.site.url}"` : "empty"} — feeds, sitemap, and SEO tags need the real production URL in voxx.json.`);
+	const type = config.content.type;
+	const noun = type === "changelog" ? "release" : type === "docs" ? "page" : "post";
+	const what = result.collectionCount > 1 ? `${result.pageCount} pages across ${result.collectionCount} collections` : `${result.pageCount} ${noun}${result.pageCount === 1 ? "" : "s"}`;
+	log.success(`Built ${what} → ${relative(cwd, outDir)}/`);
+	log.info(`  Open ${c.cyan(result.indexRel)} in a browser, or run ${c.cyan("voxx dev")} to preview with a local server.`);
+}
+//#endregion
+//#region src/commands/dev.ts
+const MIME = {
+	".html": "text/html; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".xml": "application/xml; charset=utf-8",
+	".txt": "text/plain; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".avif": "image/avif",
+	".ico": "image/x-icon",
+	".woff": "font/woff",
+	".woff2": "font/woff2",
+	".mp4": "video/mp4",
+	".webm": "video/webm",
+	".pdf": "application/pdf"
+};
+async function serveFile(outDir, urlPath) {
+	const safe = normalize(decodeURIComponent(urlPath.split("?")[0] ?? "/")).replace(/^(\.\.[\\/])+/, "");
+	const candidates = safe.endsWith("/") ? [join(safe, "index.html")] : [safe, join(safe, "index.html")];
+	for (const rel of candidates) {
+		const path = join(outDir, rel);
+		if (!path.startsWith(outDir)) continue;
+		try {
+			const body = await readFile(path);
+			return {
+				status: 200,
+				type: MIME[extname(path).toLowerCase()] ?? "application/octet-stream",
+				body
+			};
+		} catch {}
+	}
+	return {
+		status: 404,
+		type: "text/html; charset=utf-8",
+		body: Buffer.from("<h1>404</h1><p>Not found.</p>")
+	};
+}
+async function dev(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			port: { type: "string" },
+			drafts: { type: "boolean" }
+		},
+		allowPositionals: true
+	});
+	const cwd = process.cwd();
+	if (!await exists(join(cwd, "voxx.json"))) {
+		log.error("No voxx.json found. Run `voxx init` first.");
+		process.exitCode = 1;
+		return;
+	}
+	const port = Number(values.port ?? 4321);
+	if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+		log.error(`Invalid port "${values.port}".`);
+		process.exitCode = 1;
+		return;
+	}
+	const includeDrafts = values.drafts ?? true;
+	const outDir = await mkdtemp(join(tmpdir(), "voxx-dev-"));
+	let building = Promise.resolve();
+	let dirty = false;
+	const rebuild = (label) => {
+		building = building.then(async () => {
+			try {
+				const started = Date.now();
+				const result = await buildSite({
+					cwd,
+					outDir,
+					includeDrafts
+				});
+				log.success(`${label} — ${result.pageCount} pages in ${Date.now() - started}ms`);
+			} catch (err) {
+				log.error(err instanceof Error ? err.message : String(err));
+			}
+		});
+		return building;
+	};
+	await rebuild("Built");
+	const watchers = [];
+	const watchPath = (path, recursive) => {
+		try {
+			const watcher = watch(path, { recursive }, () => {
+				if (dirty) return;
+				dirty = true;
+				setTimeout(() => {
+					dirty = false;
+					rebuild("Rebuilt");
+				}, 150);
+			});
+			watchers.push(watcher);
+		} catch {
+			log.warn(`Could not watch ${path}.`);
+		}
+	};
+	const config = await loadConfig({ cwd });
+	watchPath(join(cwd, "voxx.json"), false);
+	for (const collection of config.collections) if (await exists(collection.dir)) watchPath(collection.dir, true);
+	const server = createServer((req, res) => {
+		building.then(() => serveFile(outDir, req.url ?? "/")).then(({ status, type, body }) => {
+			res.writeHead(status, {
+				"Content-Type": type,
+				"Cache-Control": "no-store"
+			});
+			res.end(body);
+		}).catch((err) => {
+			log.error(err instanceof Error ? err.message : String(err));
+			if (!res.headersSent) res.writeHead(500, { "Content-Type": "text/plain" });
+			res.end("Internal error");
+		});
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(port, resolve);
+	}).catch((err) => {
+		log.error(err.code === "EADDRINUSE" ? `Port ${port} is in use — pass --port <n>.` : err.message);
+		process.exitCode = 1;
+	});
+	if (process.exitCode === 1) return;
+	const base = config.collections[0].basePath;
+	log.info("");
+	log.success(`voxx dev serving ${c.cyan(`http://localhost:${port}${base}`)}`);
+	log.info(`  Watching content for changes${includeDrafts ? " (drafts included)" : ""}. Press Ctrl+C to stop.`);
+	const close = () => new Promise((resolve) => {
+		for (const watcher of watchers) watcher.close();
+		server.close(() => {
+			rm(outDir, {
+				recursive: true,
+				force: true
+			}).finally(resolve);
+		});
+	});
+	const shutdown = () => {
+		close().then(() => process.exit(0));
+	};
+	process.on("SIGINT", shutdown);
+	process.on("SIGTERM", shutdown);
+	return {
+		port,
+		close
+	};
+}
+//#endregion
+//#region src/commands/new.ts
+const MD_RE = /\.md$/;
+async function readContentConfig(cwd, collectionName) {
+	const cfgPath = join(cwd, "voxx.json");
+	if (!await exists(cfgPath)) return {
+		type: "blog",
+		dir: "content"
+	};
+	const cfg = JSON.parse(await readFile(cfgPath, "utf8"));
+	const collections = (cfg.collections ?? []).map(resolveCollectionDefaults);
+	if (collectionName) {
+		const found = collections.find((c) => c.name === collectionName);
+		if (!found) {
+			log.error(`Unknown collection "${collectionName}" — defined: ${collections.map((c) => c.name).join(", ")}`);
+			return;
+		}
+		return found;
+	}
+	const first = collections[0] ?? {
+		type: cfg.content?.type ?? "blog",
+		dir: cfg.content?.dir ?? "content"
+	};
+	return {
+		type: first.type,
+		dir: first.dir
+	};
+}
+async function existingSlugs(dir) {
+	const slugs = /* @__PURE__ */ new Set();
+	try {
+		for (const entry of await readdir(dir)) {
+			if (!MD_RE.test(entry)) continue;
+			const { rest } = splitDatePrefix(entry.replace(MD_RE, ""));
+			slugs.add(slugify(splitOrderPrefix(rest).rest));
+		}
+	} catch {}
+	return slugs;
+}
+function suggestSlug(base, taken) {
+	let slug = base;
+	for (let n = 2; taken.has(slug); n++) slug = `${base}-${n}`;
+	return slug;
+}
+async function resolveSlug(base, taken) {
+	if (!taken.has(base)) return base;
+	let suggestion = suggestSlug(base, taken);
+	if (!process.stdin.isTTY) {
+		log.warn(`Slug "${base}" is taken — using "${suggestion}".`);
+		return suggestion;
+	}
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		let takenName = base;
+		for (;;) {
+			const answer = (await rl.question(`Slug "${takenName}" is taken. Enter a new slug, or press Enter for "${suggestion}": `)).trim();
+			if (!answer) return suggestion;
+			const candidate = slugify(answer);
+			if (!candidate) {
+				log.warn("Please enter a valid slug.");
+				continue;
+			}
+			if (!taken.has(candidate)) return candidate;
+			log.warn(`"${candidate}" is also taken.`);
+			takenName = candidate;
+			suggestion = suggestSlug(candidate, taken);
+		}
+	} finally {
+		rl.close();
+	}
+}
+async function newPost(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		options: {
+			dir: { type: "string" },
+			date: { type: "string" },
+			slug: { type: "string" },
+			flat: { type: "boolean" },
+			section: { type: "string" },
+			order: { type: "string" },
+			collection: { type: "string" },
+			index: { type: "boolean" }
+		},
+		allowPositionals: true
+	});
+	const title = positionals.join(" ").trim();
+	if (!title) {
+		log.error("Usage: voxx new \"My Post Title\"");
+		process.exitCode = 1;
+		return;
+	}
+	const cwd = process.cwd();
+	const detected = await readContentConfig(cwd, values.collection);
+	if (!detected) {
+		process.exitCode = 1;
+		return;
+	}
+	const contentDir = values.dir ?? detected.dir;
+	if (!isSafeRelPath(contentDir)) {
+		log.error(`Invalid --dir "${contentDir}" — must stay within the project (no "..").`);
+		process.exitCode = 1;
+		return;
+	}
+	if (values.index && detected.type !== "docs") {
+		log.error("--index only applies to docs content.");
+		process.exitCode = 1;
+		return;
+	}
+	const date = values.date ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+		log.error(`Invalid --date "${values.date}" — expected YYYY-MM-DD.`);
+		process.exitCode = 1;
+		return;
+	}
+	if (detected.type === "changelog") {
+		const version = parseVersion(title) ?? title;
+		if (!isSafeRelPath(`${version}.md`) || version.includes("/") || version.includes("\\")) {
+			log.error(`Invalid changelog name "${title}" — use a version like "1.2.0".`);
+			process.exitCode = 1;
+			return;
+		}
+		const target = join(cwd, contentDir, `${version}.md`);
+		if (await writeFileSafe(target, [
+			"---",
+			`title: ${yamlValue(`v${version}`)}`,
+			`version: ${yamlValue(version)}`,
+			`date: ${date}`,
+			"---",
+			"",
+			"### Added",
+			"",
+			"- ",
+			""
+		].join("\n"), false) === "skipped") log.warn(`${relative(cwd, target)} already exists — left untouched.`);
+		else log.success(`Created ${relative(cwd, target)}`);
+		return;
+	}
+	const baseSlug = slugify(values.slug ?? title);
+	if (!baseSlug) {
+		log.error("Could not derive a slug — pass --slug.");
+		process.exitCode = 1;
+		return;
+	}
+	if (detected.type === "docs") {
+		if (values.section && !isSafeRelPath(values.section)) {
+			log.error(`Invalid --section "${values.section}" — must stay within the content directory (no "..").`);
+			process.exitCode = 1;
+			return;
+		}
+		const section = (values.section ?? "").split("/").filter(Boolean).join("/");
+		const targetDir = section ? join(cwd, contentDir, section) : join(cwd, contentDir);
+		if (values.index) {
+			const target = join(targetDir, "index.md");
+			if (await writeFileSafe(target, [
+				"---",
+				`title: ${yamlValue(title)}`,
+				"description: ",
+				"---",
+				"",
+				"Write your section landing page here.",
+				""
+			].join("\n"), false) === "skipped") log.warn(`${relative(cwd, target)} already exists — left untouched.`);
+			else log.success(`Created ${relative(cwd, target)}`);
+			return;
+		}
+		const slug = await resolveSlug(baseSlug, await existingSlugs(targetDir));
+		const order = values.order ? Number(values.order) : void 0;
+		const target = join(targetDir, order !== void 0 && Number.isFinite(order) ? `${String(order).padStart(2, "0")}-${slug}.md` : `${slug}.md`);
+		if (await writeFileSafe(target, [
+			"---",
+			`title: ${yamlValue(title)}`,
+			"description: ",
+			"---",
+			"",
+			"Write your page here.",
+			""
+		].join("\n"), false) === "skipped") log.warn(`${relative(cwd, target)} already exists — left untouched.`);
+		else log.success(`Created ${relative(cwd, target)}`);
+		return;
+	}
+	const slug = await resolveSlug(baseSlug, await existingSlugs(join(cwd, contentDir)));
+	const target = join(cwd, contentDir, values.flat ? `${slug}.md` : `${date}-${slug}.md`);
+	if (await writeFileSafe(target, [
+		"---",
+		`title: ${yamlValue(title)}`,
+		"description: ",
+		`date: ${date}`,
+		`slug: ${slug}`,
+		"tags: []",
+		"---",
+		"",
+		"Write your post here.",
+		""
+	].join("\n"), false) === "skipped") log.warn(`${relative(cwd, target)} already exists — left untouched.`);
+	else log.success(`Created ${relative(cwd, target)}`);
+}
+//#endregion
+//#region src/index.ts
+const HELP = `${c.bold("voxx")} — a zero-friction, file-based CMS for blogs and docs
+
+${c.bold("Usage:")}
+  voxx init [blog|docs|changelog] [--dir <content>] [--base <path>] [--app <dir>] [--force]
+  voxx init --add [blog|docs|changelog] [--name <name>] [--dir <dir>] [--base <path>] [--app <dir>]
+  voxx new "Title" [--collection <name>] [--slug <slug>] [--dir <content>] [--date <YYYY-MM-DD>] [--flat] [--section <path>] [--order <n>] [--index]
+  voxx build [--out <dir>] [--drafts]
+  voxx dev [--port <n>] [--drafts]
+
+${c.bold("Examples:")}
+  voxx init                 Scaffold a blog into your Next.js app
+  voxx init docs            Scaffold a docs site instead
+  voxx init changelog       Scaffold a release-notes page
+  voxx init --add docs      Add a docs collection to an existing site
+  voxx new "Hello world"    Create a new markdown post (or doc page, or release)
+  voxx new "Guides" --section guides --index   Create a docs section's index.md landing page
+  voxx build                Render a static HTML site to ./dist
+  voxx dev                  Preview the static site locally, rebuilding on change
+`;
+async function main() {
+	const [cmd, ...rest] = process.argv.slice(2);
+	switch (cmd) {
+		case "init":
+			await init(rest);
+			break;
+		case "new":
+			await newPost(rest);
+			break;
+		case "build":
+			await build(rest);
+			break;
+		case "dev":
+			await dev(rest);
+			break;
+		case void 0:
+		case "-h":
+		case "--help":
+			log.info(HELP);
+			break;
+		default:
+			log.error(`Unknown command: ${cmd}`);
+			log.info(HELP);
+			process.exitCode = 1;
+	}
+}
+main().catch((err) => {
+	log.error(err instanceof Error ? err.message : String(err));
+	process.exitCode = 1;
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=index.mjs.map