@janga/norna 0.7.27 → 0.7.29

package/scripts/lib/site-link-graph.mjs

@@ -1,4 +1,6 @@
-import { readdir, readFile } from 'node:fs/promises';
+import { publicFilePublication } from './publication-paths.mjs';
+import { getSiteAttachments, resolveAttachment, parseLocalAttachmentTarget, attachmentOutputIssues } from './page-attachments.mjs';
+import { readdir, readFile, lstat } from 'node:fs/promises';
 import path from 'node:path';
 import {
 	createPageAliasModel,
@@ -11,6 +13,7 @@ import {
 	toPosixPath,
 } from './site-content.mjs';
 import {
+	siteDir as defaultSiteDir,
 	sitePagesLabel,
 	sitePublicDir,
 	sitePublicLabel,
@@ -18,11 +21,15 @@ import {
 import { getSiteNodePathname } from './site-page-urls.mjs';
 import { getSiteStructure } from './site-structure.mjs';
 import { createCategoryDestinationModel } from './category-destinations.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+import { configSchema } from './schema-definitions.mjs';
 
 const internalUrlOrigin = 'https://norna.invalid';
 const externalSchemePattern = /^[a-z][a-z0-9+.-]*:/i;
 
-const readPublicFiles = async (directory, relativeDirectory = '') => {
+const readPublicFiles = async (directory, settings = {}, relativeDirectory = '') => {
+	const info = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+	if (info && (!info.isDirectory() || info.isSymbolicLink())) throw new Error(`${directory} must be a regular public directory.`);
 	const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
 		if (error?.code === 'ENOENT') return [];
 		throw error;
@@ -30,19 +37,22 @@ const readPublicFiles = async (directory, relativeDirectory = '') => {
 	const files = [];
 
 	for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name, 'en'))) {
+		if (entry.name === '.DS_Store' || entry.name.startsWith('._')) continue;
 		const relativePath = relativeDirectory
 			? path.join(relativeDirectory, entry.name)
 			: entry.name;
 		const entryPath = path.join(directory, entry.name);
 		if (entry.isDirectory()) {
-			files.push(...await readPublicFiles(entryPath, relativePath));
+			publicFilePublication(toPosixPath(relativePath), settings, { directory: true });
+			files.push(...await readPublicFiles(entryPath, settings, relativePath));
 		} else if (entry.isFile()) {
 			files.push({
 				filePath: entryPath,
-				label: `${sitePublicLabel}/${toPosixPath(relativePath)}`,
-				pathname: `/${toPosixPath(relativePath)}`,
+				label: entryPath,
+				relativePath: toPosixPath(relativePath),
+				...publicFilePublication(toPosixPath(relativePath), settings),
 			});
-		}
+		} else throw new Error(`${entryPath} must be a regular public file. Symbolic links are not supported.`);
 	}
 
 	return files;
@@ -68,32 +78,47 @@ const getPageLookupPathname = (pathname) => {
 
 const isExternalTarget = (target) => target.startsWith('//') || externalSchemePattern.test(target);
 
-export const resolveInternalTarget = (target, sourcePathname) => {
-	if (isExternalTarget(target)) return { kind: 'external' };
+export const resolveInternalTarget = (target, sourcePathname, siteUrl) => {
+	const absolute = isExternalTarget(target);
+	if (absolute && (!siteUrl || !/^(?:https?:)?\/\//i.test(target))) return { kind: 'external' };
 
 	let url;
+	let siteBase;
 	try {
-		url = new URL(target, `${internalUrlOrigin}${sourcePathname}`);
+		siteBase = absolute ? new URL(siteUrl) : null;
+		url = new URL(target, siteBase ?? `${internalUrlOrigin}${sourcePathname}`);
 	} catch {
+		if (absolute) return { kind: 'external' };
 		return {
 			kind: 'invalid',
 			reason: 'The target is not a valid relative or site-relative URL.',
 		};
 	}
 
-	if (url.origin !== internalUrlOrigin) return { kind: 'external' };
+	if (url.origin !== (siteBase?.origin ?? internalUrlOrigin) || url.username || url.password) return { kind: 'external' };
 
 	try {
-		const pathname = decodePathname(url.pathname);
+		let pathname = decodePathname(url.pathname);
+		let absolutePrefix;
+		if (siteBase) {
+			const encodedBase = siteBase.pathname.replace(/\/?$/, '/');
+			const base = decodePathname(encodedBase);
+			if (pathname === base.slice(0, -1)) pathname = '/';
+			else if (pathname.startsWith(base)) pathname = '/' + pathname.slice(base.length);
+			else return { kind: 'external' };
+			absolutePrefix = (target.startsWith('//') ? `//${url.host}` : url.origin) + encodedBase.slice(0, -1);
+		}
 		const fragment = url.hash.length > 1 ? decodeFragment(url.hash.slice(1)) : '';
 		return {
 			kind: 'internal',
+			...(absolutePrefix ? { absolutePrefix } : {}),
 			fragment,
 			pageLookupPathname: getPageLookupPathname(pathname),
 			pathname,
 			query: url.search,
 		};
 	} catch (error) {
+		if (absolute) return { kind: 'external' };
 		return {
 			kind: 'invalid',
 			reason: error instanceof Error ? error.message : String(error),
@@ -146,9 +171,11 @@ const looksLikePublicFile = (pathname) => {
 };
 
 export const createSiteLinkGraph = ({
+	siteUrl,
 	siteStructure,
 	pageDocuments,
 	publicFiles = [],
+	attachments = { files: [], diagnostics: [] },
 	generatedRoutes,
 }) => {
 	const activeGeneratedRoutes = generatedRoutes ?? generatedSiteRoutes;
@@ -193,15 +220,28 @@ export const createSiteLinkGraph = ({
 
 	const references = [];
 	const referencesByTarget = new Map();
-	const diagnostics = [...aliasModel.diagnostics, ...categoryModel.diagnostics];
+	const diagnostics = [...aliasModel.diagnostics, ...categoryModel.diagnostics, ...attachments.diagnostics,
+		...attachmentOutputIssues({ files: attachments.files, pages, publicFiles, generatedRoutes: activeGeneratedRoutes })];
 
 	for (const page of pages) {
 		for (const sourceReference of page.document.links) {
-			const target = resolveInternalTarget(sourceReference.target, page.pathname);
+			const target = resolveInternalTarget(sourceReference.target, page.pathname, siteUrl);
 			if (target.kind === 'external') continue;
+			const attachment = target.kind === 'internal'
+				? resolveAttachment(sourceReference.target, page.pathname, attachments.files, target.pathname) : null;
+			// One origin/base path may also host independently built sites. Only
+			// adopt absolute URLs whose destination this source tree actually owns.
+			if (target.absolutePrefix && !attachment
+				&& !pagesByPathname.has(target.pageLookupPathname)
+				&& !aliasModel.aliasesByPathname.has(target.pageLookupPathname)
+				&& !publicFilesByPathname.has(target.pathname)
+				&& !categoriesByPathname.has(target.pageLookupPathname)
+				&& !generatedRoutesByPathname.has(target.pathname)
+				&& !generatedRoutesByPathname.has(target.pageLookupPathname)) continue;
 
 			const reference = {
 				...sourceReference,
+				sourceTarget: sourceReference.target,
 				sourceContentFile: page.contentFile,
 				sourcePage: page,
 				target,
@@ -222,6 +262,23 @@ export const createSiteLinkGraph = ({
 			if (!referencesByTarget.has(targetKey)) referencesByTarget.set(targetKey, []);
 			referencesByTarget.get(targetKey).push(reference);
 
+			const localAttachment = parseLocalAttachmentTarget(sourceReference.target);
+			if (attachment) {
+				const ambiguous = localAttachment?.prefix === '' && (publicFilesByPathname.has(target.pathname) || pagesByPathname.has(target.pageLookupPathname) || aliasModel.aliasesByPathname.has(target.pageLookupPathname));
+				if (ambiguous) {
+					reference.resolution = { kind: 'ambiguous-attachment' };
+					diagnostics.push(createIssue(reference, 'ambiguous-attachment', `Link "${sourceReference.target}" could identify a page/public file or a local attachment.`, `Use ${attachment.pathname} for the attachment or an explicit site-relative page/public link.`));
+				} else reference.resolution = { kind: 'attachment', file: attachment, pathname: attachment.pathname };
+				continue;
+			}
+
+			if (localAttachment?.prefix) {
+				const expectedPath = path.join(path.dirname(page.contentFile.contentPath), 'downloads', localAttachment.filename);
+				reference.resolution = { kind: 'missing-attachment', pathname: target.pathname };
+				diagnostics.push(createIssue(reference, 'missing-attachment', `Attachment "${sourceReference.target}" was not found at ${toPosixPath(expectedPath)}.`, 'Add the file to this page’s downloads/ folder or correct the link.'));
+				continue;
+			}
+
 			const targetPage = target.pageLookupPathname
 				? pagesByPathname.get(target.pageLookupPathname)
 				: null;
@@ -304,13 +361,19 @@ export const createSiteLinkGraph = ({
 				continue;
 			}
 
+			if (target.pathname.startsWith('/_norna/downloads/') && !target.pathname.endsWith('/')) {
+				reference.resolution = { kind: 'missing-attachment', pathname: target.pathname };
+				diagnostics.push(createIssue(reference, 'missing-attachment', `Attachment "${sourceReference.target}" does not exist.`, 'Add the file to its owning page’s downloads/ or correct the link.'));
+				continue;
+			}
+
 			if (looksLikePublicFile(target.pathname)) {
 				reference.resolution = { kind: 'missing-public-file', pathname: target.pathname };
 				diagnostics.push(createIssue(
 					reference,
 					'missing-public-file',
-					`Internal link "${sourceReference.target}" on line ${sourceReference.line} points to public file "${target.pathname}", but no matching file exists under ${sitePublicLabel}/.`,
-					`Add the file under ${sitePublicLabel}/ with the same relative path, or correct the link.`,
+					`Internal link "${sourceReference.target}" on line ${sourceReference.line} points to public file "${target.pathname}", but no matching file exists under ${sitePublicLabel}/ or the owning page’s downloads/.`,
+					'Use the published address of an allowed public image or technical file, or link to a page-owned attachment.',
 				));
 				continue;
 			}
@@ -327,6 +390,8 @@ export const createSiteLinkGraph = ({
 	}
 
 	return {
+		siteUrl,
+		attachments,
 		categoryModel,
 		aliasModel,
 		aliases: aliasModel.aliases,
@@ -342,7 +407,10 @@ export const createSiteLinkGraph = ({
 };
 
 export const getSiteLinkGraph = async (options = {}) => {
-	const siteStructure = options.siteStructure ?? await getSiteStructure();
+	const siteRoot = options.siteRoot ?? defaultSiteDir;
+	const siteStructure = options.siteStructure ?? await getSiteStructure({ siteRoot });
+	const settingsPath = path.join(siteRoot, 'site-config/settings.yaml');
+	const settings = parseYamlConfig(await readFile(settingsPath, 'utf8'), settingsPath, { schema: configSchema });
 	const [pageDocuments, publicFiles] = await Promise.all([
 		Promise.all(siteStructure.contentFiles.map(async (contentFile) => {
 			const source = await readFile(contentFile.contentPath, 'utf8');
@@ -353,15 +421,17 @@ export const getSiteLinkGraph = async (options = {}) => {
 				document: await parsePageMarkdownSource(source, { label: contentFile.contentLabel }),
 			};
 		})),
-		readPublicFiles(options.publicDir ?? sitePublicDir),
+		readPublicFiles(options.publicDir ?? path.join(siteRoot, 'public'), settings),
 	]);
 
 	return createSiteLinkGraph({
+		siteUrl: settings.url,
 		pageDocuments,
 		publicFiles,
 		siteStructure,
+		attachments: await getSiteAttachments(siteStructure),
 		generatedRoutes: options.generatedRoutes,
 	});
 };
 
-export const getSitePublicFiles = async (publicDir = sitePublicDir) => readPublicFiles(publicDir);
+export const getSitePublicFiles = async (publicDir = sitePublicDir, settings = {}) => readPublicFiles(publicDir, settings);

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,182 @@
+import { comparePageOrder, parsePageOrder, planPageOrder, assertRenumberingAllowed } from './page-order.mjs';
+import { pageOrderFileChanges } from './page-order-source.mjs';
+import { writeFileAtomically } from './page-move-apply.mjs';
+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';
+import { publicationIssues } from './publication-paths.mjs';
+
+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;
+};
+
+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(), placement = null, targetPath = null,
+}) => {
+	const request = { siteRoot, kind, title, slug, order, parentPath, invocationDirectory, metadata, placement, targetPath };
+	if (placement !== null && !['before', 'after', 'first', 'last'].includes(placement)) throw new Error('Choose before, after, first or last.');
+	if (placement !== null && order !== null) throw new Error('Do not combine --order with a placement selector.');
+	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(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 });
+	let relativeTarget = null;
+	if (placement === 'before' || placement === 'after') {
+		relativeTarget = structure.nodes.find(node => node.contentPath === targetPath || `/${node.pagePath}/` === targetPath);
+		if (!relativeTarget || relativeTarget.isHome) throw new Error('Choose an existing sibling page for before/after placement.');
+		parentPath = relativeTarget.parentPagePath ? `/${relativeTarget.parentPagePath}/` : '/';
+	}
+	const parent = await resolveParent({ nodes: structure.nodes, parent: parentPath, siteRoot, invocationDirectory });
+	const siblings = structure.nodes.filter((node) => !node.isHome && node.parentPagePath === (parent.pagePath || null)).sort(comparePageOrder);
+	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 dirty = [...sources.keys()].filter(filename => filename === path.join(siteRoot, 'site-config/settings.yaml') || siblings.some(node => node.contentPath === filename));
+	if (dirty.length) throw new Error(`Save or undo these unsaved files before choosing page placement:\n${dirty.join('\n')}`);
+	const index = placement === 'first' ? 0 : relativeTarget ? siblings.indexOf(relativeTarget) + (placement === 'after' ? 1 : 0) : siblings.length;
+	const insertion = order === null ? planPageOrder(siblings, index) : { order: parsePageOrder(Number(order), '--order'), orderChanges: [] };
+	order = insertion.order;
+	const orderChanges = await pageOrderFileChanges(insertion.orderChanges);
+	const directoryName = 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 }));
+	}
+	const publicationErrors = publicationIssues({ pages: [...state.graph.pages,
+		{ pathname: address, contentLabel: destination, aliases: metadata?.page?.aliases ?? [] }],
+		publicFiles: state.publicFiles, attachments: state.graph.attachments.files, generatedRoutes: state.generatedRoutes });
+	if (publicationErrors.length) throw new Error(publicationErrors.map(({ message }) => message).join('\n'));
+	metadata = { ...metadata, navigation: { ...metadata?.navigation, order } };
+	const fingerprint = JSON.stringify([destination, title, metadata, order, orderChanges, state.settings,
+		state.graph.pages.map(page => [page.contentFile.contentPath, page.document.fullSource]), state.publicFiles.map(file => file.filePath)]);
+	return { request, fingerprint, orderChanges, 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(), allowRenumber = false, writeSource = writeFileAtomically } = {}) => {
+	// Revalidate after the author has inspected the preview. Never change its placement.
+	const current = await planSiteNodeCreation({ ...(plan.request ?? plan), sources });
+	if (current.destination !== plan.destination || current.fingerprint !== plan.fingerprint) throw new Error('The site changed. Preview the new location before creating the node.');
+	assertRenumberingAllowed(current.orderChanges, allowRenumber);
+	const written = [];
+	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 });
+		for (const change of current.orderChanges) {
+			await writeSource(change.originalPath, change.updatedSource, change.mode);
+			written.push(change);
+		}
+		return { ...current, sourcePath: filename, renumberedPages: current.orderChanges.length };
+	} catch (error) {
+		const restoreErrors = [];
+		for (const change of written.reverse()) {
+			try { await writeFileAtomically(change.originalPath, change.originalSource, change.mode); }
+			catch (failure) { restoreErrors.push(`${change.originalPath}: ${failure.message}`); }
+		}
+		// 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(() => {});
+		if (restoreErrors.length) throw new Error(`${error.message}\nRestoration was incomplete:\n${restoreErrors.join('\n')}`);
+		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');
@@ -143,8 +155,8 @@ export const astroDistDir = configuredStateDirectory
 	: path.join(siteProjectRoot, 'dist');
 export const astroRootDir = siteStateDir;
 export const astroCacheDir = path.join(astroRootDir, '.astro');
-export const generatedImagesDir = path.join(astroPublicDir, 'images', 'generated');
-export const originalImagesDir = path.join(astroPublicDir, 'images', 'original');
+export const generatedImagesDir = path.join(astroPublicDir, '_norna', 'images', 'generated');
+export const originalImagesDir = path.join(astroPublicDir, '_norna', 'images', 'original');
 export const generatedImagesManifestPath = path.join(siteStateDir, 'generated-images.json');
 
 export const engineRootLabel = getPathLabel(engineRoot);

package/scripts/lib/site-source-format.mjs

@@ -0,0 +1,12 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { load } from 'js-yaml';
+
+export const assertSiteSourceFormat = async (siteRoot, readSource = filename => readFile(filename, 'utf8')) => {
+	const filename = path.join(siteRoot, 'site-config/settings.yaml');
+	const source = await readSource(filename);
+	let settings;
+	try { settings = load(source); }
+	catch (error) { throw new Error(`${filename} contains invalid YAML: ${error.reason ?? error.message}`); }
+	if (settings?.sourceFormat !== 2) throw new Error(`${filename} needs sourceFormat: 2 after converting the site: move numeric page-directory prefixes into navigation.order frontmatter and remove those prefixes. Keep this site on its previous engine until converted. No files changed.`);
+};