scavold 0.2.0-rc.1

package/lib/sectionManifest.js

@@ -0,0 +1,200 @@
+import { join } from "node:path";
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { SECTIONING_ELEMENTS } from "./containers.js";
+
+/**
+ * Canonical URL of the section-type grammar this manifest conforms to. The
+ * grammar is owned by cratly (the cratly.io site), not by Scavold.
+ */
+export const SECTION_SCHEMA_URL = "https://cratly.io/schema/section-types/v0.json";
+
+/** Version of the section-type grammar emitted manifests conform to. */
+export const SECTION_SPEC_VERSION = 0;
+
+/** Conventional location of the emitted manifest within a website repo. */
+export const SECTION_MANIFEST_DIR = ".cratly";
+export const SECTION_MANIFEST_FILE = "sections.json";
+
+/**
+ * Editor-facing schema for Scavold's built-in section kinds. Emitted into each
+ * website's `.cratly/sections.json` so the cratly editor can render the right
+ * controls when an author inserts or edits a section.
+ *
+ * Keep the `video` props in sync with `videoProps` in
+ * composables/useVideo.js — that composable defines the runtime (data-*) props;
+ * this object describes the same options in the editor's typed vocabulary.
+ */
+export const BUILTIN_SECTIONS = {
+	// The seven sectioning wrappers are generic content containers with no
+	// named props of their own; authors may still add ad-hoc flags / key-value
+	// arguments, which the editor surfaces only when declared in config.
+	...Object.fromEntries(
+		[ ...SECTIONING_ELEMENTS ].map( name => [ name, {
+			label: name[0].toUpperCase() + name.slice( 1 ),
+		} ] ),
+	),
+
+	video: {
+		label: "Video",
+		hint: "Embedded video with playback controls.",
+		props: {
+			src: { type: "media-file", label: "Video file", required: true },
+			poster: { type: "media-file", label: "Poster image" },
+			overlay: {
+				type: "boolean",
+				label: "Background mode",
+				hint: "Play the video as a background and lay this container's content on top of it.",
+			},
+			autoplay: { type: "boolean", label: "Autoplay (muted)", default: false },
+			loop: { type: "boolean", label: "Loop" },
+			muted: { type: "boolean", label: "Muted" },
+			controls: {
+				type: "boolean",
+				label: "Show controls",
+				hint: "Always shown for a normal video; in background mode the controls are hidden unless you enable this.",
+			},
+			preload: {
+				type: "enum",
+				label: "Preload",
+				values: [ "none", "metadata", "auto" ],
+				default: "metadata",
+			},
+			label: {
+				type: "text",
+				label: "Accessible label",
+				hint: "Announced by screen readers when the surrounding text does not describe the video.",
+			},
+		},
+	},
+};
+
+/**
+ * Normalises a single prop definition from a container declaration. Accepts the
+ * shorthand string form (`image: media-file`) and the full object form.
+ *
+ * @param {string|object} def prop definition from .cratly.config.yaml
+ * @returns {object} prop definition for the manifest
+ */
+function normaliseProp( def ) {
+	if ( typeof def === "string" ) {
+		return { type: def };
+	}
+
+	return { ...def };
+}
+
+/**
+ * Derives the typed prop map for one declared container, merging the three
+ * declaration forms. Explicit `props` win; `flags` and `kv` only fill names not
+ * already present as typed props.
+ *
+ * @param {object} decl object form of a container declaration
+ * @returns {Object<string,object>}
+ */
+function propsFromDeclaration( decl ) {
+	const props = {};
+
+	if ( decl.props && typeof decl.props === "object" ) {
+		for ( const [ name, def ] of Object.entries( decl.props ) ) {
+			props[name] = normaliseProp( def );
+		}
+	}
+
+	// boolean flag sugar: `flags: [ dark, centered ]`
+	for ( const flag of decl.flags ?? [] ) {
+		props[flag] ??= { type: "boolean" };
+	}
+
+	// untyped key-value sugar: `kv: [ background, link ]` → text props
+	for ( const key of decl.kv ?? [] ) {
+		props[key] ??= { type: "text" };
+	}
+
+	return props;
+}
+
+/**
+ * Builds a section-type manifest object from the resolved set of containers.
+ *
+ * Starts from Scavold's built-in section kinds, then applies the site's
+ * `containers` declarations from .cratly.config.yaml — adding custom sections
+ * and overriding labels/hints/props of built-ins.
+ *
+ * @param {object} [crateContainers] the `containers` block from .cratly.config.yaml
+ * @param {object} [options]
+ * @param {string} [options.adapterVersion] version reported under `adapter.version`
+ * @returns {object} manifest conforming to SECTION_SCHEMA_URL
+ */
+export function buildSectionManifest( crateContainers = {}, { adapterVersion } = {} ) {
+	const sections = {};
+
+	for ( const [ name, def ] of Object.entries( BUILTIN_SECTIONS ) ) {
+		sections[name] = structuredClone( def );
+	}
+
+	for ( const [ name, value ] of Object.entries( crateContainers ) ) {
+		const decl = typeof value === "string" || value == null ? {} : value;
+		const entry = sections[name] ?? {};
+
+		if ( decl.label != null ) {
+			entry.label = decl.label;
+		}
+
+		if ( decl.hint != null ) {
+			entry.hint = decl.hint;
+		}
+
+		const props = propsFromDeclaration( decl );
+		if ( Object.keys( props ).length > 0 ) {
+			entry.props = { ...( entry.props ?? {} ), ...props };
+		}
+
+		// Editors fall back to the raw container name when no label is given.
+		if ( entry.label == null ) {
+			entry.label = name;
+		}
+
+		sections[name] = entry;
+	}
+
+	return {
+		$schema: SECTION_SCHEMA_URL,
+		specVersion: SECTION_SPEC_VERSION,
+		adapter: {
+			name: "scavold",
+			...( adapterVersion && { version: adapterVersion } ),
+		},
+		sections,
+	};
+}
+
+/**
+ * Writes a section-type manifest to `{cwd}/.cratly/sections.json`, creating the
+ * folder as needed. Skips the write when the on-disk content is already
+ * identical, so emitting during dev does not trigger spurious file-watch churn.
+ *
+ * @param {string} cwd project root
+ * @param {object} manifest manifest object from buildSectionManifest()
+ * @returns {Promise<{ path: string, written: boolean }>}
+ */
+export async function writeSectionManifest( cwd, manifest ) {
+	const dir = join( cwd, SECTION_MANIFEST_DIR );
+	const path = join( dir, SECTION_MANIFEST_FILE );
+	const next = JSON.stringify( manifest, null, "\t" ) + "\n";
+
+	let current = null;
+	try {
+		current = await readFile( path, "utf-8" );
+	} catch {
+		// file absent — fall through to write
+	}
+
+	if ( current === next ) {
+		return { path, written: false };
+	}
+
+	await mkdir( dir, { recursive: true } );
+	await writeFile( path, next, "utf-8" );
+
+	return { path, written: true };
+}

package/package.json

@@ -0,0 +1,86 @@
+{
+	"name": "scavold",
+	"version": "0.2.0-rc.1",
+	"type": "module",
+	"description": "VitePress theme framework — a scaffold for building custom VitePress themes with Vue at the core",
+	"keywords": [
+		"vitepress",
+		"vue",
+		"theme",
+		"framework",
+		"static-site-generator",
+		"i18n",
+		"responsive-images",
+		"markdown-container",
+		"cratly"
+	],
+	"author": "cepharum GmbH <info@cepharum.de> (https://cepharum.de)",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://gitlab.com/cepharum-foss/cratly/scavold.git"
+	},
+	"homepage": "https://scavold.io",
+	"bugs": "https://gitlab.com/cepharum-foss/cratly/scavold/-/issues",
+	"engines": {
+		"node": ">=20"
+	},
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"types": "./lib/index.d.ts",
+			"default": "./lib/index.js"
+		},
+		"./config": {
+			"types": "./lib/config.d.ts",
+			"default": "./lib/config.js"
+		},
+		"./components/*.vue": "./components/*.vue",
+		"./composables/*": "./composables/*",
+		"./lib/*": "./lib/*"
+	},
+	"bin": {
+		"scavold-check-csp": "./scripts/check-csp.js"
+	},
+	"files": [
+		"components",
+		"composables",
+		"l10n",
+		"lib",
+		"scripts",
+		"index.d.ts",
+		"COMPONENTS.md",
+		"FRONTMATTER.md",
+		"README.md",
+		"!**/*.test.js"
+	],
+	"scripts": {
+		"check-csp": "node scripts/check-csp.js",
+		"typecheck": "tsc --noEmit",
+		"docs:dev": "vitepress dev docs",
+		"docs:build": "vitepress build docs",
+		"docs:preview": "vitepress preview docs",
+		"test:unit": "bun test --coverage",
+		"test:unit:dev": "bun test --watch",
+		"lint": "eslint --fix"
+	},
+	"peerDependencies": {
+		"vitepress": ">=1.0.0",
+		"vue": ">=3.0.0"
+	},
+	"dependencies": {
+		"@cepharum/vue3-i18n": "^0.5.4",
+		"markdown-it-container": "^4.0.0",
+		"sharp": "^0.34.5",
+		"yaml": "^2.8.3"
+	},
+	"devDependencies": {
+		"@types/node": "^26.1.2",
+		"eslint": "^10.2.1",
+		"eslint-config-cepharum": "^2.0.2",
+		"eslint-plugin-vue": "^10.9.0",
+		"typescript": "^5.9.3",
+		"vitepress": "^1.6.4",
+		"vue": "^3.5.33"
+	}
+}

package/scripts/check-csp.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Extracts SHA-256 hashes of all inline scripts from a built VitePress site and
+// compares them against a committed reference file. Exits 1 and prints the new
+// hashes when they change, so CI can notify the developer to update the
+// Content-Security-Policy header and commit the new reference.
+//
+// Usage: check-csp [dist-dir] [hashes-file]
+//   dist-dir    Path to the built site directory  (default: docs/.vitepress/dist)
+//   hashes-file Path to the committed hash store  (default: .csp-hashes)
+
+import { createHash } from "crypto";
+import { readFileSync, writeFileSync, existsSync, readdirSync } from "fs";
+import { join, extname } from "path";
+
+function findHtml( dir ) {
+	const out = [];
+	for ( const entry of readdirSync( dir, { withFileTypes: true } ) ) {
+		const p = join( dir, entry.name );
+		if ( entry.isDirectory() ) {
+			out.push( ...findHtml( p ) );
+		} else if ( extname( entry.name ) === ".html" ) {
+			out.push( p );
+		}
+	}
+	return out;
+}
+
+function extractHashes( html ) {
+	const hashes = new Set();
+	for ( const [ , content ] of html.matchAll( /<script(?![^>]*\bsrc\b)[^>]*>([\s\S]*?)<\/script>/gi ) ) {
+		if ( content.trim() ) {
+			const hash = createHash( "sha256" ).update( content ).digest( "base64" );
+			hashes.add( `'sha256-${hash}'` );
+		}
+	}
+	return hashes;
+}
+
+const [ distDir = "docs/.vitepress/dist", hashesFile = ".csp-hashes", caddyFile ] = process.argv.slice( 2 );
+
+const hashes = new Set();
+for ( const file of findHtml( distDir ) ) {
+	for ( const h of extractHashes( readFileSync( file, "utf8" ) ) ) {
+		hashes.add( h );
+	}
+}
+
+const sorted = [ ...hashes ].sort();
+const current = sorted.join( " " );
+
+if ( caddyFile ) {
+	// caddy-csp format: one bare hash per line, no surrounding single quotes.
+	writeFileSync( caddyFile, sorted.map( h => h.replace( /'/g, "" ) ).join( "\n" ) + "\n", "utf8" );
+}
+
+const stored = existsSync( hashesFile ) ? readFileSync( hashesFile, "utf8" ).trim() : "";
+
+if ( current === stored ) {
+	console.log( "CSP script hashes unchanged." );
+	process.exit( 0 );
+}
+
+console.error( `CSP script hashes have changed.\n` );
+console.error( `Update your Content-Security-Policy script-src to:\n` );
+console.error( `  script-src 'self' ${current}\n` );
+console.error( `Then commit ${hashesFile} with:\n` );
+console.error( `  ${current}` );
+process.exit( 1 );