@janga/norna 0.7.27 → 0.7.29

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

@@ -0,0 +1,57 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import path from 'node:path';
+import { readEditorLinkState, isInside } from './editor-site-links.mjs';
+import { checkedPath, snapshot } from './editor-site-files.mjs';
+import { createPageMovePlan } from './page-move-plan.mjs';
+import { applyPageMovePlan } from './page-move-apply.mjs';
+
+export const siteAddressApiVersion = 1;
+export const sitePageAddressOptionsApiVersion = 1;
+
+export const getEditorPageAddresses = async (options) => {
+	const { structure, graph, settings, incomplete } = await readEditorLinkState(options);
+	const node = structure.nodes.find((entry) => (entry.contentPath ?? entry.categoryPath) === options.sourcePath);
+	if (!node) throw new Error('This page is no longer in the selected site. Refresh Site Tree.');
+	const internalLink = node.isHome ? '/' : `/${node.pagePath}/`;
+	const base = settings?.url?.replace(/\/$/, '') + '/';
+	return {
+		internalLink, webAddress: settings ? new URL(internalLink.slice(1), base).href : null,
+		segment: node.isHome ? '' : node.pageId,
+		aliases: graph.pagesByPathname.get(internalLink)?.aliases ?? [],
+		incomplete,
+	};
+};
+
+export const planEditorPageAddress = async ({ siteRoot, sourcePath, segment, preserveAliases = true, sources = new Map() }) => {
+	if (typeof preserveAliases !== 'boolean') throw new Error('Choose whether to preserve old addresses as aliases.');
+	await checkedPath(siteRoot, sourcePath);
+	if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(segment)) throw new Error('Use lowercase letters, numbers and single hyphens, for example install-norna. Enter one URL segment, without slashes.');
+	const state = await readEditorLinkState({ siteRoot, sources });
+	if (state.incomplete.length) throw new Error(`Repair the site before changing an address. ${state.incomplete.join('\n')}`);
+	const node = state.structure.nodes.find((entry) => entry.contentPath === sourcePath);
+	if (!node || node.isHome) throw new Error('Choose a content page other than the homepage. Category addresses follow their folders and cannot be changed through this action.');
+	const sourcePaths = [...state.structure.nodes.map((entry) => entry.contentPath ?? entry.categoryPath), path.join(siteRoot, 'site-config/settings.yaml')];
+	if (sourcePaths.some((filename) => sources.has(filename))) throw new Error('Save or undo unsaved page, category and site-settings edits before changing an address.');
+	for (const filename of sourcePaths) await checkedPath(siteRoot, filename);
+	const to = `/${node.parentPagePath ? node.parentPagePath + '/' : ''}${segment}/`;
+	const plan = await createPageMovePlan({ from: `/${node.pagePath}/`, to, preserveAliases,
+		graph: state.graph, publicFiles: state.publicFiles, siteStructure: state.structure,
+		sitePagesDir: getSiteSourcePaths(siteRoot).pages, sitePagesLabel: `${siteRoot}/root/pages`, generatedRoutes: state.generatedRoutes });
+	await checkedPath(siteRoot, plan.destinationDirectory);
+	const watched = [...new Set([...sourcePaths, ...state.publicFiles.map(({ filePath }) => filePath)])].sort();
+	const snapshots = [];
+	for (const filename of watched) snapshots.push([filename, await snapshot(filename)]);
+	const addresses = await getEditorPageAddresses({ siteRoot, sourcePath });
+	return { ...plan, siteRoot, sourcePath, segment, generatedRoutes: state.generatedRoutes,
+		webFrom: addresses.webAddress,
+		webTo: new URL(to.slice(1), state.settings.url.replace(/\/$/, '') + '/').href,
+		fingerprint: JSON.stringify([await snapshot(plan.sourceDirectory), snapshots, plan.to, preserveAliases, plan.fileChanges.map(({ updatedSource }) => updatedSource)]) };
+};
+
+export const applyEditorPageAddress = async (plan, { renameDirectory } = {}) => {
+	const current = await planEditorPageAddress(plan);
+	if (current.fingerprint !== plan.fingerprint) throw new Error('The site changed after the address preview. Start again to review the new result.');
+	if (!isInside(plan.siteRoot, current.sourceDirectory) || !isInside(plan.siteRoot, current.destinationDirectory)) throw new Error('The page must remain inside its site.');
+	await applyPageMovePlan(current, { siteRoot: plan.siteRoot, generatedRoutes: current.generatedRoutes, renameDirectory });
+	return { sourcePath: path.join(current.destinationDirectory, 'content.md'), url: current.to };
+};

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

@@ -0,0 +1,102 @@
+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 { comparePageOrder, planPageOrder, assertRenumberingAllowed } from './page-order.mjs';
+import { pageOrderFileChanges } from './page-order-source.mjs';
+
+export const sitePagePlacementApiVersion = 2;
+export const sitePagePlacementOptionsApiVersion = 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 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.`;
+};
+
+export const planEditorPagePlacement = async ({ siteRoot, sourcePath, targetPath, placement, preserveAliases = true, sources = new Map() }) => {
+	if (typeof preserveAliases !== 'boolean') throw new Error('Choose whether to preserve old addresses as aliases.');
+	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(comparePageOrder);
+	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(comparePageOrder);
+	if (sameParent && current[index]?.contentPath === sourcePath) throw new Error('This page is already in that position.');
+	const insertion = planPageOrder(existing, index);
+	const sourceOrder = insertion.order;
+	const orderChanges = await pageOrderFileChanges(insertion.orderChanges);
+	const sourceDestination = sameParent ? source.nodeDir : null;
+	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));
+		}
+		movePreview = await createPageMovePlan({ from: urlFor(source), to, order: sourceOrder, siblingOrderChanges: insertion.orderChanges, preserveAliases,
+			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(({ contentPath }) => contentPath),
+		...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, preserveAliases,
+		fileChanges: sameParent ? [...orderChanges, ...await pageOrderFileChanges([{ node: source, oldOrder: source.pageOrder, newOrder: sourceOrder }])] : movePreview.fileChanges,
+		stateFingerprint: JSON.stringify(fingerprints),
+		fingerprint: JSON.stringify([fingerprints, preserveAliases]),
+	};
+};
+
+export const applyEditorPagePlacement = async (plan, { renameDirectory = rename, writeSource, allowRenumber = false, sources = new Map() } = {}) => {
+	const current = await planEditorPagePlacement({ ...plan, sources });
+	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.');
+	}
+	assertRenumberingAllowed(current.orderChanges, allowRenumber);
+	const mutation = current.sameParent ? {
+		mode: 'reorder', orderChanges: current.orderChanges, fileChanges: current.fileChanges,
+		sourceFiles: current.fileChanges.map(change => ({ contentPath: change.originalPath, contentLabel: change.contentLabel, source: change.originalSource })),
+	} : current.movePreview;
+	await applyPageMovePlan(mutation, { siteRoot: plan.siteRoot, generatedRoutes: current.movePreview?.generatedRoutes, renameDirectory, writeSource, allowRenumber });
+	return { sourcePath: path.join(current.sameParent ? current.sourceDirectory : mutation.destinationDirectory, 'content.md'),
+		url: current.destinationUrl, renumberedPages: current.orderChanges.length };
+};

package/scripts/lib/editor-resource-actions.mjs

@@ -0,0 +1,216 @@
+import { publicFilePublication, publicationIssues } from './publication-paths.mjs';
+import { attachmentHref, attachmentPathname, attachmentOutputIssues, parseLocalAttachmentTarget, encodeAttachmentPath } from './page-attachments.mjs';
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseDocument, isScalar, isSeq } from 'yaml';
+import { checkedPath, snapshot, getEditorImageUsage, planEditorRemoval } from './editor-site-files.mjs';
+import { isInside, readEditorLinkState, summarizeReference } from './editor-site-links.mjs';
+import { getSourcePageLocation } from './source-files.mjs';
+import { parsePageMarkdownSource } from './page-markdown.mjs';
+import { inspectPublicAssetFilenames } from './public-asset-conventions.mjs';
+
+export const siteResourceActionsApiVersion = 1;
+const stat = (filename) => lstat(filename).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+const imageName = /^[a-z0-9][a-z0-9.-]*\.(jpe?g|png|svg)$/i;
+const publicPath = (siteRoot, filename, settings, directory = false) => publicFilePublication(path.relative(path.join(siteRoot, 'public'), filename).split(path.sep).join('/'), settings, { directory }).pathname;
+const encodePath = encodeAttachmentPath;
+const checkedName = (name) => {
+	if (typeof name !== 'string' || !name || name !== name.trim() || /[\\/\x00-\x1f\x7f<>:"|?*#%]/.test(name) || /^\.{1,2}$/.test(name) || /[. ]$/.test(name)) {
+		throw new Error('Enter one filename or folder name, without slashes, URL punctuation or trailing dots/spaces.');
+	}
+	return name;
+};
+const available = async (filename) => {
+	const entries = await readdir(path.dirname(filename)).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
+	if (entries.some(entry => entry.normalize('NFC').toLowerCase() === path.basename(filename).normalize('NFC').toLowerCase())) {
+		throw new Error('That name is already in use. Choose another name; existing files will not be overwritten.');
+	}
+};
+const resource = async ({ siteRoot, filePath }) => {
+	const filename = await checkedPath(siteRoot, filePath);
+	const info = await stat(filename);
+	if (!info || !(info.isFile() || info.isDirectory())) throw new Error('This file or folder no longer exists. Refresh Site Tree.');
+	const publicRoot = path.join(path.resolve(siteRoot), 'public');
+	if (isInside(publicRoot, filename)) return { filename, kind: 'public', directory: info.isDirectory(), fixed: filename === publicRoot };
+	const owner = path.dirname(path.dirname(filename));
+	if (info.isFile() && path.basename(path.dirname(filename)) === 'downloads' && getSourcePageLocation(siteRoot, owner)) return { filename, kind: 'attachment', directory: false, sourcePath: path.join(owner, 'content.md') };
+	if (info.isFile() && path.basename(path.dirname(filename)) === 'images' && getSourcePageLocation(siteRoot, owner) && imageName.test(path.basename(filename))) {
+		return { filename, kind: 'image', directory: false, sourcePath: path.join(owner, 'content.md') };
+	}
+	throw new Error('Choose a managed page image or a resource inside public/.');
+};
+
+const validatePublic = (siteRoot, state, filenames, directories = []) => {
+	for (const directory of directories) publicPath(siteRoot, directory, state.settings, true);
+	const issues = publicationIssues({ pages: state.graph.pages, attachments: state.graph.attachments.files, generatedRoutes: state.generatedRoutes,
+		publicFiles: filenames.map(filePath => ({ filePath, pathname: publicPath(siteRoot, filePath, state.settings) })) });
+	if (issues.length) throw new Error(issues.map(issue => issue.message).join('\n'));
+	const inspection = inspectPublicAssetFilenames(filenames.filter(filename => path.dirname(filename) === path.join(siteRoot, 'public')).map(filename => path.basename(filename)));
+	if (inspection.logos.length > 1) throw new Error(`Keep one navigation logo in public/: ${inspection.logos.join(', ')}. Use Replace on the existing logo.`);
+	if (inspection.socialImages.length > 1) throw new Error(`Keep one social image in public/: ${inspection.socialImages.join(', ')}.`);
+	return inspection.suspicious.map(entry => entry.message);
+};
+
+export const getEditorResourceReferences = async (options) => {
+	const selected = await resource(options);
+	if (selected.kind === 'image') return { ...await getEditorImageUsage({ ...options, sourcePath: selected.sourcePath, imagePath: selected.filename }), scope: 'Managed Markdown images and Norna image blocks on the owning page. HTML and external references are not checked.' };
+	const state = await readEditorLinkState(options);
+	return { references: state.graph.references.filter(ref => ['public-file', 'attachment'].includes(ref.resolution?.kind) && (selected.directory ? isInside(selected.filename, ref.resolution.file.filePath) : selected.filename === ref.resolution.file.filePath)).map(summarizeReference),
+		incomplete: state.incomplete, scope: 'Page-content links. HTML, configuration and external references are not checked.' };
+};
+
+// Change parsed image destinations and YAML scalars, preserving examples. Map the
+// scanner's normalized offsets back to the original CRLF/LF source.
+const renameImageReferences = async (source, oldName, newName) => {
+	const normalized = source.replace(/\r\n?/g, '\n');
+	const offsets = []; for (let i = 0; i < source.length; i++) { offsets.push(i); if (source[i] === '\r' && source[i + 1] === '\n') i++; } offsets.push(source.length);
+	const document = await parsePageMarkdownSource(normalized);
+	if (document.diagnostics.some(issue => issue.severity === 'error')) throw new Error('Repair the page content before renaming this image.');
+	const blocks = document.regions.flatMap(region => region.blocks.map(block => ({ ...block, sourceStartOffset: document.bodyOffset + region.startOffset + block.sourceStartOffset })));
+	const edits = [];
+	const destinations = new Set();
+	for (const reference of document.markdownImages.filter(reference => reference.image === oldName)) {
+		if (!reference.targetRange) throw new Error('This Markdown image reference has no editable source range.');
+		const { start, end } = reference.targetRange;
+		if (destinations.has(start)) continue;
+		destinations.add(start);
+		const prefix = reference.targetSource.slice(0, reference.targetSource.lastIndexOf('/') + 1);
+		edits.push({ start: offsets[start], end: offsets[end], text: prefix + newName });
+	}
+	for (const block of blocks) {
+		if (!['image-stack', 'image-carousel', 'card-list'].includes(block.blockType)) continue;
+		const doc = parseDocument(block.source);
+		const items = doc.get('items', true);
+		if (!isSeq(items)) continue;
+		for (const item of items.items) {
+			const image = item?.get?.('image', true);
+			if (!isScalar(image) || image.value !== oldName) continue;
+			if (!image.range) throw new Error('This image reference has no editable source range.');
+			edits.push({ start: offsets[block.sourceStartOffset + image.range[0]], end: offsets[block.sourceStartOffset + image.range[1]], text: JSON.stringify(newName) });
+		}
+	}
+	return edits;
+};
+const applyText = (source, edits) => [...edits].sort((a,b) => b.start-a.start).reduce((text,edit) => text.slice(0,edit.start)+edit.text+text.slice(edit.end),source);
+
+export const planEditorResourceRename = async ({ siteRoot, filePath, name, destinationDirectory, sources = new Map() }) => {
+	siteRoot = path.resolve(siteRoot);
+	const selected = await resource({ siteRoot, filePath });
+	if (selected.fixed) throw new Error('The public folder has a fixed name and location.');
+	const directory = destinationDirectory ?? path.dirname(selected.filename);
+	if (['image', 'attachment'].includes(selected.kind) && directory !== path.dirname(selected.filename)) throw new Error('Images stay in their owning page’s images folder.');
+	const destination = await checkedPath(siteRoot, path.join(directory, checkedName(name)));
+	if (destination === selected.filename) throw new Error('Enter a different name or location, or cancel.');
+	if (!(await stat(directory))?.isDirectory()) throw new Error('Choose an existing destination folder.');
+	if (selected.kind === 'public' && !isInside(path.join(siteRoot, 'public'), destination)) throw new Error('Public resources must stay inside public/.');
+	if (selected.directory && isInside(selected.filename, destination)) throw new Error('A folder cannot be moved inside itself.');
+	if (selected.kind === 'image' && (!imageName.test(name) || path.extname(name) !== path.extname(selected.filename))) throw new Error('Use an image filename with letters, numbers, dots or hyphens. Keep the existing extension; rename does not convert images.');
+	await available(destination);
+	const usage = await getEditorResourceReferences({ siteRoot, filePath, sources });
+	if (usage.incomplete.length || usage.references.some(ref => ref.unresolved)) throw new Error(`References could not be resolved safely. Repair them before renaming or moving.\n${usage.incomplete.join('\n')}`);
+	const files = await snapshot(selected.filename);
+	const changes = [];
+	let warnings = [];
+	if (selected.kind === 'image') {
+		for (const sourcePath of new Set(usage.references.map(ref => ref.sourcePath))) {
+			await checkedPath(siteRoot, sourcePath);
+			const original = sources.get(sourcePath) ?? await readFile(sourcePath, 'utf8');
+			const edits = await renameImageReferences(original, path.basename(selected.filename), name);
+			if (!edits.length) throw new Error(`Cannot locate the image reference in ${sourcePath}. No files changed.`);
+			changes.push({ sourcePath, original, updated: applyText(original, edits) });
+		}
+	} else if (selected.kind === 'attachment') {
+		const state = await readEditorLinkState({ siteRoot, sources });
+		const file = state.graph.attachments.files.find(file => file.filePath === selected.filename);
+		if (!file) throw new Error('The attachment is no longer available.');
+		const updated = { ...file, filePath: destination, filename: name, pathname: attachmentPathname(file.ownerPathname, name) };
+		const problems = attachmentOutputIssues({ files: state.graph.attachments.files.map(entry => entry === file ? updated : entry), pages: state.graph.pages, publicFiles: state.publicFiles, generatedRoutes: state.generatedRoutes });
+		if (problems.length) throw new Error(problems.map(issue => issue.message).join('\n'));
+		const bySource = new Map();
+		for (const ref of state.graph.references.filter(ref => ref.resolution?.kind === 'attachment' && ref.resolution.file.filePath === file.filePath)) {
+			if (!ref.targetRange) throw new Error('Cannot safely locate this attachment reference. No files changed.');
+			const filename = ref.sourceContentFile.contentPath;
+			if (!bySource.has(filename)) bySource.set(filename, { original: ref.sourcePage.document.fullSource, edits: new Map() });
+			const local = parseLocalAttachmentTarget(ref.sourceTarget);
+			const href = local ? local.prefix + encodeAttachmentPath(name) + (ref.targetSource.match(/[?#].*$/)?.[0] ?? '') : (ref.target.absolutePrefix ?? '') + attachmentHref(updated, ref.targetSource);
+			bySource.get(filename).edits.set(ref.targetRange.start, { ...ref.targetRange, text: ref.yamlScalar ? JSON.stringify(href) : href });
+		}
+		for (const [sourcePath, { original, edits }] of bySource) { await checkedPath(siteRoot, sourcePath); changes.push({ sourcePath, original, updated: applyText(original, [...edits.values()]) }); }
+	} else {
+		const state = await readEditorLinkState({ siteRoot, sources });
+		const mapped = state.publicFiles.map(file => isInside(selected.filename, file.filePath) ? path.join(destination, path.relative(selected.filename, file.filePath)) : file.filePath);
+		warnings = validatePublic(siteRoot, state, mapped, selected.directory ? [destination] : []);
+		const before = inspectPublicAssetFilenames(state.publicFiles.filter(file => path.dirname(file.filePath) === path.join(siteRoot, 'public')).map(file => path.basename(file.filePath)));
+		const after = inspectPublicAssetFilenames(mapped.filter(filename => path.dirname(filename) === path.join(siteRoot, 'public')).map(filename => path.basename(filename)));
+		for (const kind of ['logos', 'browserIcons', 'socialImages']) for (const filename of before[kind]) if (!after[kind].includes(filename)) warnings.push(`${filename} will no longer be selected automatically as a site logo, icon or social image.`);
+		const bySource = new Map();
+		for (const ref of state.graph.references) {
+			if (ref.resolution?.kind !== 'public-file' || !isInside(selected.filename, ref.resolution.file.filePath)) continue;
+			if (!ref.targetRange) throw new Error(`Cannot safely update the reference on line ${ref.line} in ${ref.sourceContentFile.contentPath}.`);
+			const target = publicPath(siteRoot, path.join(destination, path.relative(selected.filename, ref.resolution.file.filePath)), state.settings);
+			const suffix = ref.targetSource.match(/[?#].*$/)?.[0] ?? '';
+			const filename = ref.sourceContentFile.contentPath;
+			if (!bySource.has(filename)) bySource.set(filename, { original: ref.sourcePage.document.fullSource, edits: new Map() });
+			bySource.get(filename).edits.set(ref.targetRange.start, { ...ref.targetRange, text: (ref.target.absolutePrefix ?? '') + encodePath(target) + suffix });
+		}
+		for (const [sourcePath, { original, edits }] of bySource) { await checkedPath(siteRoot, sourcePath); changes.push({ sourcePath, original, updated: applyText(original, [...edits.values()]) }); }
+	}
+	return { siteRoot, filePath: selected.filename, name, destinationDirectory: directory, destination, changes, usage, warnings,
+		fingerprint: JSON.stringify([files, destination, changes, usage, warnings]) };
+};
+
+export const planEditorPublicCreation = async ({ siteRoot, directory, name, source, folder = false, replace = false, pending = [], sources = new Map() }) => {
+	siteRoot = path.resolve(siteRoot);
+	directory = await checkedPath(siteRoot, directory ?? path.join(siteRoot, 'public'));
+	const publicRoot = path.join(siteRoot, 'public');
+	if (!isInside(publicRoot, directory)) throw new Error('Choose a folder inside public/.');
+	if (directory !== publicRoot && !(await stat(directory))?.isDirectory()) throw new Error('The destination folder no longer exists.');
+	const destination = await checkedPath(siteRoot, path.join(directory, checkedName(name)));
+	if (replace) { if (!(await stat(destination))?.isFile() || folder || !source) throw new Error('Select an existing public file and a replacement file.'); }
+	else await available(destination);
+	if (source && (!(await stat(source))?.isFile() || (await stat(source)).isSymbolicLink())) throw new Error('Choose a regular file on this computer.');
+	if (source && path.resolve(source) === destination) throw new Error('This file already belongs to this folder.');
+	const state = await readEditorLinkState({ siteRoot, sources });
+	for (const filename of pending) { await checkedPath(siteRoot, filename); if (!isInside(publicRoot, filename)) throw new Error('Pending public files must stay inside public/.'); }
+	const filenames = [...new Set([...state.publicFiles.map(file => file.filePath), ...pending])].filter(filename => filename !== destination);
+	const warnings = validatePublic(siteRoot, state, [...filenames, ...(!folder ? [destination] : [])], folder ? [destination] : []);
+	return { siteRoot, directory, name, source, folder, replace, destination, warnings,
+		fingerprint: JSON.stringify([source ? await snapshot(source) : null, replace ? await snapshot(destination) : null, destination, warnings]) };
+};
+
+export const planEditorFolderRemoval = async ({ siteRoot, directory, sources = new Map() }) => {
+	siteRoot = path.resolve(siteRoot);
+	directory = await checkedPath(siteRoot, directory);
+	const publicRoot = path.join(siteRoot, 'public');
+	const publicFolder = isInside(publicRoot, directory);
+	const kind = path.basename(directory);
+	const ownerDirectory = path.dirname(directory);
+	if (!publicFolder && (!['images', 'downloads', 'pages'].includes(kind) || !getSourcePageLocation(siteRoot, ownerDirectory))) throw new Error('Only optional pages, images and public folders can be deleted.');
+	if (!(await stat(directory))?.isDirectory()) throw new Error('The selected folder no longer exists.');
+	const files = await snapshot(directory);
+	const plans = [];
+	if (publicFolder) {
+		for (const [relative, type] of files) if (type === 'file') plans.push(await planEditorRemoval({ siteRoot, sourcePath: siteRoot, filePath: path.join(directory, relative), sources }));
+	} else {
+		for (const entry of await readdir(directory, { withFileTypes: true })) {
+			const filename = path.join(directory, entry.name);
+			if (kind === 'downloads' && entry.isFile()) plans.push(await planEditorRemoval({ siteRoot, sourcePath: path.join(ownerDirectory, 'content.md'), filePath: filename, sources }));
+			else if (kind === 'images' && entry.isFile()) plans.push(await planEditorRemoval({ siteRoot, sourcePath: path.join(ownerDirectory, 'content.md'), imagePath: filename, sources }));
+			else if (kind === 'pages' && entry.isDirectory()) plans.push(await planEditorRemoval({ siteRoot, sourcePath: path.join(filename, 'content.md'), sources }));
+			else throw new Error(`Cannot delete this folder safely: ${entry.name} is not a supported ${kind === 'pages' ? 'page' : 'image'}. Review it in Explorer first.`);
+		}
+	}
+	const usage = { references: plans.flatMap(plan => plan.usage?.references ?? []).filter(ref => !isInside(directory, ref.sourcePath)), incomplete: [...new Set(plans.flatMap(plan => plan.usage?.incomplete ?? []))] };
+	return { target: directory, pages: plans.reduce((total,plan) => total + plan.pages, 0), files: files.filter(([,type]) => type === 'file').length, usage,
+		fingerprint: JSON.stringify([files, plans.map(plan => plan.fingerprint), usage]) };
+};
+
+export const getEditorResourceAddress = async (options) => {
+	const selected = await resource(options);
+	if (!['public', 'attachment'].includes(selected.kind) || selected.directory) throw new Error('Select a public file.');
+	const { settings, graph } = await readEditorLinkState(options);
+	if (!settings) throw new Error('Repair site-config/settings.yaml to copy the published address.');
+	const pathname = selected.kind === 'attachment' ? graph.attachments.files.find(file => file.filePath === selected.filename)?.pathname : publicPath(options.siteRoot, selected.filename, settings);
+	if (!pathname) throw new Error('The file no longer belongs to this site.');
+	return new URL(encodeAttachmentPath(pathname).slice(1), settings.url.replace(/\/$/, '') + '/').href;
+};

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

@@ -0,0 +1,181 @@
+import { comparePageOrder } from './page-order.mjs';
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { editorPageLocation, editorSourceDefinition, getEditorSourceFileChoices } 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'
+					? 'Technical site files, logo, browser icons and social image. Put content images in a page’s images/ and documents in its downloads/.' : role === 'configuration' ? 'Settings and content shared by the complete site' : '' };
+			items.push(container);
+		}
+		const order = location ? ['images', 'downloads', '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) => role === 'pages'
+			? comparePageOrder(byDirectory.get(path.join(directory, a.name)) ?? { pageId: a.name }, byDirectory.get(path.join(directory, b.name)) ?? { pageId: b.name })
+			: 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'
+						: location && entry.name === 'downloads' && owner.kind === 'page' ? 'downloads'
+						: role === 'site' && entry.name === 'site-config' ? 'configuration'
+							: role === 'public' || role === 'site' && entry.name === 'public' ? 'public' : 'extra';
+				if (['images', 'downloads'].includes(childRole)) {
+					const resources = await entriesAt(filename);
+					if (!resources.some(resource => resource.isFile() && (childRole === 'downloads' || /\.(jpe?g|png|svg)$/i.test(resource.name)))) {
+						if (resources.length) issue(owner, `${filename} has no supported files; inspect its unsupported entries in Explorer.`, 'warning', filename);
+						continue;
+					}
+				}
+				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', 'downloads', 'pages', 'site-config', 'public'].includes(entry.name) || role === 'pages')) {
+					issue(child, `This directory is not at a permitted Norna location: ${filename}. Use pages/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', 'downloads'].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 (!['public', 'downloads'].includes(role) && !(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);
+		}
+	}
+
+	// Roles own actions; the adapter only maps these names to native commands.
+	// Future page-owned resources can extend this without image/file guessing.
+	const byId = new Map(items.map(item => [item.id, item]));
+	for (const item of items) {
+		const parent = byId.get(item.parentId);
+		item.actions = [];
+		if (item.kind === 'page') item.actions.push('addPage', 'addImages', 'addAttachments', 'renamePage', 'properties', 'copyPageLink', 'pageReferences', ...(!item.isHome ? ['movePage', 'deletePage'] : []));
+		if (['page', 'incomplete'].includes(item.kind) || item.role === 'configuration' && item.kind === 'directory') {
+			const directory = item.kind === 'directory' ? siteRoot : item.directory;
+			const choices = await getEditorSourceFileChoices({ siteRoot, directory }).catch(() => []);
+			item.missingFiles = choices.filter(choice => path.dirname(choice.filename) === (item.kind === 'directory' ? item.sourcePath : item.directory));
+			for (const choice of item.missingFiles) item.actions.push('add_' + path.basename(choice.filename).replaceAll('.', '_').replaceAll('-', '_'));
+		}
+		if (item.kind === 'directory' && ['pages', 'images'].includes(item.role)) item.actions.push(item.role === 'pages' ? 'addPage' : 'addImages', 'deleteFolder');
+		if (item.kind === 'directory' && item.role === 'downloads') item.actions.push('addAttachments', 'deleteFolder');
+		if (item.kind === 'directory' && item.role === 'public') item.actions.push('newPublicFile', 'addPublicFiles', 'newPublicFolder', 'deleteFolder', ...(item.sourcePath !== path.join(siteRoot, 'public') ? ['renameResource', 'moveResource'] : []));
+		if (item.kind === 'file') {
+			if (parent?.role === 'public') item.actions.push('renameResource', 'replacePublicFile', 'moveResource', 'copyResourceLink', 'resourceReferences', 'deleteFile');
+			else if (parent?.role === 'downloads') item.actions.push('insertAttachment', 'renameResource', 'replaceAttachment', 'resourceReferences', 'copyResourceLink', 'deleteFile');
+			else if (parent?.role === 'images' && /\.(jpe?g|png|svg)$/i.test(item.title)) item.actions.push('insertImage', 'renameResource', 'replaceImage', 'resourceReferences', 'deleteImage');
+			else if (item.removable) item.actions.push('deleteFile');
+		}
+	}
+
+	// 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, problem.severity ?? 'error', problem.path);
+		}
+	}
+	return { ...snapshot, items, problems: owner.issues };
+};