@janga/norna 0.7.27 → 0.7.28

package/scripts/lib/site-conventions.mjs

@@ -1 +1,19 @@
-export const homePageDirectory = '000-home';
+import path from 'node:path';
+
+// Logical identities stay independent of the physical root/ directory.
+export const homePageDirectory = '.';
+export const legacyHomePageDirectory = '000-home';
+
+export const getSiteSourcePaths = (siteRoot) => {
+	const root = path.join(siteRoot, 'root');
+	return { root, pages: path.join(root, 'pages'), content: path.join(root, 'content.md'),
+		images: path.join(root, 'images'), theme: path.join(root, 'tree-theme.yaml') };
+};
+
+export const getPageSourceDirectory = (pageDirectory) => (
+	pageDirectory === homePageDirectory ? 'root' : `root/pages/${pageDirectory}`
+);
+
+export const getPageImageSourceKey = (pageDirectory, image) => (
+	[getPageSourceDirectory(pageDirectory), 'images', image].filter(Boolean).join('/')
+);

package/scripts/lib/site-navigation-tree.mjs

@@ -30,7 +30,6 @@ export const getListedSiteNavigationTree = (entries) => {
 	const filterListed = (nodes) => nodes.flatMap((node) => {
 		if (!node.node.isHome && !node.node.navigation.listed) return [];
 		const children = filterListed(node.children);
-		if (node.node.kind === 'category' && children.length === 0) return [];
 		return [{ ...node, children }];
 	});
 
@@ -48,9 +47,7 @@ export const getSequentialPageNavigation = (nodes, currentPagePath) => {
 	));
 	if (!activeRoot) return { previous: null, next: null };
 
-	const pages = flattenSiteNavigationTree([activeRoot])
-		.filter(({ node }) => node.kind === 'page')
-		.map(({ node }) => node);
+	const pages = flattenSiteNavigationTree([activeRoot]).map(({ node }) => node);
 	const currentIndex = pages.findIndex(({ pagePath }) => pagePath === currentPagePath);
 	if (currentIndex < 0) return { previous: null, next: null };
 
@@ -68,7 +65,5 @@ export const getDirectChildPages = (nodes, currentPagePath) => {
 		? nodes.filter(({ node }) => !node.isHome)
 		: current.children;
 
-	return children
-		.filter(({ node }) => node.kind === 'page')
-		.map(({ node }) => node);
+	return children.map(({ node }) => node);
 };

package/scripts/lib/site-node-create.mjs

@@ -0,0 +1,169 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import { mkdir, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { dump as dumpYaml } from 'js-yaml';
+import { slugifyAsciiIdentifier } from './heading-ids.mjs';
+import { pageDirectoryPattern } from './page-model.mjs';
+import { getSiteStructure } from './site-structure.mjs';
+import { siteSchema } from './schema-definitions.mjs';
+import { readEditorLinkState } from './editor-site-links.mjs';
+import { createPageAliasModel, assertPageAliasModel } from './page-aliases.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+
+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;
+};
+
+export 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, siteRoot, invocationDirectory }) => {
+	const sitePagesDir = getSiteSourcePaths(siteRoot).pages;
+	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 page path, or / for the top level.`);
+		}
+		return { collectionDir: path.join(node.nodeDir, 'pages'), node, pagePath: node.pagePath };
+	}
+
+	const currentDirectory = await canonicalDirectory(invocationDirectory);
+	if (currentDirectory === await canonicalDirectory(sitePagesDir) || currentDirectory === await canonicalDirectory(siteRoot)) {
+		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 ${sitePagesDir} for a top-level node, from an existing page directory for a child, or pass --parent.`,
+		].join('\n'));
+	}
+	return { collectionDir: path.join(node.nodeDir, 'pages'), node, pagePath: node.pagePath };
+};
+
+// Planning never writes. Callers must present this same destination before applying.
+export const planSiteNodeCreation = async ({
+	siteRoot, kind, title, slug = null, order = null, parentPath = '/',
+	invocationDirectory = siteRoot, metadata, sources = new Map(),
+}) => {
+	if (kind !== 'page') throw new Error('Choose a page. Navigation categories are no longer supported; use page.listChildren: true for an overview.');
+	siteRoot = path.resolve(siteRoot);
+	title = String(title ?? '').trim();
+	if (!title || /[\r\n]/.test(title)) throw new Error('A one-line page title is required.');
+	const generatedSlug = slug === null;
+	slug ??= slugifyAsciiIdentifier(title);
+	if (!slug || !pageDirectoryPattern.test(`010-${slug}`)) {
+		throw new Error(`Invalid ${generatedSlug ? 'generated ' : ''}slug "${slug}". Use lowercase ASCII letters, numbers, and single hyphens; pass --slug when automatic transliteration is unsuitable.`);
+	}
+
+	const structure = await getSiteStructure({ siteRoot });
+	const parent = await resolveParent({ nodes: structure.nodes, parent: parentPath, siteRoot, invocationDirectory });
+	const siblings = structure.nodes.filter((node) => !node.isHome && node.parentPagePath === (parent.pagePath || null));
+	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.`);
+	}
+	order = order === null ? getNextOrder(siblings) : parseOrder(String(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 state = await readEditorLinkState({ siteRoot, sources });
+	if (state.incomplete.length) throw new Error(`Page addresses could not be checked. ${state.incomplete.join('\n')}`);
+	const address = `/${pagePath}/`;
+	const owner = state.graph.aliasModel.identitiesByPathname.get(address);
+	if (owner?.kind === 'page-alias') {
+		const page = owner.source.page;
+		throw new Error(`${address} is a previous address for “${page.title}”, now at ${owner.source.targetPathname}. Choose another URL segment, or remove this previous address from “${page.title}” through Addresses and links… → Additional addresses….`);
+	}
+	if (owner) throw new Error(`Address ${address} is already in use by ${owner.label}. Choose another URL segment.`);
+	if (metadata !== undefined) {
+		metadata = parseYamlConfig(dumpYaml(metadata), 'Page information', { schema: siteSchema });
+		assertPageAliasModel(createPageAliasModel({ pages: [...state.graph.pages,
+			{ pathname: `/${pagePath}/`, contentLabel: destination, aliases: metadata.page?.aliases ?? [] }],
+			categories: [], publicFiles: state.publicFiles, generatedRoutes: state.generatedRoutes }));
+	}
+	return { siteRoot, kind, title, slug, order, parentPath: parent.pagePath ? `/${parent.pagePath}/` : '/',
+		collectionDir: parent.collectionDir, destination, pagePath, url: `/${pagePath}/`, ...(metadata === undefined ? {} : { metadata }) };
+};
+
+export const createSiteNode = async (plan, { sources = new Map() } = {}) => {
+	// Revalidate after the author has inspected the preview. Never change its placement.
+	const current = await planSiteNodeCreation({ ...plan, sources });
+	if (current.destination !== plan.destination) throw new Error('The site changed. Preview the new location before creating the node.');
+	let createdCollection = false;
+	try {
+		const info = await stat(current.collectionDir);
+		if (!info.isDirectory()) throw new Error(`${current.collectionDir} exists but is not a directory.`);
+	} catch (error) {
+		if (error.code !== 'ENOENT') throw error;
+		await mkdir(current.collectionDir);
+		createdCollection = true;
+	}
+	const created = [];
+	try {
+		// Exclusive reservation also protects an empty destination created after planning.
+		await mkdir(current.destination);
+		created.push({ file: current.destination, directory: true });
+		const filename = path.join(current.destination, 'content.md');
+		const source = `${current.metadata && Object.keys(current.metadata).length ? `---\n${dumpYaml(current.metadata, { lineWidth: -1, noRefs: true })}---\n\n` : ''}# ${escapeMarkdownHeading(current.title)}\n\n## Introduction\n\nStart writing here.\n`;
+		await writeFile(filename, source, { flag: 'wx' });
+		created.push({ file: filename });
+		const childDirectory = path.join(current.destination, 'images');
+		await mkdir(childDirectory);
+		created.push({ file: childDirectory, directory: true });
+		return { ...current, sourcePath: filename };
+	} catch (error) {
+		// Remove only entries this operation created; never recursively remove an
+		// unexpected file written concurrently by another process.
+		for (const entry of created.reverse()) {
+			await (entry.directory ? rmdir(entry.file) : unlink(entry.file)).catch(() => {});
+		}
+		if (createdCollection) await rmdir(current.collectionDir).catch(() => {});
+		throw error;
+	}
+};

package/scripts/lib/site-paths.mjs

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { homePageDirectory } from './site-conventions.mjs';
+import { getSiteSourcePaths, homePageDirectory, legacyHomePageDirectory } from './site-conventions.mjs';
 
 const siteDirectoryEnvName = 'NORNA_SITE_DIR';
 const invocationRootEnvName = 'NORNA_INVOCATION_ROOT';
@@ -32,9 +32,10 @@ if (hasStateDirectoryEnv && !configuredStateDirectory) {
 
 const hasSiteFilesInDirectory = (siteDir) => {
 	return (
-		existsSync(path.join(siteDir, 'config.yaml'))
+		(existsSync(path.join(siteDir, 'site-config', 'settings.yaml')) || existsSync(path.join(siteDir, 'config.yaml')))
 		&& (
-			existsSync(path.join(siteDir, 'pages', homePageDirectory, 'content.md'))
+			existsSync(path.join(siteDir, 'pages', legacyHomePageDirectory, 'content.md'))
+			|| existsSync(getSiteSourcePaths(siteDir).content)
 			|| existsSync(path.join(siteDir, 'content.md'))
 		)
 	);
@@ -63,6 +64,16 @@ const findSiteProjectRoot = (startDirectory, siteDirectory) => {
 	}
 };
 
+const findContainingSite = (startDirectory) => {
+	let current = path.resolve(startDirectory);
+	while (true) {
+		if (hasSiteFilesInDirectory(current)) return current;
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+};
+
 const hasSiteDirectoryEnv = Object.hasOwn(process.env, siteDirectoryEnvName);
 const configuredSiteDirectory = normalizeSiteDirectory(process.env[siteDirectoryEnvName]);
 const hasConfiguredSiteDirectory = hasSiteDirectoryEnv && configuredSiteDirectory !== '';
@@ -84,8 +95,9 @@ const resolveSitePaths = () => {
 		};
 	}
 
-	if (!hasConfiguredSiteDirectory && hasSiteFilesInDirectory(invocationRoot)) {
-		const siteDir = invocationRoot;
+	const containingSite = !hasConfiguredSiteDirectory && findContainingSite(invocationRoot);
+	if (containingSite) {
+		const siteDir = containingSite;
 		const siteProjectRoot = path.dirname(siteDir);
 
 		return {
@@ -126,11 +138,11 @@ const getPathLabel = (filePath) => {
 };
 
 export const siteDir = resolvedSitePaths.siteDir;
-export const siteConfigPath = path.join(siteDir, 'config.yaml');
-export const siteThemePath = path.join(siteDir, 'theme.yaml');
-export const sitewideContentPath = path.join(siteDir, 'sitewide-content.yaml');
-export const sitePagesDir = path.join(siteDir, 'pages');
-export const siteHomePageDir = path.join(sitePagesDir, homePageDirectory);
+export const siteConfigPath = path.join(siteDir, 'site-config', 'settings.yaml');
+export const siteThemePath = getSiteSourcePaths(siteDir).theme;
+export const sitewideContentPath = path.join(siteDir, 'site-config', 'shared-content.yaml');
+export const sitePagesDir = getSiteSourcePaths(siteDir).pages;
+export const siteHomePageDir = getSiteSourcePaths(siteDir).root;
 export const siteContentPath = path.join(siteHomePageDir, 'content.md');
 export const siteImagesDir = path.join(siteHomePageDir, 'images');
 export const sitePublicDir = path.join(siteDir, 'public');

package/scripts/lib/site-structure.mjs

@@ -1,16 +1,12 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
 import { access, readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { categorySchema } from './schema-definitions.mjs';
 import { parsePageDirectoryPath } from './page-model.mjs';
 import {
 	homePageDirectory,
-	siteContentLabel,
-	siteDir,
-	siteDirLabel,
-	sitePagesDir,
-	sitePagesLabel,
+	siteDir as defaultSiteDir,
+	siteDirLabel as defaultSiteDirLabel,
 } from './site-paths.mjs';
-import { parseYamlConfig } from './yaml-config.mjs';
 
 const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
 
@@ -24,21 +20,11 @@ const compareNodeMetadata = (left, right) => (
 	|| left.pageId.localeCompare(right.pageId, 'en')
 );
 
-const assertLegacyStructureIsAbsent = async () => {
-	const legacyContentPath = path.join(siteDir, 'content.md');
-	const legacyImagesPath = path.join(siteDir, 'images');
-	const legacyPaths = [];
-	if (await fileExists(legacyContentPath)) legacyPaths.push(`${siteDirLabel}/content.md`);
-	if (await fileExists(legacyImagesPath)) legacyPaths.push(`${siteDirLabel}/images`);
-	if (legacyPaths.length > 0) {
-		throw new Error([
-			`The old root-page structure is no longer supported: ${legacyPaths.join(', ')}.`,
-			`Move the homepage content to ${sitePagesLabel}/${homePageDirectory}/content.md and its images to ${sitePagesLabel}/${homePageDirectory}/images/.`,
-		].join('\n'));
-	}
-
-	if (await fileExists(path.join(siteDir, 'routes'))) {
-		throw new Error(`${siteDirLabel}/routes is no longer supported. Rename it to ${sitePagesLabel} and use NNN-page-id directory names.`);
+const assertLegacyStructureIsAbsent = async ({ siteDir, siteDirLabel }) => {
+	for (const name of ['content.md', 'theme.yaml', 'images', 'pages', 'routes']) {
+		if (await fileExists(path.join(siteDir, name))) {
+			throw new Error(`${siteDirLabel}/${name} uses the former page layout. Put the homepage content.md, tree-theme.yaml, optional page-theme.yaml, images/ and pages/ inside ${siteDirLabel}/root/. Keep site-config/ and public/ at the site level. Stop the development server before moving files.`);
+		}
 	}
 };
 
@@ -69,13 +55,29 @@ const assertUniqueSiblings = (nodes, pagesLabel) => {
 	}
 };
 
-const readCategory = async (categoryPath, categorySourceLabel) => {
-	const source = await readFile(categoryPath, 'utf8');
-	return parseYamlConfig(source, categorySourceLabel, { schema: categorySchema });
-};
-
-export const getSiteStructure = async () => {
-	await assertLegacyStructureIsAbsent();
+// Editors can inspect several sites in one process and retain malformed nodes
+// for repair. Builds and mutation plans keep the strict default contract.
+export const getSiteStructure = async ({
+	siteRoot = defaultSiteDir,
+	tolerant = false,
+	readSource = (filePath) => readFile(filePath, 'utf8'),
+} = {}) => {
+	const siteDir = path.resolve(siteRoot);
+	const siteDirLabel = siteDir === defaultSiteDir ? defaultSiteDirLabel : siteDir;
+	const sitePagesDir = getSiteSourcePaths(siteDir).pages;
+	const sitePagesLabel = `${siteDirLabel}/root/pages`;
+	const siteContentLabel = `${siteDirLabel}/root/content.md`;
+	const problems = [];
+	const report = (error, node = null) => {
+		if (!tolerant) throw error;
+		problems.push({ message: error.message, path: node?.contentPath ?? node?.categoryPath ?? siteDir });
+		if (node) (node.problems ??= []).push(error.message);
+	};
+	try {
+		await assertLegacyStructureIsAbsent({ siteDir, siteDirLabel, sitePagesLabel });
+	} catch (error) {
+		report(error);
+	}
 
 	const nodes = [];
 	const warnings = [];
@@ -98,90 +100,78 @@ export const getSiteStructure = async () => {
 				fileExists(contentPath),
 				fileExists(categoryPath),
 			]);
-			const metadata = parsePageDirectoryPath(pageDirectory, nodeLabel);
-
-			if (hasContent === hasCategory) {
-				const problem = hasContent
-					? 'contains both content.md and category.yaml'
-					: 'contains neither content.md nor category.yaml';
-				throw new Error(`${nodeLabel} ${problem}. Keep exactly one: content.md for a page, or category.yaml for a navigation category.`);
+			let metadata;
+			try {
+				metadata = parsePageDirectoryPath(pageDirectory, nodeLabel);
+			} catch (error) {
+				report(error);
+				continue;
 			}
 
-			const isHome = pageDirectory === homePageDirectory;
-			if (isHome && hasCategory) {
-				throw new Error(`${nodeLabel}/category.yaml is invalid. The homepage must be a page with content.md.`);
+			if (hasCategory) report(new Error(`${nodeLabel}/category.yaml is no longer supported. Create content.md with an H1 and page.listChildren: true instead.`));
+			if (!hasContent) {
+				report(new Error(`${nodeLabel} has no content.md. Every page directory needs a content.md file.`));
+				continue;
 			}
 
 			const node = {
 				...metadata,
-				isHome,
-				kind: hasCategory ? 'category' : 'page',
+				isHome: false,
+				kind: 'page',
 				nodeDir,
 				nodeLabel,
-				pagePath: isHome ? '' : metadata.pagePath,
-				parentPagePath: isHome ? null : metadata.parentPagePath,
+				pagePath: metadata.pagePath,
+				parentPagePath: metadata.parentPagePath,
 			};
 
-			if (hasCategory) {
-				if (await fileExists(path.join(nodeDir, 'images'))) {
-					throw new Error(`${nodeLabel} is a navigation category and cannot contain images/. Use content.md when the collection needs editorial content or images.`);
-				}
-				const category = await readCategory(categoryPath, `${nodeLabel}/category.yaml`);
-				Object.assign(node, {
-					categorySourceLabel: `${nodeLabel}/category.yaml`,
-					categoryPath,
-					label: category.label,
-				});
-			} else {
-				Object.assign(node, {
-					contentLabel: `${nodeLabel}/content.md`,
-					contentPath,
-					imagesDir: path.join(nodeDir, 'images'),
-					imagesLabel: `${nodeLabel}/images`,
-				});
-			}
+			Object.assign(node, {
+				contentLabel: `${nodeLabel}/content.md`,
+				contentPath,
+				imagesDir: path.join(nodeDir, 'images'),
+				imagesLabel: `${nodeLabel}/images`,
+			});
 
 			siblingNodes.push(node);
 		}
 
-		assertUniqueSiblings(siblingNodes, pagesLabel);
+		try {
+			assertUniqueSiblings(siblingNodes, pagesLabel);
+		} catch (error) {
+			report(error);
+		}
 
 		for (const node of siblingNodes.sort(compareNodeMetadata)) {
 			nodes.push(node);
 			const childPagesDir = path.join(node.nodeDir, 'pages');
 			const childDirectories = (await readDirectory(childPagesDir)).filter((entry) => entry.isDirectory());
 
-			if (node.isHome && childDirectories.length > 0) {
-				throw new Error([
-					`${node.nodeLabel} is the homepage and cannot contain child pages.`,
-					`Move these page directories beside ${homePageDirectory} under ${sitePagesLabel}/, or below another non-home page:`,
-					...childDirectories.map(({ name }) => `- ${node.nodeLabel}/pages/${name}`),
-				].join('\n'));
-			}
-
-			if (node.kind === 'category' && childDirectories.length === 0) {
-				warnings.push({
-					code: 'empty-category',
-					label: node.categorySourceLabel,
-					message: `${node.categorySourceLabel} defines an empty navigation category. Add at least one child page under ${node.nodeLabel}/pages/.`,
-				});
-			}
-
-			if (!node.isHome && childDirectories.length > 0) {
+			if (childDirectories.length > 0) {
 				await collectNodes(childPagesDir, `${node.nodeLabel}/pages`, node.pageDirectory);
 			}
 		}
 	};
 
-	await collectNodes(sitePagesDir, sitePagesLabel);
-	if (!nodes.some(({ isHome }) => isHome)) {
-		throw new Error(`Homepage content is missing. Create ${siteContentLabel}.`);
+	const rootContentPath = getSiteSourcePaths(siteDir).content;
+	if (await fileExists(path.join(getSiteSourcePaths(siteDir).root, 'category.yaml'))) {
+		report(new Error(`${siteDirLabel}/root/category.yaml is invalid. The site root must be a page with content.md.`));
 	}
+	if (await fileExists(rootContentPath)) {
+		nodes.push({
+			...parsePageDirectoryPath(homePageDirectory),
+			kind: 'page', isHome: true, nodeDir: getSiteSourcePaths(siteDir).root, nodeLabel: `${siteDirLabel}/root`,
+			contentPath: rootContentPath, contentLabel: siteContentLabel,
+			imagesDir: getSiteSourcePaths(siteDir).images, imagesLabel: `${siteDirLabel}/root/images`,
+		});
+	} else {
+		report(new Error(`Homepage content is missing. Create ${siteContentLabel}.`));
+	}
+	await collectNodes(sitePagesDir, sitePagesLabel);
 
 	return {
 		categories: nodes.filter(({ kind }) => kind === 'category'),
 		contentFiles: nodes.filter(({ kind }) => kind === 'page'),
 		nodes,
+		...(tolerant ? { problems } : {}),
 		warnings,
 	};
 };

package/scripts/lib/site-upgrade.mjs

@@ -0,0 +1,30 @@
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { readThemePackage } from './theme-packages.mjs';
+import { getSiteSourcePaths } from './site-conventions.mjs';
+
+const inspect = (filename) => lstat(filename).catch((error) => {
+	if (error.code === 'ENOENT') return null;
+	throw error;
+});
+
+// Keep the existing command without claiming the former layout is current.
+// Our maintained sites are converted directly; no general converter is needed.
+export const planSiteUpgrade = async (siteRoot) => {
+	siteRoot = path.resolve(siteRoot);
+	const source = getSiteSourcePaths(siteRoot);
+	if (!(await inspect(siteRoot))?.isDirectory()) throw new Error(`${siteRoot} must be a regular directory, not a symbolic link.`);
+	for (const name of ['content.md', 'theme.yaml', 'images', 'pages', 'routes', 'config.yaml', 'page-theme.yaml', 'sitewide-content.yaml', 'site-config/site-theme.yaml', 'root/theme.yaml']) {
+		if (await inspect(path.join(siteRoot, name))) {
+			throw new Error(`This site uses former source locations (${name}). Automatic conversion to root/ is not provided. Stop the development server and back up the site. Keep site-config/ and public/ at the site level; put the homepage content.md, images/ and pages/ in root/. Put the required tree-theme.yaml with an explicit preset in root/; optional page-theme.yaml affects one page only. Rename descendant theme.yaml to tree-theme.yaml to preserve inherited overrides. For older formats, follow the source-layout reference before moving files. Update relative source/schema links, then run norna check and norna build. No files changed.`);
+		}
+	}
+	for (const directory of [source.root, path.join(siteRoot, 'site-config')]) {
+		if (!(await inspect(directory))?.isDirectory()) throw new Error(`${directory} must be a regular directory, not a symbolic link.`);
+	}
+	for (const filename of [source.content, path.join(siteRoot, 'site-config', 'settings.yaml'), source.theme]) {
+		if (!(await inspect(filename))?.isFile()) throw new Error(`${filename} is required and must be a regular file.`);
+	}
+	await readThemePackage({ siteRoot, filename: source.theme });
+	return { siteRoot, moves: [] };
+};

package/scripts/lib/source-files.mjs

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { pageDirectoryPattern, parsePageDirectoryPath } from './page-model.mjs';
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import { configSchema, rootThemeSchema, pageThemeSchema, siteSchema, sitewideSchema, themeVisualSchema } from './schema-definitions.mjs';
+
+// Also published in schemas/manifest.json for synchronous editor discovery.
+export const sourceFileDefinitions = [
+	{ name: 'settings.yaml', location: 'site-config', schemaKind: 'config', required: true, input: 'url', description: 'Required public URL and technical site settings.' },
+	{ name: 'shared-content.yaml', location: 'site-config', schemaKind: 'sitewideContent', text: 'banners: []\n', description: 'Shared notices and footer content for the complete site.', removalEffect: 'Shared notices, authored footer content and logo display settings in this file will be removed from the whole site.' },
+	{ name: 'content.md', location: 'page', schemaKind: 'contentFrontmatter', required: true, input: 'title', description: 'Required page content.' },
+	{ name: 'tree-theme.yaml', location: 'page', schemaKind: 'theme', rootSchemaKind: 'rootTheme', required: 'root', rootText: 'preset: documentation\n', text: '# Modify inherited settings. Add preset only to replace the complete base.\n{}\n', description: 'Visual settings for this page and its descendants. Without preset, modifies inherited values; preset selects a new base. Required on the root page.', removalEffect: 'This branch resumes the ancestor tree theme. Overrides on descendants remain; a descendant preset starts an independent base.' },
+	{ name: 'page-theme.yaml', location: 'page', schemaKind: 'pageTheme', text: '# Modify this page only. Add preset only to replace the complete base.\n{}\n', description: 'Visual settings for this page only. Without preset, modifies its tree theme; preset selects a new base. Descendants keep their tree theme.', removalEffect: 'This page will use its selected tree theme again. Other pages are unchanged.' },
+];
+export const sourcePageDirectoryPattern = pageDirectoryPattern.source.replace('^', '^(?!000-)');
+const schemas = { config: configSchema, contentFrontmatter: siteSchema, sitewideContent: sitewideSchema, theme: themeVisualSchema, rootTheme: rootThemeSchema, pageTheme: pageThemeSchema };
+
+export const getSourcePageLocation = (siteRoot, directory) => {
+	const relative = path.relative(getSiteSourcePaths(siteRoot).root, directory);
+	if (!relative) return { isHome: true, ...parsePageDirectoryPath('.') };
+	if (!relative.startsWith(`pages${path.sep}`)) return null;
+	try { return { ...parsePageDirectoryPath(relative.slice(6).split(path.sep).join('/')), isHome: false }; }
+	catch { return null; }
+};
+
+export const getSourceFileDefinition = (siteRoot, filename) => {
+	const relative = path.relative(siteRoot, filename).split(path.sep).join('/');
+	const location = getSourcePageLocation(siteRoot, path.dirname(filename));
+	const definition = sourceFileDefinitions.find((entry) => entry.location === 'page'
+		? location && path.basename(filename) === entry.name : relative === `${entry.location}/${entry.name}`);
+	if (!definition) return null;
+	const schemaKind = location?.isHome && definition.rootSchemaKind ? definition.rootSchemaKind : definition.schemaKind;
+	return { ...definition, schemaKind, text: location?.isHome && definition.rootText ? definition.rootText : definition.text, schema: schemaKind === 'contentFrontmatter' ? undefined : schemas[schemaKind],
+		required: definition.required === true || definition.required === 'root' && location?.isHome === true };
+};