@janga/norna 0.7.27 → 0.7.29

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

@@ -0,0 +1,154 @@
+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)) {
+		if (path.dirname(node.contentPath) !== directory) continue;
+		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) 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 || ['public', 'attachment'].includes(policy.kind) ? 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,81 @@
+import { getSiteAttachments } from './page-attachments.mjs';
+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'), settings); }
+	catch (error) { incomplete.push(error.message); }
+	const generatedRoutes = getGeneratedSiteRoutes({ searchEnabled: settings?.search });
+	const graph = createSiteLinkGraph({ siteUrl: settings?.url, siteStructure: structure, pageDocuments, publicFiles, generatedRoutes, attachments: await getSiteAttachments(structure) });
+	// 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.code === 'ambiguous-attachment') && 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 ['public-file', 'attachment'].includes(reference.resolution?.kind) && reference.resolution.file.filePath === filePath;
+		if (reference.resolution?.kind === 'attachment' && targetPaths.has(reference.resolution.file.ownerPathname)) return true;
+		return targetPaths.has(reference.resolution?.pathname ?? reference.target.pageLookupPathname);
+	}).map(summarizeReference);
+	return { references, incomplete: state.incomplete };
+};

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

@@ -0,0 +1,149 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { verifyDevServer } from './dev-server-identity.mjs';
+import { getEditorPageAddresses } from './editor-page-addresses.mjs';
+
+export const sitePreviewApiVersion = 1;
+const engineRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const queues = new Map();
+const serialize = (key, action) => {
+	const task = (queues.get(key) ?? Promise.resolve()).catch(() => {}).then(action);
+	queues.set(key, task);
+	void task.finally(() => { if (queues.get(key) === task) queues.delete(key); }).catch(() => {});
+	return task;
+};
+const readState = async root => {
+	try { return JSON.parse(await readFile(path.join(root, '.norna/dev/state.json'), 'utf8')); }
+	catch (error) { if (error.code === 'ENOENT') return null; throw new Error('The preview server record is unreadable. Inspect Show Preview Log before restarting.', { cause: error }); }
+};
+const registryEntry = async siteRoot => {
+	let registry;
+	try { registry = await import(pathToFileURL(path.join(engineRoot, 'scripts/review-environment-registry.mjs')).href); }
+	catch (error) { if (error.code === 'ERR_MODULE_NOT_FOUND') return null; throw error; }
+	for (const [target, definition] of Object.entries(registry.reviewEnvironments)) {
+		const root = await realpath(path.join(engineRoot, definition.siteDirectory)).catch(() => null);
+		if (root === siteRoot) return { target, ...definition };
+	}
+	return null;
+};
+export const getEditorPreviewConfiguration = async ({ siteRoot, environment = process.env }) => {
+	const root = await realpath(siteRoot);
+	const registered = await registryEntry(root);
+	const value = registered ? String(registered.port) : environment.NORNA_DEV_PORT ?? '4321';
+	const port = /^\d+$/.test(value) ? Number(value) : NaN;
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('NORNA_DEV_PORT must be an integer from 1 through 65535. Correct the VS Code launch environment and restart VS Code.');
+	return { siteRoot: root, port, registered, source: registered ? `review registry (${registered.target})` : environment.NORNA_DEV_PORT === undefined ? 'default' : 'NORNA_DEV_PORT' };
+};
+export const getEditorPreviewStatus = async ({ siteRoot }) => {
+	const root = await realpath(siteRoot);
+	const state = await readState(root);
+	return { state, verified: await verifyDevServer(state, root) };
+};
+export const getEditorPreviewLog = async ({ siteRoot }) => {
+	const root = await realpath(siteRoot);
+	const files = ['dev/preparation.log', '.astro/dev.log', 'dev/state.json'];
+	const logs = await Promise.all(files.map(async name => {
+		try { return `${name}\n${(await readFile(path.join(root, '.norna', name), 'utf8')).slice(-64000)}`; }
+		catch (error) { if (error.code === 'ENOENT') return ''; throw error; }
+	}));
+	return logs.filter(Boolean).join('\n\n') || 'No preview log exists for this site yet.';
+};
+const runManager = (config, operation, { token, environment, onOutput = () => {} } = {}) => new Promise((resolve, reject) => {
+	const args = config.registered
+		? [path.join(engineRoot, 'scripts/review-environments.mjs'), operation === 'stop' ? 'stop' : 'start', config.registered.target]
+		: [path.join(engineRoot, 'bin/norna.mjs'), '--site-dir', config.siteRoot, operation === 'stop' ? 'dev:stop' : 'dev:local'];
+	const env = { ...process.env, ...environment, NORNA_DEV_PORT: String(config.port), NORNA_SITE_DIR: config.siteRoot,
+		NORNA_NO_OPEN: '1', NORNA_DEV_NO_RESTART: '1', ELECTRON_RUN_AS_NODE: '1' };
+	// The extension may itself have been launched while another site was selected.
+	delete env.NORNA_INTERNAL_STATE_DIR;
+	delete env.NORNA_INVOCATION_ROOT;
+	delete env.NORNA_DEV_EXPECT_TOKEN;
+	delete env.NORNA_DEV_START_TOKEN;
+	if (operation === 'stop') env.NORNA_DEV_EXPECT_TOKEN = token;
+	else env.NORNA_DEV_START_TOKEN = token;
+	const child = spawn(process.execPath, args, { cwd: engineRoot, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+	let output = '';
+	const capture = chunk => { output = (output + chunk).slice(-64000); onOutput(String(chunk)); };
+	child.stdout.on('data', capture); child.stderr.on('data', capture);
+	child.once('error', reject);
+	child.once('exit', code => code === 0 ? resolve() : reject(new Error(`Preview ${operation} failed. ${output.replace(/\n\s+at [\s\S]*$/, '').trim().slice(-2500) || 'Show Preview Log for details.'}`)));
+});
+const portOccupied = (port, host) => new Promise((resolve, reject) => {
+	const socket = net.connect({ port, host });
+	socket.once('connect', () => { socket.destroy(); resolve(true); });
+	socket.once('error', error => { socket.destroy(); ['ECONNREFUSED', 'EADDRNOTAVAIL', 'ENETUNREACH', 'EHOSTUNREACH'].includes(error.code) ? resolve(false) : reject(error); });
+	socket.setTimeout(1000, () => { socket.destroy(); resolve(true); });
+});
+const cancelled = signal => { if (signal?.aborted) throw new Error('Preview cancelled.'); };
+const stopVerified = async (config, state, options) => {
+	if (!(await verifyDevServer(state, config.siteRoot))) throw new Error('Cannot verify this site’s preview server. No process was stopped. Use Show Preview Log to inspect its record.');
+	if (config.registered && config.registered.port !== state.port) throw new Error('The registered port differs from the tracked server. Restore its registry port before stopping through the registered review command.');
+	await runManager({ ...config, port: state.port }, 'stop', { ...options, token: state.token });
+};
+export const stopEditorSitePreview = async (options) => {
+	const root = await realpath(options.siteRoot);
+	return serialize(root, async () => {
+		const state = await readState(root);
+		if (!state) return { stopped: false };
+		await stopVerified({ siteRoot: root, registered: await registryEntry(root) }, state, options);
+		return { stopped: true };
+	});
+};
+export const startEditorSitePreview = async (options) => {
+	const config = await getEditorPreviewConfiguration(options);
+	return serialize(config.siteRoot, async () => {
+		cancelled(options.signal);
+		// Read saved sources now, after any explicit Save Site action.
+		const addresses = await getEditorPageAddresses({ siteRoot: config.siteRoot, sourcePath: options.sourcePath ?? path.join(config.siteRoot, 'root/content.md') });
+		if (!addresses.webAddress || addresses.incomplete.length) throw new Error(`Repair the site before previewing it. ${addresses.incomplete.join('\n')}`);
+		let state = await readState(config.siteRoot);
+		let created = false;
+		if (await verifyDevServer(state, config.siteRoot)) {
+			if (state.port !== config.port) throw new Error(`This site is already running on port ${state.port}, but ${config.source} selects ${config.port}. Use Stop Preview Server before starting on the new port.`);
+			if (state.mode !== 'local') throw new Error('This site is running in LAN mode. Stop that server explicitly before starting a local preview.');
+		} else {
+			if (state) throw new Error('The tracked preview server cannot be verified. It may be stopped or belong to an older engine. Inspect Show Preview Log and stop/restart it through the site’s dev commands; preview did not stop any process.');
+			if (await portOccupied(config.port, '127.0.0.1') || await portOccupied(config.port, '::1')) throw new Error(`Port ${config.port} is used by another or unverified server. Stop it yourself or configure NORNA_DEV_PORT in the VS Code launch environment. No port fallback was attempted.`);
+			cancelled(options.signal);
+			const token = randomUUID();
+			try {
+				await runManager(config, 'start', { ...options, token });
+				state = await readState(config.siteRoot);
+				if (state?.token !== token || !(await verifyDevServer(state, config.siteRoot))) throw new Error('The new preview server did not provide a matching site identity. Inspect Show Preview Log.');
+				created = true;
+			} catch (error) {
+				const failed = await readState(config.siteRoot);
+				if (failed?.token === token && await verifyDevServer(failed, config.siteRoot)) {
+					try { await stopVerified(config, failed, options); } catch (cleanup) { throw new Error(`${error.message}\nCleanup failed: ${cleanup.message}`); }
+				}
+				throw error;
+			}
+		}
+		const url = new URL(addresses.webAddress);
+		url.protocol = 'http:'; url.hostname = '127.0.0.1'; url.port = String(state.port);
+		try {
+			cancelled(options.signal);
+			const timeout = AbortSignal.timeout(30_000);
+			const signal = options.signal ? AbortSignal.any([timeout, options.signal]) : timeout;
+			const response = await fetch(url, { signal, redirect: 'manual' });
+			await response.arrayBuffer();
+			if (!response.ok) throw new Error(`The preview page returned HTTP ${response.status}: ${url.href}. Repair the page and use Show Preview Log for details.`);
+			cancelled(options.signal);
+			if (!(await verifyDevServer(state, config.siteRoot))) throw new Error('The preview server identity changed while loading the page. No browser was opened.');
+		} catch (failure) {
+			const message = options.signal?.aborted ? 'Preview cancelled.'
+				: failure.name === 'TimeoutError' ? `Timed out loading the preview page ${url.href}. Use Show Preview Log.`
+				: failure.message;
+			if (created) {
+				try { await stopVerified(config, state, options); }
+				catch (cleanup) { throw new Error(`${message}\nCleanup failed: ${cleanup.message} Use Stop Preview Server after inspecting the log.`); }
+			}
+			throw new Error(message, { cause: failure });
+		}
+		return { url: url.href, reused: !created, siteRoot: config.siteRoot, port: state.port };
+	});
+};

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

@@ -0,0 +1,158 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getMarkdownHeadings, slugifyAsciiIdentifier } from './heading-ids.mjs';
+import { parsePageDirectoryPath } from './page-model.mjs';
+import { splitPageMarkdownSource } from './page-markdown.mjs';
+import { siteSchema } from './schema-definitions.mjs';
+import { getSiteSourcePaths, homePageDirectory } from './site-conventions.mjs';
+import { createSiteNode, escapeMarkdownHeading, planSiteNodeCreation } from './site-node-create.mjs';
+import { getSiteStructure } from './site-structure.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+import { changeYamlField } from './yaml-source-edit.mjs';
+import { readEditorLinkState } from './editor-site-links.mjs';
+import { readSiteEditingTree } from './editor-site-editing-tree.mjs';
+
+// Optional capability: older engines keep IntelliSense without exposing writes
+// through a site-tree API whose contract they do not implement.
+export const siteTreeApiVersion = 1;
+export const siteFileTreeApiVersion = 1;
+export const sitePageFormApiVersion = 1;
+export const sitePageOrderApiVersion = 1;
+export { siteTreeEditingApiVersion, getEditorSourceFileChoices, planEditorSourceFileCreation, createEditorSourceFile } from './editor-source-files.mjs';
+export { createSiteNode, planSiteNodeCreation, slugifyAsciiIdentifier };
+export { siteFileOperationsApiVersion, siteRemovalApiVersion, planEditorImageCopy, planEditorRemoval, getEditorImageUsage, createEditorImageAppend, createEditorImageBatchAppend } from './editor-site-files.mjs';
+export { getEditorIncomingLinks } from './editor-site-links.mjs';
+export { siteAddressApiVersion, sitePageAddressOptionsApiVersion, getEditorPageAddresses, planEditorPageAddress, applyEditorPageAddress } from './editor-page-addresses.mjs';
+export { sitePagePlacementApiVersion, sitePagePlacementOptionsApiVersion, planEditorPagePlacement, applyEditorPagePlacement } from './editor-page-placement.mjs';
+
+const sourceParts = (source, kind) => {
+	const split = splitPageMarkdownSource(source);
+	if (split.frontmatterUnclosed) throw new Error('Close the YAML frontmatter with --- before editing page information.');
+	const lines = source.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+	const bodyLine = split.lineOffset;
+	return {
+		yaml: bodyLine ? lines.slice(1, bodyLine - 1).join('') : '',
+		offset: bodyLine ? lines[0].length : 0,
+		body: split.body,
+		bodyLine,
+	};
+};
+
+const parseInformation = async ({ source, kind, isHome, sourcePath }) => {
+	const parts = sourceParts(source, kind);
+	const data = parseYamlConfig(parts.yaml, sourcePath, { schema: siteSchema });
+	const { headings } = await getMarkdownHeadings(parts.body);
+	const titles = headings.filter(({ depth }) => depth === 1);
+	if (titles.length !== 1) throw new Error('Keep exactly one Markdown H1 title in this page before editing its information.');
+	if (isHome && data.navigation?.listed === false) throw new Error('Home must remain listed. Remove navigation.listed: false.');
+	return {
+		title: titles[0].title,
+		description: data.page?.description ?? '',
+		listed: data.navigation?.listed !== false,
+		aliases: data.page?.aliases ?? [],
+		listChildren: data.page?.listChildren === true,
+		titleLine: parts.bodyLine + titles[0].line - 1,
+		titleLineCount: titles[0].source.split('\n').length,
+	};
+};
+
+export const getSiteNodeInformation = async (input) => {
+	try {
+		return { ...await parseInformation(input), problem: null };
+	} catch (error) {
+		return { title: input.fallbackTitle ?? path.basename(path.dirname(input.sourcePath)),
+			description: '', listed: true, aliases: [], problem: error.message };
+	}
+};
+
+export const readSiteTree = async ({ siteRoot, sources = new Map(), cache = new Map() }) => {
+	const readSource = (filename) => sources.has(filename) ? sources.get(filename) : readFile(filename, 'utf8');
+	const structure = await getSiteStructure({ siteRoot, tolerant: true, readSource });
+	const nodes = [];
+	const used = new Set();
+	for (const node of structure.nodes) {
+		const sourcePath = node.contentPath ?? node.categoryPath;
+		used.add(sourcePath);
+		let information;
+		try {
+			const source = await readSource(sourcePath);
+			const previous = cache.get(sourcePath);
+			information = previous?.source === source ? previous.information : await getSiteNodeInformation({
+				kind: node.kind, isHome: node.isHome, source, sourcePath, fallbackTitle: node.label ?? node.pageId,
+			});
+			cache.set(sourcePath, { source, information });
+		} catch (error) {
+			information = { title: node.label ?? node.pageId, listed: true, aliases: [], problem: error.message };
+		}
+		nodes.push({ ...node, ...information, sourcePath, url: node.isHome ? '/' : `/${node.pagePath}/`,
+			problem: information.problem ?? node.problems?.[0] ?? null });
+	}
+	for (const filename of cache.keys()) if (!used.has(filename)) cache.delete(filename);
+	return { nodes, problems: [...structure.problems, ...structure.warnings.map(warning => ({ ...warning, severity: 'warning' }))] };
+};
+
+// One physical projection preserves resources and repairable entries even when
+// the logical structure cannot be read. The logical page API remains separate.
+export const readSiteFileTree = async (options) => {
+	const siteRoot = path.resolve(options.siteRoot);
+	const snapshot = await readSiteTree({ ...options, siteRoot }).catch((error) => ({
+		nodes: [], problems: [{ path: siteRoot, message: error.message }],
+	}));
+	return readSiteEditingTree({ ...options, siteRoot, snapshot, getInformation: getSiteNodeInformation });
+};
+
+export const editSiteNodeInformation = async ({ siteRoot, sourcePath, source, field, value, sources = new Map() }) => {
+	const relative = path.relative(getSiteSourcePaths(siteRoot).pages, sourcePath).split(path.sep).join('/');
+	const filename = path.posix.basename(relative);
+	if (filename !== 'content.md') throw new Error('Choose a page content.md source file.');
+	const pageDirectory = path.resolve(sourcePath) === getSiteSourcePaths(path.resolve(siteRoot)).content
+		? homePageDirectory : path.posix.dirname(relative);
+	parsePageDirectoryPath(pageDirectory);
+	const kind = 'page';
+	const isHome = pageDirectory === homePageDirectory;
+	const info = await parseInformation({ source, kind, isHome, sourcePath });
+	const allowed = ['title', 'description', 'listed', 'aliases', 'listChildren'];
+	if (!allowed.includes(field)) throw new Error('This information field is read-only.');
+	if (field === 'aliases') {
+		if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) throw new Error('Enter additional addresses as site-relative paths, such as /old-guide/.');
+	} else if (field === 'listed' || field === 'listChildren') {
+		if (typeof value !== 'boolean') throw new Error(field === 'listed' ? 'Choose whether this page is listed in navigation.' : 'Choose whether to append the list of child pages.');
+		if (field === 'listed' && isHome && !value) throw new Error('Home must remain listed.');
+	} else {
+		if (typeof value !== 'string' || /[\r\n]/.test(value)) throw new Error('Use a single line of text.');
+		value = value.trim();
+		if (field === 'title' && !value) throw new Error('Enter a title.');
+	}
+	if (info[field] === value) return [];
+	const eol = source.includes('\r\n') ? '\r\n' : '\n';
+	if (field === 'title') {
+		const lines = source.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+		const start = lines.slice(0, info.titleLine).join('').length;
+		const original = lines.slice(info.titleLine, info.titleLine + info.titleLineCount).join('');
+		return [{ start, end: start + original.replace(/\r?\n$/, '').length, text: `# ${escapeMarkdownHeading(value)}` }];
+	}
+	const parts = sourceParts(source, kind);
+	const keys = field === 'listed' ? ['navigation', 'listed'] : ['page', field === 'aliases' ? 'aliases' : field === 'listChildren' ? 'listChildren' : 'description'];
+	const yaml = changeYamlField(parts.yaml, keys, (field === 'description' && !value) || (field === 'aliases' && !value.length) || (field === 'listChildren' && !value) ? undefined : value, eol);
+	const next = parts.bodyLine ? !yaml.trim() ? source.slice(parts.offset + parts.yaml.length).replace(/^---[ \t]*(?:\r?\n|$)/, '')
+			: source.slice(0, parts.offset) + yaml + source.slice(parts.offset + parts.yaml.length)
+			: `---${eol}${yaml}---${eol}${eol}${source}`;
+	// Validate the complete result before offering it to the editor.
+	await parseInformation({ source: next, kind, isHome, sourcePath });
+	if (field === 'aliases') {
+		const state = await readEditorLinkState({ siteRoot, sources: new Map([...sources, [sourcePath, next]]) });
+		if (state.incomplete.length) throw new Error(`Additional addresses could not be checked. ${state.incomplete.join('\n')}`);
+	}
+	let start = 0;
+	while (start < source.length && start < next.length && source[start] === next[start]) start++;
+	let end = source.length;
+	let nextEnd = next.length;
+	while (end > start && nextEnd > start && source[end - 1] === next[nextEnd - 1]) { end--; nextEnd--; }
+	return [{ start, end, text: next.slice(start, nextEnd) }];
+};
+
+export { siteResourceActionsApiVersion, getEditorResourceReferences, planEditorResourceRename, planEditorPublicCreation, planEditorFolderRemoval, getEditorResourceAddress } from './editor-resource-actions.mjs';
+
+export { siteAttachmentsApiVersion, planEditorAttachmentCopy, createEditorAttachmentInsertion } from './editor-attachments.mjs';
+
+export { sitePreviewApiVersion, getEditorPreviewConfiguration, getEditorPreviewStatus, getEditorPreviewLog, startEditorSitePreview, stopEditorSitePreview } from './editor-site-preview.mjs';

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

@@ -0,0 +1,87 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import { lstat, mkdir, open, rmdir, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { getSourcePageLocation, getSourceFileDefinition, sourceFileDefinitions } from './source-files.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+import { checkedPath } from './editor-site-files.mjs';
+import { escapeMarkdownHeading } from './site-node-create.mjs';
+
+export const siteTreeEditingApiVersion = 1;
+const stat = (filename) => lstat(filename).catch((error) => {
+	if (error.code === 'ENOENT') return null;
+	throw error;
+});
+
+export const editorPageLocation = getSourcePageLocation;
+export const editorSourceDefinition = getSourceFileDefinition;
+
+export const getEditorSourceFileChoices = async ({ siteRoot, directory }) => {
+	siteRoot = path.resolve(siteRoot);
+	directory = await checkedPath(siteRoot, directory);
+	const location = editorPageLocation(siteRoot, directory);
+	const directoryInfo = await stat(directory);
+	if ((!location && directory !== siteRoot) || (!directoryInfo?.isDirectory() && !(location?.isHome && !directoryInfo))) {
+		throw new Error('Select an existing page directory at a permitted location in this site.');
+	}
+	const content = await stat(path.join(directory, 'content.md'));
+	const names = location ? sourceFileDefinitions.filter((entry) => entry.location === 'page' && (entry.input === 'title' ? !content : content?.isFile() || location.isHome)).map((entry) => entry.name) : [];
+	if (directory === siteRoot || location?.isHome) {
+		names.push(...sourceFileDefinitions.filter((entry) => entry.location === 'site-config').map((entry) => `site-config/${entry.name}`));
+	}
+	if (directory === siteRoot) names.push('root/content.md', 'root/tree-theme.yaml');
+	const choices = [];
+	for (const name of names) {
+		const filename = path.join(name.startsWith('site-config/') || name.startsWith('root/') ? siteRoot : directory, name);
+		if (await stat(filename)) continue;
+		// A file or symlink occupying site-config must be repaired, not replaced.
+		const parent = await stat(path.dirname(filename));
+		if (parent && (!parent.isDirectory() || parent.isSymbolicLink())) continue;
+		const definition = editorSourceDefinition(siteRoot, filename);
+		choices.push({ filename, name, description: definition.description, input: definition.input,
+			required: Boolean(definition.required), effect: definition.description });
+	}
+	return choices;
+};
+
+export const planEditorSourceFileCreation = async ({ siteRoot, directory, filename, value }) => {
+	siteRoot = path.resolve(siteRoot);
+	const choices = await getEditorSourceFileChoices({ siteRoot, directory });
+	const choice = choices.find((entry) => entry.filename === filename);
+	if (!choice) throw new Error('This file already exists or is not allowed here. Refresh Site Tree and review Add again.');
+	await checkedPath(siteRoot, filename);
+	const definition = editorSourceDefinition(siteRoot, filename);
+	let text = definition.text;
+	if (definition.input) {
+		if (typeof value !== 'string' || !value.trim() || /[\r\n]/.test(value)) throw new Error('Enter a non-empty, single line of text.');
+		text = definition.input === 'title' ? `# ${escapeMarkdownHeading(value.trim())}\n`
+			: `${definition.schemaKind === 'config' ? 'sourceFormat: 2\n' : ''}${definition.input}: ${JSON.stringify(value.trim())}\n`;
+	}
+	if (definition.schema) parseYamlConfig(text, filename, { schema: definition.schema });
+	const identity = async (location) => { const entry = await stat(location); return entry ? [entry.dev, entry.ino] : null; };
+	return { siteRoot, directory: path.resolve(directory), filename, value, text,
+		fingerprint: JSON.stringify([await identity(siteRoot), await identity(directory), filename, text]) };
+};
+
+export const createEditorSourceFile = async (plan) => {
+	const current = await planEditorSourceFileCreation(plan);
+	if (plan.fingerprint !== current.fingerprint) throw new Error('The selected directory changed. Review Add again.');
+	const parent = path.dirname(current.filename);
+	let createdDirectory = false;
+	let handle;
+	try {
+		if (!await stat(parent)) { await mkdir(parent); createdDirectory = true; }
+		await checkedPath(current.siteRoot, current.filename);
+		handle = await open(current.filename, 'wx');
+		await handle.writeFile(current.text, 'utf8');
+	} catch (error) {
+		if (handle) {
+			const owned = await handle.stat();
+			await handle.close(); handle = null;
+			const existing = await stat(current.filename);
+			if (existing?.ino === owned.ino && existing?.dev === owned.dev) await unlink(current.filename);
+		}
+		if (createdDirectory) await rmdir(parent).catch(() => {});
+		throw error;
+	} finally { await handle?.close(); }
+	return { sourcePath: current.filename };
+};