@janga/norna 0.7.0 → 0.7.2

package/scripts/dev-local.mjs

@@ -5,18 +5,26 @@ import { networkInterfaces } from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { getAstroArgs, runAstroInherit } from './lib/astro-command.mjs';
+import projectConfig from './lib/project-config.mjs';
 import { astroCacheDir, engineRoot, siteProjectRoot } from './lib/site-paths.mjs';
 
 const execFileAsync = promisify(execFile);
 
 const port = 4321;
-const localHost = 'localhost';
-const localUrl = `http://${localHost}:${port}/`;
-const probeUrls = [localUrl, `http://127.0.0.1:${port}/`, `http://[::1]:${port}/`];
+const localHost = '127.0.0.1';
+const localUrl = `http://${localHost}:${port}${projectConfig.site.basePath}`;
+const probeUrls = [
+	localUrl,
+	`http://localhost:${port}${projectConfig.site.basePath}`,
+];
 const skipOpen = process.env.WALDE_NO_OPEN === '1';
 const statePath = path.join(astroCacheDir, 'dev-local.json');
 const logPath = path.join(astroCacheDir, 'dev.log');
-const command = process.argv[2] ?? 'start';
+const args = process.argv.slice(2);
+const knownCommands = new Set(['start', 'lan', 'status', 'logs', 'restart', 'stop']);
+const command = args.find((arg) => knownCommands.has(arg)) ?? args.find((arg) => !arg.startsWith('-')) ?? 'start';
+const shouldKillBlockingPort = args.includes('--kill');
+const shouldFollowLogs = args.includes('--follow');
 
 const runAstro = async (args, options = {}) => execFileAsync(process.execPath, getAstroArgs(args), {
 	cwd: siteProjectRoot,
@@ -57,7 +65,7 @@ const readState = async () => {
 const getLanUrls = () => Object.values(networkInterfaces())
 	.flat()
 	.filter((network) => network?.family === 'IPv4' && !network.internal)
-	.map((network) => `http://${network.address}:${port}/`);
+	.map((network) => `http://${network.address}:${port}${projectConfig.site.basePath}`);
 
 const writeState = async (pid, host) => {
 	await mkdir(path.dirname(statePath), { recursive: true });
@@ -98,7 +106,7 @@ const isPortFreeOnHost = (loopbackHost) => new Promise((resolve, reject) => {
 });
 
 const isPortFree = async () => {
-	for (const loopbackHost of ['127.0.0.1', '::1']) {
+	for (const loopbackHost of ['127.0.0.1']) {
 		if (!(await isPortFreeOnHost(loopbackHost))) {
 			return false;
 		}
@@ -155,6 +163,35 @@ const waitForPidToStopListening = async (pid) => {
 	return false;
 };
 
+const killPortPids = async (pids) => {
+	for (const pid of pids) {
+		console.log(`Stopping process ${pid} on port ${port}.`);
+		try {
+			process.kill(pid, 'SIGTERM');
+		} catch (error) {
+			if (error.code !== 'ESRCH') {
+				throw error;
+			}
+		}
+	}
+
+	for (const pid of pids) {
+		if (await waitForPidToStopListening(pid)) {
+			continue;
+		}
+
+		console.log(`Process ${pid} did not stop; sending SIGKILL.`);
+		try {
+			process.kill(pid, 'SIGKILL');
+		} catch (error) {
+			if (error.code !== 'ESRCH') {
+				throw error;
+			}
+		}
+		await waitForPidToStopListening(pid);
+	}
+};
+
 const openBrowser = async () => {
 	if (skipOpen) {
 		console.log(`Browser open skipped. Open ${localUrl}`);
@@ -210,12 +247,22 @@ const stopServer = async ({ quiet = false } = {}) => {
 	}
 };
 
-const startServer = async ({ host = localHost, open = true } = {}) => {
+const startServer = async ({ host = localHost, open = true, killBlockingPort = false } = {}) => {
 	await stopServer({ quiet: true });
 
-	const existingPids = await getPortPids();
+	let existingPids = await getPortPids();
 	if (existingPids.length > 0 || !(await isPortFree())) {
-		throw new Error(`Port ${port} is already in use. Stop the process using it, then rerun the dev command.`);
+		if (!killBlockingPort || existingPids.length === 0) {
+			throw new Error(`Port ${port} is already in use. Stop the process using it, then rerun the dev command, or pass --kill.`);
+		}
+
+		await killPortPids(existingPids);
+		await removeState();
+		existingPids = await getPortPids();
+
+		if (existingPids.length > 0 || !(await isPortFree())) {
+			throw new Error(`Port ${port} is still in use after trying to stop ${existingPids.join(', ')}.`);
+		}
 	}
 
 	await syncSitePublic();
@@ -271,9 +318,7 @@ const showStatus = async () => {
 };
 
 const showLogs = async () => {
-	const shouldFollow = process.argv.includes('--follow');
-
-	if (shouldFollow) {
+	if (shouldFollowLogs) {
 		const tail = spawn('tail', ['-n', '80', '-f', logPath], { stdio: 'inherit' });
 		await new Promise((resolve, reject) => {
 			tail.once('exit', resolve);
@@ -296,16 +341,20 @@ const showLogs = async () => {
 };
 
 if (command === 'start') {
-	await startServer({ open: !skipOpen });
+	await startServer({ open: !skipOpen, killBlockingPort: shouldKillBlockingPort });
 } else if (command === 'lan') {
-	await startServer({ host: '0.0.0.0', open: !skipOpen });
+	await startServer({ host: '0.0.0.0', open: !skipOpen, killBlockingPort: shouldKillBlockingPort });
 } else if (command === 'status') {
 	await showStatus();
 } else if (command === 'logs') {
 	await showLogs();
 } else if (command === 'restart') {
 	const state = await readState();
-	await startServer({ host: state?.host === '0.0.0.0' ? '0.0.0.0' : localHost, open: false });
+	await startServer({
+		host: state?.host === '0.0.0.0' ? '0.0.0.0' : localHost,
+		open: false,
+		killBlockingPort: shouldKillBlockingPort,
+	});
 } else if (command === 'stop') {
 	await stopServer();
 } else {

package/scripts/init-site.mjs

@@ -156,7 +156,7 @@ const addGalleryDependency = (packageJson, version) => {
 const addGalleryScripts = (packageJson, scripts, { includePureAliases }) => {
 	packageJson.scripts ??= {};
 	const wantedScripts = {
-		...(includePureAliases ? { dev: 'npm run norna:dev' } : {}),
+		...(includePureAliases ? { dev: 'npm run norna:dev --' } : {}),
 		...scripts,
 		...(includePureAliases ? { build: 'npm run norna:build' } : {}),
 	};

package/scripts/lib/project-config.mjs

@@ -176,6 +176,27 @@ const readUrl = (object, key, path) => {
 	}
 };
 
+const readBasePath = (object, key, path) => {
+	const value = object[key] ?? '/';
+
+	if (typeof value !== 'string' || value.trim() === '') {
+		throw new Error(`${path}.${key} must be a non-empty URL path in ${siteConfigLabel}.`);
+	}
+
+	const normalizedValue = value.trim();
+
+	if (
+		!normalizedValue.startsWith('/')
+		|| !normalizedValue.endsWith('/')
+		|| normalizedValue.includes('//')
+		|| /[\s?#]/.test(normalizedValue)
+	) {
+		throw new Error(`${path}.${key} must start and end with "/" and must not contain whitespace, "?", "#", or "//" in ${siteConfigLabel}.`);
+	}
+
+	return normalizedValue;
+};
+
 const readSmoothScroll = (navigation) => {
 	const rawSmoothScroll = assertObject(navigation.smoothScroll ?? {}, 'navigation.smoothScroll');
 	const minimumDurationMs = readPositiveInteger(rawSmoothScroll, 'minimumDurationMs', 'navigation.smoothScroll', 2_000);
@@ -274,6 +295,7 @@ const defaultFontFamily = "Arial, 'Helvetica Neue', Helvetica, sans-serif";
 
 export const projectConfig = Object.freeze({
 	site: Object.freeze({
+		basePath: readBasePath(rawSite, 'basePath', 'site'),
 		url: readUrl(rawSite, 'url', 'site'),
 	}),
 	layout: Object.freeze({

package/scripts/lib/site-content.mjs

@@ -18,12 +18,13 @@ const explicitHeadingIdRegex = /\s*\{#([a-z0-9-]+)\}\s*$/;
 const inlineStyleReferenceRegex = /\[[^\]\n]+\]\{\.([a-z][a-z0-9-]*)\}/g;
 const frontmatterDelimiterRegex = /^---\s*$/;
 const knownContentTopLevelFrontmatterKeys = new Set(['title', 'description', 'slug', 'navigation', 'presentation', 'frame', 'sections']);
-const knownThemeTopLevelFrontmatterKeys = new Set(['presentation', 'frame']);
+const knownThemeTopLevelFrontmatterKeys = new Set(['navigation', 'presentation', 'frame']);
 const knownNestedFrontmatterKeys = new Set([
 	'align',
 	'alt',
 	'backgroundColor',
 	'body',
+	'brand',
 	'caption',
 	'carousel',
 	'color',

package/scripts/lib/site-paths.mjs

@@ -20,15 +20,19 @@ export const invocationRoot = configuredInvocationRoot
 	? path.resolve(configuredInvocationRoot)
 	: process.cwd();
 
-const hasSiteFiles = (projectRoot, siteDirectory) => {
-	const siteDir = path.resolve(projectRoot, siteDirectory);
-
+const hasSiteFilesInDirectory = (siteDir) => {
 	return (
 		existsSync(path.join(siteDir, 'config.mjs'))
 		&& existsSync(path.join(siteDir, 'content.md'))
 	);
 };
 
+const hasSiteFiles = (projectRoot, siteDirectory) => {
+	const siteDir = path.resolve(projectRoot, siteDirectory);
+
+	return hasSiteFilesInDirectory(siteDir);
+};
+
 const findSiteProjectRoot = (startDirectory, siteDirectory) => {
 	let current = path.resolve(startDirectory);
 
@@ -67,6 +71,17 @@ const resolveSitePaths = () => {
 		};
 	}
 
+	if (!hasConfiguredSiteDirectory && hasSiteFilesInDirectory(invocationRoot)) {
+		const siteDir = invocationRoot;
+		const siteProjectRoot = path.dirname(siteDir);
+
+		return {
+			siteDirectory: path.relative(siteProjectRoot, siteDir) || path.basename(siteDir),
+			siteDir,
+			siteProjectRoot,
+		};
+	}
+
 	const discoveredRoot = findSiteProjectRoot(invocationRoot, fallbackSiteDirectory);
 	const siteProjectRoot = discoveredRoot ?? invocationRoot;
 

package/scripts/lib/typography.mjs

@@ -29,13 +29,13 @@ export const typographyPresets = {
 	'compact-gallery': {
 		heading: {
 			align: { desktop: 'left', mobile: 'left' },
-			size: 'small',
+			size: 'medium',
 			lineHeight: 1.08,
 			spacing: '0.45em',
 		},
 		body: {
 			align: { desktop: 'left', mobile: 'left' },
-			size: 'small',
+			size: 'medium',
 			lineHeight: 1.42,
 			paragraphSpacing: '0.6em',
 		},
@@ -55,7 +55,7 @@ export const typographyPresets = {
 		},
 		body: {
 			align: { desktop: 'left', mobile: 'left' },
-			size: 'large',
+			size: 'medium',
 			lineHeight: 1.62,
 			paragraphSpacing: '1em',
 		},
@@ -69,13 +69,13 @@ export const typographyPresets = {
 	statement: {
 		heading: {
 			align: { desktop: 'left', mobile: 'left' },
-			size: 'large',
+			size: 'medium',
 			lineHeight: 1.04,
 			spacing: '0.5em',
 		},
 		body: {
 			align: { desktop: 'left', mobile: 'left' },
-			size: 'large',
+			size: 'medium',
 			lineHeight: 1.42,
 			paragraphSpacing: '0.75em',
 		},

package/scripts/show-typography.mjs

@@ -7,6 +7,8 @@ import {
 	typographyPresets,
 } from './lib/typography.mjs';
 import {
+	getContentFiles,
+	readSiteFile,
 	splitSiteFile,
 	validateContentFrontmatterStructure,
 	validateFrontmatterIndentation,
@@ -21,6 +23,14 @@ import {
 
 const mode = process.argv[2] ?? 'show';
 
+const typographyRoles = ['heading', 'body', 'caption'];
+const typographyFields = {
+	heading: ['align', 'size', 'lineHeight', 'spacing'],
+	body: ['align', 'size', 'lineHeight', 'paragraphSpacing'],
+	caption: ['align', 'size', 'lineHeight', 'spacing'],
+};
+const responsiveFields = new Set(['align']);
+
 const countIndent = (line) => line.match(/^\s*/)?.[0].length ?? 0;
 
 const parseScalar = (rawValue) => {
@@ -83,6 +93,213 @@ const findMap = (lines, label, parentStart = 0, parentEnd = lines.length, requir
 	return null;
 };
 
+const isPlainObject = (value) => (
+	value !== null &&
+	typeof value === 'object' &&
+	!Array.isArray(value)
+);
+
+const hasPath = (value, path) => {
+	let current = value;
+
+	for (const segment of path) {
+		if (!isPlainObject(current) || !(segment in current)) {
+			return false;
+		}
+
+		current = current[segment];
+	}
+
+	return true;
+};
+
+const getPath = (value, path) => path.reduce((current, segment) => current?.[segment], value);
+
+const setPath = (value, path, entry) => {
+	let current = value;
+
+	for (const segment of path.slice(0, -1)) {
+		current[segment] ??= {};
+		current = current[segment];
+	}
+
+	current[path.at(-1)] = entry;
+};
+
+const annotateResolvedValues = (resolved, sources) => {
+	const annotated = {};
+
+	for (const role of typographyRoles) {
+		for (const field of typographyFields[role]) {
+			if (responsiveFields.has(field)) {
+				for (const viewport of ['desktop', 'mobile']) {
+					const path = [role, field, viewport];
+					const source = getPath(sources, path);
+					setPath(annotated, path, {
+						value: getPath(resolved.values, path),
+						source: source.source,
+						...(source.inherited ? { inherited: true } : {}),
+					});
+				}
+				continue;
+			}
+
+			const path = [role, field];
+			const source = getPath(sources, path);
+			setPath(annotated, path, {
+				value: getPath(resolved.values, path),
+				source: source.source,
+				...(source.inherited ? { inherited: true } : {}),
+			});
+		}
+	}
+
+	return annotated;
+};
+
+const presetSources = (presetName) => {
+	const sources = {};
+
+	for (const role of typographyRoles) {
+		for (const field of typographyFields[role]) {
+			if (responsiveFields.has(field)) {
+				for (const viewport of ['desktop', 'mobile']) {
+					setPath(sources, [role, field, viewport], {
+						source: `preset:${presetName}`,
+						inherited: false,
+					});
+				}
+				continue;
+			}
+
+			setPath(sources, [role, field], {
+				source: `preset:${presetName}`,
+				inherited: false,
+			});
+		}
+	}
+
+	return sources;
+};
+
+const applyOverrideSources = (sources, typographyConfig, sourceLabel) => {
+	const overrides = typographyConfig?.overrides;
+	if (!overrides) return sources;
+
+	for (const role of typographyRoles) {
+		for (const field of typographyFields[role]) {
+			if (responsiveFields.has(field)) {
+				for (const viewport of ['desktop', 'mobile']) {
+					const path = [role, field, viewport];
+					if (hasPath(overrides, path)) {
+						setPath(sources, path, {
+							source: `${sourceLabel} override`,
+							inherited: false,
+						});
+					}
+				}
+				continue;
+			}
+
+			const path = [role, field];
+			if (hasPath(overrides, path)) {
+				setPath(sources, path, {
+					source: `${sourceLabel} override`,
+					inherited: false,
+				});
+			}
+		}
+	}
+
+	return sources;
+};
+
+const inheritedSources = (sources) => {
+	const inherited = structuredClone(sources);
+
+	for (const role of typographyRoles) {
+		for (const field of typographyFields[role]) {
+			if (responsiveFields.has(field)) {
+				for (const viewport of ['desktop', 'mobile']) {
+					const path = [role, field, viewport];
+					setPath(inherited, path, {
+						...getPath(sources, path),
+						inherited: true,
+					});
+				}
+				continue;
+			}
+
+			const path = [role, field];
+			setPath(inherited, path, {
+				...getPath(sources, path),
+				inherited: true,
+			});
+		}
+	}
+
+	return inherited;
+};
+
+const resolveAnnotatedTypographyConfig = (typographyConfig, sourceLabel) => {
+	const resolved = resolveTypographyConfig(typographyConfig ?? defaultTypography);
+	const sources = applyOverrideSources(
+		presetSources(resolved.preset),
+		typographyConfig,
+		sourceLabel,
+	);
+
+	return {
+		preset: {
+			value: resolved.preset,
+			source: typographyConfig?.preset ? sourceLabel : 'engine default',
+			...(typographyConfig?.preset ? {} : { inherited: true }),
+		},
+		resolved,
+		sources,
+	};
+};
+
+const resolveAnnotatedTypographyOverride = (baseAnnotated, typographyConfig, sourceLabel) => {
+	if (typographyConfig?.preset) {
+		return resolveAnnotatedTypographyConfig(typographyConfig, sourceLabel);
+	}
+
+	if (typographyConfig?.overrides) {
+		const resolved = resolveTypographyOverride(baseAnnotated.resolved, typographyConfig);
+		const sources = applyOverrideSources(
+			inheritedSources(baseAnnotated.sources),
+			typographyConfig,
+			sourceLabel,
+		);
+
+		return {
+			preset: {
+				value: resolved.preset,
+				source: baseAnnotated.preset.source,
+				inherited: true,
+			},
+			resolved,
+			sources,
+		};
+	}
+
+	return {
+		preset: {
+			value: baseAnnotated.resolved.preset,
+			source: baseAnnotated.preset.source,
+			inherited: true,
+		},
+		resolved: baseAnnotated.resolved,
+		sources: inheritedSources(baseAnnotated.sources),
+	};
+};
+
+const formatAnnotatedTypography = (annotated) => ({
+	preset: annotated.preset,
+	resolved: annotateResolvedValues(annotated.resolved, annotated.sources),
+});
+
 const getSectionBlocks = (lines) => {
 	const sectionsMap = findMap(lines, 'sections');
 	if (!sectionsMap) return [];
@@ -118,8 +335,7 @@ const getSectionBlocks = (lines) => {
 	return sections;
 };
 
-const readSiteTypography = async () => {
-	const { frontmatter, frontmatterBody } = splitSiteFile(await readFile(siteContentPath, 'utf8'));
+const readThemeTypography = async () => {
 	const themeFile = await readFile(siteThemePath, 'utf8').catch((error) => {
 		if (error?.code === 'ENOENT') {
 			return '---\n---\n';
@@ -129,29 +345,41 @@ const readSiteTypography = async () => {
 	});
 	const { frontmatter: themeFrontmatter, frontmatterBody: themeFrontmatterBody } = splitSiteFile(themeFile, siteThemeLabel);
 	const indentationIssues = [];
-	validateFrontmatterIndentation(frontmatter, (issue) => indentationIssues.push(issue));
-	validateContentFrontmatterStructure(frontmatter, (issue) => indentationIssues.push(issue));
 	validateFrontmatterIndentation(themeFrontmatter, (issue) => indentationIssues.push(issue));
 	validateThemeFrontmatterStructure(themeFrontmatter, (issue) => indentationIssues.push(issue));
 	if (indentationIssues.length > 0) {
 		throw new Error([
-			`Cannot inspect typography because ${siteContentLabel} or ${siteThemeLabel} has invalid frontmatter.`,
+			`Cannot inspect typography because ${siteThemeLabel} has invalid frontmatter.`,
 			...indentationIssues.map((issue) => `- ${issue.message}`),
 		].join('\n'));
 	}
 
-	const lines = frontmatterBody.split(/\r?\n/);
 	const themeLines = themeFrontmatterBody.split(/\r?\n/);
 	const themePresentation = findMap(themeLines, 'presentation', 0, themeLines.length, 0);
 	const themeTypographyConfig = themePresentation
 		? findMap(themeLines, 'typography', themePresentation.index + 1, themePresentation.nextIndex)?.value
 		: null;
+	return resolveAnnotatedTypographyConfig(themeTypographyConfig ?? defaultTypography, siteThemeLabel);
+};
+
+const readPageTypography = async (contentFile, themeTypography) => {
+	const { frontmatter, frontmatterBody } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
+	const indentationIssues = [];
+	validateFrontmatterIndentation(frontmatter, (issue) => indentationIssues.push(issue));
+	validateContentFrontmatterStructure(frontmatter, (issue) => indentationIssues.push(issue));
+	if (indentationIssues.length > 0) {
+		throw new Error([
+			`Cannot inspect typography because ${contentFile.contentLabel} has invalid frontmatter.`,
+			...indentationIssues.map((issue) => `- ${issue.message}`),
+		].join('\n'));
+	}
+
+	const lines = frontmatterBody.split(/\r?\n/);
 	const pagePresentation = findMap(lines, 'presentation', 0, lines.length, 0);
 	const pageTypographyConfig = pagePresentation
 		? findMap(lines, 'typography', pagePresentation.index + 1, pagePresentation.nextIndex)?.value
 		: null;
-	const themeTypography = resolveTypographyConfig(themeTypographyConfig ?? defaultTypography);
-	const pageTypography = resolveTypographyOverride(themeTypography, pageTypographyConfig ?? undefined);
+	const pageTypography = resolveAnnotatedTypographyOverride(themeTypography, pageTypographyConfig ?? undefined, contentFile.contentLabel);
 	const sections = getSectionBlocks(lines).map((section) => {
 		const presentation = findMap(lines, 'presentation', section.start + 1, section.end);
 		const typography = presentation
@@ -160,13 +388,13 @@ const readSiteTypography = async () => {
 
 		return {
 			id: section.id,
-			typography,
-			resolved: resolveTypographyOverride(pageTypography, typography ?? undefined),
+			typography: resolveAnnotatedTypographyOverride(pageTypography, typography ?? undefined, `${contentFile.contentLabel} sections.${section.id}`),
 		};
 	});
 
 	return {
-		themeTypography,
+		source: contentFile.contentLabel,
+		route: contentFile.isHome ? '/' : `/${contentFile.routeFolder}/`,
 		pageTypography,
 		sections,
 	};
@@ -175,31 +403,26 @@ const readSiteTypography = async () => {
 if (mode === 'presets') {
 	console.log(toYamlLines(typographyPresets).join('\n'));
 } else if (mode === 'show') {
-	const siteTypography = await readSiteTypography();
+	const themeTypography = await readThemeTypography();
+	const pages = await Promise.all((await getContentFiles()).map((contentFile) => readPageTypography(contentFile, themeTypography)));
 	const output = {
-		source: siteContentLabel,
 		theme: {
 			source: siteThemeLabel,
 			presentation: {
-				typography: {
-					preset: siteTypography.themeTypography.preset,
-					resolved: siteTypography.themeTypography.values,
-				},
-			},
-		},
-		page: {
-			typography: {
-				preset: siteTypography.pageTypography.preset,
-				resolved: siteTypography.pageTypography.values,
+				typography: formatAnnotatedTypography(themeTypography),
 			},
 		},
-		sections: Object.fromEntries(siteTypography.sections.map((section) => [
-			section.id,
+		pages: Object.fromEntries(pages.map((page) => [
+			page.route,
 			{
-				typography: {
-					preset: section.resolved.preset,
-					resolved: section.resolved.values,
-				},
+				source: page.source,
+				typography: formatAnnotatedTypography(page.pageTypography),
+				sections: Object.fromEntries(page.sections.map((section) => [
+					section.id,
+					{
+						typography: formatAnnotatedTypography(section.typography),
+					},
+				])),
 			},
 		])),
 	};