@janga/norna 0.7.18 → 0.7.22

package/scripts/add-site-node.mjs

@@ -0,0 +1,251 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, realpath, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { dump as dumpYaml } from 'js-yaml';
+import { slugifyAsciiIdentifier } from './lib/heading-ids.mjs';
+import { pageDirectoryPattern } from './lib/page-model.mjs';
+import {
+	invocationRoot,
+	siteDir,
+	sitePagesDir,
+	siteProjectRoot,
+} from './lib/site-paths.mjs';
+import { getSiteStructure } from './lib/site-structure.mjs';
+
+const usage = `
+Usage:
+  norna page:add <title> [--parent <path>] [--slug <slug>] [--order <NNN>] [--dry-run]
+  norna category:add <label> [--parent <path>] [--slug <slug>] [--order <NNN>] [--dry-run]
+
+Parent selection:
+  --parent /                 Add a top-level node
+  --parent /guides/         Add a child below the guides node
+  no --parent               Use the current node directory, or site/pages/
+`.trim();
+
+const parseValueOption = (rawArgs, index, name) => {
+	const arg = rawArgs[index];
+	if (arg === name) {
+		const value = rawArgs[index + 1];
+		if (!value || value.startsWith('-')) throw new Error(`${name} requires a value.\n${usage}`);
+		return { consumed: 2, value };
+	}
+	if (arg.startsWith(`${name}=`)) {
+		const value = arg.slice(name.length + 1);
+		if (!value) throw new Error(`${name} requires a value.\n${usage}`);
+		return { consumed: 1, value };
+	}
+	return null;
+};
+
+const parseArgs = (rawArgs) => {
+	const options = {
+		dryRun: false,
+		help: false,
+		order: null,
+		parent: null,
+		slug: null,
+		titleParts: [],
+	};
+	const seen = new Set();
+
+	for (let index = 0; index < rawArgs.length;) {
+		const arg = rawArgs[index];
+		if (arg === '-h' || arg === '--help') {
+			options.help = true;
+			index += 1;
+			continue;
+		}
+		if (arg === '--dry-run') {
+			if (seen.has('dryRun')) throw new Error(`--dry-run may be specified only once.\n${usage}`);
+			seen.add('dryRun');
+			options.dryRun = true;
+			index += 1;
+			continue;
+		}
+
+		let matched = false;
+		for (const [name, key] of [['--order', 'order'], ['--parent', 'parent'], ['--slug', 'slug']]) {
+			const parsed = parseValueOption(rawArgs, index, name);
+			if (!parsed) continue;
+			if (seen.has(key)) throw new Error(`${name} may be specified only once.\n${usage}`);
+			seen.add(key);
+			options[key] = parsed.value;
+			index += parsed.consumed;
+			matched = true;
+			break;
+		}
+		if (matched) continue;
+
+		if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}\n${usage}`);
+		options.titleParts.push(arg);
+		index += 1;
+	}
+
+	return options;
+};
+
+const parseOrder = (value) => {
+	if (!/^\d{1,3}$/.test(value)) {
+		throw new Error(`Invalid --order "${value}". Use an integer from 1 to 999.`);
+	}
+	const order = Number.parseInt(value, 10);
+	if (order < 1 || order > 999) {
+		throw new Error(`Invalid --order "${value}". Use an integer from 1 to 999.`);
+	}
+	return order;
+};
+
+const normalizeParentPath = (value) => {
+	if (value === '/') return '';
+	if (value.includes('\\') || value.includes('?') || value.includes('#')) {
+		throw new Error(`Invalid --parent "${value}". Use a logical path such as /guides/installation/.`);
+	}
+	const normalized = value.replace(/^\/+|\/+$/g, '');
+	if (!normalized || normalized.split('/').some((segment) => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(segment))) {
+		throw new Error(`Invalid --parent "${value}". Use / for the top level or a logical path such as /guides/installation/.`);
+	}
+	return normalized;
+};
+
+const getNextOrder = (siblings) => {
+	const highestOrder = siblings.reduce((highest, node) => Math.max(highest, node.pageOrder), 0);
+	const nextOrder = Math.floor(highestOrder / 10) * 10 + 10;
+	if (nextOrder > 999) {
+		throw new Error('No automatic page order remains below 1000. Reorder the sibling nodes before adding another one.');
+	}
+	return nextOrder;
+};
+
+const toDisplayPath = (filePath) => {
+	const relativePath = path.relative(siteProjectRoot, filePath);
+	return (relativePath && !relativePath.startsWith('..') && !path.isAbsolute(relativePath)
+		? relativePath
+		: filePath).split(path.sep).join('/');
+};
+
+const escapeMarkdownHeading = (value) => value.replace(/([\\`*_[\]{}<>#])/g, '\\$1');
+
+const canonicalDirectory = async (directory) => realpath(directory).catch((error) => {
+	if (error?.code === 'ENOENT') return path.resolve(directory);
+	throw error;
+});
+
+const resolveParent = async ({ nodes, parent }) => {
+	if (parent !== null) {
+		const parentPath = normalizeParentPath(parent);
+		if (!parentPath) {
+			return { collectionDir: sitePagesDir, node: null, pagePath: '' };
+		}
+		const node = nodes.find((candidate) => candidate.pagePath === parentPath);
+		if (!node) {
+			throw new Error(`Cannot find parent "${parent}". Use an existing logical page/category path, or / for the top level.`);
+		}
+		if (node.isHome) throw new Error('The homepage cannot contain child pages or categories.');
+		return { collectionDir: path.join(node.nodeDir, 'pages'), node, pagePath: node.pagePath };
+	}
+
+	const currentDirectory = await canonicalDirectory(invocationRoot);
+	if (currentDirectory === await canonicalDirectory(sitePagesDir)) {
+		return { collectionDir: sitePagesDir, node: null, pagePath: '' };
+	}
+	let node = null;
+	for (const candidate of nodes) {
+		if (await canonicalDirectory(candidate.nodeDir) === currentDirectory) {
+			node = candidate;
+			break;
+		}
+	}
+	if (!node) {
+		throw new Error([
+			'Cannot infer where to add the node from the current directory.',
+			`Run the command from ${toDisplayPath(sitePagesDir)} for a top-level node, from an existing page/category directory for a child, or pass --parent.`,
+		].join('\n'));
+	}
+	if (node.isHome) throw new Error('The homepage cannot contain child pages or categories.');
+	return { collectionDir: path.join(node.nodeDir, 'pages'), node, pagePath: node.pagePath };
+};
+
+const assertCollectionDirectory = async (collectionDir) => {
+	try {
+		const info = await stat(collectionDir);
+		if (!info.isDirectory()) throw new Error(`${toDisplayPath(collectionDir)} exists but is not a directory.`);
+		return false;
+	} catch (error) {
+		if (error?.code !== 'ENOENT') throw error;
+		await mkdir(collectionDir);
+		return true;
+	}
+};
+
+const writeNode = async ({ destination, kind, title }) => {
+	const stagingRoot = path.join(siteDir, '.norna', 'create');
+	await mkdir(stagingRoot, { recursive: true });
+	const stagingDirectory = path.join(stagingRoot, `node-${process.pid}-${randomUUID()}`);
+	await mkdir(stagingDirectory);
+
+	try {
+		if (kind === 'page') {
+			await writeFile(path.join(stagingDirectory, 'content.md'), `# ${escapeMarkdownHeading(title)}\n\n## Introduction\n\nStart writing here.\n`);
+			await mkdir(path.join(stagingDirectory, 'images'));
+		} else {
+			await writeFile(path.join(stagingDirectory, 'category.yaml'), dumpYaml({ label: title }, {
+				lineWidth: -1,
+				noRefs: true,
+			}));
+			await mkdir(path.join(stagingDirectory, 'pages'));
+		}
+		await rename(stagingDirectory, destination);
+	} finally {
+		await rm(stagingDirectory, { force: true, recursive: true });
+	}
+};
+
+const [kind, ...rawArgs] = process.argv.slice(2);
+if (!['category', 'page'].includes(kind)) throw new Error(usage);
+const options = parseArgs(rawArgs);
+if (options.help) {
+	console.log(usage);
+	process.exit(0);
+}
+
+const title = options.titleParts.join(' ').trim();
+if (!title || /[\r\n]/.test(title)) throw new Error(`A one-line ${kind === 'page' ? 'page title' : 'category label'} is required.\n${usage}`);
+const slug = options.slug ?? slugifyAsciiIdentifier(title);
+if (!slug || !pageDirectoryPattern.test(`010-${slug}`)) {
+	throw new Error(`Invalid ${options.slug === null ? 'generated ' : ''}slug "${slug}". Use lowercase ASCII letters, numbers, and single hyphens; pass --slug when automatic transliteration is unsuitable.`);
+}
+
+const structure = await getSiteStructure();
+const parent = await resolveParent({ nodes: structure.nodes, parent: options.parent });
+const siblings = structure.nodes.filter((node) => node.parentPagePath === (parent.pagePath || null) && !node.isHome);
+if (siblings.some((node) => node.pageId === slug)) {
+	throw new Error(`Cannot create "${slug}" below ${parent.pagePath ? `/${parent.pagePath}/` : '/'}. A sibling with that slug already exists.`);
+}
+const order = options.order === null ? getNextOrder(siblings) : parseOrder(options.order);
+if (siblings.some((node) => node.pageOrder === order)) {
+	throw new Error(`Cannot use order ${String(order).padStart(3, '0')} below ${parent.pagePath ? `/${parent.pagePath}/` : '/'}. A sibling already uses it.`);
+}
+
+const directoryName = `${String(order).padStart(3, '0')}-${slug}`;
+const destination = path.join(parent.collectionDir, directoryName);
+const pagePath = [parent.pagePath, slug].filter(Boolean).join('/');
+const action = options.dryRun ? 'Would create' : 'Created';
+
+if (!options.dryRun) {
+	const createdCollection = await assertCollectionDirectory(parent.collectionDir);
+	try {
+		await writeNode({ destination, kind, title });
+	} catch (error) {
+		if (createdCollection) await rmdir(parent.collectionDir).catch(() => {});
+		throw error;
+	}
+}
+
+console.log(`${action} ${kind} "${title}" at ${toDisplayPath(destination)}.`);
+if (kind === 'page') {
+	console.log(`URL: /${pagePath}/`);
+} else {
+	console.log('This navigation category has no page or URL of its own.');
+	console.log(`Child URL prefix: /${pagePath}/`);
+}

package/scripts/check-config.mjs

@@ -1,7 +1,8 @@
-import { siteConfigLabel, sitePublicLabel } from './lib/site-paths.mjs';
+import { siteConfigLabel, sitePublicLabel, siteThemeLabel } from './lib/site-paths.mjs';
 import { getLogoAssets, getPublicAssetInspection } from './lib/logo-assets.mjs';
 import { logoAssetFilenames } from './lib/public-asset-conventions.mjs';
 import { readSitewideContent } from './lib/sitewide-content.mjs';
+import { assertSectionBackgroundPatternCompatibility } from './lib/presentation.mjs';
 import { readThemeConfig, validatePageThemeFiles } from './lib/theme-config.mjs';
 
 const formatErrorMessage = (error) => {
@@ -16,7 +17,13 @@ try {
 	const { projectConfig } = await import('./lib/project-config.mjs');
 	const themeConfig = await readThemeConfig();
 	const sitewideContent = await readSitewideContent();
-	await validatePageThemeFiles();
+	const pageThemeFiles = await validatePageThemeFiles();
+	if (projectConfig.navigation.mode === 'tree') {
+		assertSectionBackgroundPatternCompatibility(themeConfig, siteThemeLabel, 'tree');
+		for (const pageThemeFile of pageThemeFiles) {
+			assertSectionBackgroundPatternCompatibility(pageThemeFile.config, pageThemeFile.label, 'tree');
+		}
+	}
 	const logoAssets = getLogoAssets();
 	const publicAssetInspection = getPublicAssetInspection();
 	const logoAssetPaths = logoAssetFilenames.map((filename) => `${sitePublicLabel}/${filename}`);
@@ -53,6 +60,7 @@ try {
 	console.log(`Font family: ${projectConfig.typography.fontFamily}`);
 	console.log(`Language: ${projectConfig.locale.lang}`);
 	console.log(`Navigation mode: ${projectConfig.navigation.mode}`);
+	console.log(`Section tracking: ${projectConfig.navigation.sectionTracking ? 'enabled' : 'disabled'}`);
 	console.log(`Scroll behavior: ${projectConfig.navigation.scrollBehavior}`);
 } catch (error) {
 	console.error('Config check failed.');

package/scripts/deploy-site.mjs

@@ -2,16 +2,12 @@ import { execFile, spawn } from 'node:child_process';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import {
-	getBodySections,
 	getContentFiles,
 	readSiteFile,
 	supportedImageExtensions,
 	toPosixPath,
 } from './lib/site-content.mjs';
-import {
-	extractNornaMarkdownBlocks,
-	getNornaBlockImageReferences,
-} from './lib/norna-markdown-blocks.mjs';
+import { parsePageMarkdown } from './lib/page-markdown.mjs';
 import { getGitHubRepositoryContext, githubPagesWorkflow } from './lib/github-repository.mjs';
 import {
 	engineRoot,
@@ -149,10 +145,11 @@ const getExpectedImagePaths = async () => {
 
 	for (const contentFile of contentFiles) {
 		const { body } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
+		const page = await parsePageMarkdown(body, { label: contentFile.contentLabel });
 
-		for (const section of (await getBodySections(body)).sections) {
-			const blocks = extractNornaMarkdownBlocks(section.text, { label: contentFile.contentLabel });
-			for (const { image } of getNornaBlockImageReferences(blocks)) {
+		for (const region of page.regions) {
+			if (region.blockErrors.length > 0) throw new Error(region.blockErrors[0].message);
+			for (const { image } of region.managedImages) {
 				if (image.includes('/') || image.includes('\\')) continue;
 				if (!supportedImageExtensions.has(path.extname(image).toLowerCase())) continue;
 

package/scripts/generate-images.mjs

@@ -4,7 +4,6 @@ import { copyFile, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs
 import path from 'node:path';
 import { promisify } from 'node:util';
 import {
-	getBodySections,
 	getContentFiles,
 	readSiteFile,
 	rasterImageExtensions,
@@ -13,10 +12,7 @@ import {
 	toPosixPath,
 } from './lib/site-content.mjs';
 import { readImageDimensions } from './lib/image-dimensions.mjs';
-import {
-	extractNornaMarkdownBlocks,
-	getNornaBlockImageReferences,
-} from './lib/norna-markdown-blocks.mjs';
+import { parsePageMarkdown } from './lib/page-markdown.mjs';
 import {
 	astroPublicDir,
 	generatedImagesDir,
@@ -105,18 +101,18 @@ const getImageSourceKey = (contentFile, image) => `pages/${contentFile.pageDirec
 
 const getReferencedImages = async (contentFile) => {
 	const { body } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
-	const { sections } = await getBodySections(body);
+	const page = await parsePageMarkdown(body, { label: contentFile.contentLabel });
 	const references = [];
 
-	for (const section of sections) {
-		const blocks = extractNornaMarkdownBlocks(section.text, { label: contentFile.contentLabel });
-		for (const { image, line, blockDisplayType } of getNornaBlockImageReferences(blocks)) {
+	for (const region of page.regions) {
+		if (region.blockErrors.length > 0) throw new Error(region.blockErrors[0].message);
+		for (const { image, line, blockDisplayType } of region.managedImages) {
 			references.push({
 				contentFile,
 				image,
 				line,
 				blockDisplayType,
-				sectionLabel: section.id ?? 'page title',
+				sectionLabel: region.id ?? 'page title',
 				sourceKey: getImageSourceKey(contentFile, image),
 			});
 		}
@@ -182,11 +178,11 @@ const validateCarouselOrientations = async (manifest) => {
 
 	for (const contentFile of contentFiles) {
 		const { body } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
-		const { sections } = await getBodySections(body);
+		const page = await parsePageMarkdown(body, { label: contentFile.contentLabel });
 
-		for (const section of sections) {
-			const blocks = extractNornaMarkdownBlocks(section.text, { label: contentFile.contentLabel });
-			for (const block of blocks.filter((candidate) => candidate.type === 'image-carousel')) {
+		for (const region of page.regions) {
+			if (region.blockErrors.length > 0) throw new Error(region.blockErrors[0].message);
+			for (const block of region.blocks.filter((candidate) => candidate.type === 'image-carousel')) {
 				const orientations = new Set(
 					block.images
 						.map((image) => manifest[getImageSourceKey(contentFile, image.image)])
@@ -198,7 +194,7 @@ const validateCarouselOrientations = async (manifest) => {
 				orientations.delete('square');
 				if (orientations.size > 1) {
 					throw new Error(
-						`Carousel in ${section.id ? `section "${section.id}"` : 'the page introduction'} on line ${block.line} mixes landscape and portrait images. Use landscape images with optional square images, or portrait images with optional square images.`,
+						`Carousel in ${region.id ? `section "${region.id}"` : 'the page introduction'} on line ${block.line} mixes landscape and portrait images. Use landscape images with optional square images, or portrait images with optional square images.`,
 					);
 				}
 			}

package/scripts/generate-schemas.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'astro/zod';
 import {
+	categorySchema,
 	configSchema,
 	pageThemeSchema,
 	siteSchema,
@@ -14,6 +15,7 @@ import { applySchemaEditorMetadata } from './lib/schema-editor-metadata.mjs';
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const schemaDirectory = path.join(root, 'schemas');
 const definitions = [
+	['category.schema.json', 'Norna page category', categorySchema],
 	['config.schema.json', 'Norna site configuration', configSchema],
 	['theme.schema.json', 'Norna visual theme', themeVisualSchema],
 	['page-theme.schema.json', 'Norna page theme', pageThemeSchema],
@@ -32,8 +34,9 @@ for (const [filename, title, schema] of definitions) {
 
 schemaFiles.set('manifest.json', `${JSON.stringify({
 	editorApiVersion: 1,
-	schemaVersion: 2,
+	schemaVersion: 3,
 	files: {
+		category: 'category.schema.json',
 		config: 'config.schema.json',
 		contentFrontmatter: 'content-frontmatter.schema.json',
 		sitewideContent: 'sitewide-content.schema.json',

package/scripts/init-site.mjs

@@ -9,6 +9,38 @@ import {
 
 const packageName = '@janga/norna';
 const cliExecutableName = 'norna';
+const standaloneGitignore = `# build output
+dist/
+
+# legacy generated public output
+/public/
+
+# generated site state
+**/.norna/public/
+**/.norna/.astro/
+
+# legacy Astro cache location
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+`;
+const siteGitignore = `.norna/public/
+.norna/.astro/
+`;
 
 const usage = `
 Usage: norna init <target-dir> [--type standalone|embedded] [--site-dir <path>]
@@ -203,6 +235,8 @@ if (type === 'standalone') {
 	if (siteDirectory !== 'site') targetPackageJson.scripts = {};
 	addNornaScripts(targetPackageJson, nornaScripts, { includeStandaloneAliases: true });
 	await writeFile(targetPackageJsonPath, `${JSON.stringify(targetPackageJson, null, 2)}\n`);
+	await writeFile(path.join(targetRoot, '.gitignore'), standaloneGitignore);
+	await writeFile(path.join(targetSiteDir, '.gitignore'), siteGitignore);
 } else {
 	if (!existingEntries) {
 		throw new Error(`Target directory must exist for --type embedded: ${targetRoot}`);
@@ -228,6 +262,7 @@ if (type === 'standalone') {
 		filter: (source) => path.basename(source) !== '.DS_Store',
 		recursive: true,
 	});
+	await writeFile(path.join(targetSiteDir, '.gitignore'), siteGitignore);
 	await writeFile(targetPackageJsonPath, `${JSON.stringify(targetPackageJson, null, 2)}\n`);
 }
 

package/scripts/lib/astro-command.mjs

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { mkdirSync } from 'node:fs';
 import {
+	astroRootDir,
 	engineRoot,
 	siteProjectRoot,
 } from './site-paths.mjs';
@@ -11,18 +13,21 @@ const astroPackagePath = require.resolve('astro/package.json');
 const astroPackage = require(astroPackagePath);
 
 export const astroBinPath = path.join(path.dirname(astroPackagePath), astroPackage.bin.astro);
-export const astroConfigPath = path.relative(siteProjectRoot, path.join(engineRoot, 'astro.config.mjs'))
+export const astroConfigPath = path.relative(astroRootDir, path.join(engineRoot, 'astro.config.mjs'))
 	.split(path.sep)
 	.join('/');
 
-export const getAstroArgs = (args) => [
-	astroBinPath,
-	'--root',
-	siteProjectRoot,
-	'--config',
-	astroConfigPath,
-	...args,
-];
+export const getAstroArgs = (args) => {
+	mkdirSync(astroRootDir, { recursive: true });
+	return [
+		astroBinPath,
+		'--root',
+		astroRootDir,
+		'--config',
+		astroConfigPath,
+		...args,
+	];
+};
 
 export const runAstroInherit = (args, options = {}) => runInherit(
 	process.execPath,