@janga/norna 0.7.23 → 0.7.25

package/scripts/build-site.mjs

@@ -14,3 +14,4 @@ await runScript('scripts/sync-content-sections.mjs', ['--check']);
 await runScript('scripts/sync-site-public.mjs');
 await runScript('scripts/generate-images.mjs');
 await runAstroInherit(['build']);
+await runScript('scripts/generate-search-index.mjs');

package/scripts/check-config.mjs

@@ -1,7 +1,8 @@
 import path from 'node:path';
 import { siteConfigLabel, sitePagesDir, sitePublicLabel, siteThemeLabel } from './lib/site-paths.mjs';
 import { getLogoAssets, getPublicAssetInspection } from './lib/logo-assets.mjs';
-import { logoAssetFilenames } from './lib/public-asset-conventions.mjs';
+import { logoAssetFilenames, socialImageAssetFilenames } from './lib/public-asset-conventions.mjs';
+import { getSocialImageAssets } from './lib/social-image-assets.mjs';
 import { readSitewideContent } from './lib/sitewide-content.mjs';
 import { assertSectionBackgroundPatternCompatibility } from './lib/presentation.mjs';
 import { readThemeConfig, validatePageThemeFiles } from './lib/theme-config.mjs';
@@ -43,6 +44,7 @@ try {
 		}
 	}
 	const logoAssets = getLogoAssets();
+	const socialImageAssets = getSocialImageAssets();
 	const publicAssetInspection = getPublicAssetInspection();
 	const logoAssetPaths = logoAssetFilenames.map((filename) => `${sitePublicLabel}/${filename}`);
 	for (const issue of publicAssetInspection.suspicious) {
@@ -56,6 +58,13 @@ try {
 		].join('\n'));
 	}
 
+	if (socialImageAssets.length > 1) {
+		throw new Error([
+			`Found multiple social sharing images in ${sitePublicLabel}. Keep exactly one of ${socialImageAssetFilenames.join(', ')}.`,
+			...socialImageAssets.map(({ filename }) => `- ${sitePublicLabel}/${filename}`),
+		].join('\n'));
+	}
+
 	if (logoAssets.length === 0) {
 		if (sitewideContent.logo) {
 			throw new Error(`Site-wide logo is configured, but no logo file was found. Add exactly one of ${logoAssetPaths.join(', ')}, or remove logo.`);
@@ -67,6 +76,11 @@ try {
 	console.log('Config check passed.');
 	console.log(`Site URL: ${projectConfig.site.url}`);
 	console.log(`Base path: ${projectConfig.site.basePath}`);
+	const editLinkDestinations = [
+		projectConfig.editLink?.localEditor ? `local ${projectConfig.editLink.localEditor}` : null,
+		projectConfig.editLink?.baseUrl ? `remote ${projectConfig.editLink.baseUrl}` : null,
+	].filter(Boolean);
+	console.log(`Edit links: ${editLinkDestinations.join(', ') || '(disabled)'}`);
 	console.log(`Theme preset: ${themeConfig.preset ?? '(none)'}`);
 	console.log(`Page width: ${projectConfig.layout.pageWidth}`);
 	console.log(`Gutter: desktop ${projectConfig.layout.gutter.desktop}, mobile ${projectConfig.layout.gutter.mobile}`);
@@ -81,6 +95,7 @@ try {
 	console.log(`Font family: ${projectConfig.typography.fontFamily}`);
 	console.log(`Language: ${projectConfig.locale.lang}`);
 	console.log(`Navigation mode: ${projectConfig.navigation.mode}`);
+	console.log(`Static search: ${projectConfig.search.enabled ? 'enabled' : 'disabled'}`);
 	console.log(`Scroll behavior: ${projectConfig.navigation.scrollBehavior}`);
 } catch (error) {
 	console.error('Config check failed.');

package/scripts/dev-local.mjs

@@ -5,7 +5,12 @@ import { networkInterfaces } from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { getAstroArgs, runAstroInherit } from './lib/astro-command.mjs';
-import { astroCacheDir, engineRoot, siteProjectRoot } from './lib/site-paths.mjs';
+import {
+	astroCacheDir,
+	engineRoot,
+	siteProjectRoot,
+	siteStateDir,
+} from './lib/site-paths.mjs';
 
 const execFileAsync = promisify(execFile);
 
@@ -27,7 +32,10 @@ const probeUrls = [
 	`http://localhost:${port}${projectConfig.site.basePath}`,
 ];
 const skipOpen = process.env.NORNA_NO_OPEN === '1';
-const statePath = path.join(astroCacheDir, 'dev-local.json');
+const stateDirectory = path.join(siteStateDir, 'dev');
+const statePath = path.join(stateDirectory, 'state.json');
+const legacyStatePath = path.join(astroCacheDir, 'dev-local.json');
+const astroStatePath = path.join(astroCacheDir, 'dev.json');
 const logPath = path.join(astroCacheDir, 'dev.log');
 const args = process.argv.slice(2);
 const knownCommands = new Set(['start', 'lan', 'status', 'logs', 'restart', 'stop']);
@@ -51,9 +59,9 @@ const generateImages = async () => execFileAsync(process.execPath, [path.join(en
 	maxBuffer: 1024 * 1024 * 10,
 });
 
-const readState = async () => {
+const readJsonFile = async (filePath) => {
 	try {
-		return JSON.parse(await readFile(statePath, 'utf8'));
+		return JSON.parse(await readFile(filePath, 'utf8'));
 	} catch (error) {
 		if (error.code === 'ENOENT') {
 			return null;
@@ -63,15 +71,34 @@ const readState = async () => {
 	}
 };
 
+const readState = async () => (
+	await readJsonFile(statePath)
+	?? await readJsonFile(legacyStatePath)
+);
+
 const getLanUrls = () => Object.values(networkInterfaces())
 	.flat()
 	.filter((network) => network?.family === 'IPv4' && !network.internal)
 	.map((network) => `http://${network.address}:${port}${projectConfig.site.basePath}`);
 
 const writeState = async (host) => {
-	await mkdir(path.dirname(statePath), { recursive: true });
+	const astroState = await readJsonFile(astroStatePath);
+	let pid = astroState?.port === port && isProcessAlive(astroState.pid)
+		? astroState.pid
+		: null;
+	if (!Number.isInteger(pid)) {
+		const listeningPids = await getPortPids({ required: false });
+		pid = listeningPids?.length === 1 ? listeningPids[0] : null;
+	}
+
+	if (!Number.isInteger(pid)) {
+		throw new Error(`The dev server started at ${localUrl}, but Norna could not record its process. Stop the process on port ${port} before starting it again.`);
+	}
+
+	await mkdir(stateDirectory, { recursive: true });
 	await writeFile(statePath, `${JSON.stringify({
 		port,
+		pid,
 		host,
 		mode: host === '0.0.0.0' ? 'lan' : 'local',
 		url: localUrl,
@@ -81,6 +108,8 @@ const writeState = async (host) => {
 
 const removeState = async () => {
 	await rm(statePath, { force: true });
+	await rm(legacyStatePath, { force: true });
+	await rm(stateDirectory, { recursive: true, force: true });
 };
 
 const readDevLog = async () => {
@@ -161,6 +190,16 @@ const sleep = (milliseconds) => new Promise((resolve) => {
 	setTimeout(resolve, milliseconds);
 });
 
+const isProcessAlive = (pid) => {
+	if (!Number.isInteger(pid)) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === 'EPERM';
+	}
+};
+
 const isServerReachable = async () => {
 	for (const probeUrl of probeUrls) {
 		try {
@@ -213,7 +252,7 @@ const parseWindowsPortPids = (stdout) => [...new Set(
 		.filter(Number.isInteger),
 )];
 
-const getPortPids = async () => {
+const getPortPids = async ({ required = true } = {}) => {
 	try {
 		if (process.platform === 'win32') {
 			const { stdout } = await execFileAsync('powershell.exe', [
@@ -234,6 +273,7 @@ const getPortPids = async () => {
 	} catch (error) {
 		if (error.code === 1) return [];
 		if (error.code === 'ENOENT') {
+			if (!required) return null;
 			const commandName = process.platform === 'win32' ? 'PowerShell' : 'lsof';
 			throw new Error(`Cannot use --kill because ${commandName} is not available. Stop the process on port ${port} manually, then rerun the command.`);
 		}
@@ -273,6 +313,31 @@ const terminatePortProcesses = async (host) => {
 	}
 };
 
+const terminateTrackedProcess = async (state, host) => {
+	if (state?.port !== port || !Number.isInteger(state.pid)) return false;
+	if (!isProcessAlive(state.pid)) return false;
+
+	const listeningPids = await getPortPids({ required: false });
+	if (listeningPids && !listeningPids.includes(state.pid)) return false;
+	if (!listeningPids && !(await isServerReachable())) return false;
+
+	try {
+		process.kill(state.pid, 'SIGTERM');
+	} catch (error) {
+		if (error.code !== 'ESRCH') throw error;
+	}
+
+	if (await waitForPortToBeFree(host)) return true;
+
+	try {
+		process.kill(state.pid, 'SIGKILL');
+	} catch (error) {
+		if (error.code !== 'ESRCH') throw error;
+	}
+
+	return waitForPortToBeFree(host);
+};
+
 const openBrowser = async () => {
 	if (skipOpen) {
 		console.log(`Browser open skipped. Open ${localUrl}`);
@@ -294,10 +359,27 @@ const openBrowser = async () => {
 
 const stopServer = async ({ quiet = false } = {}) => {
 	const state = await readState();
-	const { stdout = '', stderr = '' } = await runAstro(['dev', 'stop']);
-	const stopped = `${stdout}\n${stderr}`.includes('Stopped dev server');
-	if (stopped) await waitForPortToBeFree(state?.host ?? localHost);
-	await removeState();
+	let astroError;
+	let astroOutput = '';
+	try {
+		const { stdout = '', stderr = '' } = await runAstro(['dev', 'stop']);
+		astroOutput = `${stdout}\n${stderr}`;
+	} catch (error) {
+		astroError = error;
+	}
+
+	let stopped = astroOutput.includes('Stopped dev server');
+	if (stopped) {
+		await waitForPortToBeFree(state?.host ?? localHost);
+	} else {
+		stopped = await terminateTrackedProcess(state, state?.host ?? localHost);
+	}
+
+	if (stopped || !(await isServerReachable())) {
+		await removeState();
+	}
+
+	if (astroError && !stopped) throw astroError;
 
 	if (!quiet) {
 		console.log(stopped
@@ -370,7 +452,20 @@ const showStatus = async () => {
 	}
 
 	if (reachable) {
-		console.log(`A server is responding at ${localUrl}, but Astro does not track it for this site.`);
+		const listeningPids = await getPortPids({ required: false });
+		const stateOwnsPort = state?.port === port
+			&& Number.isInteger(state.pid)
+			&& (listeningPids ? listeningPids.includes(state.pid) : isProcessAlive(state.pid));
+		if (stateOwnsPort) {
+			console.log(`dev:${state.mode ?? 'local'} is running at ${localUrl}. Norna retained its process record after Astro cleared its cache.`);
+			if (state.host === '0.0.0.0') {
+				const lanUrls = getLanUrls();
+				if (lanUrls.length > 0) console.log(`On this local network: ${lanUrls.join(', ')}`);
+			}
+			return;
+		}
+
+		console.log(`A server is responding at ${localUrl}, but neither Astro nor Norna tracks it for this site.`);
 		return;
 	}
 

package/scripts/generate-search-index.mjs

@@ -0,0 +1,57 @@
+import { cp, mkdir, readdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import * as pagefind from 'pagefind';
+import projectConfig from './lib/project-config.mjs';
+import {
+	astroDistDir,
+	astroPublicDir,
+} from './lib/site-paths.mjs';
+
+const searchDirectoryName = 'pagefind';
+const distSearchDirectory = path.join(astroDistDir, searchDirectoryName);
+const localSearchDirectory = path.join(astroPublicDir, searchDirectoryName);
+
+if (!projectConfig.search.enabled) {
+	await rm(localSearchDirectory, { force: true, recursive: true });
+	console.log('Static search is disabled.');
+} else {
+	await rm(distSearchDirectory, { force: true, recursive: true });
+
+	try {
+		const { errors: createErrors, index } = await pagefind.createIndex();
+		if (!index || createErrors.length > 0) {
+			throw new Error(createErrors.join('\n') || 'Pagefind did not create an index.');
+		}
+
+		const { errors: indexingErrors, page_count: scannedPageCount } = await index.addDirectory({
+			path: astroDistDir,
+		});
+		if (indexingErrors.length > 0) throw new Error(indexingErrors.join('\n'));
+		if (scannedPageCount === 0) {
+			throw new Error('No rendered pages contained searchable editorial content.');
+		}
+
+		const { errors: writeErrors } = await index.writeFiles({
+			outputPath: distSearchDirectory,
+		});
+		if (writeErrors.length > 0) throw new Error(writeErrors.join('\n'));
+		const fragmentDirectory = path.join(distSearchDirectory, 'fragment');
+		const indexedPageCount = (await readdir(fragmentDirectory))
+			.filter((filename) => filename.endsWith('.pf_fragment'))
+			.length;
+		if (indexedPageCount === 0) {
+			throw new Error('No rendered pages contained searchable editorial content.');
+		}
+
+		await rm(localSearchDirectory, { force: true, recursive: true });
+		await mkdir(astroPublicDir, { recursive: true });
+		await cp(distSearchDirectory, localSearchDirectory, { recursive: true });
+
+		console.log(`Generated static search index for ${indexedPageCount} page${indexedPageCount === 1 ? '' : 's'}.`);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Could not generate the static search index. ${message}`);
+	} finally {
+		await pagefind.close();
+	}
+}

package/scripts/init-site.mjs

@@ -18,6 +18,7 @@ dist/
 # generated site state
 **/.norna/public/
 **/.norna/.astro/
+**/.norna/dev/
 
 # legacy Astro cache location
 .astro/
@@ -40,6 +41,7 @@ pnpm-debug.log*
 `;
 const siteGitignore = `.norna/public/
 .norna/.astro/
+.norna/dev/
 `;
 
 const usage = `
@@ -165,6 +167,7 @@ const nornaScripts = {
 	'norna:config:check': cliCommand('config:check'),
 	'norna:content:check': cliCommand('content:check'),
 	'norna:sync': cliCommand('content:sync'),
+	'norna:navigation:review': cliCommand('navigation:review'),
 	'norna:theme:presets': cliCommand('theme:presets'),
 	'norna:theme:export': cliCommand('theme:export'),
 	'norna:typography:profiles': cliCommand('typography profiles'),

package/scripts/lib/code-fence-metadata.mjs

@@ -0,0 +1,228 @@
+const titlePrefix = 'title="';
+const lineSelectorPattern = /^\{(\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*)\}$/;
+
+const invalidMetadata = (message, fix) => ({
+	error: {
+		code: 'invalid-code-fence-metadata',
+		fix,
+		message,
+	},
+});
+
+const parseTitle = (source) => {
+	let title = '';
+	let index = titlePrefix.length;
+
+	while (index < source.length) {
+		const character = source[index];
+		if (character === '"') {
+			return {
+				rest: source.slice(index + 1),
+				title,
+			};
+		}
+
+		if (character === '\\') {
+			const escaped = source[index + 1];
+			if (escaped !== '"' && escaped !== '\\') {
+				return invalidMetadata(
+					`Code title contains unsupported escape "\\${escaped ?? ''}".`,
+					'Only escape a double quote (\\") or backslash (\\\\) inside the title.',
+				);
+			}
+			title += escaped;
+			index += 2;
+			continue;
+		}
+
+		title += character;
+		index += 1;
+	}
+
+	return invalidMetadata(
+		'Code title is missing its closing double quote.',
+		'Close the title, for example title="src/config.js".',
+	);
+};
+
+const parseHighlightedLines = (selector, lineCount) => {
+	const match = selector.match(lineSelectorPattern);
+	if (!match) {
+		return invalidMetadata(
+			`Invalid code line selector "${selector}".`,
+			'Use positive line numbers and inclusive ranges without spaces, for example {2,4-6}.',
+		);
+	}
+
+	const highlightedLines = new Set();
+	for (const part of match[1].split(',')) {
+		const [startSource, endSource = startSource] = part.split('-');
+		const start = Number.parseInt(startSource, 10);
+		const end = Number.parseInt(endSource, 10);
+
+		if (start < 1 || end < start) {
+			return invalidMetadata(
+				`Invalid code line range "${part}".`,
+				'Use positive line numbers with the lower number first, for example {2,4-6}.',
+			);
+		}
+		if (Number.isInteger(lineCount) && end > lineCount) {
+			return invalidMetadata(
+				`Code line selector "${part}" refers to line ${end}, but the block has ${lineCount} ${lineCount === 1 ? 'line' : 'lines'}.`,
+				`Select only lines 1-${lineCount}.`,
+			);
+		}
+
+		for (let line = start; line <= end; line += 1) {
+			if (highlightedLines.has(line)) {
+				return invalidMetadata(
+					`Code line ${line} is selected more than once.`,
+					'Remove overlapping or repeated line numbers from the selector.',
+				);
+			}
+			highlightedLines.add(line);
+		}
+	}
+
+	return { highlightedLines: [...highlightedLines].sort((left, right) => left - right) };
+};
+
+export const parseCodeFenceMetadata = (rawMetadata, options = {}) => {
+	const source = String(rawMetadata ?? '').trim();
+	if (!source) return { highlightedLines: [], title: null };
+
+	let rest = source;
+	let title = null;
+	if (rest.startsWith(titlePrefix)) {
+		const titleResult = parseTitle(rest);
+		if (titleResult.error) return titleResult;
+		if (!titleResult.title.trim()) {
+			return invalidMetadata(
+				'Code title cannot be empty.',
+				'Remove title="" or provide a short filename or label.',
+			);
+		}
+		title = titleResult.title;
+		rest = titleResult.rest;
+		if (rest && !rest.startsWith(' ')) {
+			return invalidMetadata(
+				'Code title must be separated from the line selector by one space.',
+				'Write metadata as title="src/config.js" {2,4-6}.',
+			);
+		}
+		rest = rest.trim();
+	}
+
+	if (!rest) return { highlightedLines: [], title };
+	if (!rest.startsWith('{')) {
+		return invalidMetadata(
+			`Unknown code fence metadata "${rest}".`,
+			'Use an optional title followed by an optional line selector: title="src/config.js" {2,4-6}.',
+		);
+	}
+	if (/^\{[^}]*\}\s+/.test(rest)) {
+		return invalidMetadata(
+			'The code line selector must come after the optional title.',
+			'Write metadata as title="src/config.js" {2,4-6}.',
+		);
+	}
+
+	const linesResult = parseHighlightedLines(rest, options.lineCount);
+	if (linesResult.error) return linesResult;
+	return {
+		highlightedLines: linesResult.highlightedLines,
+		title,
+	};
+};
+
+const formatDiagnostic = ({ error, label, line, offset }) => ({
+	...error,
+	line,
+	message: `${label} line ${line}: ${error.message}`,
+	offset,
+});
+
+export const getCodeFenceMetadataDiagnostics = (tree, options = {}) => {
+	const diagnostics = [];
+	const label = options.label ?? 'Markdown';
+	const lineOffset = options.lineOffset ?? 0;
+	const excludedLanguages = options.excludedLanguages ?? new Set();
+
+	const visit = (node) => {
+		if (!node || typeof node !== 'object') return;
+		if (node.type === 'code' && !excludedLanguages.has(node.lang)) {
+			const metadataWithoutLanguage = typeof node.lang === 'string'
+				&& (node.lang.startsWith('title=') || node.lang.startsWith('{'));
+			const result = metadataWithoutLanguage
+				? invalidMetadata(
+					'Code fence metadata requires a language before it.',
+					'Add a language first, for example ```js title="src/config.js" {2}.',
+				)
+				: parseCodeFenceMetadata(node.meta, {
+				lineCount: String(node.value ?? '').split('\n').length,
+				});
+			if (result.error) {
+				const line = lineOffset + (node.position?.start.line ?? 1);
+				diagnostics.push(formatDiagnostic({
+					error: result.error,
+					label,
+					line,
+					offset: node.position?.start.offset ?? 0,
+				}));
+			}
+		}
+
+		for (const child of node.children ?? []) visit(child);
+	};
+
+	visit(tree);
+	return diagnostics;
+};
+
+const getTransformerMetadata = (context) => {
+	if (!context.meta.nornaCodeFence) {
+		const result = parseCodeFenceMetadata(context.options.meta?.__raw, {
+			lineCount: context.tokens?.length,
+		});
+		if (result.error) throw new Error(`${result.error.message} ${result.error.fix}`);
+		context.meta.nornaCodeFence = result;
+	}
+	return context.meta.nornaCodeFence;
+};
+
+export const nornaCodeFenceTransformer = {
+	name: 'norna-code-fence-metadata',
+	line(node, line) {
+		const metadata = getTransformerMetadata(this);
+		if (!metadata.highlightedLines.includes(line)) return;
+		this.addClassToHast(node, 'norna-code-line-highlighted');
+		node.properties.dataLine = String(line);
+	},
+	pre(node) {
+		const metadata = getTransformerMetadata(this);
+		if (metadata.highlightedLines.length > 0) {
+			this.addClassToHast(node, 'norna-code-has-highlighted-lines');
+		}
+		if (!metadata.title) return;
+
+		return {
+			type: 'element',
+			tagName: 'figure',
+			properties: { className: ['norna-code-example'] },
+			children: [
+					{
+						type: 'element',
+						tagName: 'figcaption',
+						properties: { className: ['norna-code-title'] },
+						children: [{
+							type: 'element',
+							tagName: 'span',
+							properties: { className: ['norna-code-title-text'] },
+							children: [{ type: 'text', value: metadata.title }],
+						}],
+					},
+				node,
+			],
+		};
+	},
+};

package/scripts/lib/edit-source-link.mjs

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const localEditorNames = Object.freeze(['vscode']);
+
+const assertHttpUrl = (value, label) => {
+	if (typeof value !== 'string' || value.trim() === '') {
+		throw new Error(`${label} must be a non-empty absolute URL.`);
+	}
+
+	let url;
+	try {
+		url = new URL(value.trim());
+	} catch {
+		throw new Error(`${label} must be an absolute URL such as "https://github.com/owner/repository/edit/main/".`);
+	}
+
+	if (!['http:', 'https:'].includes(url.protocol)) {
+		throw new Error(`${label} must use http or https.`);
+	}
+	if (url.username || url.password) {
+		throw new Error(`${label} must not contain credentials.`);
+	}
+	if (url.search || url.hash) {
+		throw new Error(`${label} must not contain a query string or fragment.`);
+	}
+
+	return url;
+};
+
+export const normalizeEditLinkBaseUrl = (value, label = 'editLink.baseUrl') => {
+	const url = assertHttpUrl(value, label);
+	if (!url.pathname.endsWith('/')) url.pathname = `${url.pathname}/`;
+	return url.href;
+};
+
+export const getEditSourceUrl = ({ baseUrl, sourcePath }) => {
+	const normalizedBaseUrl = normalizeEditLinkBaseUrl(baseUrl);
+	if (typeof sourcePath !== 'string' || sourcePath.trim() === '') {
+		throw new Error('Edit-source path must be a non-empty project-relative path.');
+	}
+
+	const normalizedSourcePath = sourcePath.trim().replaceAll('\\', '/');
+	const segments = normalizedSourcePath.split('/');
+	if (
+		normalizedSourcePath.startsWith('/')
+		|| segments.some((segment) => segment === '' || segment === '.' || segment === '..')
+	) {
+		throw new Error(`Edit-source path "${sourcePath}" must be a project-relative path without traversal segments.`);
+	}
+
+	const encodedPath = segments.map((segment) => encodeURIComponent(segment)).join('/');
+	return new URL(encodedPath, normalizedBaseUrl).href;
+};
+
+export const isLoopbackHostname = (hostname) => {
+	const normalizedHostname = String(hostname ?? '')
+		.trim()
+		.toLowerCase()
+		.replace(/^\[|\]$/g, '')
+		.replace(/\.$/, '');
+
+	return normalizedHostname === 'localhost'
+		|| normalizedHostname.endsWith('.localhost')
+		|| normalizedHostname === '::1'
+		|| normalizedHostname.startsWith('::ffff:127.')
+		|| /^127(?:\.\d{1,3}){3}$/.test(normalizedHostname);
+};
+
+export const getLocalEditorSourceUrl = ({ editor, sourcePath }) => {
+	if (!localEditorNames.includes(editor)) {
+		throw new Error(`Unknown local editor "${editor}". Use one of: ${localEditorNames.join(', ')}.`);
+	}
+	if (typeof sourcePath !== 'string' || !path.isAbsolute(sourcePath)) {
+		throw new Error('Local editor source path must be absolute.');
+	}
+
+	const fileUrl = pathToFileURL(path.normalize(sourcePath));
+	return `vscode://file${fileUrl.pathname}`;
+};
+
+export const resolveEditSourceTarget = ({
+	baseUrl,
+	development = false,
+	hostname,
+	localEditor,
+	sourceLabel,
+	sourcePath,
+}) => {
+	if (development && localEditor && isLoopbackHostname(hostname)) {
+		return Object.freeze({
+			href: getLocalEditorSourceUrl({ editor: localEditor, sourcePath }),
+			kind: 'local',
+		});
+	}
+	if (!baseUrl) return null;
+
+	return Object.freeze({
+		href: getEditSourceUrl({ baseUrl, sourcePath: sourceLabel }),
+		kind: 'remote',
+	});
+};