@janga/norna 0.7.1 → 0.7.3

package/README.md

@@ -1,7 +1,7 @@
 # norna
 
-`norna` is a reusable command-line toolchain for small static gallery
-sites. It provides the CLI, Astro renderer, validation scripts, image pipeline,
+`norna` is a reusable command-line toolchain for small static websites.
+It provides the CLI, Astro renderer, validation scripts, image pipeline,
 starter project, fixtures, and deploy helpers used by site repositories such as
 `www.walde.se`.
 
@@ -21,10 +21,11 @@ belong in each site repository. For example, Karin Walde's site lives in
 A `norna` site is file-driven:
 
 1. A site repository depends on this package.
-2. The site keeps technical settings, including page width, gallery width, and
-   the global font family, in `site/config.mjs`.
-3. The site can keep site-wide visual theme defaults in `site/theme.md`.
-4. The site keeps homepage content, section order, gallery rows, alt text, and
+2. The site keeps technical settings, including public URL and optional URL
+   base path, in `site/config.mjs`.
+3. The site keeps site-wide visual theme defaults, including layout, image
+   sizing, font, typography, colors, and frame colors, in `site/theme.md`.
+4. The site keeps homepage content, section order, image rows, alt text, and
    captions in `site/content.md`.
 5. Optional route pages live under
    `site/routes/<route-folder>/route-content.md`.
@@ -35,7 +36,10 @@ A `norna` site is file-driven:
    Astro pages, and can help publish the committed branch through GitHub Pages.
 
 The default site directory is `site/`. Commands can also use another directory
-with `NORNA_SITE_DIR` or `norna --site-dir <path>`.
+with `NORNA_SITE_DIR` or `norna --site-dir <path>`. Without an explicit site
+directory, commands first accept the current directory when it contains
+`config.mjs` and `content.md`; otherwise they walk upward looking for a
+`site/` directory with those files.
 
 ## Quick Start
 
@@ -52,10 +56,10 @@ For a new site repository:
 
 ```sh
 cd ../
-npx @janga/norna@latest init my-gallery
-cd my-gallery
+npx @janga/norna@latest init my-site
+cd my-site
 npm install
-npm run norna:dev
+npm run dev
 ```
 
 Run `init` before `npm install`. A new site directory is not a Node project
@@ -71,16 +75,19 @@ Actions use the same engine version.
 
 - Create a site: [Getting Started](docs/getting-started.md)
 - Understand required site files: [Site Structure](docs/site-structure.md)
-- Edit sections and galleries: [Content](docs/content.md)
+- Edit sections and image rows: [Content](docs/content.md)
 - Configure a site: [Configuration](docs/configuration.md)
-- Configure site-wide theme: [Content](docs/content.md#site-theme)
-- Set page width: [`layout.pageWidth`](docs/configuration.md#layoutpagewidth)
-- Set side gutters: [`layout.gutter`](docs/configuration.md#layoutgutter)
-- Set gallery width: [`gallery.width`](docs/configuration.md#gallerywidth)
+- Publish under a GitHub Pages project path:
+  [`site.basePath`](docs/configuration.md#sitebasepath)
+- Configure site-wide theme: [Theme](docs/theme.md)
+- Add route pages: [Routes](docs/routes.md)
+- Set page width: [`layout.pageWidth`](docs/theme.md#layout)
+- Set side gutters: [`layout.gutter`](docs/theme.md#layout)
+- Set image area width: [`gallery.width`](docs/theme.md#image-sizing)
 - Keep images within viewport height:
-  [`gallery.maxAvailableHeightPercent`](docs/configuration.md#gallerymaxavailableheightpercent)
-- Set the site font: [`typography.fontFamily`](docs/configuration.md#typographyfontfamily)
-- Choose typography presets and overrides: [Content](docs/content.md#typography-presets)
+  [`gallery.maxAvailableHeightPercent`](docs/theme.md#image-sizing)
+- Set the site font: [`typography.fontFamily`](docs/theme.md#typography)
+- Choose typography presets and overrides: [Typography](docs/typography.md)
 - Look up CLI and npm scripts: [Commands](docs/commands.md)
 - Understand generated images: [Images And Metadata](docs/images-and-metadata.md)
 - Run local preview: [Local Development](docs/local-development.md)
@@ -98,8 +105,15 @@ Actions use the same engine version.
 GitHub Pages workflows created from the starter install the image tools during
 deployment.
 
+## License
+
+`norna` is licensed under [GNU GPL v3](LICENSE).
+
 ## Documentation
 
+The Norna-built introduction site lives in [`site/`](site/) and is configured
+for GitHub Pages at <https://janga.github.io/norna/>.
+
 Start with [docs/README.md](docs/README.md) for the documentation map and
 recommended reading order.
 

package/astro.config.mjs

@@ -7,9 +7,11 @@ import {
 	astroPublicDir,
 	engineRoot,
 } from './scripts/lib/site-paths.mjs';
+import projectConfig from './scripts/lib/project-config.mjs';
 
 // https://astro.build/config
 export default defineConfig({
+	base: projectConfig.site.basePath,
 	cacheDir: astroCacheDir,
 	outDir: astroDistDir,
 	publicDir: astroPublicDir,

package/bin/norna-cli.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import path from 'node:path';
+
+const args = process.argv.slice(2);
+process.env.NORNA_INVOCATION_ROOT ??= process.cwd();
+
+const usage = `
+Usage: norna <command> [options]
+
+Commands:
+  dev:local              Start local Astro dev server
+  dev:lan                Start dev server for this local network
+  dev:restart            Restart local Astro dev server
+  dev:status             Show local dev server status
+  dev:logs               Show local dev server logs
+  dev:stop               Stop local dev server
+  config:check           Validate site/config.mjs
+  content:check          Validate site/content.md and image references
+  content:sync           Rewrite section order and move misplaced images
+  typography presets     Show built-in typography preset values
+  typography show        Show resolved typography for the selected site
+  site:public            Sync site/public/ to public/
+  images                 Generate optimized image variants
+  engine:update          Update @janga/norna in a site repository
+  engine:version         Show installed engine and Astro versions
+  init                   Create a new site project from the starter
+  build                  Build the selected site
+  build:local            Build and restart local dev server
+  deploy                 Build and deploy committed branch
+  deploy:commit          Build, commit allowed changes, push, and check Pages
+  deploy:watch           Watch GitHub Pages workflow
+  preview                Preview dist/
+  astro                  Run Astro with norna config
+  doctor                 Print resolved paths
+
+Global options:
+  --site-dir <path>      Use a specific site source directory
+  -h, --help             Show this help
+`.trim();
+
+const parseArgs = (rawArgs) => {
+	const commandArgs = [];
+	let siteDir = null;
+
+	for (let index = 0; index < rawArgs.length; index += 1) {
+		const arg = rawArgs[index];
+
+		if (arg === '--site-dir') {
+			const value = rawArgs[index + 1];
+			if (!value || value.startsWith('-')) {
+				throw new Error('--site-dir requires a path.');
+			}
+
+			siteDir = value;
+			index += 1;
+			continue;
+		}
+
+		if (arg.startsWith('--site-dir=')) {
+			siteDir = arg.slice('--site-dir='.length);
+			if (!siteDir) {
+				throw new Error('--site-dir requires a path.');
+			}
+			continue;
+		}
+
+		commandArgs.push(arg);
+	}
+
+	return { commandArgs, siteDir };
+};
+
+let parsedArgs;
+
+try {
+	parsedArgs = parseArgs(args);
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}
+
+const { commandArgs, siteDir } = parsedArgs;
+
+if (siteDir) {
+	process.env.NORNA_SITE_DIR = siteDir;
+}
+
+const [command = 'help', ...rest] = commandArgs;
+const [subcommand, ...subcommandRest] = rest;
+
+if (command === '-h' || command === '--help' || command === 'help') {
+	console.log(usage);
+	process.exit(0);
+}
+
+const [
+	{ runAstroInherit },
+	{ engineRoot, siteProjectRoot },
+	{ runInherit },
+] = await Promise.all([
+	import('../scripts/lib/astro-command.mjs'),
+	import('../scripts/lib/site-paths.mjs'),
+	import('../scripts/lib/run-command.mjs'),
+]);
+
+const runScript = (relativePath, scriptArgs = []) => runInherit(
+	process.execPath,
+	[path.join(engineRoot, relativePath), ...scriptArgs],
+	{ cwd: siteProjectRoot },
+);
+
+const runBuild = () => runScript('scripts/build-site.mjs');
+
+try {
+	if (command === 'dev' || command === 'dev:local') {
+		await runScript('scripts/dev-local.mjs', rest);
+	} else if (command === 'dev:lan') {
+		await runScript('scripts/dev-local.mjs', ['lan', ...rest]);
+	} else if (command === 'dev:restart') {
+		await runScript('scripts/dev-local.mjs', ['restart', ...rest]);
+	} else if (command === 'dev:status') {
+		await runScript('scripts/dev-local.mjs', ['status', ...rest]);
+	} else if (command === 'dev:logs') {
+		await runScript('scripts/dev-local.mjs', ['logs', ...rest]);
+	} else if (command === 'dev:stop') {
+		await runScript('scripts/dev-local.mjs', ['stop', ...rest]);
+	} else if (command === 'config:check') {
+		await runScript('scripts/check-config.mjs', rest);
+	} else if (command === 'content:check') {
+		await runScript('scripts/sync-content-sections.mjs', ['--check', ...rest]);
+		await runAstroInherit(['sync']);
+	} else if (command === 'content:sync') {
+		await runScript('scripts/sync-content-sections.mjs', ['--write', ...rest]);
+	} else if (command === 'typography:presets' || (command === 'typography' && subcommand === 'presets')) {
+		const scriptArgs = command === 'typography' ? subcommandRest : rest;
+		await runScript('scripts/show-typography.mjs', ['presets', ...scriptArgs]);
+	} else if (command === 'typography:show' || (command === 'typography' && subcommand === 'show')) {
+		const scriptArgs = command === 'typography' ? subcommandRest : rest;
+		await runScript('scripts/show-typography.mjs', ['show', ...scriptArgs]);
+	} else if (command === 'typography') {
+		throw new Error(`Unknown typography command: ${subcommand ?? ''}\n${usage}`);
+	} else if (command === 'site:public') {
+		await runScript('scripts/sync-site-public.mjs', rest);
+	} else if (command === 'images') {
+		await runScript('scripts/generate-images.mjs', rest);
+	} else if (command === 'engine:update') {
+		await runScript('scripts/update-engine.mjs', rest);
+	} else if (command === 'engine:version') {
+		await runScript('scripts/engine-version.mjs', rest);
+	} else if (command === 'init') {
+		await runScript('scripts/init-site.mjs', rest);
+	} else if (command === 'build') {
+		await runBuild();
+	} else if (command === 'build:local') {
+		await runBuild();
+		await runScript('scripts/dev-local.mjs', ['restart']);
+	} else if (command === 'deploy') {
+		await runScript('scripts/deploy-site.mjs', rest);
+	} else if (command === 'deploy:commit') {
+		await runScript('scripts/deploy-site.mjs', ['commit', ...rest]);
+	} else if (command === 'deploy:watch') {
+		await runScript('scripts/watch-pages-deploy.mjs', rest);
+	} else if (command === 'doctor') {
+		await runScript('scripts/doctor.mjs', rest);
+	} else if (command === 'astro') {
+		await runAstroInherit(rest);
+	} else if (command === 'preview') {
+		await runAstroInherit(['preview', ...rest]);
+	} else {
+		throw new Error(`Unknown command: ${command}\n${usage}`);
+	}
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}

package/bin/norna.mjs

@@ -1,170 +1,169 @@
 #!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile, realpath } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-const args = process.argv.slice(2);
-process.env.NORNA_INVOCATION_ROOT ??= process.cwd();
-
-const usage = `
-Usage: norna <command> [options]
-
-Commands:
-  dev:local              Start local Astro dev server
-  dev:lan                Start dev server for this local network
-  dev:restart            Restart local Astro dev server
-  dev:status             Show local dev server status
-  dev:logs               Show local dev server logs
-  dev:stop               Stop local dev server
-  config:check           Validate site/config.mjs
-  content:check          Validate site/content.md and gallery references
-  content:sync           Rewrite section order and move misplaced images
-  typography:presets     Show built-in typography preset values
-  typography:show        Show resolved typography for the selected site
-  site:public            Sync site/public/ to public/
-  images                 Generate optimized image variants
-  engine:update          Update @janga/norna in a site repository
-  engine:version         Show installed engine and Astro versions
-  init                   Create a new site project from the starter
-  build                  Build the selected site
-  build:local            Build and restart local dev server
-  deploy                 Build and deploy committed branch
-  deploy:commit          Build, commit allowed changes, push, and check Pages
-  deploy:watch           Watch GitHub Pages workflow
-  preview                Preview dist/
-  astro                  Run Astro with norna config
-  doctor                 Print resolved paths
-
-Global options:
-  --site-dir <path>      Use a specific site source directory
-  -h, --help             Show this help
-`.trim();
-
-const parseArgs = (rawArgs) => {
-	const commandArgs = [];
-	let siteDir = null;
-
-	for (let index = 0; index < rawArgs.length; index += 1) {
-		const arg = rawArgs[index];
-
-		if (arg === '--site-dir') {
-			const value = rawArgs[index + 1];
-			if (!value || value.startsWith('-')) {
-				throw new Error('--site-dir requires a path.');
-			}
-
-			siteDir = value;
-			index += 1;
-			continue;
+const packageName = '@janga/norna';
+const currentEntrypoint = fileURLToPath(import.meta.url);
+const implementationEntrypoint = new URL('./norna-cli.mjs', import.meta.url);
+
+const readJson = async (filePath) => JSON.parse(await readFile(filePath, 'utf8'));
+
+const readJsonOptional = async (filePath) => {
+	try {
+		return await readJson(filePath);
+	} catch (error) {
+		if (error.code === 'ENOENT') {
+			return null;
 		}
 
-		if (arg.startsWith('--site-dir=')) {
-			siteDir = arg.slice('--site-dir='.length);
-			if (!siteDir) {
-				throw new Error('--site-dir requires a path.');
-			}
-			continue;
+		throw error;
+	}
+};
+
+const realpathOptional = async (filePath) => {
+	try {
+		return await realpath(filePath);
+	} catch (error) {
+		if (error.code === 'ENOENT') {
+			return null;
 		}
 
-		commandArgs.push(arg);
+		throw error;
 	}
+};
+
+const findNearestProjectRoot = (startDirectory) => {
+	let current = path.resolve(startDirectory);
+
+	while (true) {
+		if (existsSync(path.join(current, 'package.json'))) {
+			return current;
+		}
+
+		const parent = path.dirname(current);
+		if (parent === current) {
+			return null;
+		}
 
-	return { commandArgs, siteDir };
+		current = parent;
+	}
 };
 
-let parsedArgs;
+const isWithinDirectory = (parentDirectory, childDirectory) => {
+	const relativePath = path.relative(parentDirectory, childDirectory);
+	return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+};
 
-try {
-	parsedArgs = parseArgs(args);
-} catch (error) {
-	console.error(error instanceof Error ? error.message : String(error));
-	process.exit(1);
-}
+const declaresNornaDependency = (packageJson) => [
+	'dependencies',
+	'devDependencies',
+	'optionalDependencies',
+	'peerDependencies',
+].some((field) => Object.hasOwn(packageJson[field] ?? {}, packageName));
 
-const { commandArgs, siteDir } = parsedArgs;
+const getPackageBinEntrypoint = (packageRoot, packageJson) => {
+	const bin = packageJson.bin;
+	const binPath = typeof bin === 'string' ? bin : bin?.norna;
 
-if (siteDir) {
-	process.env.NORNA_SITE_DIR = siteDir;
-}
+	if (!binPath) {
+		throw new Error(`${packageName} does not define a norna bin entrypoint.`);
+	}
 
-const [command = 'help', ...rest] = commandArgs;
+	return path.resolve(packageRoot, binPath);
+};
 
-if (command === '-h' || command === '--help' || command === 'help') {
-	console.log(usage);
-	process.exit(0);
-}
+const resolveLocalEntrypoint = async () => {
+	const currentPackageRoot = findNearestProjectRoot(path.dirname(currentEntrypoint));
+	const currentPackageJson = currentPackageRoot
+		? await readJsonOptional(path.join(currentPackageRoot, 'package.json'))
+		: null;
+
+	if (
+		currentPackageJson?.name === packageName
+		&& isWithinDirectory(currentPackageRoot, process.cwd())
+	) {
+		return null;
+	}
+
+	const projectRoot = findNearestProjectRoot(process.cwd());
+	if (!projectRoot) {
+		return null;
+	}
+
+	const projectPackageJson = await readJsonOptional(path.join(projectRoot, 'package.json'));
+	if (!projectPackageJson || projectPackageJson.name === packageName || !declaresNornaDependency(projectPackageJson)) {
+		return null;
+	}
+
+	let localPackageJsonPath;
+	try {
+		const requireFromProject = createRequire(path.join(projectRoot, 'package.json'));
+		localPackageJsonPath = requireFromProject.resolve(`${packageName}/package.json`);
+	} catch (error) {
+		if (error.code === 'MODULE_NOT_FOUND') {
+			return null;
+		}
+
+		throw error;
+	}
+
+	const localPackageJson = await readJson(localPackageJsonPath);
+	const localPackageRoot = path.dirname(localPackageJsonPath);
+	return getPackageBinEntrypoint(localPackageRoot, localPackageJson);
+};
+
+const runLocalEntrypoint = (entrypoint) => {
+	const child = spawn(process.execPath, [entrypoint, ...process.argv.slice(2)], {
+		cwd: process.cwd(),
+		env: process.env,
+		stdio: 'inherit',
+	});
+
+	const forwardSignal = (signal) => {
+		if (!child.killed) {
+			child.kill(signal);
+		}
+	};
+	const signals = ['SIGINT', 'SIGTERM'];
+	for (const signal of signals) {
+		process.once(signal, forwardSignal);
+	}
+
+	child.once('exit', (code, signal) => {
+		for (const forwardedSignal of signals) {
+			process.removeListener(forwardedSignal, forwardSignal);
+		}
+
+		if (signal) {
+			process.kill(process.pid, signal);
+			return;
+		}
+
+		process.exit(code ?? 1);
+	});
+
+	child.once('error', (error) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+};
+
+const localEntrypoint = await resolveLocalEntrypoint();
+if (localEntrypoint) {
+	const [currentRealpath, localRealpath] = await Promise.all([
+		realpathOptional(currentEntrypoint),
+		realpathOptional(localEntrypoint),
+	]);
 
-const [
-	{ runAstroInherit },
-	{ engineRoot, siteProjectRoot },
-	{ runInherit },
-] = await Promise.all([
-	import('../scripts/lib/astro-command.mjs'),
-	import('../scripts/lib/site-paths.mjs'),
-	import('../scripts/lib/run-command.mjs'),
-]);
-
-const runScript = (relativePath, scriptArgs = []) => runInherit(
-	process.execPath,
-	[path.join(engineRoot, relativePath), ...scriptArgs],
-	{ cwd: siteProjectRoot },
-);
-
-const runBuild = () => runScript('scripts/build-site.mjs');
-
-try {
-	if (command === 'dev' || command === 'dev:local') {
-		await runScript('scripts/dev-local.mjs', rest);
-	} else if (command === 'dev:lan') {
-		await runScript('scripts/dev-local.mjs', ['lan', ...rest]);
-	} else if (command === 'dev:restart') {
-		await runScript('scripts/dev-local.mjs', ['restart', ...rest]);
-	} else if (command === 'dev:status') {
-		await runScript('scripts/dev-local.mjs', ['status', ...rest]);
-	} else if (command === 'dev:logs') {
-		await runScript('scripts/dev-local.mjs', ['logs', ...rest]);
-	} else if (command === 'dev:stop') {
-		await runScript('scripts/dev-local.mjs', ['stop', ...rest]);
-	} else if (command === 'config:check') {
-		await runScript('scripts/check-config.mjs', rest);
-	} else if (command === 'content:check') {
-		await runScript('scripts/sync-content-sections.mjs', ['--check', ...rest]);
-		await runAstroInherit(['sync']);
-	} else if (command === 'content:sync') {
-		await runScript('scripts/sync-content-sections.mjs', ['--write', ...rest]);
-	} else if (command === 'typography:presets') {
-		await runScript('scripts/show-typography.mjs', ['presets', ...rest]);
-	} else if (command === 'typography:show') {
-		await runScript('scripts/show-typography.mjs', ['show', ...rest]);
-	} else if (command === 'site:public') {
-		await runScript('scripts/sync-site-public.mjs', rest);
-	} else if (command === 'images') {
-		await runScript('scripts/generate-images.mjs', rest);
-	} else if (command === 'engine:update') {
-		await runScript('scripts/update-engine.mjs', rest);
-	} else if (command === 'engine:version') {
-		await runScript('scripts/engine-version.mjs', rest);
-	} else if (command === 'init') {
-		await runScript('scripts/init-site.mjs', rest);
-	} else if (command === 'build') {
-		await runBuild();
-	} else if (command === 'build:local') {
-		await runBuild();
-		await runScript('scripts/dev-local.mjs', ['restart']);
-	} else if (command === 'deploy') {
-		await runScript('scripts/deploy-site.mjs', rest);
-	} else if (command === 'deploy:commit') {
-		await runScript('scripts/deploy-site.mjs', ['commit', ...rest]);
-	} else if (command === 'deploy:watch') {
-		await runScript('scripts/watch-pages-deploy.mjs', rest);
-	} else if (command === 'doctor') {
-		await runScript('scripts/doctor.mjs', rest);
-	} else if (command === 'astro') {
-		await runAstroInherit(rest);
-	} else if (command === 'preview') {
-		await runAstroInherit(['preview', ...rest]);
+	if (localRealpath && currentRealpath !== localRealpath) {
+		runLocalEntrypoint(localEntrypoint);
 	} else {
-		throw new Error(`Unknown command: ${command}\n${usage}`);
+		await import(implementationEntrypoint.href);
 	}
-} catch (error) {
-	console.error(error instanceof Error ? error.message : String(error));
-	process.exit(1);
+} else {
+	await import(implementationEntrypoint.href);
 }