@janga/norna 0.7.0

package/README.md

@@ -0,0 +1,109 @@
+# norna
+
+`norna` is a reusable command-line toolchain for small static gallery
+sites. 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`.
+
+Use this repository when you are:
+
+- creating a new site repository from the starter,
+- maintaining the reusable `@janga/norna` engine,
+- looking up the generic CLI, content, configuration, image, build, or deploy
+  behavior.
+
+Site-specific content, domain files, source images, and publication decisions
+belong in each site repository. For example, Karin Walde's site lives in
+`www.walde.se` and depends on a pinned version of this package.
+
+## Mental Model
+
+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
+   captions in `site/content.md`.
+5. Optional route pages live under
+   `site/routes/<route-folder>/route-content.md`.
+6. Source images live under `site/images/<section-id>/` for the homepage, or
+   under `site/routes/<route-folder>/images/<section-id>/` for a route.
+7. Static public files live under `site/public/`.
+8. `norna` validates the files, generates WebP variants, builds static
+   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>`.
+
+## Quick Start
+
+For engine development in this repository:
+
+```sh
+npm install
+npm run dev:local
+npm run test:fixture:build
+npm run package:check
+```
+
+For a new site repository:
+
+```sh
+cd ../
+npx @janga/norna@latest init my-gallery
+cd my-gallery
+npm install
+npm run norna:dev
+```
+
+Run `init` before `npm install`. A new site directory is not a Node project
+until the starter has created its `package.json`; running `npm install` in an
+empty directory can make npm use a parent project instead. Keep real site
+repositories next to this engine repository, not inside it.
+
+The starter pins `@janga/norna` to an exact npm version. Commit the
+generated `package-lock.json` in the site repository so local builds and GitHub
+Actions use the same engine version.
+
+## Common Tasks
+
+- 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)
+- 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)
+- 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)
+- 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)
+- Publish a site: [Publishing](docs/publishing.md)
+- Work on the engine: [Engine Development](docs/engine-development.md)
+
+## Requirements
+
+- Node.js `>=22.12.0`.
+- ImageMagick, either `magick` or the older `identify` and `convert` commands,
+  when generating images locally.
+- GitHub CLI (`gh`) when using deploy checks or deploy monitoring.
+- Playwright Chromium when running navigation diagnostics.
+
+GitHub Pages workflows created from the starter install the image tools during
+deployment.
+
+## Documentation
+
+Start with [docs/README.md](docs/README.md) for the documentation map and
+recommended reading order.
+
+Planning and future work are tracked in [BACKLOG.md](BACKLOG.md).
+
+`AGENTS.md` contains operating rules for coding agents. Human-facing product
+and workflow documentation should live in this README and `docs/`.

package/astro.config.mjs

@@ -0,0 +1,17 @@
+// @ts-check
+import path from 'node:path';
+import { defineConfig } from 'astro/config';
+import {
+	astroCacheDir,
+	astroDistDir,
+	astroPublicDir,
+	engineRoot,
+} from './scripts/lib/site-paths.mjs';
+
+// https://astro.build/config
+export default defineConfig({
+	cacheDir: astroCacheDir,
+	outDir: astroDistDir,
+	publicDir: astroPublicDir,
+	srcDir: path.join(engineRoot, 'src'),
+});

package/bin/norna.mjs

@@ -0,0 +1,170 @@
+#!/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 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;
+		}
+
+		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;
+
+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') {
+		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]);
+	} else {
+		throw new Error(`Unknown command: ${command}\n${usage}`);
+	}
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}

package/docs/README.md

@@ -0,0 +1,48 @@
+# norna Documentation
+
+This directory contains the reusable product and engine documentation for
+`norna`. The root README is the entry point; these files hold the details.
+
+## Recommended Reading
+
+For a site maintainer:
+
+1. [Getting Started](getting-started.md)
+2. [Site Structure](site-structure.md)
+3. [Configuration](configuration.md)
+4. [Content](content.md)
+5. [Images And Metadata](images-and-metadata.md)
+6. [Local Development](local-development.md)
+7. [Publishing](publishing.md)
+
+For a developer integrating or updating the engine:
+
+1. [Commands](commands.md)
+2. [Command Organization](command-organization.md)
+3. [Site Examples Structure Note](site-examples-structure-note.md)
+4. [Configuration](configuration.md)
+5. [Content](content.md)
+6. [Engine Development](engine-development.md)
+
+For a quick reference:
+
+- [Configuration](configuration.md) describes every supported
+  `site/config.mjs` field, including `layout.pageWidth`, `layout.gutter`,
+  gallery viewport limits, `typography.fontFamily`, validation rule, and
+  default.
+- [Content](content.md) describes page and route frontmatter, section
+  frontmatter, typography presets, site themes, inline styles, temporary
+  sections, Markdown section matching, and content validation.
+- [Commands](commands.md) lists the public CLI surface and starter npm scripts.
+- [Command Organization](command-organization.md) defines command namespaces
+  for pure gallery projects, mixed projects, and engine development.
+- [Site Structure](site-structure.md) separates versioned source files from
+  generated build output.
+- [Site Examples Structure Note](site-examples-structure-note.md) defines the
+  intended vocabulary for starters, examples, docs sites, reference docs, and
+  fixtures before any repository reorganization.
+
+Site repositories should document only their site-specific choices and link here
+for generic `norna` behavior.
+
+Planning and future work are tracked in [../BACKLOG.md](../BACKLOG.md).