@janga/norna 0.7.0

package/scripts/doctor.mjs

@@ -0,0 +1,38 @@
+import {
+	astroCacheDir,
+	astroDistDir,
+	astroPublicDir,
+	engineRoot,
+	generatedImagesManifestPath,
+	invocationRoot,
+	siteConfigPath,
+	siteContentPath,
+	siteDir,
+	siteDirectory,
+	siteImagesDir,
+	siteProjectRoot,
+	sitePublicDir,
+	siteRoutesDir,
+	siteThemePath,
+} from './lib/site-paths.mjs';
+
+const lines = [
+	'norna doctor',
+	`Invocation root: ${invocationRoot}`,
+	`Site project root: ${siteProjectRoot}`,
+	`Site directory: ${siteDirectory}`,
+	`Site directory path: ${siteDir}`,
+	`Site config: ${siteConfigPath}`,
+	`Site theme: ${siteThemePath}`,
+	`Site content: ${siteContentPath}`,
+	`Site images: ${siteImagesDir}`,
+	`Site routes: ${siteRoutesDir}`,
+	`Site public source: ${sitePublicDir}`,
+	`Generated image manifest: ${generatedImagesManifestPath}`,
+	`Astro public output: ${astroPublicDir}`,
+	`Astro dist output: ${astroDistDir}`,
+	`Astro cache: ${astroCacheDir}`,
+	`Engine root: ${engineRoot}`,
+];
+
+console.log(lines.join('\n'));

package/scripts/engine-version.mjs

@@ -0,0 +1,137 @@
+import { createRequire } from 'node:module';
+import { mkdir, readFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+import {
+	engineRoot,
+	engineRootLabel,
+	siteProjectRoot,
+	siteProjectRootLabel,
+} from './lib/site-paths.mjs';
+
+const packageName = '@janga/norna';
+const requireFromEngine = createRequire(import.meta.url);
+
+const usage = `
+Usage: norna engine:version [--latest]
+
+Options:
+  --latest      Also query npm for the latest published norna version
+`.trim();
+
+const args = process.argv.slice(2);
+const includeLatest = args.includes('--latest');
+const unknownArgs = args.filter((arg) => arg !== '--latest');
+
+if (unknownArgs.length > 0) {
+	throw new Error(`Unknown option: ${unknownArgs[0]}\n${usage}`);
+}
+
+const readJson = async (filePath) => JSON.parse(await readFile(filePath, 'utf8'));
+
+const readOptionalJson = async (filePath) => {
+	try {
+		return await readJson(filePath);
+	} catch (error) {
+		if (error?.code === 'ENOENT') {
+			return null;
+		}
+
+		throw error;
+	}
+};
+
+const getPackageDependency = (packageJson) => {
+	if (!packageJson) {
+		return null;
+	}
+
+	for (const dependencyType of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+		const dependencyVersion = packageJson[dependencyType]?.[packageName];
+
+		if (dependencyVersion) {
+			return {
+				type: dependencyType,
+				version: dependencyVersion,
+			};
+		}
+	}
+
+	return null;
+};
+
+const runCapture = (command, args, options = {}) => new Promise((resolve, reject) => {
+	const child = spawn(command, args, {
+		cwd: siteProjectRoot,
+		stdio: ['ignore', 'pipe', 'pipe'],
+		...options,
+	});
+	let stdout = '';
+	let stderr = '';
+
+	child.stdout?.on('data', (chunk) => {
+		stdout += chunk;
+	});
+	child.stderr?.on('data', (chunk) => {
+		stderr += chunk;
+	});
+	child.once('error', reject);
+	child.once('exit', (code, signal) => {
+		if (code === 0) {
+			resolve(stdout.trim());
+			return;
+		}
+
+		const commandText = [command, ...args].join(' ');
+		reject(new Error(signal
+			? `${commandText} exited with signal ${signal}.`
+			: `${commandText} exited with code ${code}.\n${stderr.trim()}`));
+	});
+});
+
+const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+const configuredNpmCache = process.env.npm_config_cache ?? process.env.NPM_CONFIG_CACHE;
+const npmCachePath = path.resolve(siteProjectRoot, configuredNpmCache ?? path.join('node_modules', '.cache', 'norna-npm'));
+const sitePackageJson = await readOptionalJson(path.join(siteProjectRoot, 'package.json'));
+const enginePackageJson = await readJson(path.join(engineRoot, 'package.json'));
+const astroPackageJson = await readJson(requireFromEngine.resolve('astro/package.json'));
+const siteDependency = getPackageDependency(sitePackageJson);
+
+console.log('norna engine:version');
+console.log(`Site project root: ${siteProjectRootLabel}`);
+
+if (siteDependency) {
+	console.log(`Site dependency: ${packageName} ${siteDependency.version} (${siteDependency.type})`);
+} else if (sitePackageJson?.name === packageName) {
+	console.log('Site dependency: current engine repository');
+} else {
+	console.log(`Site dependency: ${packageName} not declared`);
+}
+
+console.log(`Installed norna: ${enginePackageJson.version}`);
+console.log(`Engine root: ${engineRootLabel}`);
+console.log(`Astro dependency: ${enginePackageJson.dependencies?.astro ?? 'not declared'}`);
+console.log(`Installed Astro: ${astroPackageJson.version}`);
+
+if (includeLatest) {
+	try {
+		await mkdir(npmCachePath, { recursive: true });
+		const latestVersion = await runCapture(npmBin, [
+			'view',
+			packageName,
+			'version',
+			'--registry=https://registry.npmjs.org/',
+			'--fetch-retries=0',
+		], {
+			env: {
+				...process.env,
+				npm_config_cache: npmCachePath,
+			},
+		});
+		console.log(`npm latest: ${latestVersion}`);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.log(`npm latest: unavailable (${message})`);
+	}
+}

package/scripts/generate-images.mjs

@@ -0,0 +1,369 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import {
+	getFrontmatterSections,
+	getContentFiles,
+	getImageIndex,
+	readSiteFile,
+	supportedImageExtensions,
+} from './lib/site-content.mjs';
+import {
+	astroPublicDir,
+	generatedImagesDir,
+	generatedImagesManifestPath,
+	originalImagesDir,
+	siteImagesDir,
+} from './lib/site-paths.mjs';
+
+const execFileAsync = promisify(execFile);
+
+const imageOutputVersion = 2;
+const sourceHashSlugLength = 8;
+const widths = [480, 768, 1080, 1440, 1920];
+
+const run = async (command, args) => {
+	const { stdout } = await execFileAsync(command, args, { maxBuffer: 1024 * 1024 * 10 });
+	return stdout.trim();
+};
+
+const canRun = async (command, args = ['-version']) => {
+	try {
+		await run(command, args);
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+const getImageMagick = async () => {
+	if (await canRun('magick')) {
+		return {
+			identify: (sourcePath) => run('magick', ['identify', '-format', '%w %h', sourcePath]),
+			convert: (sourcePath, outputPath, width) => run('magick', [
+				sourcePath,
+				'-auto-orient',
+				'-resize',
+				`${width}x`,
+				'-strip',
+				'-quality',
+				'82',
+				outputPath,
+			]),
+		};
+	}
+
+	if (await canRun('identify') && await canRun('convert')) {
+		return {
+			identify: (sourcePath) => run('identify', ['-format', '%w %h', sourcePath]),
+			convert: (sourcePath, outputPath, width) => run('convert', [
+				sourcePath,
+				'-auto-orient',
+				'-resize',
+				`${width}x`,
+				'-strip',
+				'-quality',
+				'82',
+				outputPath,
+			]),
+		};
+	}
+
+	throw new Error('ImageMagick is missing. Install either the "magick" command or both "identify" and "convert".');
+};
+
+const toPublicPath = (filePath) => filePath.split(path.sep).join('/');
+const getPublicPath = (filePath) => `/${toPublicPath(path.relative(astroPublicDir, filePath))}`;
+const getFilePathFromPublicPath = (publicPath) => path.join(astroPublicDir, publicPath.replace(/^\//, ''));
+
+const getSourceHashSlug = (sourceHash) => sourceHash.slice(0, sourceHashSlugLength);
+
+const getGeneratedPath = (sourcePath, sourceHash, width) => {
+	const parsed = path.parse(path.relative(siteImagesDir, sourcePath).startsWith('..')
+		? path.relative(path.dirname(siteImagesDir), sourcePath)
+		: path.relative(siteImagesDir, sourcePath));
+	return path.join(generatedImagesDir, parsed.dir, `${parsed.name}-${getSourceHashSlug(sourceHash)}-${width}.webp`);
+};
+
+const fail = (message) => {
+	throw new Error(message);
+};
+
+const getReferencedImages = async (contentFile) => {
+	const { frontmatter } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
+	const sections = getFrontmatterSections(frontmatter);
+	const references = [];
+
+	for (const section of sections) {
+		const imageReferences = section.imageReferences ?? section.images.map((image) => ({ image }));
+		for (const { image, line } of imageReferences) {
+			references.push({
+				contentFile,
+				image,
+				line,
+				sectionId: section.id,
+			});
+		}
+	}
+
+	return references;
+};
+
+const getContentSourcePath = ({ image, line }, imageIndex) => {
+	if (image.includes('/') || image.includes('\\') || image.startsWith('/')) {
+		fail(`Image reference must be a filename without a directory: ${image}`);
+	}
+
+	const extension = path.extname(image).toLowerCase();
+	if (!supportedImageExtensions.has(extension)) {
+		fail(`Image reference uses an unsupported file type: ${image}`);
+	}
+
+	const sourcePath = imageIndex.get(image);
+
+	if (!sourcePath) {
+		fail(`Image file "${image}" does not exist anywhere under the page images directory.`);
+	}
+
+	return sourcePath;
+};
+
+const getReferencedSources = async () => {
+	const contentFiles = await getContentFiles();
+	const seen = new Map();
+	const sources = [];
+
+	for (const contentFile of contentFiles) {
+		const references = await getReferencedImages(contentFile);
+		const imageIndex = await getImageIndex(contentFile.imagesDir, fail);
+
+		for (const reference of references) {
+			const sourcePath = getContentSourcePath(reference, imageIndex);
+			const siteImagePath = toPublicPath(path.relative(contentFile.imagesDir, sourcePath));
+			const imageName = path.basename(sourcePath);
+
+			if (seen.has(imageName)) {
+				const firstReference = seen.get(imageName);
+				fail(`Image reference "${imageName}" appears more than once, in ${firstReference.contentFile.contentLabel} line ${firstReference.line} and ${reference.contentFile.contentLabel} line ${reference.line}.`);
+			}
+
+			const fileStat = await stat(sourcePath).catch(() => null);
+			if (!fileStat?.isFile()) {
+				fail(`Image file does not exist: ${contentFile.imagesLabel}/${siteImagePath}`);
+			}
+
+			const currentDirectory = path.basename(path.dirname(sourcePath));
+			if (reference.sectionId && currentDirectory !== reference.sectionId) {
+				fail(`Image "${imageName}" is used in section "${reference.sectionId}" but is located in ${contentFile.imagesLabel}/${currentDirectory}/. Run norna content:sync, or npm run norna:sync in starter-style repositories, to move it.`);
+			}
+
+			seen.set(imageName, reference);
+			sources.push(sourcePath);
+		}
+	}
+
+	return sources.sort();
+};
+
+const getOrientation = ({ width, height }) => {
+	if (width === height) return 'square';
+	return width > height ? 'landscape' : 'portrait';
+};
+
+const validateCarouselOrientations = (sections, manifest) => {
+	for (const section of sections) {
+		for (const carousel of section.carousels) {
+			const orientations = new Set(
+				carousel.images
+					.map((image) => manifest[image])
+					.filter(Boolean)
+					.map(getOrientation)
+			);
+
+			orientations.delete('square');
+			if (orientations.size > 1) {
+				throw new Error(
+					`Carousel in section "${section.id}" on line ${carousel.line} mixes landscape and portrait images. Use landscape images with optional square images, or portrait images with optional square images.`,
+				);
+			}
+		}
+	}
+};
+
+const identify = async (sourcePath) => {
+	const output = await imageMagick.identify(sourcePath);
+	const [width, height] = output.split(' ').map(Number);
+	return { width, height };
+};
+
+const convert = async (sourcePath, outputPath, width) => {
+	await mkdir(path.dirname(outputPath), { recursive: true });
+	await imageMagick.convert(sourcePath, outputPath, width);
+};
+
+const getHash = (value) => createHash('sha256').update(value).digest('hex');
+
+const getSourceHash = async (sourcePath) => {
+	const file = await readFile(sourcePath);
+	return getHash(file);
+};
+
+const getVariantWidths = ({ width }) => {
+	const variantWidths = widths.filter((candidateWidth) => candidateWidth <= width);
+
+	if (!variantWidths.includes(width)) {
+		variantWidths.push(width);
+	}
+
+	return variantWidths;
+};
+
+const getVariants = (sourcePath, sourceHash, variantWidths) => variantWidths.map((width) => ({
+	src: getPublicPath(getGeneratedPath(sourcePath, sourceHash, width)),
+	width,
+}));
+
+const readManifest = async () => {
+	try {
+		return JSON.parse(await readFile(generatedImagesManifestPath, 'utf8'));
+	} catch (error) {
+		if (error?.code === 'ENOENT') {
+			return {};
+		}
+
+		throw error;
+	}
+};
+
+const fileExists = async (filePath) => {
+	const fileStat = await stat(filePath).catch(() => null);
+	return fileStat?.isFile() ?? false;
+};
+
+const hasGeneratedVariants = async (variants) => {
+	for (const variant of variants) {
+		if (!(await fileExists(getFilePathFromPublicPath(variant.src)))) {
+			return false;
+		}
+	}
+
+	return true;
+};
+
+const getReusableEntry = async (sourcePath, previousEntry, sourceHash) => {
+	if (
+		previousEntry?.sourceHash !== sourceHash
+		|| previousEntry?.outputVersion !== imageOutputVersion
+		|| !Number.isFinite(previousEntry?.width)
+		|| !Number.isFinite(previousEntry?.height)
+	) {
+		return null;
+	}
+
+	const variants = getVariants(sourcePath, sourceHash, getVariantWidths(previousEntry));
+
+	if (!(await hasGeneratedVariants(variants))) {
+		return null;
+	}
+
+	return {
+		outputVersion: imageOutputVersion,
+		sourceHash,
+		width: previousEntry.width,
+		height: previousEntry.height,
+		variants,
+	};
+};
+
+const listGeneratedFiles = async (directory) => {
+	const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
+		if (error?.code === 'ENOENT') {
+			return [];
+		}
+
+		throw error;
+	});
+	const files = [];
+
+	for (const entry of entries) {
+		const entryPath = path.join(directory, entry.name);
+
+		if (entry.isDirectory()) {
+			files.push(...await listGeneratedFiles(entryPath));
+		} else if (entry.isFile()) {
+			files.push(entryPath);
+		}
+	}
+
+	return files;
+};
+
+const removeUnreferencedGeneratedFiles = async (manifest) => {
+	const expectedFiles = new Set(
+		Object.values(manifest)
+			.flatMap((entry) => entry.variants ?? [])
+			.map((variant) => getFilePathFromPublicPath(variant.src)),
+	);
+	const generatedFiles = await listGeneratedFiles(generatedImagesDir);
+
+	for (const generatedFile of generatedFiles) {
+		if (!expectedFiles.has(generatedFile)) {
+			await rm(generatedFile, { force: true });
+		}
+	}
+};
+
+await rm(originalImagesDir, { recursive: true, force: true });
+await mkdir(generatedImagesDir, { recursive: true });
+
+const contentFiles = await getContentFiles();
+const frontmatterSections = (await Promise.all(contentFiles.map(async (contentFile) => {
+	const { frontmatter } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
+	return getFrontmatterSections(frontmatter);
+}))).flat();
+const sources = await getReferencedSources();
+const previousManifest = await readManifest();
+const manifest = {};
+
+if (sources.length === 0) {
+	await removeUnreferencedGeneratedFiles(manifest);
+	await mkdir(path.dirname(generatedImagesManifestPath), { recursive: true });
+	await writeFile(generatedImagesManifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+	process.exit(0);
+}
+
+const imageMagick = await getImageMagick();
+
+for (const sourcePath of sources) {
+	const imageName = path.basename(sourcePath);
+	const sourceHash = await getSourceHash(sourcePath);
+	const reusableEntry = await getReusableEntry(sourcePath, previousManifest[imageName], sourceHash);
+
+	if (reusableEntry) {
+		manifest[imageName] = reusableEntry;
+		continue;
+	}
+
+	const dimensions = await identify(sourcePath);
+	const variantWidths = getVariantWidths(dimensions);
+	const variants = getVariants(sourcePath, sourceHash, variantWidths);
+	for (const width of variantWidths) {
+		const outputPath = getGeneratedPath(sourcePath, sourceHash, width);
+		await convert(sourcePath, outputPath, width);
+	}
+
+	manifest[imageName] = {
+		outputVersion: imageOutputVersion,
+		sourceHash,
+		width: dimensions.width,
+		height: dimensions.height,
+		variants,
+	};
+}
+
+validateCarouselOrientations(frontmatterSections, manifest);
+await removeUnreferencedGeneratedFiles(manifest);
+await mkdir(path.dirname(generatedImagesManifestPath), { recursive: true });
+await writeFile(generatedImagesManifestPath, `${JSON.stringify(manifest, null, 2)}\n`);