@janga/norna 0.7.27 → 0.7.29

package/scripts/add-site-node.mjs

@@ -1,251 +1,32 @@
-import { randomUUID } from 'node:crypto';
-import { mkdir, realpath, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { dump as dumpYaml } from 'js-yaml';
-import { slugifyAsciiIdentifier } from './lib/heading-ids.mjs';
-import { pageDirectoryPattern } from './lib/page-model.mjs';
-import {
-	invocationRoot,
-	siteDir,
-	sitePagesDir,
-	siteProjectRoot,
-} from './lib/site-paths.mjs';
-import { getSiteStructure } from './lib/site-structure.mjs';
-
-const usage = `
-Usage:
-  norna page:add <title> [--parent <path>] [--slug <slug>] [--order <NNN>] [--dry-run]
-  norna category:add <label> [--parent <path>] [--slug <slug>] [--order <NNN>] [--dry-run]
-
-Parent selection:
-  --parent /                 Add a top-level node
-  --parent /guides/         Add a child below the guides node
-  no --parent               Use the current node directory, or site/pages/
-`.trim();
-
-const parseValueOption = (rawArgs, index, name) => {
-	const arg = rawArgs[index];
-	if (arg === name) {
-		const value = rawArgs[index + 1];
-		if (!value || value.startsWith('-')) throw new Error(`${name} requires a value.\n${usage}`);
-		return { consumed: 2, value };
-	}
-	if (arg.startsWith(`${name}=`)) {
-		const value = arg.slice(name.length + 1);
-		if (!value) throw new Error(`${name} requires a value.\n${usage}`);
-		return { consumed: 1, value };
-	}
-	return null;
-};
-
-const parseArgs = (rawArgs) => {
-	const options = {
-		dryRun: false,
-		help: false,
-		order: null,
-		parent: null,
-		slug: null,
-		titleParts: [],
-	};
-	const seen = new Set();
-
-	for (let index = 0; index < rawArgs.length;) {
-		const arg = rawArgs[index];
-		if (arg === '-h' || arg === '--help') {
-			options.help = true;
-			index += 1;
-			continue;
-		}
-		if (arg === '--dry-run') {
-			if (seen.has('dryRun')) throw new Error(`--dry-run may be specified only once.\n${usage}`);
-			seen.add('dryRun');
-			options.dryRun = true;
-			index += 1;
-			continue;
-		}
-
-		let matched = false;
-		for (const [name, key] of [['--order', 'order'], ['--parent', 'parent'], ['--slug', 'slug']]) {
-			const parsed = parseValueOption(rawArgs, index, name);
-			if (!parsed) continue;
-			if (seen.has(key)) throw new Error(`${name} may be specified only once.\n${usage}`);
-			seen.add(key);
-			options[key] = parsed.value;
-			index += parsed.consumed;
-			matched = true;
-			break;
-		}
-		if (matched) continue;
-
-		if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}\n${usage}`);
-		options.titleParts.push(arg);
-		index += 1;
-	}
-
-	return options;
-};
-
-const parseOrder = (value) => {
-	if (!/^\d{1,3}$/.test(value)) {
-		throw new Error(`Invalid --order "${value}". Use an integer from 1 to 999.`);
-	}
-	const order = Number.parseInt(value, 10);
-	if (order < 1 || order > 999) {
-		throw new Error(`Invalid --order "${value}". Use an integer from 1 to 999.`);
-	}
-	return order;
-};
-
-const normalizeParentPath = (value) => {
-	if (value === '/') return '';
-	if (value.includes('\\') || value.includes('?') || value.includes('#')) {
-		throw new Error(`Invalid --parent "${value}". Use a logical path such as /guides/installation/.`);
-	}
-	const normalized = value.replace(/^\/+|\/+$/g, '');
-	if (!normalized || normalized.split('/').some((segment) => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(segment))) {
-		throw new Error(`Invalid --parent "${value}". Use / for the top level or a logical path such as /guides/installation/.`);
-	}
-	return normalized;
-};
-
-const getNextOrder = (siblings) => {
-	const highestOrder = siblings.reduce((highest, node) => Math.max(highest, node.pageOrder), 0);
-	const nextOrder = Math.floor(highestOrder / 10) * 10 + 10;
-	if (nextOrder > 999) {
-		throw new Error('No automatic page order remains below 1000. Reorder the sibling nodes before adding another one.');
-	}
-	return nextOrder;
-};
-
-const toDisplayPath = (filePath) => {
-	const relativePath = path.relative(siteProjectRoot, filePath);
-	return (relativePath && !relativePath.startsWith('..') && !path.isAbsolute(relativePath)
-		? relativePath
-		: filePath).split(path.sep).join('/');
-};
-
-const escapeMarkdownHeading = (value) => value.replace(/([\\`*_[\]{}<>#])/g, '\\$1');
-
-const canonicalDirectory = async (directory) => realpath(directory).catch((error) => {
-	if (error?.code === 'ENOENT') return path.resolve(directory);
-	throw error;
-});
-
-const resolveParent = async ({ nodes, parent }) => {
-	if (parent !== null) {
-		const parentPath = normalizeParentPath(parent);
-		if (!parentPath) {
-			return { collectionDir: sitePagesDir, node: null, pagePath: '' };
-		}
-		const node = nodes.find((candidate) => candidate.pagePath === parentPath);
-		if (!node) {
-			throw new Error(`Cannot find parent "${parent}". Use an existing logical page/category path, or / for the top level.`);
-		}
-		if (node.isHome) throw new Error('The homepage cannot contain child pages or categories.');
-		return { collectionDir: path.join(node.nodeDir, 'pages'), node, pagePath: node.pagePath };
-	}
-
-	const currentDirectory = await canonicalDirectory(invocationRoot);
-	if (currentDirectory === await canonicalDirectory(sitePagesDir)) {
-		return { collectionDir: sitePagesDir, node: null, pagePath: '' };
-	}
-	let node = null;
-	for (const candidate of nodes) {
-		if (await canonicalDirectory(candidate.nodeDir) === currentDirectory) {
-			node = candidate;
-			break;
-		}
-	}
-	if (!node) {
-		throw new Error([
-			'Cannot infer where to add the node from the current directory.',
-			`Run the command from ${toDisplayPath(sitePagesDir)} for a top-level node, from an existing page/category directory for a child, or pass --parent.`,
-		].join('\n'));
-	}
-	if (node.isHome) throw new Error('The homepage cannot contain child pages or categories.');
-	return { collectionDir: path.join(node.nodeDir, 'pages'), node, pagePath: node.pagePath };
-};
-
-const assertCollectionDirectory = async (collectionDir) => {
-	try {
-		const info = await stat(collectionDir);
-		if (!info.isDirectory()) throw new Error(`${toDisplayPath(collectionDir)} exists but is not a directory.`);
-		return false;
-	} catch (error) {
-		if (error?.code !== 'ENOENT') throw error;
-		await mkdir(collectionDir);
-		return true;
-	}
-};
-
-const writeNode = async ({ destination, kind, title }) => {
-	const stagingRoot = path.join(siteDir, '.norna', 'create');
-	await mkdir(stagingRoot, { recursive: true });
-	const stagingDirectory = path.join(stagingRoot, `node-${process.pid}-${randomUUID()}`);
-	await mkdir(stagingDirectory);
-
-	try {
-		if (kind === 'page') {
-			await writeFile(path.join(stagingDirectory, 'content.md'), `# ${escapeMarkdownHeading(title)}\n\n## Introduction\n\nStart writing here.\n`);
-			await mkdir(path.join(stagingDirectory, 'images'));
-		} else {
-			await writeFile(path.join(stagingDirectory, 'category.yaml'), dumpYaml({ label: title }, {
-				lineWidth: -1,
-				noRefs: true,
-			}));
-			await mkdir(path.join(stagingDirectory, 'pages'));
-		}
-		await rename(stagingDirectory, destination);
-	} finally {
-		await rm(stagingDirectory, { force: true, recursive: true });
-	}
-};
-
-const [kind, ...rawArgs] = process.argv.slice(2);
-if (!['category', 'page'].includes(kind)) throw new Error(usage);
-const options = parseArgs(rawArgs);
-if (options.help) {
-	console.log(usage);
-	process.exit(0);
-}
-
-const title = options.titleParts.join(' ').trim();
-if (!title || /[\r\n]/.test(title)) throw new Error(`A one-line ${kind === 'page' ? 'page title' : 'category label'} is required.\n${usage}`);
-const slug = options.slug ?? slugifyAsciiIdentifier(title);
-if (!slug || !pageDirectoryPattern.test(`010-${slug}`)) {
-	throw new Error(`Invalid ${options.slug === null ? 'generated ' : ''}slug "${slug}". Use lowercase ASCII letters, numbers, and single hyphens; pass --slug when automatic transliteration is unsuitable.`);
-}
-
-const structure = await getSiteStructure();
-const parent = await resolveParent({ nodes: structure.nodes, parent: options.parent });
-const siblings = structure.nodes.filter((node) => node.parentPagePath === (parent.pagePath || null) && !node.isHome);
-if (siblings.some((node) => node.pageId === slug)) {
-	throw new Error(`Cannot create "${slug}" below ${parent.pagePath ? `/${parent.pagePath}/` : '/'}. A sibling with that slug already exists.`);
-}
-const order = options.order === null ? getNextOrder(siblings) : parseOrder(options.order);
-if (siblings.some((node) => node.pageOrder === order)) {
-	throw new Error(`Cannot use order ${String(order).padStart(3, '0')} below ${parent.pagePath ? `/${parent.pagePath}/` : '/'}. A sibling already uses it.`);
-}
-
-const directoryName = `${String(order).padStart(3, '0')}-${slug}`;
-const destination = path.join(parent.collectionDir, directoryName);
-const pagePath = [parent.pagePath, slug].filter(Boolean).join('/');
-const action = options.dryRun ? 'Would create' : 'Created';
-
-if (!options.dryRun) {
-	const createdCollection = await assertCollectionDirectory(parent.collectionDir);
-	try {
-		await writeNode({ destination, kind, title });
-	} catch (error) {
-		if (createdCollection) await rmdir(parent.collectionDir).catch(() => {});
-		throw error;
-	}
-}
-
-console.log(`${action} ${kind} "${title}" at ${toDisplayPath(destination)}.`);
-if (kind === 'page') {
-	console.log(`URL: /${pagePath}/`);
-} else {
-	console.log('This navigation category has no authored content page. Norna generates its destination from the child pages.');
-	console.log(`Child URL prefix: /${pagePath}/`);
-}
+import { invocationRoot, siteDir, siteProjectRoot } from './lib/site-paths.mjs';
+import { createSiteNode, planSiteNodeCreation } from './lib/site-node-create.mjs';
+import { parsePlacementArguments, confirmCliRenumbering, describeRenumbering } from './lib/page-placement-cli.mjs';
+
+const usage = `Usage:
+  norna page:add <title> [--parent <path>] [--first | --last] [--slug <slug>]
+  norna page:add <title> --before <page-url> | --after <page-url>
+
+Options: --order <integer>, --dry-run, --allow-renumber
+Without a placement, append under --parent or the current page/site directory.
+Before/after infer the parent. --order cannot accompany a relative placement.`;
+const display = filename => path.relative(siteProjectRoot, filename) || filename;
+try {
+ const [kind, ...args] = process.argv.slice(2);
+ if (kind !== 'page') throw new Error(usage);
+ const options = parsePlacementArguments(args);
+ if (options.help) { console.log(usage); process.exit(0); }
+ if (options.write || options.noAliases) throw new Error('page:add uses --dry-run; --write and --no-aliases are page:move options.');
+ const title = options.positionals.join(' ').trim();
+ if (!title) throw new Error(`A one-line page title is required.\n${usage}`);
+ const plan = await planSiteNodeCreation({ siteRoot: siteDir, kind, title, slug: options.slug, order: options.order,
+  parentPath: options.parent, invocationDirectory: invocationRoot,
+  placement: options.order !== null ? null : options.placement, targetPath: options.target });
+ console.log(`Page: ${title}\nSource: ${display(plan.destination)}\nURL: ${plan.url}\nOrder: ${plan.order}`);
+ const renumbering = describeRenumbering(plan.orderChanges, display);
+ if (renumbering) console.log(renumbering);
+ if (options.dryRun) { console.log(`Would create page "${title}". Dry run only. No files changed.`); process.exit(0); }
+ if (!await confirmCliRenumbering(plan.orderChanges, options)) { console.log('Cancelled. No files changed.'); process.exit(0); }
+ const result = await createSiteNode(plan, { allowRenumber: true });
+ console.log(`Created page "${title}" at ${display(plan.destination)}. ${result.renumberedPages} existing sibling page(s) renumbered.`);
+} catch (error) { console.error(error.message); process.exitCode = 1; }

package/scripts/build-site.mjs

@@ -9,9 +9,14 @@ const runScript = (relativePath, args = []) => runInherit(
 	{ cwd: siteProjectRoot },
 );
 
-await runScript('scripts/check-config.mjs');
-await runScript('scripts/sync-content-sections.mjs', ['--check']);
-await runScript('scripts/sync-site-public.mjs');
-await runScript('scripts/generate-images.mjs');
-await runAstroInherit(['build']);
-await runScript('scripts/generate-search-index.mjs');
+try {
+	await runScript('scripts/check-config.mjs');
+	await runScript('scripts/sync-content-sections.mjs', ['--check']);
+	await runScript('scripts/sync-site-public.mjs');
+	await runScript('scripts/generate-images.mjs');
+	await runAstroInherit(['build']);
+	await runScript('scripts/generate-search-index.mjs');
+} catch (error) {
+	console.error(error.message);
+	process.exitCode = 1;
+}

package/scripts/check-config.mjs

@@ -1,12 +1,11 @@
-import path from 'node:path';
-import { siteConfigLabel, sitePagesDir, sitePublicLabel, siteThemeLabel } from './lib/site-paths.mjs';
+import { siteConfigLabel, siteDir, sitePublicLabel } from './lib/site-paths.mjs';
 import { getLogoAssets, getPublicAssetInspection } from './lib/logo-assets.mjs';
 import { logoAssetFilenames, socialImageAssetFilenames } from './lib/public-asset-conventions.mjs';
 import { getSocialImageAssets } from './lib/social-image-assets.mjs';
 import { readSitewideContent } from './lib/sitewide-content.mjs';
 import { assertSectionBackgroundPatternCompatibility } from './lib/presentation.mjs';
 import { readThemeConfig, validatePageThemeFiles } from './lib/theme-config.mjs';
-import { mergePageThemeConfig } from './lib/theme-presets.mjs';
+import { selectPageTheme } from './lib/theme-packages.mjs';
 
 const formatErrorMessage = (error) => {
 	if (error instanceof Error) {
@@ -21,26 +20,11 @@ try {
 	const themeConfig = await readThemeConfig();
 	const sitewideContent = await readSitewideContent();
 	const pageThemeFiles = await validatePageThemeFiles();
-	const pageThemesByDirectory = new Map(pageThemeFiles.map((file) => [path.dirname(file.path), file]));
-	for (const pageThemeFile of pageThemeFiles) {
-		const ancestorThemes = [];
-		let directory = path.dirname(pageThemeFile.path);
-		while (directory.startsWith(`${sitePagesDir}${path.sep}`)) {
-			const ancestorTheme = pageThemesByDirectory.get(directory);
-			if (ancestorTheme) ancestorThemes.unshift(ancestorTheme);
-			directory = path.dirname(directory);
-		}
-
-		const resolvedPageTheme = ancestorThemes.reduce(
-			(current, ancestor) => mergePageThemeConfig(current, ancestor.config),
-			themeConfig,
-		);
-		resolveThemeVisualConfig(resolvedPageTheme, pageThemeFile.label);
-	}
-	if (projectConfig.navigation.mode === 'tree') {
-		assertSectionBackgroundPatternCompatibility(themeConfig, siteThemeLabel, 'tree');
-		for (const pageThemeFile of pageThemeFiles) {
-			assertSectionBackgroundPatternCompatibility(pageThemeFile.config, pageThemeFile.label, 'tree');
+	for (const pageDirectory of new Set(['.', ...pageThemeFiles.map((file) => file.pageDirectory)])) {
+		const { treeTheme, selected } = await selectPageTheme({ siteRoot: siteDir, pageDirectory });
+		for (const theme of [treeTheme, selected]) {
+			resolveThemeVisualConfig(theme.config, theme.label);
+			if (projectConfig.navigation.mode === 'tree') assertSectionBackgroundPatternCompatibility(theme.config, theme.label, 'tree');
 		}
 	}
 	const logoAssets = getLogoAssets();

package/scripts/dev-local.mjs

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto';
+import { readDevServerIdentity, verifyDevServer } from './lib/dev-server-identity.mjs';
 import { execFile } from 'node:child_process';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import net from 'node:net';
@@ -10,20 +12,35 @@ import {
 	engineRoot,
 	siteProjectRoot,
 	siteStateDir,
+	siteDir,
 } from './lib/site-paths.mjs';
 
 const execFileAsync = promisify(execFile);
 
-const port = Number.parseInt(process.env.NORNA_DEV_PORT ?? '4321', 10);
+const portValue = process.env.NORNA_DEV_PORT ?? '4321';
+const port = /^\d+$/.test(portValue) ? Number(portValue) : NaN;
+const serverToken = process.env.NORNA_DEV_START_TOKEN || randomUUID();
 if (!Number.isInteger(port) || port < 1 || port > 65_535) {
 	throw new Error('NORNA_DEV_PORT must be an integer from 1 through 65535.');
 }
+const args = process.argv.slice(2);
+const knownCommands = new Set(['start', 'lan', 'status', 'logs', 'restart', 'stop']);
+const command = args.find((arg) => knownCommands.has(arg)) ?? args.find((arg) => !arg.startsWith('-')) ?? 'start';
+const shouldKillBlockingPort = args.includes('--kill');
+const shouldFollowLogs = args.includes('--follow');
+
 let projectConfig;
-try {
-	({ default: projectConfig } = await import('./lib/project-config.mjs'));
-} catch (error) {
-	console.error(error instanceof Error ? error.message : String(error));
-	process.exit(1);
+if (['stop', 'status', 'logs'].includes(command)) {
+	// Recovery commands use the recorded server even while sources need conversion.
+	const recorded = await readFile(path.join(siteStateDir, 'dev', 'state.json'), 'utf8').then(JSON.parse).catch(() => null);
+	projectConfig = { site: { basePath: recorded?.url ? new URL(recorded.url).pathname : '/' } };
+} else {
+	try {
+		({ default: projectConfig } = await import('./lib/project-config.mjs'));
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
 }
 const localHost = '127.0.0.1';
 const localUrl = `http://${localHost}:${port}${projectConfig.site.basePath}`;
@@ -38,11 +55,6 @@ const legacyStatePath = path.join(astroCacheDir, 'dev-local.json');
 const astroStatePath = path.join(astroCacheDir, 'dev.json');
 const logPath = path.join(astroCacheDir, 'dev.log');
 const preparationLogPath = path.join(stateDirectory, 'preparation.log');
-const args = process.argv.slice(2);
-const knownCommands = new Set(['start', 'lan', 'status', 'logs', 'restart', 'stop']);
-const command = args.find((arg) => knownCommands.has(arg)) ?? args.find((arg) => !arg.startsWith('-')) ?? 'start';
-const shouldKillBlockingPort = args.includes('--kill');
-const shouldFollowLogs = args.includes('--follow');
 
 const runAstro = async (args, options = {}) => execFileAsync(process.execPath, getAstroArgs(args), {
 	cwd: siteProjectRoot,
@@ -100,6 +112,8 @@ const writeState = async (host) => {
 	await writeFile(statePath, `${JSON.stringify({
 		port,
 		pid,
+		token: serverToken,
+		siteRoot: siteDir,
 		host,
 		mode: host === '0.0.0.0' ? 'lan' : 'local',
 		url: localUrl,
@@ -360,6 +374,12 @@ const openBrowser = async () => {
 
 const stopServer = async ({ quiet = false } = {}) => {
 	const state = await readState();
+	if (process.env.NORNA_DEV_EXPECT_TOKEN) {
+		if (state?.token !== process.env.NORNA_DEV_EXPECT_TOKEN || state.port !== port || !(await verifyDevServer(state, siteDir))) throw new Error('Cannot verify this site’s server. No process was stopped.');
+		if (!(await terminateTrackedProcess(state, state.host ?? localHost))) throw new Error('The verified preview server did not stop. Try Stop Preview Server again.');
+		await removeState();
+		return;
+	}
 	let astroError;
 	let astroOutput = '';
 	try {
@@ -390,7 +410,7 @@ const stopServer = async ({ quiet = false } = {}) => {
 };
 
 const startServer = async ({ host = localHost, open = true, killBlockingPort = false } = {}) => {
-	await stopServer({ quiet: true });
+	if (process.env.NORNA_DEV_NO_RESTART !== '1') await stopServer({ quiet: true });
 
 	if (!(await isPortFree(host))) {
 		if (!killBlockingPort) {
@@ -425,8 +445,24 @@ const startServer = async ({ host = localHost, open = true, killBlockingPort = f
 	}
 	const previousLog = await readDevLog();
 	try {
-		await runAstroInherit(['dev', '--background', '--host', host, '--port', String(port)]);
+		await runAstroInherit(['dev', '--background', '--host', host, '--port', String(port)], { env: { ...process.env, NORNA_DEV_TOKEN: serverToken } });
+		// Record the process before probing rendered pages, so failed readiness
+		// checks can clean up only the server started by this request.
+		await writeState(host);
+		await waitForServer();
 	} catch (error) {
+		let cleanupHint = '';
+		const identity = await readDevServerIdentity({ port, token: serverToken }, siteDir);
+		if (identity) {
+			const candidate = { port, ...identity };
+			try {
+				if (!(await terminateTrackedProcess(candidate, host))) throw new Error('The process did not stop.');
+				const recorded = await readState();
+				if (recorded?.token === serverToken) await removeState();
+			} catch (cleanup) {
+				cleanupHint = `Cleanup failed: ${cleanup.message} Use the site's dev:stop command after inspecting the log.`;
+			}
+		}
 		const currentLog = await readDevLog();
 		const newLog = currentLog.startsWith(previousLog)
 			? currentLog.slice(previousLog.length)
@@ -436,11 +472,9 @@ const startServer = async ({ host = localHost, open = true, killBlockingPort = f
 			`Could not start the dev server at ${localUrl}.`,
 			excerpt ? `Astro reported:\n${excerpt}` : 'Astro did not write a detailed startup error.',
 			`Full log: ${logPath}`,
-		].join('\n\n'), { cause: error });
+			cleanupHint,
+		].filter(Boolean).join('\n\n'), { cause: error });
 	}
-	await waitForServer();
-
-	await writeState(host);
 	if (open) {
 		await openBrowser();
 	} else {

package/scripts/export-theme-preset.mjs

@@ -4,7 +4,7 @@ import {
 	renderThemePresetReference,
 	themePresetNames,
 } from './lib/theme-presets.mjs';
-import { siteDir, siteThemeLabel } from './lib/site-paths.mjs';
+import { siteDir, siteDirLabel, siteThemeLabel } from './lib/site-paths.mjs';
 
 const [presetName, ...extraArgs] = process.argv.slice(2);
 
@@ -14,7 +14,7 @@ if (!presetName || extraArgs.length > 0) {
 
 const filename = `orig-${presetName}-theme.yaml`;
 const outputPath = path.join(siteDir, filename);
-const outputLabel = path.posix.join(path.posix.dirname(siteThemeLabel), filename);
+const outputLabel = path.posix.join(siteDirLabel, filename);
 const source = renderThemePresetReference(presetName, siteThemeLabel);
 
 try {