@minamocms/framework 0.0.0-stage → 0.10.1

package/dist/services/resolve-blog-url.js

@@ -0,0 +1,31 @@
+import { existsSync } from 'node:fs';
+import { sanitisePath } from "./path-safety.js";
+import { buildRedirectLookup, loadRedirects } from "./redirects.js";
+import { urlToPostPath } from "./post-urls.js";
+// Mirrors resolve-url.ts's shape exactly (a live post always wins over
+// a redirect at the same URL), kept as its own distinct result type
+// rather than reusing ResolvedUrl - clearer branching at the call site
+// and avoids touching Group C's already-tested resolve-url.ts.
+//
+// Unlike pagesRoot (always expected to exist on a real site),
+// postsRoot is optional - a site that has never used blog posts has
+// no content/posts/ directory at all. sanitisePath calls realpathSync
+// directly on its root argument, which throws a raw, uncaught ENOENT
+// if that root itself is missing - so postsRoot's existence is checked
+// first, before ever calling sanitisePath, rather than letting a
+// perfectly ordinary "no posts yet" site crash on its first /blog/ hit.
+export function resolveBlogUrl(config, url) {
+    const relativePath = urlToPostPath(url);
+    if (relativePath !== null && existsSync(config.postsRoot)) {
+        const postFile = sanitisePath(config.postsRoot, relativePath);
+        if (existsSync(postFile)) {
+            return { kind: 'post', relativePath };
+        }
+    }
+    const lookup = buildRedirectLookup(loadRedirects(config).entries);
+    const to = lookup.get(url);
+    if (to !== undefined) {
+        return { kind: 'redirect', to };
+    }
+    return { kind: 'not-found' };
+}

package/dist/services/resolve-url.d.ts

@@ -0,0 +1,11 @@
+import type { SiteConfig } from '../config.ts';
+export type ResolvedUrl = {
+    kind: 'page';
+    relativePath: string;
+} | {
+    kind: 'redirect';
+    to: string;
+} | {
+    kind: 'not-found';
+};
+export declare function resolveUrl(config: SiteConfig, url: string): ResolvedUrl;

package/dist/services/resolve-url.js

@@ -0,0 +1,20 @@
+import { existsSync } from 'node:fs';
+import { sanitisePath } from "./path-safety.js";
+import { buildRedirectLookup, loadRedirects } from "./redirects.js";
+import { urlToPagePath } from "./urls.js";
+// A redirect whose "from" matches a live page is never served: the
+// page always wins (E6). Only consults redirects.json when no live
+// page exists at the requested URL.
+export function resolveUrl(config, url) {
+    const relativePath = urlToPagePath(url);
+    const pageFile = sanitisePath(config.pagesRoot, relativePath);
+    if (existsSync(pageFile)) {
+        return { kind: 'page', relativePath };
+    }
+    const lookup = buildRedirectLookup(loadRedirects(config).entries);
+    const to = lookup.get(url);
+    if (to !== undefined) {
+        return { kind: 'redirect', to };
+    }
+    return { kind: 'not-found' };
+}

package/dist/services/site-settings.d.ts

@@ -0,0 +1,28 @@
+import type { SiteConfig } from '../config.ts';
+import type { CommitAuthor } from './git.ts';
+import { type ThemeSchemas } from './validation.ts';
+export type SiteSettings = Record<string, unknown>;
+export declare function siteSettingsPath(config: SiteConfig): string;
+export interface StoredSiteSettings {
+    settings: SiteSettings;
+    etag: string | null;
+}
+export declare function readSiteSettings(config: SiteConfig): StoredSiteSettings;
+export declare function resolveSiteSettings(config: SiteConfig, themeSchemas: ThemeSchemas): SiteSettings;
+export declare function resolveSiteSettingsFrom(saved: SiteSettings, themeSchemas: ThemeSchemas): SiteSettings;
+export declare function siteSettingsMtimeMs(config: SiteConfig): number;
+export type SaveSiteSettingsReason = 'validation-failed' | 'conflict' | 'commit-failed' | 'rollback-failed';
+export declare class SaveSiteSettingsError extends Error {
+    readonly reason: SaveSiteSettingsReason;
+    readonly errors: Array<{
+        path: string;
+        message: string;
+    }>;
+    constructor(reason: SaveSiteSettingsReason, message: string, errors?: Array<{
+        path: string;
+        message: string;
+    }>, options?: {
+        cause?: unknown;
+    });
+}
+export declare function saveSiteSettings(config: SiteConfig, themeSchemas: ThemeSchemas, settings: unknown, expectedEtag: string, message: string, author: CommitAuthor): Promise<string>;

package/dist/services/site-settings.js

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { CURRENT_SCHEMA_VERSION } from "../migrations/index.js";
+import { computeEtag, etagsMatch } from "./etag.js";
+import { commitPaths } from "./git.js";
+import { sanitisePath } from "./path-safety.js";
+import { validateSiteSettings } from "./validation.js";
+import { enqueue } from "./write-queue.js";
+export function siteSettingsPath(config) {
+    return sanitisePath(config.contentRoot, 'settings.json');
+}
+// A settings.json that isn't a readable object counts as empty rather
+// than breaking every page: settings only ever fill in a theme's
+// defaults, and the admin shows the file's problem when it's saved.
+export function readSiteSettings(config) {
+    const path = siteSettingsPath(config);
+    if (!existsSync(path)) {
+        return { settings: {}, etag: null };
+    }
+    const bytes = readFileSync(path);
+    let settings = {};
+    try {
+        const parsed = JSON.parse(bytes.toString('utf-8'));
+        if (typeof parsed.settings === 'object' && parsed.settings !== null && !Array.isArray(parsed.settings)) {
+            settings = parsed.settings;
+        }
+    }
+    catch {
+        settings = {};
+    }
+    return { settings, etag: computeEtag(bytes) };
+}
+// What templates see as `settings`: every setting the theme defines,
+// with its default where nothing has been saved. Only the theme's own
+// settings - a saved value for a setting the theme no longer defines is
+// left out.
+export function resolveSiteSettings(config, themeSchemas) {
+    return resolveSiteSettingsFrom(readSiteSettings(config).settings, themeSchemas);
+}
+// The same, from values given rather than read from disk: the preview
+// of settings an editor has changed but not saved yet.
+export function resolveSiteSettingsFrom(saved, themeSchemas) {
+    const properties = themeSchemas.settings?.properties;
+    if (!properties) {
+        return {};
+    }
+    const resolved = {};
+    for (const [name, property] of Object.entries(properties)) {
+        if (name in saved) {
+            resolved[name] = saved[name];
+        }
+        else if (property && typeof property === 'object' && 'default' in property) {
+            resolved[name] = property.default;
+        }
+    }
+    return resolved;
+}
+// For the render cache: pages depend on settings like they depend on
+// menus, so a save must make every cached page stale. 0 when there is
+// no settings.json.
+export function siteSettingsMtimeMs(config) {
+    try {
+        return statSync(siteSettingsPath(config)).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+export class SaveSiteSettingsError extends Error {
+    reason;
+    errors;
+    constructor(reason, message, errors = [], options) {
+        super(message, options);
+        this.name = 'SaveSiteSettingsError';
+        this.reason = reason;
+        this.errors = errors;
+    }
+}
+async function saveSiteSettingsJob(config, themeSchemas, settings, expectedEtag, message, author) {
+    // Checked inside the queued job, never before it (the same TOCTOU
+    // reasoning as drafts.ts and manage-menus.ts). No file yet means
+    // nothing to conflict with.
+    const current = readSiteSettings(config);
+    if (current.etag !== null && !etagsMatch(current.etag, expectedEtag)) {
+        throw new SaveSiteSettingsError('conflict', 'The site settings changed since you opened them');
+    }
+    const result = validateSiteSettings(settings, themeSchemas);
+    if (!result.valid) {
+        throw new SaveSiteSettingsError('validation-failed', `Site settings failed validation: ${result.errors.map((error) => `${error.path || '/'} ${error.message}`).join('; ')}`, result.errors);
+    }
+    const path = siteSettingsPath(config);
+    const before = existsSync(path) ? readFileSync(path) : null;
+    const bytes = Buffer.from(`${JSON.stringify({ schemaVersion: CURRENT_SCHEMA_VERSION, settings }, null, 2)}\n`);
+    writeFileSync(path, bytes);
+    try {
+        commitPaths(config.siteRoot, [path], message, author);
+    }
+    catch (error) {
+        try {
+            if (before === null) {
+                unlinkSync(path);
+            }
+            else {
+                writeFileSync(path, before);
+            }
+        }
+        catch (rollbackError) {
+            throw new SaveSiteSettingsError('rollback-failed', 'Saving the site settings failed and putting them back also failed; content/settings.json needs manual inspection', [], { cause: rollbackError });
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new SaveSiteSettingsError('commit-failed', `Saving the site settings failed: ${detail}`, [], { cause: error });
+    }
+    return computeEtag(bytes);
+}
+export function saveSiteSettings(config, themeSchemas, settings, expectedEtag, message, author) {
+    return enqueue(() => saveSiteSettingsJob(config, themeSchemas, settings, expectedEtag, message, author));
+}

package/dist/services/startup-checks.d.ts

@@ -0,0 +1,10 @@
+export type StartupCheckReason = 'node-version-too-low' | 'site-root-missing' | 'git-binary-absent' | 'not-a-git-repo' | 'invalid-site-config' | 'invalid-token-config';
+export declare class StartupCheckError extends Error {
+    readonly reason: StartupCheckReason;
+    constructor(reason: StartupCheckReason, message: string);
+}
+export interface StartupCheckOptions {
+    env?: NodeJS.ProcessEnv;
+    nodeVersion?: string;
+}
+export declare function runStartupChecks(siteRoot: string, options?: StartupCheckOptions): void;

package/dist/services/startup-checks.js

@@ -0,0 +1,81 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+export class StartupCheckError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'StartupCheckError';
+        this.reason = reason;
+    }
+}
+function parseVersion(version) {
+    const [major = 0, minor = 0, patch = 0] = version
+        .replace(/^v/, '')
+        .split('.')
+        .map((part) => Number.parseInt(part, 10) || 0);
+    return { major, minor, patch };
+}
+function isBelow(version, floor) {
+    if (version.major !== floor.major) {
+        return version.major < floor.major;
+    }
+    if (version.minor !== floor.minor) {
+        return version.minor < floor.minor;
+    }
+    return version.patch < floor.patch;
+}
+// Reads the Node version floor from the agent's own package.json rather
+// than hardcoding a second literal here, so the dev-toolchain minimum
+// (package.json engines.node, driven by --experimental-strip-types) and
+// the shipped-agent's runtime minimum can't drift apart by accident.
+// This is the agent's own bundled file, not site data, so resolving it
+// relative to this module's own location is correct here, the same way
+// validation.ts resolves its own schema files.
+function readNodeVersionFloor() {
+    const packageJsonPath = join(import.meta.dirname, '..', '..', 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const floor = packageJson.engines?.node;
+    if (!floor) {
+        throw new Error('package.json is missing engines.node');
+    }
+    return floor.replace(/^[^\d]*/, '');
+}
+// Fail-fast, in this specific order. Checking "is a git repo" before
+// confirming the site root exists would make a missing root fail with
+// the same ENOENT as "git binary absent" (both execFileSync failures),
+// which would misreport one case as the other.
+export function runStartupChecks(siteRoot, options = {}) {
+    const nodeVersion = options.nodeVersion ?? process.version;
+    const floor = parseVersion(readNodeVersionFloor());
+    if (isBelow(parseVersion(nodeVersion), floor)) {
+        throw new StartupCheckError('node-version-too-low', `Node ${readNodeVersionFloor()} or later is required, found ${nodeVersion}`);
+    }
+    try {
+        if (!statSync(siteRoot).isDirectory()) {
+            throw new Error('not a directory');
+        }
+    }
+    catch {
+        throw new StartupCheckError('site-root-missing', `Site root does not exist or is not a directory: ${siteRoot}`);
+    }
+    const env = options.env ?? process.env;
+    try {
+        // Deliberately not run with cwd: siteRoot, so this check never
+        // depends on the site root existing.
+        execFileSync('git', ['--version'], { env, stdio: 'ignore' });
+    }
+    catch {
+        throw new StartupCheckError('git-binary-absent', 'git binary not found on PATH');
+    }
+    try {
+        execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+            cwd: siteRoot,
+            env,
+            stdio: 'ignore',
+        });
+    }
+    catch {
+        throw new StartupCheckError('not-a-git-repo', `Site root is not a git repository: ${siteRoot}`);
+    }
+}

package/dist/services/static-file.d.ts

@@ -0,0 +1,7 @@
+import type { FastifyReply } from 'fastify';
+export interface StaticFileMatch {
+    fullPath: string;
+    contentType: string;
+}
+export declare function findStaticFile(root: string, relativePath: string): StaticFileMatch | null;
+export declare function sendStaticFile(reply: FastifyReply, match: StaticFileMatch): void;

package/dist/services/static-file.js

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { mimeTypeFor } from "./mime-types.js";
+import { PathSafetyError, sanitisePath } from "./path-safety.js";
+export function findStaticFile(root, relativePath) {
+    // sanitisePath's own symlink-escape check calls realpathSync on the
+    // root itself, which throws (a raw ENOENT, not a PathSafetyError) if
+    // the root doesn't exist at all. theme/assets/ is always created by
+    // scaffoldSite, but theme/root/ is genuinely optional (found live:
+    // this crashed with a 500 on a fixture site with no theme/root/ at
+    // all) - checked here rather than in sanitisePath itself, since
+    // every other caller of that shared, security-audited function
+    // legitimately expects its root to exist.
+    if (!existsSync(root)) {
+        return null;
+    }
+    try {
+        const fullPath = sanitisePath(root, relativePath);
+        if (!existsSync(fullPath) || !statSync(fullPath).isFile()) {
+            return null;
+        }
+        return { fullPath, contentType: mimeTypeFor(fullPath) };
+    }
+    catch (error) {
+        if (error instanceof PathSafetyError) {
+            return null;
+        }
+        throw error;
+    }
+}
+// Access-Control-Allow-Origin: * - both callers are already
+// deliberately unauthenticated, public routes (see assets.ts's own
+// comment for the full reasoning: a font loaded via @font-face
+// enforces CORS unconditionally, and the admin's preview route makes
+// genuinely cross-origin requests for paths that look same-origin).
+export function sendStaticFile(reply, match) {
+    reply.header('Access-Control-Allow-Origin', '*').type(match.contentType).send(readFileSync(match.fullPath));
+}

package/dist/services/theme-component-file.d.ts

@@ -0,0 +1,6 @@
+export interface ParsedThemeComponentFile {
+    markup: string;
+    schema: object;
+}
+export declare function parseThemeComponentFile(source: string): ParsedThemeComponentFile | null;
+export declare function stripSchemaBlock(source: string): string;

package/dist/services/theme-component-file.js

@@ -0,0 +1,39 @@
+// {% schema %} ... {% endschema %} embedded in a single .liquid file,
+// matching Shopify's own theme-section convention - the natural fit
+// since this project already deliberately mirrors Shopify-style
+// sections and blocks. Never a real, live Liquid tag (CLAUDE.md: no
+// dynamically registered Liquid tags or filters, ever) - extracted by
+// plain string parsing before the file is ever handed to the Liquid
+// engine, and stripped out of what actually gets rendered.
+const SCHEMA_BLOCK_PATTERN = /\{%-?\s*schema\s*-?%\}([\s\S]*?)\{%-?\s*endschema\s*-?%\}/;
+// Returns null if no schema block is found, or its content isn't
+// valid JSON - callers treat this the same as today's "file missing/
+// unreadable" case (skip, don't throw). A deliberate behaviour change
+// from the old two-file shape: previously markup and schema loaded and
+// failed independently; now they're one file, so a broken schema block
+// fails the whole component, not just the schema half.
+export function parseThemeComponentFile(source) {
+    const match = SCHEMA_BLOCK_PATTERN.exec(source);
+    if (!match) {
+        return null;
+    }
+    let schema;
+    try {
+        schema = JSON.parse(match[1]);
+    }
+    catch {
+        return null;
+    }
+    if (typeof schema !== 'object' || schema === null) {
+        return null;
+    }
+    const markup = source.slice(0, match.index) + source.slice(match.index + match[0].length);
+    return { markup, schema };
+}
+// The markup Liquid actually sees: {% schema %} is never a real, live
+// Liquid tag, so it is removed before anything is parsed - including
+// when a pushed theme's syntax is checked (theme-files.ts).
+export function stripSchemaBlock(source) {
+    const match = SCHEMA_BLOCK_PATTERN.exec(source);
+    return match ? source.slice(0, match.index) + source.slice(match.index + match[0].length) : source;
+}

package/dist/services/theme-files.d.ts

@@ -0,0 +1,33 @@
+import type { SiteConfig } from '../config.ts';
+import type { ThemeState } from '../theme-state.ts';
+import type { CommitAuthor } from './git.ts';
+export declare function isValidThemePath(path: string): boolean;
+export declare function hashThemeFile(bytes: Buffer): string;
+export interface ThemeFileEntry {
+    path: string;
+    size: number;
+    hash: string;
+}
+export declare function listThemeFiles(config: SiteConfig): ThemeFileEntry[];
+export declare function readThemeFile(config: SiteConfig, path: string): Buffer | null;
+export type ThemePushReason = 'invalid-path' | 'conflict' | 'invalid-liquid' | 'write-failed' | 'commit-failed' | 'rollback-failed';
+export declare class ThemePushError extends Error {
+    readonly reason: ThemePushReason;
+    constructor(reason: ThemePushReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface ThemeWrite {
+    path: string;
+    bytes: Buffer;
+    expected: string | null;
+}
+export interface ThemeDelete {
+    path: string;
+    expected: string;
+}
+export interface ThemePushResult {
+    generation: number;
+    warnings: string[];
+}
+export declare function pushTheme(config: SiteConfig, theme: ThemeState, writes: ThemeWrite[], deletes: ThemeDelete[], message: string, author: CommitAuthor): Promise<ThemePushResult>;

package/dist/services/theme-files.js

@@ -0,0 +1,148 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, relative } from 'node:path';
+import { createEngine } from "../renderer/engine.js";
+import { listFilesRecursively } from "./fs-walk.js";
+import { commitPaths } from "./git.js";
+import { sanitisePath } from "./path-safety.js";
+import { stripSchemaBlock } from "./theme-component-file.js";
+import { enqueue } from "./write-queue.js";
+// A theme file path, relative to theme/: folders and a file name, no dot
+// segments and no hidden files (.DS_Store and the like are never part of
+// a theme).
+const THEME_PATH = /^(?:[A-Za-z0-9_-][A-Za-z0-9._-]*\/)*[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+export function isValidThemePath(path) {
+    return THEME_PATH.test(path);
+}
+export function hashThemeFile(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+export function listThemeFiles(config) {
+    return listFilesRecursively(config.themeRoot, config.themeRoot, '')
+        .filter(isValidThemePath)
+        .sort()
+        .map((path) => {
+        const full = sanitisePath(config.themeRoot, path);
+        const bytes = readFileSync(full);
+        return { path, size: statSync(full).size, hash: hashThemeFile(bytes) };
+    });
+}
+export function readThemeFile(config, path) {
+    if (!isValidThemePath(path)) {
+        return null;
+    }
+    const full = sanitisePath(config.themeRoot, path);
+    return existsSync(full) ? readFileSync(full) : null;
+}
+export class ThemePushError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'ThemePushError';
+        this.reason = reason;
+    }
+}
+function currentHash(path) {
+    return existsSync(path) ? hashThemeFile(readFileSync(path)) : null;
+}
+// Only syntax: a template that can't be parsed breaks every page using
+// it, so it is refused. Anything that parses is left to render as the
+// theme author wrote it. Parsed exactly as the site will: the agent's
+// own engine settings, with any {% schema %} block removed first.
+function checkLiquid(writes) {
+    const parser = createEngine({});
+    for (const write of writes) {
+        if (!write.path.endsWith('.liquid')) {
+            continue;
+        }
+        try {
+            parser.parse(stripSchemaBlock(write.bytes.toString('utf-8')));
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new ThemePushError('invalid-liquid', `theme/${write.path} is not valid Liquid: ${detail}`);
+        }
+    }
+}
+// Writes and deletes theme files as one change: every file is checked
+// against what the client expected first (so a file changed on the site
+// since the client last pulled it is never overwritten), then everything
+// is written, committed once, and the running theme reloaded. If the
+// commit fails, every file is put back as it was.
+async function pushThemeJob(config, theme, writes, deletes, message, author) {
+    const all = [...writes.map((write) => write.path), ...deletes.map((entry) => entry.path)];
+    for (const path of all) {
+        if (!isValidThemePath(path)) {
+            throw new ThemePushError('invalid-path', `Not a theme file path: ${JSON.stringify(path)}`);
+        }
+    }
+    if (new Set(all).size !== all.length) {
+        throw new ThemePushError('invalid-path', 'The same theme file appears more than once in one push');
+    }
+    mkdirSync(config.themeRoot, { recursive: true });
+    const resolved = new Map(all.map((path) => [path, sanitisePath(config.themeRoot, path)]));
+    const conflicts = [];
+    for (const write of writes) {
+        if (currentHash(resolved.get(write.path)) !== write.expected) {
+            conflicts.push(write.path);
+        }
+    }
+    for (const entry of deletes) {
+        if (currentHash(resolved.get(entry.path)) !== entry.expected) {
+            conflicts.push(entry.path);
+        }
+    }
+    if (conflicts.length > 0) {
+        throw new ThemePushError('conflict', `Changed on the site since you last saw them: ${conflicts.map((path) => `theme/${path}`).join(', ')}`);
+    }
+    checkLiquid(writes);
+    const originals = new Map();
+    for (const path of all) {
+        const full = resolved.get(path);
+        originals.set(path, existsSync(full) ? readFileSync(full) : null);
+    }
+    function restore() {
+        for (const [path, bytes] of originals) {
+            const full = resolved.get(path);
+            if (bytes === null) {
+                rmSync(full, { force: true });
+            }
+            else {
+                mkdirSync(dirname(full), { recursive: true });
+                writeFileSync(full, bytes);
+            }
+        }
+    }
+    try {
+        for (const write of writes) {
+            const full = resolved.get(write.path);
+            mkdirSync(dirname(full), { recursive: true });
+            writeFileSync(full, write.bytes);
+        }
+        for (const entry of deletes) {
+            rmSync(resolved.get(entry.path), { force: true });
+        }
+    }
+    catch (error) {
+        restore();
+        throw new ThemePushError('write-failed', 'Writing the theme failed; nothing was changed', { cause: error });
+    }
+    try {
+        commitPaths(config.siteRoot, [...resolved.values()].map((full) => relative(config.siteRoot, full)), message, author);
+    }
+    catch (error) {
+        try {
+            restore();
+        }
+        catch (rollbackError) {
+            throw new ThemePushError('rollback-failed', 'Committing the theme failed and putting it back also failed; theme/ needs manual inspection', { cause: rollbackError });
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ThemePushError('commit-failed', `Committing the theme failed: ${detail}`, { cause: error });
+    }
+    const reloaded = theme.reload();
+    return { generation: reloaded.generation, warnings: reloaded.themeSchemas.warnings ?? [] };
+}
+export function pushTheme(config, theme, writes, deletes, message, author) {
+    return enqueue(() => pushThemeJob(config, theme, writes, deletes, message, author));
+}

package/dist/services/theme-page-templates.d.ts

@@ -0,0 +1,7 @@
+import { type ThemeSchemas } from './validation.ts';
+export interface PageTemplate {
+    id: string;
+    title: string;
+    content: unknown;
+}
+export declare function loadPageTemplates(templatesRoot: string, themeSchemas: ThemeSchemas): PageTemplate[];

package/dist/services/theme-page-templates.js

@@ -0,0 +1,53 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { validatePage } from "./validation.js";
+// templatesRoot is agent configuration (config.templatesRoot), not a
+// request-supplied :path parameter - same non-sanitised, boot-time-only
+// directory walk as theme-schemas.ts's own loadTypeSchemas, never
+// reused for untrusted request paths.
+//
+// Flat *.json files, one per template, named directly (e.g.
+// blog-article.json) - mirrors loadTypeSchemas's walk exactly. Each
+// file must already be a fully valid page (the same page.schema.json
+// every real content/pages/*.json file is validated against, via the
+// theme's own current section/block schemas) - a template IS a real
+// page file, nothing more, so a theme author can create one by
+// literally copying and adapting a real page rather than learning a
+// new authoring convention. A template that fails to parse or fails
+// validation is skipped, never a boot failure - same defensive
+// handling loadTypeSchemas already gives a malformed schema.json.
+export function loadPageTemplates(templatesRoot, themeSchemas) {
+    const templates = [];
+    let entries;
+    try {
+        entries = readdirSync(templatesRoot, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+            .map((entry) => entry.name);
+    }
+    catch {
+        return templates;
+    }
+    for (const fileName of entries) {
+        const id = fileName.slice(0, -'.json'.length);
+        let raw;
+        try {
+            raw = readFileSync(join(templatesRoot, fileName), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        let content;
+        try {
+            content = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (!validatePage(content, themeSchemas).valid) {
+            continue;
+        }
+        const title = content.title;
+        templates.push({ id, title, content });
+    }
+    return templates;
+}

package/dist/services/theme-schemas.d.ts

@@ -0,0 +1,2 @@
+import { type ThemeSchemas } from './validation.ts';
+export declare function loadThemeSchemas(themeRoot: string): ThemeSchemas;