@minamocms/framework 0.0.0-stage → 0.10.1

package/dist/services/theme-schemas.js

@@ -0,0 +1,137 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseThemeComponentFile } from "./theme-component-file.js";
+import { requiredFieldsHaveValidDefaults } from "./validation.js";
+// themeRoot is agent configuration (the configured site's theme
+// directory), not a request-supplied :path parameter. This walk is
+// deliberately NOT the Group B path-sanitisation helper and must
+// never be reused for untrusted request paths.
+//
+// Flat *.liquid files, one per type, named directly (e.g. hero.liquid,
+// media-text.liquid) - no subfolder per type. Mirrors theme-templates.ts's
+// loadFlatTemplates walk exactly (already established for snippets/
+// layouts), extended to extract the embedded {% schema %} block instead
+// of returning the raw file contents.
+//
+// kind is only used to word each warning ("Section" vs "Block") -
+// callers already know which directory they asked for.
+function loadTypeSchemas(typesDir, kind) {
+    const schemas = {};
+    const acceptsBlocks = {};
+    const warnings = [];
+    let entries;
+    try {
+        entries = readdirSync(typesDir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.liquid'))
+            .map((entry) => entry.name);
+    }
+    catch {
+        return { schemas, acceptsBlocks, warnings };
+    }
+    for (const fileName of entries) {
+        const type = fileName.slice(0, -'.liquid'.length);
+        const label = `${kind} type "${type}" (${fileName}) was excluded from the theme`;
+        let source;
+        try {
+            source = readFileSync(join(typesDir, fileName), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const parsed = parseThemeComponentFile(source);
+        if (!parsed) {
+            warnings.push(`${label}: no valid {% schema %} block found (missing, or not parseable JSON).`);
+            continue;
+        }
+        // A type whose required settings fields lack usable defaults is
+        // skipped the same way a malformed schema block already is -
+        // never a boot failure, just excluded from what gets registered
+        // (guide-theme-authoring.md, Group L).
+        if (!requiredFieldsHaveValidDefaults(parsed.schema)) {
+            warnings.push(`${label}: a property listed in "required" has no valid "default" (see guide-theme-authoring.md).`);
+            continue;
+        }
+        schemas[type] = parsed.schema;
+        // The only place "does this type support nested blocks" is ever
+        // expressed - a markup convention (does the template loop
+        // blocksHtml), not a schema field (guide-theme-authoring.md).
+        acceptsBlocks[type] = parsed.markup.includes('blocksHtml');
+    }
+    return { schemas, acceptsBlocks, warnings };
+}
+// theme/config/site_settings.json: the site-wide settings the theme
+// defines, in the same JSON Schema form a section's {% schema %} uses,
+// vetted the same way. No file means no site settings, which is fine; a
+// file that can't be used is left out with a warning, like a broken
+// section.
+//
+// Not Shopify's config/settings_schema.json, which 0.7.0 and 0.7.1 used:
+// Shopify's VS Code extension checks any file of that name against
+// Shopify's own format (a list of groups), marking Minamo's as wrong -
+// which is how one real site had its file rewritten into Shopify's form.
+// A settings_schema.json in Minamo's form is still read, with a warning
+// to rename it; one in Shopify's form (or anything else) is Shopify's,
+// and left alone.
+const SETTINGS_FILE = 'site_settings.json';
+const OLD_SETTINGS_FILE = 'settings_schema.json';
+function readConfigFile(themeRoot, name) {
+    try {
+        return readFileSync(join(themeRoot, 'config', name), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function loadSettingsSchema(themeRoot) {
+    const source = readConfigFile(themeRoot, SETTINGS_FILE);
+    if (source === null) {
+        return loadOldSettingsSchema(themeRoot);
+    }
+    const label = `Site settings (config/${SETTINGS_FILE}) were excluded from the theme`;
+    let schema;
+    try {
+        schema = JSON.parse(source);
+    }
+    catch {
+        return { warning: `${label}: the file is not valid JSON.` };
+    }
+    if (typeof schema !== 'object' || schema === null || Array.isArray(schema)) {
+        return { warning: `${label}: the file must hold a JSON Schema object, the same form as a section's {% schema %}.` };
+    }
+    if (!requiredFieldsHaveValidDefaults(schema)) {
+        return { warning: `${label}: a property listed in "required" has no valid "default" (see guide-theme-authoring.md).` };
+    }
+    return { schema };
+}
+function loadOldSettingsSchema(themeRoot) {
+    const source = readConfigFile(themeRoot, OLD_SETTINGS_FILE);
+    if (source === null) {
+        return {};
+    }
+    let schema;
+    try {
+        schema = JSON.parse(source);
+    }
+    catch {
+        return {};
+    }
+    if (typeof schema !== 'object' || schema === null || Array.isArray(schema) || !requiredFieldsHaveValidDefaults(schema)) {
+        return {};
+    }
+    return {
+        schema,
+        warning: `Site settings are defined in config/${OLD_SETTINGS_FILE}, the name Shopify uses for its own, different format (its VS Code extension marks the file as wrong). Rename it to config/${SETTINGS_FILE}; nothing else changes.`,
+    };
+}
+export function loadThemeSchemas(themeRoot) {
+    const sections = loadTypeSchemas(join(themeRoot, 'sections'), 'Section');
+    const blocks = loadTypeSchemas(join(themeRoot, 'blocks'), 'Block');
+    const settings = loadSettingsSchema(themeRoot);
+    return {
+        sections: sections.schemas,
+        blocks: blocks.schemas,
+        acceptsBlocks: { sections: sections.acceptsBlocks, blocks: blocks.acceptsBlocks },
+        ...(settings.schema ? { settings: settings.schema } : {}),
+        warnings: [...sections.warnings, ...blocks.warnings, ...(settings.warning ? [settings.warning] : [])],
+    };
+}

package/dist/services/token-auth.d.ts

@@ -0,0 +1,10 @@
+import type { FastifyRequest } from 'fastify';
+import type { Scope, TokenEntry } from '../server-config.ts';
+export type AuthReason = 'missing-token' | 'invalid-token' | 'missing-scope';
+export declare class AuthError extends Error {
+    readonly reason: AuthReason;
+    readonly statusCode: number;
+    constructor(reason: AuthReason, message: string);
+}
+export declare function verifyToken(tokens: TokenEntry[], presentedToken: string): Scope[] | null;
+export declare function requireScope(tokens: TokenEntry[], scope: Scope): (request: FastifyRequest) => Promise<void>;

package/dist/services/token-auth.js

@@ -0,0 +1,64 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+// The first domain error in this codebase's established XxxError+
+// reason convention that has to cross the Fastify HTTP boundary -
+// every prior one throws pre-HTTP (at boot) or predates Phase 2
+// entirely. statusCode is set explicitly in the constructor so the
+// existing global error handler (server.ts, which branches on
+// error.statusCode) passes these through with their real message
+// intact, never sanitising them as a generic 500 - confirmed
+// empirically that a preHandler-thrown error with .statusCode set
+// reaches that same handler correctly.
+export class AuthError extends Error {
+    reason;
+    statusCode;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'AuthError';
+        this.reason = reason;
+        this.statusCode = reason === 'missing-scope' ? 403 : 401;
+    }
+}
+const BEARER_PREFIX = 'Bearer ';
+function hashToken(token) {
+    return createHash('sha256').update(token).digest();
+}
+// Never compare token digests (or hex strings) with === or
+// Buffer.equals() - neither is guaranteed constant-time. Only
+// timingSafeEqual, which is why both sides must first be reduced to
+// a fixed-length digest: it throws on mismatched buffer lengths, and
+// a raw incoming token is never the same length as another token in
+// general (confirmed empirically before this was written).
+export function verifyToken(tokens, presentedToken) {
+    const presentedDigest = hashToken(presentedToken);
+    for (const entry of tokens) {
+        const storedDigest = Buffer.from(entry.hash, 'hex');
+        if (timingSafeEqual(presentedDigest, storedDigest)) {
+            return entry.scopes;
+        }
+    }
+    return null;
+}
+// Applied as a per-route preHandler option
+// (fastify.get(path, { preHandler: requireScope(tokens, 'content') }, handler)),
+// not a whole-file addHook: a single route-group file may eventually
+// mix scopes (e.g. a content-scoped GET and a media-scoped POST in
+// the same file), so the check is granular to the route, not the
+// file. Each route-group file still registers plainly, never wrapped
+// in fastify-plugin's fp(), preserving the per-plugin encapsulation
+// this design depends on.
+export function requireScope(tokens, scope) {
+    return async function scopeGuard(request) {
+        const header = request.headers.authorization;
+        if (!header || !header.startsWith(BEARER_PREFIX)) {
+            throw new AuthError('missing-token', 'Missing or malformed Authorization header');
+        }
+        const presentedToken = header.slice(BEARER_PREFIX.length);
+        const scopes = verifyToken(tokens, presentedToken);
+        if (scopes === null) {
+            throw new AuthError('invalid-token', 'The presented token does not match any configured token');
+        }
+        if (!scopes.includes(scope)) {
+            throw new AuthError('missing-scope', `This route requires the "${scope}" scope`);
+        }
+    };
+}

package/dist/services/urls.d.ts

@@ -0,0 +1,2 @@
+export declare function urlToPagePath(url: string): string;
+export declare function pagePathToUrl(relativePagePath: string): string;

package/dist/services/urls.js

@@ -0,0 +1,20 @@
+// Pure, filesystem-free mapping between a public URL and a page's path
+// relative to pagesRoot. A page with children is a file (about.json)
+// sitting alongside a same-named sibling directory (about/) holding
+// descendants, so this mapping never needs to know whether a given
+// page currently has children - unlike an about/index.json convention,
+// which would make resolution filesystem-dependent.
+export function urlToPagePath(url) {
+    const trimmed = url.replace(/^\/+/, '').replace(/\/+$/, '');
+    if (trimmed === '') {
+        return 'index.json';
+    }
+    return `${trimmed}.json`;
+}
+export function pagePathToUrl(relativePagePath) {
+    const withoutExtension = relativePagePath.replace(/\.json$/, '');
+    if (withoutExtension === 'index') {
+        return '/';
+    }
+    return `/${withoutExtension}`;
+}

package/dist/services/validation.d.ts

@@ -0,0 +1,26 @@
+export interface ValidationError {
+    path: string;
+    message: string;
+    keyword: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+export interface ThemeSchemas {
+    sections: Record<string, object>;
+    blocks: Record<string, object>;
+    acceptsBlocks: {
+        sections: Record<string, boolean>;
+        blocks: Record<string, boolean>;
+    };
+    settings?: object;
+    warnings?: string[];
+}
+export declare function requiredFieldsHaveValidDefaults(schema: object): boolean;
+export declare function validateInstance(instance: unknown, kind: 'section' | 'block', themeSchemas: ThemeSchemas): ValidationResult;
+export declare function validatePage(page: unknown, themeSchemas: ThemeSchemas): ValidationResult;
+export declare function validateMenu(menu: unknown): ValidationResult;
+export declare function validateRedirects(redirects: unknown): ValidationResult;
+export declare function validateContent(relativePath: string, content: unknown, themeSchemas: ThemeSchemas): ValidationResult;
+export declare function validateSiteSettings(settings: unknown, themeSchemas: ThemeSchemas): ValidationResult;

package/dist/services/validation.js

@@ -0,0 +1,195 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Ajv } from 'ajv';
+// strict: false because theme schema.json files are authored by theme
+// authors, not agent code, and are validated the same lenient way
+// everywhere (see theme-schemas.ts).
+const ajv = new Ajv({ allErrors: true, strict: false });
+// The nine format values guide-theme-authoring.md/AGENTS.md actually
+// document (richtext/image/video/textarea/uri/date/color/range/toggle -
+// uri and date are real standard JSON Schema formats already understood
+// without this) are still, correctly, UI hints only: registering them
+// as a literal no-op format (the `true` here, not a real validator
+// function) doesn't make Ajv enforce anything about them, it only
+// stops it printing "unknown format \"x\" ignored" for values that are
+// completely expected. A theme author's genuine typo (e.g. "iamge")
+// still isn't in this list, so it still warns - this only silences the
+// ones we ourselves tell theme authors to use, not unknown-format
+// warnings in general.
+// "url" (the link field's documented name) and "uri" (its name before)
+// are hints too: a link is a site path like "/about" as often as a full
+// address, which a real uri check would reject.
+for (const format of ['richtext', 'image', 'textarea', 'color', 'range', 'toggle', 'video', 'url', 'uri']) {
+    ajv.addFormat(format, true);
+}
+const schemasDir = join(import.meta.dirname, '..', 'schemas');
+function readSchema(filename) {
+    return JSON.parse(readFileSync(join(schemasDir, filename), 'utf-8'));
+}
+const instanceSchema = readSchema('instance.schema.json');
+ajv.addSchema(instanceSchema);
+const validatePageEnvelope = ajv.compile(readSchema('page.schema.json'));
+const validateMenuEnvelope = ajv.compile(readSchema('menu.schema.json'));
+const validateRedirectsEnvelope = ajv.compile(readSchema('redirects.schema.json'));
+const validateInstanceEnvelope = ajv.compile(instanceSchema);
+function normaliseErrors(errors) {
+    if (!errors) {
+        return [];
+    }
+    return errors.map((error) => {
+        let path = error.instancePath;
+        if (error.keyword === 'required') {
+            const { missingProperty } = error.params;
+            path = `${error.instancePath}/${missingProperty}`;
+        }
+        else if (error.keyword === 'additionalProperties') {
+            const { additionalProperty } = error.params;
+            path = `${error.instancePath}/${additionalProperty}`;
+        }
+        return { path, message: error.message ?? '', keyword: error.keyword };
+    });
+}
+function runValidator(validate, data) {
+    const valid = validate(data);
+    return { valid: Boolean(valid), errors: normaliseErrors(validate.errors) };
+}
+function prefixErrors(errors, prefix) {
+    return errors.map((error) => ({ ...error, path: `${prefix}${error.path}` }));
+}
+// The theme-authored schema JSON is passed through verbatim end to end
+// (see theme-schemas.ts), so an optional allowedBlocks array rides
+// through the whole pipeline for free, exactly like the "title" keyword
+// already does - never a real Ajv keyword, just a plain top-level
+// annotation read directly off the object. Absent/malformed means
+// unrestricted, matching every theme file written before this existed.
+function allowedBlockTypesOf(schema) {
+    const value = schema?.allowedBlocks;
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string') ? value : undefined;
+}
+// A theme author's own settings schema must declare a "default" for
+// every property it lists as required, and that default must itself
+// satisfy the property's own sub-schema - a bare "default": "" against
+// a minLength: 1 field would technically have a default but still
+// leave a pre-filled instance invalid, defeating the reason this
+// exists (see theme-schemas.ts, which skips a type failing this check
+// exactly like it already skips a malformed {% schema %} block).
+export function requiredFieldsHaveValidDefaults(schema) {
+    const { required, properties } = schema;
+    if (!Array.isArray(required)) {
+        return true;
+    }
+    const propertyMap = (properties && typeof properties === 'object' ? properties : {});
+    return required.every((name) => {
+        if (typeof name !== 'string') {
+            return false;
+        }
+        const propertySchema = propertyMap[name];
+        if (typeof propertySchema !== 'object' || propertySchema === null || !('default' in propertySchema)) {
+            return false;
+        }
+        // ajv.validate compiles+runs propertySchema in isolation, detached
+        // from whatever schema it was pulled out of - a "$ref" pointing at
+        // a "$defs" entry declared on the parent (not inside this property
+        // sub-schema itself) can't resolve here, and Ajv throws
+        // (MissingRefError) rather than returning false. That's a real
+        // theme-authoring mistake (this function's whole contract assumes
+        // a schema self-contained enough to validate standalone), not a
+        // reason to crash the caller - loadTypeSchemas already treats a
+        // false return here as "type excluded, boot warning printed", so
+        // folding a thrown validation error into that exact same false
+        // keeps every possible way a required field's default can be
+        // unusable on the one graceful path, instead of one of them being
+        // the sole exception that takes the whole server down.
+        try {
+            return ajv.validate(propertySchema, propertySchema.default) === true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+export function validateInstance(instance, kind, themeSchemas) {
+    const envelopeResult = runValidator(validateInstanceEnvelope, instance);
+    if (!envelopeResult.valid) {
+        return envelopeResult;
+    }
+    const typed = instance;
+    const typeSchemas = kind === 'section' ? themeSchemas.sections : themeSchemas.blocks;
+    const typeSchema = typeSchemas[typed.type];
+    const errors = [];
+    if (!typeSchema) {
+        errors.push({
+            path: '/type',
+            message: `Unknown ${kind} type "${typed.type}"`,
+            keyword: 'unknownType',
+        });
+    }
+    else {
+        const settingsValidate = ajv.compile(typeSchema);
+        const settingsResult = runValidator(settingsValidate, typed.settings);
+        errors.push(...prefixErrors(settingsResult.errors, '/settings'));
+    }
+    if (typed.blocks) {
+        const allowedBlocks = allowedBlockTypesOf(typeSchema);
+        typed.blocks.forEach((block, index) => {
+            const blockType = block?.type;
+            if (allowedBlocks && typeof blockType === 'string' && !allowedBlocks.includes(blockType)) {
+                errors.push({
+                    path: `/blocks/${index}/type`,
+                    message: `Block type "${blockType}" is not allowed here`,
+                    keyword: 'disallowedBlockType',
+                });
+            }
+            const blockResult = validateInstance(block, 'block', themeSchemas);
+            errors.push(...prefixErrors(blockResult.errors, `/blocks/${index}`));
+        });
+    }
+    return { valid: errors.length === 0, errors };
+}
+function validateSectionedContent(envelopeValidate, content, themeSchemas) {
+    const envelopeResult = runValidator(envelopeValidate, content);
+    if (!envelopeResult.valid) {
+        return envelopeResult;
+    }
+    const typed = content;
+    const errors = [];
+    typed.sections.forEach((section, index) => {
+        const sectionResult = validateInstance(section, 'section', themeSchemas);
+        errors.push(...prefixErrors(sectionResult.errors, `/sections/${index}`));
+    });
+    return { valid: errors.length === 0, errors };
+}
+export function validatePage(page, themeSchemas) {
+    return validateSectionedContent(validatePageEnvelope, page, themeSchemas);
+}
+export function validateMenu(menu) {
+    return runValidator(validateMenuEnvelope, menu);
+}
+// Never routed through validateContent's dispatcher below: redirects.json
+// lives at the site root, not under content/, so it never has a
+// content/-relative path for that dispatcher to match against.
+export function validateRedirects(redirects) {
+    return runValidator(validateRedirectsEnvelope, redirects);
+}
+// Dispatches on the relative path's prefix, not an in-file `type`
+// field: a menu has no `type` field at all, and the correct schema to
+// parse against must be known before the content is even validated.
+export function validateContent(relativePath, content, themeSchemas) {
+    if (relativePath.startsWith('menus/')) {
+        return validateMenu(content);
+    }
+    return validatePage(content, themeSchemas);
+}
+// Site settings (content/settings.json) against the theme's own
+// settings schema. A theme that defines none accepts none.
+export function validateSiteSettings(settings, themeSchemas) {
+    if (typeof settings !== 'object' || settings === null || Array.isArray(settings)) {
+        return { valid: false, errors: [{ path: '', message: 'must be an object', keyword: 'type' }] };
+    }
+    if (!themeSchemas.settings) {
+        return Object.keys(settings).length === 0
+            ? { valid: true, errors: [] }
+            : { valid: false, errors: [{ path: '', message: 'the theme defines no site settings', keyword: 'noSettingsSchema' }] };
+    }
+    return runValidator(ajv.compile(themeSchemas.settings), settings);
+}

package/dist/services/write-queue.d.ts

@@ -0,0 +1 @@
+export declare function enqueue<T>(job: () => Promise<T>): Promise<T>;

package/dist/services/write-queue.js

@@ -0,0 +1,14 @@
+// The single in-process write queue: all disk and git mutations go
+// through enqueue(), one job at a time (constraint 6). Ordering only -
+// no domain knowledge of what "clean" means for a failed job. That is
+// each job's own responsibility (see drafts.ts, publish.ts).
+//
+// In-memory only, does not survive restart: the API only reports
+// success after a write (and commit, where applicable) completes, so an
+// in-flight request during a crash simply fails and the caller retries.
+let tail = Promise.resolve();
+export function enqueue(job) {
+    const result = tail.then(job, job);
+    tail = result.then(() => undefined, () => undefined);
+    return result;
+}

package/dist/site-check/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/site-check/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { runSiteCheck } from "./run-check.js";
+// Run from vhost/ (see the scaffold's own "check" script), so the
+// site root is one level up - the exact same relative relationship
+// SERVER_JS in create-site/generate-site.ts already relies on.
+const siteRoot = resolve(process.cwd(), '..');
+const KIND_LABELS = {
+    schema: 'Theme schema',
+    'render-error': 'Render error',
+    'missing-asset': 'Missing asset',
+    'broken-link': 'Broken link',
+    'misplaced-media': 'Misplaced media',
+};
+function printGrouped(findings) {
+    const byKind = new Map();
+    for (const finding of findings) {
+        const list = byKind.get(finding.kind) ?? [];
+        list.push(finding);
+        byKind.set(finding.kind, list);
+    }
+    for (const [kind, list] of byKind) {
+        console.log(`\n${KIND_LABELS[kind]} (${list.length}):`);
+        for (const finding of list) {
+            const location = finding.pageUrl ? `  ${finding.pageUrl}: ` : '  ';
+            console.log(`${location}${finding.message}`);
+        }
+    }
+}
+function printSuggestions(suggestions) {
+    if (suggestions.length === 0) {
+        return;
+    }
+    console.log(`\nSuggestions (${suggestions.length}):`);
+    for (const suggestion of suggestions) {
+        console.log(`  ${suggestion}`);
+    }
+}
+const result = await runSiteCheck(siteRoot);
+if (result.ok) {
+    console.log('No problems found.');
+    printSuggestions(result.suggestions);
+    process.exit(0);
+}
+console.log(`${result.findings.length} problem${result.findings.length === 1 ? '' : 's'} found:`);
+printGrouped(result.findings);
+printSuggestions(result.suggestions);
+process.exit(1);

package/dist/site-check/run-check.d.ts

@@ -0,0 +1,12 @@
+export type CheckFindingKind = 'schema' | 'render-error' | 'missing-asset' | 'broken-link' | 'misplaced-media';
+export interface CheckFinding {
+    kind: CheckFindingKind;
+    message: string;
+    pageUrl?: string;
+}
+export interface CheckResult {
+    ok: boolean;
+    findings: CheckFinding[];
+    suggestions: string[];
+}
+export declare function runSiteCheck(siteRoot: string): Promise<CheckResult>;