@janga/norna 0.7.27 → 0.7.29

package/scripts/lib/page-attachments.mjs

@@ -0,0 +1,59 @@
+import { lstat, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { getSiteNodePathname } from './site-page-urls.mjs';
+import { attachmentPublicationPath, publicationIssues } from './publication-paths.mjs';
+
+export const attachmentPathname = attachmentPublicationPath;
+export const encodeAttachmentPath = value => value.split('/').map(segment => encodeURIComponent(segment).replace(/[()']/g, char => '%' + char.charCodeAt(0).toString(16))).join('/');
+export const validateAttachmentName = name => {
+	if (typeof name !== 'string' || !name || name !== name.trim() || /[\\/\x00-\x1f\x7f<>:"|?*#%]/.test(name) || /^\.{1,2}$/.test(name) || /[. ]$/.test(name)) throw new Error('Use one filename without slashes, URL punctuation or trailing dots/spaces.');
+	return name;
+};
+
+export const readPageAttachments = async contentFile => {
+	const directory = path.join(path.dirname(contentFile.contentPath), 'downloads');
+	const info = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+	if (!info) return { files: [], diagnostics: [] };
+	const diagnostics = [], files = [];
+	const problem = message => diagnostics.push({ severity: 'error', code: 'invalid-attachment', contentFile, message, fix: 'Keep regular files directly in the page’s downloads/ folder; remove unsupported entries.' });
+	if (!info.isDirectory() || info.isSymbolicLink()) { problem(`${directory} must be a real directory.`); return { files, diagnostics }; }
+	const names = new Set();
+	for (const entry of await readdir(directory, { withFileTypes: true })) {
+		if (entry.name === '.DS_Store' || entry.name.startsWith('._')) continue;
+		const filePath = path.join(directory, entry.name);
+		try { validateAttachmentName(entry.name); } catch (error) { problem(`${filePath}: ${error.message}`); continue; }
+		if (!entry.isFile()) { problem(`${filePath}: attachment subfolders and symbolic links are not supported.`); continue; }
+		const key = entry.name.normalize('NFC').toLowerCase();
+		if (names.has(key)) problem(`${directory}: attachment filenames must be unique regardless of case or Unicode normalization.`);
+		names.add(key);
+		files.push({ filePath, filename: entry.name, contentPath: contentFile.contentPath, ownerPathname: getSiteNodePathname(contentFile), pathname: attachmentPathname(getSiteNodePathname(contentFile), entry.name) });
+	}
+	return { files, diagnostics };
+};
+export const getSiteAttachments = async siteStructure => {
+	const results = await Promise.all(siteStructure.contentFiles.map(readPageAttachments));
+	return { files: results.flatMap(result => result.files), diagnostics: results.flatMap(result => result.diagnostics) };
+};
+
+// Explicit downloads paths identify page-owned files. Bare names retain the
+// existing shorthand rules, including ambiguity with page/public links.
+export const parseLocalAttachmentTarget = target => {
+	const raw = target.split(/[?#]/, 1)[0];
+	if (!raw || /^[a-z][a-z\d+.-]*:/i.test(raw)) return null;
+	const prefix = raw.match(/^(?:\.\/)?downloads\//)?.[0] ?? '';
+	try {
+		const filename = decodeURIComponent(raw.slice(prefix.length));
+		validateAttachmentName(filename);
+		return { filename, prefix };
+	} catch { return null; }
+};
+export const localAttachmentName = target => parseLocalAttachmentTarget(target)?.filename ?? null;
+export const resolveAttachment = (target, sourcePathname, files, resolvedPathname) => {
+	const name = localAttachmentName(target);
+	return name ? files.find(file => file.ownerPathname === sourcePathname && file.filename === name)
+		: files.find(file => file.pathname === resolvedPathname);
+};
+export const attachmentHref = (file, target) => encodeAttachmentPath(file.pathname) + (target.match(/[?#].*$/)?.[0] ?? '');
+
+export const attachmentOutputIssues = ({ files, pages, publicFiles, generatedRoutes }) =>
+	publicationIssues({ attachments: files, pages, publicFiles, generatedRoutes });

package/scripts/lib/page-markdown.mjs

@@ -1,3 +1,4 @@
+import { extractMarkdownImageReferences, markdownImageDiagnostic } from './markdown-images.mjs';
 import { getCodeFenceMetadataDiagnostics } from './code-fence-metadata.mjs';
 import { parseContentTabs } from './content-tabs.mjs';
 import { getDetailsHeadingDiagnostics } from './details-headings.mjs';
@@ -11,7 +12,6 @@ import {
 } from './markdown-links.mjs';
 import {
 	extractInlineNoteDiagnostics,
-	extractMarkdownImageReferences,
 	extractNornaMarkdownBlockDiagnostics,
 	getNornaBlockImageReferences,
 	nornaBlockTypes,
@@ -191,6 +191,7 @@ const createRegion = ({
 	tableErrors,
 	tabResult,
 	pageNotes,
+	imageReferences,
 }) => {
 	const endOffset = nextHeading?.index ?? source.length;
 	const markdown = source.slice(heading.index, endOffset).trimEnd();
@@ -201,10 +202,7 @@ const createRegion = ({
 	});
 	const inRegion = (offset) => offset >= heading.index && offset < endOffset;
 	const fieldNoteErrors = getStructuredSidenoteDiagnostics(blockResult.blocks, { label, regionOffset: heading.index });
-	const markdownImages = extractMarkdownImageReferences(markdown).map((reference) => ({
-		...reference,
-		line: regionLineOffset + reference.line,
-	}));
+	const markdownImages = imageReferences.filter((reference) => inRegion(reference.range.start));
 	const regionHeadings = headings.filter((candidate) => (
 		candidate.index >= heading.index
 		&& candidate.index < endOffset
@@ -226,7 +224,7 @@ const createRegion = ({
 		kind: heading.depth === 1 ? 'page-intro' : 'section',
 		bodyLine: heading.line,
 		line: lineOffset + heading.line,
-		managedImages: getNornaBlockImageReferences(blockResult.blocks),
+		managedImages: [...getNornaBlockImageReferences(blockResult.blocks), ...markdownImages.filter((reference) => reference.kind === 'managed')],
 		markdown,
 		markdownImages,
 		notes: pageNotes.notes.filter((note) => inRegion(note.referenceOffset)),
@@ -246,6 +244,7 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 	const tabResult = parseContentTabs(source, { label, lineOffset });
 	const pageNotes = extractInlineNoteDiagnostics(source, { label, lineOffset, tabResult });
 	const { headings, tree } = await getMarkdownHeadings(tabResult.maskedSource);
+	const imageReferences = extractMarkdownImageReferences({ source, tree, lineOffset });
 	const detailsDiagnostics = getDetailsHeadingDiagnostics(tree, { source: tabResult.maskedSource, label, lineOffset });
 	const calloutErrors = getSemanticCalloutDiagnostics(tree, { label, lineOffset });
 	const codeFenceErrors = getCodeFenceMetadataDiagnostics(tree, {
@@ -271,6 +270,7 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 		pageNotes,
 		tableErrors,
 		tabResult,
+		imageReferences,
 	}));
 	const headingIssues = getHeadingIdentifierIssues(headings);
 	const headingDiagnostics = getHeadingDiagnostics(headings, lineOffset);
@@ -346,6 +346,7 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 	return {
 		blocks,
 		diagnostics: [
+			...imageReferences.filter((reference) => reference.kind === 'invalid').map((reference) => markdownImageDiagnostic(reference, label)),
 			...detailsDiagnostics,
 			...structureDiagnostics,
 			...headingDiagnostics,
@@ -363,7 +364,7 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 		lineOffset,
 		links,
 		managedImages: regions.flatMap((region) => region.managedImages),
-		markdownImages: regions.flatMap((region) => region.markdownImages),
+		markdownImages: imageReferences,
 		navigationHeadings,
 		notes: regions.flatMap((region) => region.notes),
 		noteDiagnostics,
@@ -395,8 +396,11 @@ export const parsePageMarkdownSource = async (source, options = {}) => {
 		};
 	};
 
+	const mapImage = (reference) => reference.blockType === 'markdown-image' ? { ...reference, range: toOriginalRange(reference.range), targetRange: toOriginalRange(reference.targetRange) } : reference;
 	return {
 		...model,
+		markdownImages: model.markdownImages.map(mapImage),
+		managedImages: model.managedImages.map(mapImage),
 		bodyOffset: normalization.originalOffsets[split.bodyOffset] ?? split.bodyOffset,
 		frontmatter: split.frontmatter,
 		frontmatterUnclosed: split.frontmatterUnclosed,

package/scripts/lib/page-model.mjs

@@ -1,37 +1,32 @@
 import { homePageDirectory } from './site-conventions.mjs';
 
-export const pageDirectoryPattern = /^(\d{3})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+export const pageDirectoryPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 const pageEntryPathSeparator = '--';
 
 export const parsePageDirectory = (pageDirectory, label = 'page directory') => {
-	const match = pageDirectory.match(pageDirectoryPattern);
-
-	if (!match) {
-		throw new Error(
-			`Invalid ${label} "${pageDirectory}". Page directories must use the form NNN-page-id, for example 010-getting-started. Page ids may contain only lowercase letters, numbers, and single hyphens.`,
-		);
+	if (!pageDirectoryPattern.test(pageDirectory)) {
+		throw new Error(`Invalid ${label} "${pageDirectory}". Page directories must use a slug with lowercase letters, numbers, and single hyphens, for example getting-started.`);
 	}
-	if (match[1] === '000' && pageDirectory !== homePageDirectory) {
-		throw new Error(`Invalid ${label} "${pageDirectory}". The 000 prefix is reserved for ${homePageDirectory}.`);
-	}
-
-	return {
-		pageDirectory,
-		pageOrder: Number.parseInt(match[1], 10),
-		pageId: match[2],
-	};
+	return { pageDirectory, pageOrder: null, pageId: pageDirectory };
 };
 
 const normalizePageDirectoryPath = (pageDirectoryPath) => pageDirectoryPath.replaceAll('\\', '/');
 
 export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page directory path') => {
 	const normalizedPath = normalizePageDirectoryPath(pageDirectoryPath);
+	if (normalizedPath === homePageDirectory) {
+		return {
+			pageDirectory: homePageDirectory, pageDirectories: [], pageId: 'home',
+			pageIds: [], pageOrder: 0, pagePath: '',
+			parentPagePath: null, depth: 0,
+		};
+	}
 	const segments = normalizedPath.split('/').filter(Boolean);
 
 	if (!normalizedPath || normalizedPath.startsWith('/') || normalizedPath.endsWith('/') || segments.length % 2 === 0) {
 		throw new Error(
-			`Invalid ${label} "${pageDirectoryPath}". Nested pages must use the form NNN-page-id/pages/NNN-child-id.`,
+			`Invalid ${label} "${pageDirectoryPath}". Nested pages must use the form page-id/pages/child-id.`,
 		);
 	}
 
@@ -50,31 +45,18 @@ export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page director
 	}
 
 	const pageIds = pageDirectories.map(({ pageId }) => pageId);
-	const pageOrders = pageDirectories.map(({ pageOrder }) => pageOrder);
 	const currentPage = pageDirectories.at(-1);
-	const homeIndex = pageDirectories.findIndex(({ pageDirectory }) => pageDirectory === homePageDirectory);
-	if (homeIndex > 0) {
-		throw new Error(`Invalid ${label} "${pageDirectoryPath}". ${homePageDirectory} is allowed only as a top-level page.`);
-	}
-	if (homeIndex === 0 && pageDirectories.length > 1) {
-		throw new Error(
-			`Invalid ${label} "${pageDirectoryPath}". ${homePageDirectory} is the homepage and cannot contain child pages. Place the page beside it under site/pages/, or below another non-home page.`,
-		);
-	}
-	const isHome = homeIndex === 0;
-	const logicalPageIds = isHome ? [] : pageIds;
-	const logicalPageOrders = isHome ? [] : pageOrders;
 
 	return {
 		pageDirectory: normalizedPath,
 		pageDirectories: pageDirectories.map(({ pageDirectory }) => pageDirectory),
 		pageId: currentPage.pageId,
-		pageIds: logicalPageIds,
+		pageIds,
 		pageOrder: currentPage.pageOrder,
-		pageOrders: logicalPageOrders,
-		pagePath: logicalPageIds.join('/'),
-		parentPagePath: logicalPageIds.length > 1
-			? logicalPageIds.slice(0, -1).join('/')
+		pagePath: pageIds.join('/'),
+		// Navigation projects the root's children as top-level entries.
+		parentPagePath: pageIds.length > 1
+			? pageIds.slice(0, -1).join('/')
 			: null,
 		depth: pageDirectories.length,
 	};
@@ -82,10 +64,11 @@ export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page director
 
 export const encodePageDirectoryPath = (pageDirectoryPath) => {
 	const { pageDirectories } = parsePageDirectoryPath(pageDirectoryPath);
-	return pageDirectories.join(pageEntryPathSeparator);
+	return pageDirectories.length ? pageDirectories.join(pageEntryPathSeparator) : '~home';
 };
 
 export const decodePageDirectoryPath = (pageEntryPath, label = 'page entry path') => {
+	if (pageEntryPath === '~home') return homePageDirectory;
 	const pageDirectories = pageEntryPath.split(pageEntryPathSeparator);
 	if (pageDirectories.some((pageDirectory) => !pageDirectory)) {
 		throw new Error(`Invalid ${label} "${pageEntryPath}".`);

package/scripts/lib/page-move-apply.mjs

@@ -0,0 +1,119 @@
+import { assertRenumberingAllowed } from './page-order.mjs';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getSiteLinkGraph } from './site-link-graph.mjs';
+import { getSiteStructure } from './site-structure.mjs';
+
+export const writeFileAtomically = async (filePath, source, mode) => {
+	const temporaryPath = path.join(
+		path.dirname(filePath),
+		`.${path.basename(filePath)}.norna-${process.pid}-${randomUUID()}.tmp`,
+	);
+	try {
+		await writeFile(temporaryPath, source, { mode: mode & 0o777 });
+		await rename(temporaryPath, filePath);
+	} finally {
+		await rm(temporaryPath, { force: true });
+	}
+};
+
+const assertSourcesUnchanged = async (plan) => {
+	for (const file of plan.sourceFiles) {
+		const currentSource = await readFile(file.contentPath, 'utf8');
+		if (currentSource !== file.source) {
+			throw new Error([
+				`Page move stopped because ${file.contentLabel} changed after the plan was created.`,
+				'Run the command again to build a fresh plan. No file was changed.',
+			].join('\n'));
+		}
+	}
+};
+
+const assertFinalSite = async (siteRoot, generatedRoutes) => {
+	const structure = await getSiteStructure({ siteRoot });
+	const graph = await getSiteLinkGraph({ siteRoot, siteStructure: structure, publicDir: path.join(siteRoot, 'public'), generatedRoutes });
+	const errors = graph.diagnostics.filter(({ severity }) => severity === 'error');
+	if (errors.length === 0) return;
+	throw new Error([
+		'Post-move link validation failed.',
+		...errors.flatMap((diagnostic) => [
+			`- ${diagnostic.message}`,
+			...(diagnostic.fix ? [`  Fix: ${diagnostic.fix}`] : []),
+		]),
+	].join('\n'));
+};
+
+export const applyPageMovePlan = async (plan, { siteRoot, generatedRoutes, renameDirectory = rename, writeSource = writeFileAtomically, allowRenumber = false }) => {
+	assertRenumberingAllowed(plan.orderChanges ?? [], allowRenumber);
+	await assertSourcesUnchanged(plan);
+	let collectionCreated = false;
+	let directoryMoved = false;
+	let fileWritten = false;
+
+	try {
+		if (plan.mode === 'move') {
+			if (!plan.destinationCollectionExists) {
+				await mkdir(plan.destinationCollectionDirectory);
+				collectionCreated = true;
+			}
+			try {
+				await renameDirectory(plan.sourceDirectory, plan.destinationDirectory);
+				directoryMoved = true;
+			} catch (error) {
+				if (error?.code === 'EXDEV') {
+					throw new Error('Page directories must stay on one filesystem so Norna can move the complete subtree atomically.');
+				}
+				throw error;
+			}
+		}
+
+		for (const change of plan.fileChanges) {
+			await writeSource(change.finalPath, change.updatedSource, change.mode);
+			fileWritten = true;
+		}
+		await assertFinalSite(siteRoot, generatedRoutes);
+	} catch (error) {
+		const changesStarted = directoryMoved || fileWritten;
+		const rollbackErrors = [];
+		if (directoryMoved) {
+			try {
+				await renameDirectory(plan.destinationDirectory, plan.sourceDirectory);
+				directoryMoved = false;
+			} catch (rollbackError) {
+				rollbackErrors.push(`Could not restore the page directory: ${rollbackError.message}`);
+			}
+		}
+
+		for (const change of changesStarted ? plan.fileChanges : []) {
+			try {
+				const restorePath = directoryMoved && change.finalPath !== change.originalPath
+					? change.finalPath
+					: change.originalPath;
+				await writeFileAtomically(restorePath, change.originalSource, change.mode);
+			} catch (rollbackError) {
+				rollbackErrors.push(`Could not restore ${change.contentLabel}: ${rollbackError.message}`);
+			}
+		}
+
+		if (collectionCreated && !directoryMoved) {
+			try {
+				await rmdir(plan.destinationCollectionDirectory);
+			} catch (rollbackError) {
+				if (rollbackError?.code !== 'ENOENT' && rollbackError?.code !== 'ENOTEMPTY') {
+					rollbackErrors.push(`Could not remove the newly created pages directory: ${rollbackError.message}`);
+				}
+			}
+		}
+
+		throw new Error([
+			error instanceof Error ? error.message : String(error),
+			rollbackErrors.length === 0
+				? (changesStarted
+					? 'The original page directory and content files were restored.'
+					: 'No source file was changed.')
+				: 'Rollback was incomplete. Inspect these paths before running page:move again:',
+			...rollbackErrors.map((message) => `- ${message}`),
+		].join('\n'));
+	}
+};

package/scripts/lib/page-move-plan.mjs

@@ -1,3 +1,6 @@
+import { comparePageOrder, parsePageOrder, planPageOrder, describeRenumbering } from './page-order.mjs';
+import { setPageOrder } from './page-order-source.mjs';
+import { attachmentPathname, encodeAttachmentPath, localAttachmentName } from './page-attachments.mjs';
 import { access, constants, readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import {
@@ -11,6 +14,7 @@ import {
 	toPosixPath,
 } from './site-content.mjs';
 import { getSiteNodePathname } from './site-page-urls.mjs';
+import { changeYamlField } from './yaml-source-edit.mjs';
 
 const pagePathPattern = /^\/(?:[a-z0-9]+(?:-[a-z0-9]+)*\/)+$/;
 
@@ -37,15 +41,6 @@ const replaceFilePathPrefix = (filePath, fromDirectory, toDirectory) => (
 	path.join(toDirectory, path.relative(fromDirectory, filePath))
 );
 
-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 destination siblings or pass --order.');
-	}
-	return nextOrder;
-};
-
 const getTargetSuffix = (target) => {
 	const queryIndex = target.indexOf('?');
 	const fragmentIndex = target.indexOf('#');
@@ -61,12 +56,6 @@ const applyReplacements = (source, replacements) => {
 	return updated;
 };
 
-const insertBeforeTrailingBlankLines = (lines, additions) => {
-	let index = lines.length;
-	while (index > 0 && !lines[index - 1].trim()) index -= 1;
-	lines.splice(index, 0, ...additions);
-};
-
 const addPageAliasToSource = (source, alias, label) => {
 	const eol = source.includes('\r\n') ? '\r\n' : '\n';
 	const { body, frontmatter, frontmatterBody } = splitSiteFile(source, label);
@@ -88,64 +77,31 @@ const addPageAliasToSource = (source, alias, label) => {
 		};
 	}
 
-	const lines = frontmatterBody.split(/\r?\n/);
-	const pageIndex = lines.findIndex((line) => /^page:\s*(?:#.*)?$/.test(line));
-	if (data.page && pageIndex < 0) {
-		throw new Error([
-			`Cannot add ${alias} to ${label} without rewriting its flow-style page metadata.`,
-			'Use block YAML beginning with "page:" on its own line, or rerun with --no-aliases.',
-		].join('\n'));
-	}
-
-	if (pageIndex < 0) {
-		insertBeforeTrailingBlankLines(lines, [
-			'page:',
-			'  aliases:',
-			`    - ${alias}`,
-		]);
-	} else {
-		let pageEnd = lines.length;
-		for (let index = pageIndex + 1; index < lines.length; index += 1) {
-			const line = lines[index];
-			if (!line.trim() || line.trimStart().startsWith('#')) continue;
-			if (!line.startsWith(' ')) {
-				pageEnd = index;
-				break;
-			}
-		}
-
-		const aliasesIndex = lines.findIndex((line, index) => (
-			index > pageIndex
-			&& index < pageEnd
-			&& /^ {2}aliases:\s*(?:#.*)?$/.test(line)
-		));
-		if (data.page?.aliases && aliasesIndex < 0) {
-			throw new Error([
-				`Cannot add ${alias} to ${label} without rewriting its flow-style aliases list.`,
-				'Use a block list below "  aliases:", or rerun with --no-aliases.',
-			].join('\n'));
-		}
-
-		if (aliasesIndex < 0) {
-			lines.splice(pageIndex + 1, 0, '  aliases:', `    - ${alias}`);
-		} else {
-			let lastAliasIndex = -1;
-			for (let index = aliasesIndex + 1; index < pageEnd; index += 1) {
-				if (/^ {4}-\s+/.test(lines[index])) lastAliasIndex = index;
-			}
-			if (lastAliasIndex < 0) {
-				throw new Error(`Cannot find the block-list entries below "aliases:" in ${label}.`);
-			}
-			lines.splice(lastAliasIndex + 1, 0, `    - ${alias}`);
-		}
+	let yaml;
+	try {
+		yaml = changeYamlField(frontmatterBody, ['page', 'aliases'], [...(data.page?.aliases ?? []), alias], eol);
+	} catch (error) {
+		throw Object.assign(new Error(`Cannot preserve ${alias} in ${label}. ${error.message}`), { sourcePath: label });
 	}
 
 	return {
 		changed: true,
-		source: `---${eol}${lines.join(eol)}${eol}---${eol}${body}`,
+		source: `---${eol}${yaml.replace(/\r?\n$/, '')}${eol}---${eol}${body}`,
 	};
 };
 
+const removePageAliasFromSource = (source, alias, label) => {
+	const { body, frontmatter, frontmatterBody } = splitSiteFile(source, label);
+	if (!frontmatter) return source;
+	const data = parseContentFrontmatter(frontmatterBody, label);
+	if (!data.page?.aliases?.includes(alias)) return source;
+	const eol = source.includes('\r\n') ? '\r\n' : '\n';
+	const remaining = data.page.aliases.filter((entry) => entry !== alias);
+	const yaml = changeYamlField(frontmatterBody, ['page', 'aliases'], remaining.length ? remaining : undefined, eol);
+	if (!yaml.trim()) return body.replace(/^\r?\n/, '');
+	return `---${eol}${yaml.replace(/\r?\n$/, '')}${eol}---${eol}${body}`;
+};
+
 const normalizeMovePathname = (value, optionName) => {
 	if (value === '/') return { pagePath: '', pathname: '/' };
 	if (typeof value !== 'string' || !pagePathPattern.test(value)) {
@@ -239,6 +195,11 @@ const getResolvedReferenceIntent = ({
 		};
 	}
 
+	if (resolution?.kind === 'attachment') {
+		const owner = movedCurrentToNew.get(resolution.file.ownerPathname) ?? resolution.file.ownerPathname;
+		return { kind: 'attachment', lookupPathname: attachmentPathname(owner, resolution.file.filename), owner, filename: resolution.file.filename };
+	}
+
 	if (resolution?.kind === 'public-file') {
 		return { kind: 'public-file', lookupPathname: target.pathname };
 	}
@@ -297,7 +258,7 @@ const getReferenceIntent = ({
 	const sourceMapping = mappingByCurrentPathname.get(reference.sourcePage.pathname);
 	if (!sourceMapping || sourceMapping.oldPathname === sourceMapping.currentPathname) return currentIntent;
 
-	const oldTarget = resolveInternalTarget(reference.targetSource, sourceMapping.oldPathname);
+	const oldTarget = resolveInternalTarget(reference.targetSource, sourceMapping.oldPathname, graph.siteUrl);
 	const oldIntent = getTargetIntent({
 		graph,
 		movedCurrentToNew,
@@ -349,8 +310,9 @@ const createReferenceChanges = ({ graph, mappings }) => {
 
 		const sourcePathname = movedCurrentToNew.get(reference.sourcePage.pathname)
 			?? reference.sourcePage.pathname;
-		const resolvedAfterMove = resolveInternalTarget(reference.targetSource, sourcePathname);
-		const stillResolves = resolvedAfterMove.kind === 'internal'
+		const originalTarget = intent.kind === 'attachment' ? reference.sourceTarget ?? reference.targetSource : reference.targetSource;
+		const resolvedAfterMove = resolveInternalTarget(originalTarget, sourcePathname, graph.siteUrl);
+		const stillResolves = intent.kind === 'attachment' ? (localAttachmentName(originalTarget) === intent.filename && sourcePathname === intent.owner || resolvedAfterMove.pathname === intent.lookupPathname) : resolvedAfterMove.kind === 'internal'
 			&& (intent.kind === 'public-file'
 				? resolvedAfterMove.pathname === intent.lookupPathname
 				: resolvedAfterMove.pageLookupPathname === intent.lookupPathname);
@@ -362,7 +324,7 @@ const createReferenceChanges = ({ graph, mappings }) => {
 			);
 		}
 
-		const value = `${intent.lookupPathname}${getTargetSuffix(reference.targetSource)}`;
+		const value = `${reference.target.absolutePrefix ?? ''}${intent.kind === 'attachment' ? encodeAttachmentPath(intent.lookupPathname) : intent.lookupPathname}${getTargetSuffix(reference.targetSource)}`;
 		const key = `${reference.sourceContentFile.contentPath}:${reference.targetRange.start}:${reference.targetRange.end}`;
 		const existing = changeKeys.get(key);
 		if (existing && existing.to !== value) {
@@ -396,7 +358,9 @@ const formatGraphDiagnostics = (diagnostics) => diagnostics.flatMap((diagnostic)
 export const createPageMovePlan = async ({
 	from,
 	graph,
+	generatedRoutes,
 	order = null,
+	siblingOrderChanges = [],
 	preserveAliases = true,
 	publicFiles,
 	sitePagesDir,
@@ -442,6 +406,7 @@ export const createPageMovePlan = async ({
 	let destinationCollectionDirectory = null;
 	let destinationCollectionExists = true;
 	let virtualNodes = siteStructure.nodes;
+	let orderChanges = siblingOrderChanges;
 
 	if (mode === 'move') {
 		const destinationParentPath = getParentPagePath(destination.pagePath);
@@ -456,22 +421,23 @@ export const createPageMovePlan = async ({
 		}
 
 		const destinationSiblings = siteStructure.nodes.filter((node) => (
-			node.parentPagePath === destinationParentPath
+			!node.isHome && node.parentPagePath === destinationParentPath
 			&& !isPathInSubtree(node.pagePath, source.pagePath)
 		));
 		const sameParent = sourceNode.parentPagePath === destinationParentPath;
-		destinationOrder = order ?? (sameParent ? sourceNode.pageOrder : getNextOrder(destinationSiblings));
-		if (destinationSiblings.some((node) => node.pageOrder === destinationOrder)) {
-			throw new Error(`Destination order ${String(destinationOrder).padStart(3, '0')} is already used below ${destinationParentPath ? `/${destinationParentPath}/` : '/'}.`);
+		if (order !== null) destinationOrder = parsePageOrder(order, '--order');
+		else if (!sameParent) {
+			const insertion = planPageOrder(destinationSiblings.sort(comparePageOrder), destinationSiblings.length);
+			destinationOrder = insertion.order;
+			orderChanges = insertion.orderChanges;
 		}
-
 		const destinationSlug = destination.pagePath.split('/').at(-1);
 		destinationCollectionDirectory = destinationParent
 			? path.join(destinationParent.nodeDir, 'pages')
 			: sitePagesDir;
 		destinationDirectory = path.join(
 			destinationCollectionDirectory,
-			`${String(destinationOrder).padStart(3, '0')}-${destinationSlug}`,
+			destinationSlug,
 		);
 		if (await exists(destinationDirectory)) {
 			throw new Error(`Destination directory ${destinationDirectory} already exists.`);
@@ -559,6 +525,9 @@ export const createPageMovePlan = async ({
 		})));
 
 		const mapping = mappingByContentPath.get(contentPath);
+		if (mapping && page.aliases.includes(mapping.newPathname)) {
+			updatedSource = removePageAliasFromSource(updatedSource, mapping.newPathname, page.contentFile.contentLabel);
+		}
 		if (mapping && preserveAliases) {
 			const aliasResult = addPageAliasToSource(updatedSource, mapping.oldPathname, page.contentFile.contentLabel);
 			updatedSource = aliasResult.source;
@@ -570,6 +539,11 @@ export const createPageMovePlan = async ({
 			}
 		}
 
+		const siblingChange = orderChanges.find(change => change.node.contentPath === contentPath);
+		if (siblingChange) updatedSource = setPageOrder(updatedSource, siblingChange.newOrder, contentPath);
+		if (mode === 'move' && contentPath === activeRoot.contentPath && destinationOrder !== activeRoot.pageOrder) {
+			updatedSource = setPageOrder(updatedSource, destinationOrder, contentPath);
+		}
 		updatedSources.set(contentPath, updatedSource);
 		if (updatedSource !== page.document.fullSource) {
 			const fileStat = await stat(contentPath);
@@ -610,15 +584,24 @@ export const createPageMovePlan = async ({
 		nodes: virtualNodes,
 		warnings: siteStructure.warnings,
 	};
+	const virtualAttachments = { diagnostics: graph.attachments?.diagnostics ?? [], files: (graph.attachments?.files ?? []).map(file => {
+		const mapping = mappings.find(entry => entry.currentPathname === file.ownerPathname);
+		if (!mapping) return file;
+		return { ...file, ownerPathname: mapping.newPathname, pathname: attachmentPathname(mapping.newPathname, file.filename) };
+	}) };
 	const virtualGraph = createSiteLinkGraph({
+		siteUrl: graph.siteUrl,
+		attachments: virtualAttachments,
 		pageDocuments: virtualPageDocuments,
 		publicFiles,
 		siteStructure: virtualStructure,
+		generatedRoutes,
 	});
-	if (virtualGraph.diagnostics.length > 0) {
+	const errors = virtualGraph.diagnostics.filter(({ severity }) => severity === 'error');
+	if (errors.length > 0) {
 		throw new Error([
 			'Page move preflight failed. No file was changed.',
-			...formatGraphDiagnostics(virtualGraph.diagnostics),
+			...formatGraphDiagnostics(errors),
 		].join('\n'));
 	}
 
@@ -634,6 +617,8 @@ export const createPageMovePlan = async ({
 
 	return {
 		aliasChanges,
+		generatedRoutes,
+		orderChanges,
 		destinationCollectionDirectory,
 		destinationCollectionExists,
 		destinationDirectory,
@@ -668,6 +653,7 @@ export const formatPageMovePlan = (plan, displayPath) => {
 	for (const change of plan.linkChanges) {
 		lines.push(`- ${change.contentLabel} line ${change.line}: ${change.from} -> ${change.to}`);
 	}
+	if (plan.orderChanges?.length) lines.push('', describeRenumbering(plan.orderChanges, displayPath));
 	lines.push('', 'Aliases:');
 	if (!plan.preserveAliases) lines.push('- skipped by --no-aliases');
 	else if (plan.aliasChanges.length === 0) lines.push('- none needed');

package/scripts/lib/page-order-source.mjs

@@ -0,0 +1,22 @@
+import { readFile, stat } from 'node:fs/promises';
+import { splitSiteFile } from './site-content.mjs';
+import { changeYamlField } from './yaml-source-edit.mjs';
+import { parsePageOrder } from './page-order.mjs';
+
+export const setPageOrder = (source, order, label) => {
+	parsePageOrder(order);
+	const eol = source.includes('\r\n') ? '\r\n' : '\n';
+	const { frontmatter, frontmatterBody, body } = splitSiteFile(source, label);
+	try {
+		const yaml = changeYamlField(frontmatterBody, ['navigation', 'order'], order ?? undefined, eol);
+		return frontmatter ? `---${eol}${yaml.replace(/\r?\n$/, '')}${eol}---${eol}${body}`
+			: `---${eol}${yaml}---${eol}${eol}${source}`;
+	} catch (error) { throw Object.assign(new Error(`Cannot set page order in ${label}. ${error.message}`), { sourcePath: label }); }
+};
+
+export const pageOrderFileChanges = async changes => Promise.all(changes.map(async ({ node, oldOrder, newOrder }) => {
+	const originalSource = await readFile(node.contentPath, 'utf8');
+	return { contentPath: node.contentPath, contentLabel: node.contentLabel, oldOrder, newOrder,
+		originalPath: node.contentPath, finalPath: node.contentPath, originalSource,
+		updatedSource: setPageOrder(originalSource, newOrder, node.contentPath), mode: (await stat(node.contentPath)).mode };
+}));