@janga/norna 0.7.0

package/docs/images-and-metadata.md

@@ -0,0 +1,88 @@
+# Images And Metadata
+
+This document describes the generic image pipeline. Site repositories own their
+source images and any copyright or licensing policy for those images.
+
+## Source Images
+
+Source images live under `site/images/<section-id>/` and are referenced from
+`site/content.md` by filename only.
+
+Supported source extensions:
+
+- `.jpg`
+- `.jpeg`
+- `.png`
+
+Image filenames must be globally unique under `site/images/`. The content and
+image scripts reject duplicate filenames because gallery rows identify images by
+filename only.
+
+## Generated Variants
+
+`npm run norna:images` and `npm run norna:build` generate WebP files in:
+
+```text
+site/.norna/public/images/generated/
+```
+
+The normal display widths are:
+
+```text
+480, 768, 1080, 1440, 1920
+```
+
+Widths larger than the source image are skipped. If the source image is wider
+than all normal display widths, the pipeline also creates one variant at the
+source width.
+
+Generated filenames include the first eight characters of the source SHA-256
+hash:
+
+```text
+example-work-1a2b3c4d-1440.webp
+```
+
+When a source image changes, the generated URL changes too. This avoids stale
+browser, CDN, and GitHub Actions cache entries at the old URL.
+
+## Manifest
+
+The generated image manifest is:
+
+```text
+site/.norna/generated-images.json
+```
+
+It is versioned site state. It stores source hashes, original dimensions,
+output version, and generated variant paths. The image pipeline reuses generated
+files only when the manifest entry matches the current source hash and output
+version, and all expected variant files exist.
+
+Generated files under `site/.norna/public/` are build-preparation output
+and should not be versioned.
+
+## Metadata Behavior
+
+The current engine does not inspect, require, warn about, or write source image
+copyright metadata.
+
+Generated WebP files are created with ImageMagick using `-strip`, so embedded
+metadata is not a publication mechanism for generated variants. Keep licensing,
+credits, copyright notices, alt text, and captions in site-owned files such as
+`site/content.md`, `COPYRIGHT.md`, or other site documentation.
+
+If a site wants embedded metadata in original source files, that process is
+outside the current `norna` command surface.
+
+## GitHub Actions Cache
+
+The starter workflow caches:
+
+```text
+site/.norna/public/images/generated
+```
+
+The cache key should include `site/.norna/generated-images.json` so
+unchanged generated variants can be restored during deploy. With a cache miss or
+a changed source hash, variants are rebuilt from source images.

package/docs/local-development.md

@@ -0,0 +1,61 @@
+# Local Development
+
+Use the local preview commands when editing a site or the engine demo.
+
+## Start Preview
+
+```sh
+npm run norna:dev
+```
+
+The wrapper:
+
+1. syncs `site/public/` into `site/.norna/public/`,
+2. starts Astro in background mode,
+3. waits until the site responds,
+4. opens `http://localhost:4321/` unless `WALDE_NO_OPEN=1` is set.
+
+The host and port are currently fixed in the script:
+
+```text
+localhost:4321
+```
+
+If the port is already in use, the command fails and asks you to stop the
+process using it.
+
+## Test On A Phone
+
+To make the local dev server available to devices on the same Wi-Fi network:
+
+```sh
+npm run norna:dev:lan
+```
+
+The command prints one or more local IPv4 URLs. Open one of them on the phone.
+The phone and computer must use the same network, and macOS may ask to allow
+incoming connections for Node. Stop the server after testing with
+`npm run norna:dev:stop` because it is accessible from the local network.
+
+## Manage Preview
+
+```sh
+npm run norna:dev:status
+npm run norna:dev:logs
+npm run norna:dev:logs -- --follow
+npm run norna:dev:restart
+npm run norna:dev:stop
+```
+
+The local server state and logs live under `.astro/`.
+
+## Rebuild Stale Preview
+
+Use this when generated content or image state looks stale:
+
+```sh
+npm run norna:build:local
+```
+
+It runs the full build and restarts the local dev server without opening a new
+browser window.

package/docs/publishing.md

@@ -0,0 +1,81 @@
+# Publishing
+
+Publishing is site-specific. The generic deploy commands read repository,
+branch, workflow, watch, and public URL settings from the selected site's
+`site/config.mjs`.
+
+Do not run deploy commands from the engine repository unless you deliberately
+want to test the demo configuration.
+
+## GitHub Pages Workflow
+
+Each site repository should own its `.github/workflows/deploy.yml`. The starter
+workflow:
+
+1. checks out the site repository,
+2. sets up Node,
+3. installs image tools,
+4. restores the generated image cache,
+5. runs `npm ci`,
+6. runs `npm run build` in the starter, which aliases
+   `npm run norna:build`,
+7. uploads `dist/`,
+8. deploys to GitHub Pages.
+
+Site-specific static files such as `site/public/CNAME`, `robots.txt`, and
+`sitemap.xml` belong in the site repository.
+
+## Deploy An Already Committed Branch
+
+Use:
+
+```sh
+npm run norna:deploy
+```
+
+The deploy command:
+
+- requires the current branch to equal `github.branch`,
+- requires a clean worktree before build,
+- fetches `origin`,
+- refuses to proceed when the branch is behind or diverged,
+- runs the full build,
+- requires the build to leave the worktree clean,
+- pushes only when the local branch is ahead of `origin/<branch>`,
+- checks the configured GitHub Pages workflow.
+
+It does not create commits or push uncommitted changes.
+
+## Deploy With A Generated Commit
+
+The older convenience flow remains available:
+
+```sh
+npm run norna:deploy:commit -- "Commit message"
+```
+
+It builds, stages only allowed site changes, commits, pushes, and checks Pages.
+The allowlist is implemented in `scripts/deploy-site.mjs` and includes the
+site content file, selected config/static files, expected gallery images,
+generated image manifest, package files, `tsconfig.json`, `astro.config.mjs`,
+and `src/` changes.
+
+## Watch A Deploy
+
+Use:
+
+```sh
+npm run norna:deploy:watch
+```
+
+By default it monitors the workflow run for the current `HEAD` on the configured
+branch and repository. Useful one-run overrides include:
+
+```sh
+npm run norna:deploy:watch -- --timeout 20m --interval 5s
+npm run norna:deploy:watch -- --sha <commit-sha>
+```
+
+The monitor prints the run id, run URL, Actions URL, branch, commit SHA, status,
+and configured public site URL. On failures it fetches failed job details and a
+log excerpt.

package/docs/site-examples-structure-note.md

@@ -0,0 +1,105 @@
+# Site Examples Structure Note
+
+This note defines the intended repository vocabulary before reorganizing
+starter files, demo sites, fixtures, and documentation sites. It is a design
+note, not an implementation record.
+
+## Goal
+
+`norna` should make it easy to find runnable examples and understand which
+files are product documentation, which files are examples, and which files are
+test fixtures.
+
+The current repository grew from one local demo, one starter, and a set of
+tests. A future structure should keep those roles separate.
+
+## Terms
+
+### Starter
+
+A starter is a template copied by `norna init`.
+
+It should be small, conservative, and suitable as the first commit in a real
+site repository. It should not be a showcase for every feature.
+
+### Example Site
+
+An example site is a runnable site that demonstrates one or more features.
+
+Examples can be richer than the starter. They may show routes, navigation,
+typography presets, galleries, image carousels, inline styles, and site-specific
+configuration choices.
+
+### Documentation Site
+
+A documentation site is a runnable `norna` site that explains the product
+visually.
+
+It can use images, diagrams, screenshots, and route pages to explain concepts
+such as file structure, presentation inheritance, route navigation, and image
+handling.
+
+### Reference Documentation
+
+Reference documentation is GitHub-readable Markdown for exact interfaces and
+workflows.
+
+It belongs in `docs/` and should remain useful without building a site. It is
+the right home for command reference, configuration reference, content schema,
+publishing workflows, and engine development notes.
+
+### Fixture
+
+A fixture is test data.
+
+It should be minimal, stable, and optimized for regression tests rather than
+for human reading or visual appeal.
+
+## Intended Direction
+
+A future structure should collect runnable site examples in one place, for
+example:
+
+```text
+sites/
+  starter-basic/
+  dog-gallery/
+  routes-demo/
+  typography-demo/
+  docs-site/
+```
+
+The exact names can change, but the roles should remain clear:
+
+- `starter-basic/`: copied by `norna init`.
+- `dog-gallery/`: local visual demo and manual inspection site.
+- `routes-demo/`: focused route/navigation example if dog-gallery becomes too
+  broad.
+- `typography-demo/`: focused typography preset and override example if needed.
+- `docs-site/`: visual documentation built with `norna`.
+
+`docs/` should remain for reference documentation. It should link to the
+documentation site when visual explanation is more useful than reference text.
+
+Fixtures may either stay under `fixtures/` or move under a clearly named test
+area later. They should not be confused with examples.
+
+## Constraints
+
+- Do not remove the starter concept; it has a different purpose from examples.
+- Do not make the documentation site the only documentation.
+- Do not let examples become required input for production site repositories.
+- Keep `norna init` deterministic and easy to test.
+- Keep engine tests using stable fixtures, not visually evolving demo content.
+
+## Open Decisions
+
+- Exact top-level directory name: `sites/`, `examples/`, or another name.
+- Whether `starter-basic/` belongs beside examples or in a separate template
+  area.
+- Whether the current dog-gallery remains the primary manual test site or
+  becomes one example among several.
+- Whether the documentation site should be published anywhere, or exist only as
+  a local/example build.
+- How demo selection should work in npm scripts, for example
+  `npm run demo:dev -- dog-gallery`.

package/docs/site-structure.md

@@ -0,0 +1,81 @@
+# Site Structure
+
+A `norna` site repository owns the content and configuration for one
+published site. The engine repository owns the reusable CLI and renderer.
+
+## Default Layout
+
+The selected site directory defaults to `site/`:
+
+```text
+site/
+|-- config.mjs
+|-- theme.md
+|-- content.md
+|-- images/
+|   `-- <section-id>/
+|-- routes/
+|   `-- <route-folder>/
+|       |-- route-content.md
+|       `-- images/
+|           `-- <section-id>/
+|-- public/
+`-- .norna/
+    |-- generated-images.json
+    `-- public/
+```
+
+Use `NORNA_SITE_DIR` or `norna --site-dir <path>` to select another
+site directory. Commands started from a subdirectory walk upward until they find
+the selected site directory containing both `config.mjs` and `content.md`.
+`theme.md` is optional; omit it to use the engine's built-in presentation
+defaults.
+
+## Versioned Source Files
+
+Version these files in a site repository:
+
+- `site/config.mjs`: technical site configuration.
+- `site/theme.md`: optional site-wide visual theme, inline styles, and frame
+  defaults.
+- `site/content.md`: homepage page file with editable content, section
+  definitions, gallery rows, alt text, and captions.
+- `site/images/<section-id>/`: original source images.
+- `site/routes/<route-folder>/route-content.md`: optional route page files.
+- `site/routes/<route-folder>/images/<section-id>/`: original source images
+  for that route page.
+- `site/public/`: site-specific static public files.
+- `site/.norna/generated-images.json`: generated image manifest used to
+  decide whether WebP variants can be reused.
+- `.github/workflows/deploy.yml`: site-owned GitHub Pages workflow.
+- `package.json` and `package-lock.json`: scripts and pinned engine dependency.
+
+## Generated Files
+
+Do not edit these by hand:
+
+- `site/.norna/public/`: build-preparation output copied from
+  `site/public/`, plus generated images.
+- `dist/`: final static build output.
+- `.astro/`: Astro cache, generated types, and dev-server state.
+- `public/`: legacy generated public output from older engine versions.
+
+`site:public` removes stale copied static files under
+`site/.norna/public/` while preserving generated image output under
+`site/.norna/public/images/`.
+
+Favicons are convention-based. Put files such as `favicon.svg`, `favicon.ico`,
+`favicon.png`, or `apple-touch-icon.png` in `site/public/`. The renderer emits
+icon links only for files that exist.
+
+## Engine Repository Layout
+
+In this repository:
+
+- `bin/norna.mjs` dispatches public CLI commands.
+- `scripts/` contains validation, image, local preview, deploy, and test tools.
+- `src/` contains the Astro renderer, components, styles, and content schema.
+- `starters/basic/` is copied by `norna init <target-dir>` to create a
+  site repository.
+- `fixtures/basic/site/` is used by engine regression tests.
+- `site/` is the local dog-gallery demo used by default in this repository.

package/fixtures/basic/site/.norna/generated-images.json

@@ -0,0 +1 @@
+{}

package/fixtures/basic/site/config.mjs

@@ -0,0 +1,59 @@
+export default {
+	site: {
+		url: 'https://example.com/',
+	},
+	layout: {
+		pageWidth: '1180px',
+		gutter: {
+			desktop: 'clamp(1.25rem, 4vw, 3rem)',
+			mobile: '1rem',
+		},
+	},
+	gallery: {
+		maxAvailableWidthPercent: {
+			desktop: 100,
+			mobile: 100,
+		},
+		maxAvailableHeightPercent: {
+			desktop: 74,
+			mobile: 68,
+		},
+	},
+	typography: {
+		fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif",
+	},
+	navigation: {
+		smoothScroll: {
+			enabled: true,
+			minimumDurationMs: 600,
+			maximumDurationMs: 1_200,
+			durationPerPixelMs: 0.2,
+		},
+	},
+	locale: {
+		lang: 'en',
+		labels: {
+			skipToContent: 'Skip to content',
+			sectionNavigation: 'Sections',
+			gallery: 'Gallery',
+		},
+	},
+	footer: {
+		copyrightMessage: '(c) Fixture Artist.',
+		buildInfo: {
+			enabled: true,
+			text: 'Built',
+			dateTimeFormat: {
+				locale: 'en-GB',
+				timeZone: 'UTC',
+				dateStyle: 'short',
+				timeStyle: 'short',
+			},
+		},
+	},
+	github: {
+		repo: 'owner/fixture-gallery',
+		branch: 'main',
+		pagesWorkflow: 'Deploy to GitHub Pages',
+	},
+};

package/fixtures/basic/site/content.md

@@ -0,0 +1,17 @@
+---
+title: Fixture Gallery
+description: Minimal cli-gallery fixture site.
+sections:
+  - id: intro
+    gallery: []
+  - id: work
+    gallery: []
+
+---
+## Intro {#intro}
+
+This fixture validates the cli-gallery engine against a stable empty gallery.
+
+## Work {#work}
+
+Fixture section with no gallery images.

package/fixtures/basic/site/images/work/.gitkeep

@@ -0,0 +1 @@
+

package/fixtures/basic/site/public/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Allow: /

package/fixtures/basic/site/theme.md

@@ -0,0 +1,7 @@
+---
+presentation:
+  typography:
+    preset: quiet-gallery
+frame:
+  colors: presentation
+---

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@janga/norna",
+  "description": "A command-line publishing workflow for simple static sites.",
+  "type": "module",
+  "version": "0.7.0",
+  "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/janga/norna.git"
+  },
+  "bugs": {
+    "url": "https://github.com/janga/norna/issues"
+  },
+  "homepage": "https://github.com/janga/norna#readme",
+  "keywords": [
+    "astro",
+    "gallery",
+    "static-site",
+    "cli"
+  ],
+  "bin": {
+    "norna": "bin/norna.mjs"
+  },
+  "files": [
+    "astro.config.mjs",
+    "bin/",
+    "docs/",
+    "fixtures/",
+    "scripts/",
+    "src/",
+    "starters/",
+    "!**/.norna/public/",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "npm run dev:local",
+    "dev:local": "npm run demo:dev",
+    "dev:lan": "node bin/norna.mjs dev:lan",
+    "dev:restart": "node bin/norna.mjs dev:restart",
+    "dev:status": "node bin/norna.mjs dev:status",
+    "dev:logs": "node bin/norna.mjs dev:logs",
+    "dev:stop": "node bin/norna.mjs dev:stop",
+    "config:check": "node bin/norna.mjs config:check",
+    "content:check": "node bin/norna.mjs content:check",
+    "content:sync": "node bin/norna.mjs content:sync",
+    "typography:presets": "node bin/norna.mjs typography:presets",
+    "typography:show": "node bin/norna.mjs typography:show",
+    "site:public": "node bin/norna.mjs site:public",
+    "images": "node bin/norna.mjs images",
+    "build": "npm run demo:build",
+    "build:local": "node bin/norna.mjs build:local",
+    "deploy": "node bin/norna.mjs deploy",
+    "deploy:commit": "node bin/norna.mjs deploy:commit",
+    "deploy:watch": "node bin/norna.mjs deploy:watch",
+    "doctor": "node bin/norna.mjs doctor",
+    "demo:dev": "node bin/norna.mjs dev:local",
+    "demo:build": "node bin/norna.mjs build",
+    "test": "npm run test:content-check && npm run test:site-public && npm run test:engine-commands && npm run test:ci-lockfile && npm run test:temporary-visibility && npm run test:fixture:build && npm run demo:build && npm run package:check",
+    "test:fixture:build": "node bin/norna.mjs --site-dir fixtures/basic/site build",
+    "test:content-check": "node scripts/test-content-check.mjs",
+    "test:site-public": "node scripts/test-site-public.mjs",
+    "test:engine-commands": "node scripts/test-engine-commands.mjs",
+    "test:ci-lockfile": "node scripts/test-ci-lockfile.mjs",
+    "test:temporary-visibility": "node scripts/test-temporary-visibility.mjs",
+    "test:navigation": "node scripts/test-navigation.mjs",
+    "test:navigation:stress": "node scripts/test-navigation.mjs tests/navigation-stress.spec.ts",
+    "test:navigation:preview": "node scripts/test-navigation-preview.mjs",
+    "package:check": "node scripts/test-package-check.mjs",
+    "release:publish": "npm publish --access public --registry=https://registry.npmjs.org/ --cache /private/tmp/norna-npm-cache",
+    "release:patch": "node scripts/release.mjs patch",
+    "release:minor": "node scripts/release.mjs minor",
+    "release:major": "node scripts/release.mjs major",
+    "preview": "node bin/norna.mjs preview",
+    "astro": "node bin/norna.mjs astro"
+  },
+  "dependencies": {
+    "astro": "^7.1.3",
+    "embla-carousel": "^8.6.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.1"
+  }
+}

package/scripts/build-site.mjs

@@ -0,0 +1,16 @@
+import path from 'node:path';
+import { engineRoot, siteProjectRoot } from './lib/site-paths.mjs';
+import { runAstroInherit } from './lib/astro-command.mjs';
+import { runInherit } from './lib/run-command.mjs';
+
+const runScript = (relativePath, args = []) => runInherit(
+	process.execPath,
+	[path.join(engineRoot, relativePath), ...args],
+	{ cwd: siteProjectRoot },
+);
+
+await runScript('scripts/check-config.mjs');
+await runScript('scripts/sync-content-sections.mjs', ['--check']);
+await runScript('scripts/sync-site-public.mjs');
+await runScript('scripts/generate-images.mjs');
+await runAstroInherit(['build']);

package/scripts/check-config.mjs

@@ -0,0 +1,37 @@
+import { siteConfigLabel } from './lib/site-paths.mjs';
+
+const formatErrorMessage = (error) => {
+	if (error instanceof SyntaxError) {
+		return [
+			`${siteConfigLabel} contains invalid JavaScript syntax.`,
+			error.message,
+		].join('\n');
+	}
+
+	if (error instanceof Error) {
+		return error.message;
+	}
+
+	return String(error);
+};
+
+try {
+	const { projectConfig } = await import('./lib/project-config.mjs');
+
+	console.log('Config check passed.');
+	console.log(`Site URL: ${projectConfig.site.url}`);
+	console.log(`Page width: ${projectConfig.layout.pageWidth}`);
+	console.log(`Gutter: desktop ${projectConfig.layout.gutter.desktop}, mobile ${projectConfig.layout.gutter.mobile}`);
+	console.log(`Gallery width: ${projectConfig.gallery.width}`);
+	console.log(`Gallery max available width: desktop ${projectConfig.gallery.maxAvailableWidthPercent.desktop}%, mobile ${projectConfig.gallery.maxAvailableWidthPercent.mobile}%`);
+	console.log(`Gallery max available height: desktop ${projectConfig.gallery.maxAvailableHeightPercent.desktop}%, mobile ${projectConfig.gallery.maxAvailableHeightPercent.mobile}%`);
+	console.log(`Font family: ${projectConfig.typography.fontFamily}`);
+	console.log(`Language: ${projectConfig.locale.lang}`);
+	console.log(`GitHub repo: ${projectConfig.github.repo}`);
+	console.log(`Deploy branch: ${projectConfig.github.branch}`);
+	console.log(`Pages workflow: ${projectConfig.github.pagesWorkflow}`);
+} catch (error) {
+	console.error('Config check failed.');
+	console.error(formatErrorMessage(error));
+	process.exit(1);
+}