@janga/norna 0.7.27 → 0.7.28

package/scripts/lib/editor-page-placement.mjs

@@ -0,0 +1,172 @@
+import { randomUUID } from 'node:crypto';
+import { rename } from 'node:fs/promises';
+import path from 'node:path';
+import { checkedPath, snapshot } from './editor-site-files.mjs';
+import { readEditorLinkState } from './editor-site-links.mjs';
+import { createPageMovePlan } from './page-move-plan.mjs';
+import { applyPageMovePlan } from './page-move-apply.mjs';
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import { getSiteStructure } from './site-structure.mjs';
+
+export const sitePagePlacementApiVersion = 1;
+
+const urlFor = (node) => node.isHome ? '/' : `/${node.pagePath}/`;
+const childOf = (node, parent) => node.parentPagePath === (parent.pagePath || null);
+const inBranch = (node, ancestor) => node.pagePath === ancestor.pagePath || node.pagePath.startsWith(`${ancestor.pagePath}/`);
+const pad = (order) => String(order).padStart(3, '0');
+const renamedDirectory = (node, order) => path.join(path.dirname(node.nodeDir), `${pad(order)}-${node.pageId}`);
+
+const explainDestination = (owner, address) => {
+	if (owner.kind === 'page') return `Cannot move here. ${address} already belongs to “${owner.source.title}”. Choose another location.`;
+	if (owner.kind === 'page-alias') return `Cannot move here. ${address} is a previous address for “${owner.source.page.title}” at ${owner.source.targetPathname}. Choose another location.`;
+	if (owner.kind === 'public-file') return `Cannot move here. ${address} is used by public file ${owner.label}. Choose another location.`;
+	if (owner.kind === 'generated-route') return `Cannot move here. ${address} is used by generated route ${owner.label}. Choose another location.`;
+	return `Cannot move here. ${address} is already used by ${owner.label}. Choose another location.`;
+};
+
+const orderForInsertion = (siblings, index) => {
+	const before = siblings[index - 1]?.pageOrder ?? 0;
+	const after = siblings[index]?.pageOrder ?? 1000;
+	return after - before > 1 ? Math.floor((before + after) / 2) : null;
+};
+
+const applyDirectoryRenames = async (changes, renameDirectory) => {
+	const staged = changes.map((change) => ({ ...change,
+		temporary: path.join(path.dirname(change.from), `.${path.basename(change.from)}.norna-order-${randomUUID()}.tmp`),
+		current: change.from }));
+	const restore = async () => {
+		const failures = [];
+		for (const change of staged.filter((entry) => entry.current === entry.to).reverse()) {
+			try { await renameDirectory(change.to, change.temporary); change.current = change.temporary; }
+			catch (error) { failures.push(`${change.to}: ${error.message}`); }
+		}
+		for (const change of staged.filter((entry) => entry.current === entry.temporary).reverse()) {
+			try { await renameDirectory(change.temporary, change.from); change.current = change.from; }
+			catch (error) { failures.push(`${change.from}: ${error.message}`); }
+		}
+		return failures;
+	};
+	try {
+		for (const change of staged) {
+			await renameDirectory(change.from, change.temporary);
+			change.current = change.temporary;
+		}
+		for (const change of staged) {
+			await renameDirectory(change.temporary, change.to);
+			change.current = change.to;
+		}
+	} catch (error) {
+		const failures = await restore();
+		throw new Error(`${error.message}${failures.length ? `\nRestoration was incomplete. Inspect:\n${failures.join('\n')}` : '\nThe original page order was restored.'}`);
+	}
+	return restore;
+};
+
+export const planEditorPagePlacement = async ({ siteRoot, sourcePath, targetPath, placement, sources = new Map() }) => {
+	if (!['before', 'after', 'first', 'last'].includes(placement)) throw new Error('Choose before, after, first child or last child.');
+	siteRoot = path.resolve(siteRoot);
+	await checkedPath(siteRoot, sourcePath);
+	await checkedPath(siteRoot, targetPath);
+	const state = await readEditorLinkState({ siteRoot, sources });
+	if (state.incomplete.length) throw new Error(`Repair the site before moving a page. ${state.incomplete.join('\n')}`);
+	const contentPaths = new Set(state.structure.nodes.map((node) => node.contentPath ?? node.categoryPath));
+	const dirtyPaths = (files) => `Save or undo these unsaved files before moving:\n${files.map((filename) => `- ${path.relative(siteRoot, filename)}`).join('\n')}`;
+	const dirtySiteFiles = [...sources.keys()].filter((filename) => contentPaths.has(filename)
+		|| filename === path.join(siteRoot, 'site-config/settings.yaml')
+		|| filename === sourcePath || filename.startsWith(path.dirname(sourcePath) + path.sep));
+	if (dirtySiteFiles.length) throw new Error(dirtyPaths(dirtySiteFiles));
+	const source = state.structure.nodes.find((node) => node.contentPath === sourcePath);
+	const target = state.structure.nodes.find((node) => node.contentPath === targetPath);
+	if (!source || source.isHome || !target) throw new Error('Select an existing page below the homepage and an existing destination page.');
+	const parent = placement === 'first' || placement === 'last' ? target
+		: state.structure.nodes.find((node) => node.pagePath === target.parentPagePath)
+			?? state.structure.nodes.find((node) => node.isHome && !target.parentPagePath);
+	if (!parent || inBranch(parent, source)) throw new Error('A page cannot move inside its own branch. Choose another destination.');
+	const sameParent = source.parentPagePath === (parent.pagePath || null);
+	const existing = state.structure.nodes.filter((node) => node.kind === 'page' && !node.isHome && childOf(node, parent) && node.contentPath !== sourcePath)
+		.sort((left, right) => left.pageOrder - right.pageOrder);
+	const targetIndex = existing.findIndex((node) => node.contentPath === targetPath);
+	if ((placement === 'before' || placement === 'after') && targetIndex < 0) throw new Error('The destination page changed. Refresh Site Tree and try again.');
+	const index = placement === 'first' ? 0 : placement === 'last' ? existing.length
+		: targetIndex + (placement === 'after' ? 1 : 0);
+	const current = state.structure.nodes.filter((node) => node.kind === 'page' && !node.isHome && node.parentPagePath === source.parentPagePath)
+		.sort((left, right) => left.pageOrder - right.pageOrder);
+	if (sameParent && current[index]?.contentPath === sourcePath) throw new Error('This page is already in that position.');
+	if (existing.length >= 999) throw new Error('This parent already has the maximum of 999 pages. Choose another parent.');
+	const inserted = [...existing];
+	inserted.splice(index, 0, source);
+	let sourceOrder = orderForInsertion(existing, index);
+	const orderChanges = [];
+	if (sourceOrder === null) {
+		const step = Math.floor(999 / inserted.length);
+		for (let position = 0; position < inserted.length; position += 1) {
+			const node = inserted[position];
+			const order = (position + 1) * step;
+			if (node.contentPath === sourcePath) sourceOrder = order;
+			else if (node.pageOrder !== order) orderChanges.push({ from: node.nodeDir, to: renamedDirectory(node, order) });
+		}
+	}
+	const sourceDestination = sameParent ? renamedDirectory(source, sourceOrder) : null;
+	if (sameParent && sourceDestination !== source.nodeDir) orderChanges.push({ from: source.nodeDir, to: sourceDestination });
+	const dirtyRenamedFiles = [...sources.keys()].filter((filename) => orderChanges.some(({ from }) => filename.startsWith(from + path.sep)));
+	if (dirtyRenamedFiles.length) throw new Error(dirtyPaths(dirtyRenamedFiles));
+	const to = sameParent ? urlFor(source) : `${urlFor(parent)}${source.pageId}/`;
+	let movePreview = null;
+	if (!sameParent) {
+		const owner = state.graph.aliasModel.identitiesByPathname.get(to);
+		if (owner && !(owner.kind === 'page-alias' && owner.source.page.contentFile.contentPath === sourcePath)) {
+			throw new Error(explainDestination(owner, to));
+		}
+		const occupied = new Set(existing.map((node) => node.pageOrder));
+		const provisionalOrder = occupied.has(sourceOrder)
+			? Array.from({ length: 999 }, (_, position) => position + 1).find((order) => !occupied.has(order))
+			: sourceOrder;
+		movePreview = await createPageMovePlan({ from: urlFor(source), to, order: provisionalOrder,
+			graph: state.graph, publicFiles: state.publicFiles, siteStructure: state.structure,
+			sitePagesDir: getSiteSourcePaths(siteRoot).pages,
+			sitePagesLabel: `${siteRoot}/root/pages`, generatedRoutes: state.generatedRoutes });
+	}
+	const watched = new Set([source.nodeDir, path.join(siteRoot, 'site-config/settings.yaml'),
+		...orderChanges.map(({ from }) => from),
+		...state.structure.nodes.map((node) => node.contentPath ?? node.categoryPath),
+		...state.publicFiles.map((file) => file.filePath)]);
+	const fingerprints = [];
+	for (const filename of [...watched].sort()) fingerprints.push([filename, await snapshot(filename)]);
+	return {
+		siteRoot, sourcePath, targetPath, placement, sourceDirectory: source.nodeDir,
+		sameParent, sourceOrder, sourceUrl: urlFor(source), destinationUrl: to,
+		sourceDestination, orderChanges, movePreview,
+		fingerprint: JSON.stringify(fingerprints),
+	};
+};
+
+export const applyEditorPagePlacement = async (plan, { renameDirectory = rename } = {}) => {
+	const current = await planEditorPagePlacement(plan);
+	if (current.fingerprint !== plan.fingerprint || current.sourceOrder !== plan.sourceOrder
+		|| JSON.stringify(current.orderChanges) !== JSON.stringify(plan.orderChanges)) {
+		throw new Error('The site changed since this move was previewed. Review the placement and addresses again.');
+	}
+	if (current.sameParent) {
+		await applyDirectoryRenames(current.orderChanges, renameDirectory);
+		try { await getSiteStructure({ siteRoot: plan.siteRoot }); }
+		catch (error) {
+			const reversed = current.orderChanges.map(({ from, to }) => ({ from: to, to: from }));
+			const restoreErrors = await applyDirectoryRenames(reversed, renameDirectory).then(() => [], (failure) => [failure.message]);
+			throw new Error(`${error.message}${restoreErrors.length ? `\nRestoration was incomplete: ${restoreErrors.join('\n')}` : '\nThe original page order was restored.'}`);
+		}
+		return { sourcePath: path.join(current.sourceDestination, 'content.md'), url: current.sourceUrl };
+	}
+	const restoreOrder = await applyDirectoryRenames(current.orderChanges, renameDirectory);
+	try {
+		const state = await readEditorLinkState({ siteRoot: plan.siteRoot });
+		const move = await createPageMovePlan({ from: current.sourceUrl, to: current.destinationUrl, order: current.sourceOrder,
+			graph: state.graph, publicFiles: state.publicFiles, siteStructure: state.structure,
+			sitePagesDir: getSiteSourcePaths(plan.siteRoot).pages,
+			sitePagesLabel: `${plan.siteRoot}/root/pages`, generatedRoutes: state.generatedRoutes });
+		await applyPageMovePlan(move, { siteRoot: plan.siteRoot, generatedRoutes: state.generatedRoutes, renameDirectory });
+		return { sourcePath: path.join(move.destinationDirectory, 'content.md'), url: current.destinationUrl };
+	} catch (error) {
+		const failures = await restoreOrder();
+		throw new Error(`${error.message}${failures.length ? `\nPage order restoration was incomplete. Inspect:\n${failures.join('\n')}` : ''}`);
+	}
+};

package/scripts/lib/editor-site-editing-tree.mjs

@@ -0,0 +1,146 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { editorPageLocation, editorSourceDefinition } from './editor-source-files.mjs';
+import { editorFileRemovalPolicy } from './editor-file-policy.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+import { parsePageMarkdownSource } from './page-markdown.mjs';
+import { sourceFileDefinitions } from './source-files.mjs';
+import { getThemeDiagnostics } from './editor-language-service.mjs';
+import { createEditorThemeHelp } from './editor-theme-help.mjs';
+
+const excluded = new Set(['.norna', '.git', '.DS_Store', 'node_modules', 'dist', '.vscode-test']);
+const knownNames = new Set([...sourceFileDefinitions.map((entry) => entry.name), 'category.yaml', 'theme.yaml', 'site-theme.yaml']);
+const resourceId = (filename) => `resource:${filename}`;
+
+// The physical traversal retains damaged entries that the logical page model
+// cannot route. It reuses source schemas and page-path rules, without changing
+// build validation.
+export const readSiteEditingTree = async ({ siteRoot, sources = new Map(), snapshot, getInformation }) => {
+	siteRoot = path.resolve(siteRoot);
+	const items = [];
+	const themeHelp = createEditorThemeHelp({ siteRoot, sources });
+	const byDirectory = new Map(snapshot.nodes.map((node) => [path.dirname(node.sourcePath), node]));
+	const read = (filename) => sources.has(filename) ? sources.get(filename) : readFile(filename, 'utf8');
+	const entriesAt = async (directory) => (await readdir(directory, { withFileTypes: true }))
+		.filter((entry) => !excluded.has(entry.name) && !entry.name.startsWith('._') && (entry.isFile() || entry.isDirectory()));
+	const issue = (item, message, severity = 'error', filename = item.sourcePath, line = 1) => {
+		(item.issues ??= []).push({ message, severity, path: filename, line });
+	};
+	const validate = async (item) => {
+		const definition = editorSourceDefinition(siteRoot, item.sourcePath);
+		if (!definition) return;
+		try {
+			const source = await read(item.sourcePath);
+			if (definition.schema) {
+				parseYamlConfig(source, item.sourcePath, { schema: definition.schema });
+				if (['rootTheme', 'theme', 'pageTheme'].includes(definition.schemaKind)) {
+					for (const diagnostic of await getThemeDiagnostics({ siteRoot, documentPath: item.sourcePath, source, sources })) issue(item, diagnostic.message, diagnostic.severity, item.sourcePath, diagnostic.line);
+				}
+			} else {
+				const document = await parsePageMarkdownSource(source, { label: item.sourcePath });
+				for (const diagnostic of document.diagnostics) issue(item, diagnostic.message, diagnostic.severity, item.sourcePath, diagnostic.line);
+			}
+		} catch (error) { issue(item, error.message); }
+	};
+	const visit = async (directory, parentId, owner, role, location = null) => {
+		let entries;
+		try { entries = await entriesAt(directory); }
+		catch (error) {
+			if (location?.isHome && error.code === 'ENOENT') entries = [];
+			else {
+				if (owner) issue(owner, `Cannot read ${directory}: ${error.message}`, 'error', directory);
+				return;
+			}
+		}
+		const names = new Map(entries.map((entry) => [entry.name, entry]));
+		let container;
+		if (location) {
+			const hasContent = names.get('content.md')?.isFile();
+			const hasCategory = names.get('category.yaml')?.isFile();
+			const kind = hasContent ? 'page' : 'incomplete';
+			const sourcePath = path.join(directory, 'content.md');
+			const logical = byDirectory.get(directory);
+			let information = {};
+			if (kind !== 'incomplete') {
+				try { information = logical?.kind === kind ? logical : await getInformation({ source: await read(sourcePath), sourcePath, kind, isHome: location.isHome, fallbackTitle: location.pageId }); }
+				catch (error) { information = { problem: `Cannot read ${sourcePath}: ${error.message}` }; }
+			}
+			container = { ...logical, ...location, ...information, kind, sourcePath, id: sourcePath, ownerId: sourcePath, parentId,
+				directory, title: information.title ?? (location.isHome ? path.basename(siteRoot) : location.pageId),
+				url: location.isHome ? '/' : `/${location.pagePath}/`, missingSource: kind === 'incomplete' };
+			items.push(container);
+			if (kind === 'page') container.themeHelp = await themeHelp(directory);
+			if (information.problem) issue(container, information.problem);
+			if (kind !== 'incomplete') await validate(container);
+			else issue(container, location.isHome ? 'Homepage content.md is missing. Use Add to create it.'
+				: 'Page content.md is missing. Use Add to create it.');
+			if (hasCategory) issue(container, 'category.yaml is no longer supported. Use content.md with page.listChildren: true for an overview.');
+			owner = container;
+		} else if (role === 'site') {
+			container = { id: null };
+		} else {
+			container = { id: resourceId(directory), parentId, ownerId: owner.id, sourcePath: directory,
+				kind: 'directory', role, title: path.basename(directory), description: role === 'public'
+					? 'Files published unchanged with the site, such as robots.txt and icons.' : role === 'configuration' ? 'Settings and content shared by the complete site' : '' };
+			items.push(container);
+		}
+		const order = location ? ['images', 'tree-theme.yaml', 'page-theme.yaml', 'pages']
+			: role === 'site' ? ['site-config', 'public', 'root']
+			: role === 'configuration' ? ['settings.yaml', 'shared-content.yaml'] : [];
+		const rank = (entry) => order.includes(entry.name) ? order.indexOf(entry.name) : order.length;
+		entries.sort((a, b) => rank(a) - rank(b) || a.name.localeCompare(b.name, 'en', { numeric: true }));
+		for (const entry of entries) {
+			const filename = path.join(directory, entry.name);
+			if (location && entry.name === 'content.md' && entry.isFile() && owner.kind === 'page') continue;
+			if (entry.isDirectory()) {
+				const childLocation = role === 'pages' || role === 'site' && entry.name === 'root' ? editorPageLocation(siteRoot, filename) : null;
+				const childRole = childLocation ? 'page' : location && entry.name === 'pages' ? 'pages'
+					: location && entry.name === 'images' && owner.kind === 'page' ? 'images'
+						: role === 'site' && entry.name === 'site-config' ? 'configuration'
+							: role === 'public' || role === 'site' && entry.name === 'public' ? 'public' : 'extra';
+				await visit(filename, container.id, owner, childRole, childLocation);
+				const child = items.find((item) => item.sourcePath === filename);
+				if (child && childRole === 'extra' && (knownNames.has(entry.name) || ['images', 'pages', 'site-config', 'public'].includes(entry.name) || role === 'pages')) {
+					issue(child, `This directory is not at a permitted Norna location: ${filename}. Use pages/NNN-page-id for child entries, images/ beside page content, and site-config/ or public/ only at the site root.`, 'warning');
+				}
+				continue;
+			}
+			const definition = role !== 'public' ? editorSourceDefinition(siteRoot, filename) : null;
+			const file = { id: resourceId(filename), parentId: container.id, ownerId: owner.id, kind: 'file', sourcePath: filename,
+				title: entry.name, role: definition ? 'configuration' : 'asset', description: definition?.description ?? '',
+				removable: Boolean(editorFileRemovalPolicy({ siteRoot, sourcePath: owner.sourcePath, filePath: filename })) };
+			items.push(file);
+			if (['rootTheme', 'theme', 'pageTheme'].includes(definition?.schemaKind)) file.themeHelp = await themeHelp(directory, filename);
+			if (definition) await validate(file);
+			else if (role !== 'public' && ['site-config', 'public', 'pages', 'images'].includes(entry.name)) issue(file, `Expected a directory named ${entry.name}, but this is a file. Rename or move this file through Explorer before creating the directory.`, 'warning');
+			else if (role !== 'public' && entry.name === 'category.yaml') issue(file, 'category.yaml is no longer supported. Create content.md with page.listChildren: true, then remove this file.', 'warning');
+			else if (role !== 'public' && knownNames.has(entry.name)) issue(file, `This source file is in the wrong location. Put content.md, tree-theme.yaml and page-theme.yaml in a valid page directory; put settings.yaml and shared-content.yaml in the site's site-config/.`, 'warning');
+			else if (role !== 'public' && !(role === 'images' && /\.(jpe?g|png|svg)$/i.test(entry.name))) file.note = 'Not used by Norna';
+		}
+	};
+	const source = getSiteSourcePaths(siteRoot);
+	// Site resources have their own owner even when root/content.md is unreadable.
+	// The site context is not a visible row in the physical tree.
+	const owner = { id: siteRoot, sourcePath: siteRoot, issues: [] };
+	await visit(siteRoot, null, owner, 'site');
+	if (!items.some((item) => item.isHome)) await visit(source.root, null, owner, 'page', editorPageLocation(siteRoot, source.root));
+	const configuration = items.find((item) => item.role === 'configuration' && item.kind === 'directory');
+	const homepage = items.find((item) => item.isHome);
+	for (const [filename, target] of [[path.join(siteRoot, 'site-config/settings.yaml'), configuration], [source.theme, homepage]]) {
+		try { await read(filename); }
+		catch (error) {
+			issue(target ?? owner, error.code === 'ENOENT' || error.code === 'ENOTDIR'
+				? `Required ${path.relative(siteRoot, filename)} is missing. Use Add to create it.` : error.message, 'error', filename);
+		}
+	}
+
+	// Keep shared structural diagnostics, including duplicate sibling identifiers.
+	for (const problem of snapshot.problems) {
+		if (![owner, ...items].some((item) => item.issues?.some((entry) => entry.message === problem.message && entry.path === problem.path))) {
+			const target = items.find((item) => item.sourcePath === problem.path || item.directory === problem.path) ?? owner;
+			issue(target, problem.message, 'error', problem.path);
+		}
+	}
+	return { ...snapshot, items, problems: owner.issues };
+};

package/scripts/lib/editor-site-files.mjs

@@ -0,0 +1,153 @@
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { markdownToMdast } from 'satteri';
+import { parsePageMarkdownSource } from './page-markdown.mjs';
+import { getSiteStructure } from './site-structure.mjs';
+import { getEditorIncomingLinks } from './editor-site-links.mjs';
+import { editorFileRemovalPolicy } from './editor-file-policy.mjs';
+import { getEditorThemeRemovalHelp } from './editor-theme-help.mjs';
+
+export const siteFileOperationsApiVersion = 1;
+export const siteRemovalApiVersion = 1;
+const imageName = /^[a-z0-9][a-z0-9.-]*\.(jpe?g|png|svg)$/i;
+const stat = (filename) => lstat(filename).catch((error) => {
+	if (error.code === 'ENOENT') return null;
+	throw error;
+});
+
+export const checkedPath = async (siteRoot, filename) => {
+	const root = path.resolve(siteRoot);
+	const target = path.resolve(filename);
+	const relative = path.relative(root, target);
+	if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+		throw new Error('Choose a file in the selected site.');
+	}
+	let current = root;
+	for (const segment of ['', ...relative.split(path.sep).filter(Boolean)]) {
+		current = path.join(current, segment);
+		if ((await stat(current))?.isSymbolicLink()) throw new Error('Symbolic links cannot be changed through Site Tree. Use the real source directory.');
+	}
+	return target;
+};
+
+const pageTarget = async ({ siteRoot, sourcePath }) => {
+	const filename = await checkedPath(siteRoot, sourcePath);
+	const structure = await getSiteStructure({ siteRoot, tolerant: true });
+	const page = structure.nodes.find((node) => (node.contentPath ?? node.categoryPath) === filename);
+	if (!page) throw new Error('The selected page is no longer in this site. Refresh Site Tree and select it again.');
+	return { page, structure, directory: path.dirname(filename), sourcePath: filename };
+};
+
+export const snapshot = async (filename) => {
+	const result = [];
+	const visit = async (current) => {
+		const information = await stat(current);
+		if (!information) throw new Error('The selected file no longer exists. Refresh Site Tree.');
+		if (information.isSymbolicLink()) throw new Error('This selection contains a symbolic link. Remove it through the ordinary Explorer instead.');
+		if (!information.isFile() && !information.isDirectory()) throw new Error('This selection contains an unsupported filesystem entry.');
+		result.push([path.relative(filename, current), information.isDirectory() ? 'directory' : 'file', information.size, information.mtimeMs, information.ctimeMs, information.ino]);
+		if (information.isDirectory()) for (const entry of (await readdir(current)).sort()) await visit(path.join(current, entry));
+	};
+	await visit(filename);
+	return result;
+};
+
+export const planEditorImageCopy = async ({ siteRoot, sourcePath, imagePath, filename, replace = false }) => {
+	const target = await pageTarget({ siteRoot, sourcePath });
+	if (target.page.kind !== 'page') throw new Error('Choose a content page for this image.');
+	if (!imageName.test(filename)) throw new Error('Use a filename starting with a letter or number, followed by letters, numbers, dots or hyphens, ending in .jpg, .jpeg, .png or .svg.');
+	const source = path.resolve(imagePath);
+	const information = await stat(source);
+	if (!information?.isFile() || information.isSymbolicLink()) throw new Error('Choose a regular image file to copy.');
+	if (!/\.(jpe?g|png|svg)$/i.test(source) || path.extname(source).toLowerCase() !== path.extname(filename).toLowerCase()) {
+		throw new Error('Keep the source image extension. This action does not convert image formats.');
+	}
+	const destination = await checkedPath(siteRoot, path.join(target.directory, 'images', filename));
+	if (source === destination) throw new Error('This image already belongs to the selected page. Use Insert Image instead.');
+	const existing = await stat(destination);
+	if (replace ? !existing?.isFile() : existing !== null) {
+		throw new Error(replace ? 'The image to replace no longer exists.' : 'An image already has this name on the page. Choose another filename or use Replace Image.');
+	}
+	return { source, destination, sourcePath: target.sourcePath, filename,
+		fingerprint: JSON.stringify([await snapshot(source), existing ? await snapshot(destination) : null]) };
+};
+
+export const getEditorImageUsage = async ({ siteRoot, sourcePath, imagePath, sources = new Map() }) => {
+	const { page, structure, directory } = await pageTarget({ siteRoot, sourcePath });
+	const target = await checkedPath(siteRoot, imagePath);
+	const targetStat = await stat(target);
+	if (page.kind !== 'page' || path.dirname(target) !== path.join(directory, 'images') || !imageName.test(path.basename(target)) || !targetStat?.isFile()) {
+		throw new Error('Choose an image directly inside this page’s images folder.');
+	}
+	const references = [];
+	const incomplete = structure.problems.map((problem) => problem.message);
+	for (const node of structure.nodes.filter((node) => node.contentPath)) {
+		try {
+			const source = sources.has(node.contentPath) ? sources.get(node.contentPath) : await readFile(node.contentPath, 'utf8');
+			const document = await parsePageMarkdownSource(source, { label: node.contentPath });
+			if (document.diagnostics.some(({ severity }) => severity === 'error')) incomplete.push(node.contentPath);
+			for (const reference of document.managedImages.filter((reference) => reference.image.toLowerCase() === path.basename(target).toLowerCase())) {
+				const localPath = path.join(path.dirname(node.contentPath), 'images', reference.image);
+				const local = await stat(localPath);
+				if (local ? local.dev !== targetStat.dev || local.ino !== targetStat.ino : reference.image !== path.basename(target)) continue;
+				references.push({ sourcePath: node.contentPath, line: reference.line, unresolved: !local });
+			}
+		} catch (error) { incomplete.push(`${node.contentPath}: ${error.message}`); }
+	}
+	return { references, incomplete };
+};
+
+export const planEditorRemoval = async ({ siteRoot, sourcePath, imagePath, filePath, sources }) => {
+	siteRoot = path.resolve(siteRoot);
+	const siteFile = filePath && !imagePath && path.resolve(sourcePath) === siteRoot;
+	const target = siteFile ? { sourcePath: await checkedPath(siteRoot, sourcePath) } : await pageTarget({ siteRoot, sourcePath });
+	if (!imagePath && !filePath && target.page.isHome) throw new Error('The homepage is required and cannot be removed.');
+	const filename = imagePath || filePath ? await checkedPath(siteRoot, imagePath ?? filePath) : target.directory;
+	const policy = filePath ? editorFileRemovalPolicy({ siteRoot: path.resolve(siteRoot), sourcePath: target.sourcePath, filePath: filename }) : null;
+	if (filePath && (!policy || !(await stat(filename))?.isFile())) throw new Error('This file cannot be removed separately. Required page files belong to their page; required site settings must remain.');
+	const usage = imagePath ? await getEditorImageUsage({ siteRoot, sourcePath, imagePath, sources })
+		: !filePath || policy.kind === 'public' ? await getEditorIncomingLinks({ siteRoot, sourcePath, sources,
+			descendants: !filePath, excludeBranch: !filePath, filePath }) : null;
+	const files = await snapshot(filename);
+	const effect = policy?.kind === 'theme'
+		? `${policy.effect}\n\n${await getEditorThemeRemovalHelp({ siteRoot, filename, sources })}` : policy?.effect;
+	return { target: filename, recursive: !imagePath && !filePath, effect,
+		files: files.filter(([, kind]) => kind === 'file').map(([relative]) => relative || path.basename(filename)),
+		pages: imagePath || filePath ? 0 : target.structure.nodes.filter((node) => {
+			const relative = path.relative(filename, node.contentPath ?? node.categoryPath);
+			return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+		}).length,
+		usage, fingerprint: JSON.stringify([files, usage, effect]) };
+};
+
+export const createEditorImageAppend = async ({ source, filename, alt, caption = '' }) => {
+	if (typeof alt !== 'string' || !alt.trim()) throw new Error('Describe the image before inserting it.');
+	return createEditorImageBatchAppend({ source, items: [{ filename, alt, caption }] });
+};
+
+export const createEditorImageBatchAppend = async ({ source, items }) => {
+	if (!Array.isArray(items) || !items.length) throw new Error('Choose at least one image to insert.');
+	for (const item of items) {
+		if (!imageName.test(item.filename)) throw new Error('Choose a managed image filename.');
+		if (item.alt !== undefined && typeof item.alt !== 'string') throw new Error('Alternative text must be text.');
+		if (item.caption !== undefined && typeof item.caption !== 'string') throw new Error('Caption must be text.');
+	}
+	const document = await parsePageMarkdownSource(source, { label: 'content.md' });
+	if (document.diagnostics.some(({ severity }) => severity === 'error')) {
+		throw new Error('Repair this page’s content errors before appending an image block. The imported file remains available.');
+	}
+	const eol = source.includes('\r\n') ? '\r\n' : '\n';
+	const block = ['```image-stack', 'items:', ...items.flatMap(({ filename, alt, caption }) => [
+		`  - image: ${filename}`,
+		...(alt !== undefined ? [`    alt: ${JSON.stringify(alt)}`] : []),
+		...(caption ? [`    caption: ${JSON.stringify(caption)}`] : []),
+	]), '```', ''].join(eol);
+	const text = `${source.endsWith(eol + eol) ? '' : source.endsWith(eol) ? eol : eol + eol}${block}`;
+	const result = await parsePageMarkdownSource(source + text, { label: 'content.md' });
+	const appended = markdownToMdast(source + text, { features: { gfm: true, frontmatter: true } }).children.at(-1);
+	if (appended?.type !== 'code' || appended.lang !== 'image-stack' || appended.position.start.offset < source.length
+		|| result.managedImages.length !== document.managedImages.length + items.length || result.diagnostics.some(({ severity }) => severity === 'error')) {
+		throw new Error('Close the open Markdown block or comment before appending an image. The imported file remains available.');
+	}
+	return { start: source.length, end: source.length, text };
+};

package/scripts/lib/editor-site-links.mjs

@@ -0,0 +1,79 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getGeneratedSiteRoutes } from './page-aliases.mjs';
+import { parsePageMarkdownSource } from './page-markdown.mjs';
+import { configSchema } from './schema-definitions.mjs';
+import { parseContentFrontmatter, splitSiteFile } from './site-content.mjs';
+import { createSiteLinkGraph, getSitePublicFiles } from './site-link-graph.mjs';
+import { getSiteStructure } from './site-structure.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+
+export const isInside = (root, filename) => {
+	const relative = path.relative(root, filename);
+	return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+};
+
+// The engine remains the only URL resolver. Editor reads overlay unsaved
+// buffers and retain useful results when another page needs repair.
+export const readEditorLinkState = async ({ siteRoot, sources = new Map() }) => {
+	const readSource = (filename) => sources.has(filename) ? sources.get(filename) : readFile(filename, 'utf8');
+	const structure = await getSiteStructure({ siteRoot, tolerant: true, readSource });
+	const incomplete = structure.problems.map(({ message }) => message);
+	let settings;
+	const settingsPath = path.join(siteRoot, 'site-config/settings.yaml');
+	try { settings = parseYamlConfig(await readSource(settingsPath), settingsPath, { schema: configSchema }); }
+	catch (error) { incomplete.push(error.message); }
+	const pageDocuments = await Promise.all(structure.contentFiles.map(async (contentFile) => {
+		let source = '';
+		let data = {};
+		try {
+			source = await readSource(contentFile.contentPath);
+			data = parseContentFrontmatter(splitSiteFile(source, contentFile.contentLabel).frontmatterBody, contentFile.contentLabel);
+		} catch (error) { incomplete.push(error.message); }
+		let document;
+		try {
+			document = await parsePageMarkdownSource(source, { label: contentFile.contentLabel });
+			for (const diagnostic of document.diagnostics.filter(({ severity }) => severity === 'error')) {
+				incomplete.push(`${contentFile.contentLabel}:${diagnostic.line}: ${diagnostic.message}`);
+			}
+		} catch (error) {
+			incomplete.push(error.message);
+			document = await parsePageMarkdownSource('# Unavailable page\n', { label: contentFile.contentLabel });
+		}
+		return { contentFile, data, document };
+	}));
+	let publicFiles = [];
+	try { publicFiles = await getSitePublicFiles(path.join(siteRoot, 'public')); }
+	catch (error) { incomplete.push(error.message); }
+	const generatedRoutes = getGeneratedSiteRoutes({ searchEnabled: settings?.search });
+	const graph = createSiteLinkGraph({ siteStructure: structure, pageDocuments, publicFiles, generatedRoutes });
+	// Missing destinations do not make reference discovery incomplete. Ambiguous
+	// ownership of an address does, and must never be presented as a clean check.
+	incomplete.push(...graph.diagnostics.filter((entry) => !entry.reference && entry.severity === 'error').map(({ message }) => message));
+	return { structure, graph, publicFiles, generatedRoutes, settings, incomplete: [...new Set(incomplete)].sort() };
+};
+
+export const summarizeReference = (reference) => ({
+	sourcePath: reference.sourceContentFile.contentPath,
+	title: reference.sourcePage.title,
+	line: reference.line,
+	column: reference.column ?? 1,
+	target: reference.target.kind === 'internal' ? reference.resolution?.pathname ?? reference.target.pathname : '',
+	text: reference.sourcePage.document.fullSource.split(/\r?\n/)[reference.line - 1]?.trim() ?? '',
+});
+
+export const getEditorIncomingLinks = async ({ siteRoot, sourcePath, sources, descendants = false, excludeBranch = false, filePath, alias }) => {
+	const state = await readEditorLinkState({ siteRoot, sources });
+	const node = state.structure.nodes.find((entry) => (entry.contentPath ?? entry.categoryPath) === sourcePath);
+	if (!node && !(filePath && path.resolve(sourcePath) === path.resolve(siteRoot))) throw new Error('This page is no longer in the selected site. Refresh Site Tree.');
+	const directory = node ? path.dirname(sourcePath) : siteRoot;
+	const targetPaths = new Set(state.structure.nodes.filter((entry) => entry === node || (descendants && isInside(directory, entry.nodeDir)))
+		.map((entry) => entry.isHome ? '/' : `/${entry.pagePath}/`));
+	const references = state.graph.references.filter((reference) => {
+		if (excludeBranch && isInside(directory, reference.sourceContentFile.contentPath)) return false;
+		if (alias) return reference.target.pageLookupPathname === alias;
+		if (filePath) return reference.resolution?.kind === 'public-file' && reference.resolution.file.filePath === filePath;
+		return targetPaths.has(reference.resolution?.pathname ?? reference.target.pageLookupPathname);
+	}).map(summarizeReference);
+	return { references, incomplete: state.incomplete };
+};