@minamocms/framework 0.0.0-stage → 0.10.1

package/dist/search/rebuild-index.js

@@ -0,0 +1,320 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
+import { listFilesRecursively } from "../services/fs-walk.js";
+import { loadThemeSchemas } from "../services/theme-schemas.js";
+import { pagePathToUrl } from "../services/urls.js";
+import { enqueue } from "../services/write-queue.js";
+import { openNodeSqliteDriver } from "./drivers/node-sqlite-driver.js";
+// How many content files the rebuild loop processes between yields to
+// the event loop (see the yield's own comment below for why this
+// exists at all). Large enough that setImmediate's own overhead is
+// negligible next to the real per-file work (a parse plus several
+// SQLite inserts); small enough that no single slice runs long enough
+// to meaningfully stall another request. Not a config knob - no
+// evidence yet this needs to be tunable per site.
+const YIELD_EVERY_N_FILES = 25;
+function collectStrings(value, out) {
+    if (typeof value === 'string') {
+        out.push(value);
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value) {
+            collectStrings(item, out);
+        }
+    }
+    else if (value !== null && typeof value === 'object') {
+        for (const nested of Object.values(value)) {
+            collectStrings(nested, out);
+        }
+    }
+}
+// Recursively collects every string value out of each section's
+// settings and any nested blocks' settings (instance.schema.json's
+// blocks is self-referential, so this covers arbitrarily deep
+// nesting). Only settings values, not id/type, so the indexed body is
+// actual authored content, not structural metadata.
+function extractBody(instances) {
+    const strings = [];
+    const walk = (list) => {
+        if (!list) {
+            return;
+        }
+        for (const instance of list) {
+            collectStrings(instance.settings, strings);
+            walk(instance.blocks);
+        }
+    };
+    walk(instances);
+    return strings.join(' ');
+}
+// Epoch milliseconds for a date-like string - undefined if it doesn't
+// parse, so a malformed date is silently skipped rather than indexed
+// as a nonsensical NaN row (the same "malformed input skipped, not a
+// rebuild failure" tolerance every other part of this pipeline
+// already has for a bad file or a missing theme type).
+function parseDateValue(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+// Turns one raw value into ApiFieldRow entries for a given field key -
+// shared by both theme-flagged fields (extractInstanceApiFields below)
+// and the built-in post envelope fields (extractEnvelopeApiFields),
+// since both need the identical "what does this value actually mean
+// for indexing" logic. Three shapes:
+// - an array: one row per scalar element, all under the same
+//   fieldKey (e.g. a post's own "tags") - a plain "eq" filter then
+//   matches via the exact same mechanism a single-valued field already
+//   uses, no separate array-aware query logic needed anywhere else.
+// - a date-like string (isDateField true - a theme field schema'd
+//   "type": "string", "format": "date", reusing the existing format
+//   convention, or the post envelope's own publishDate): stored as an
+//   epoch-ms number in valueNumber, not text, so range operators work
+//   on it through the same numeric path a flagged price field uses.
+// - a plain scalar (string/number/boolean): stored in its own typed
+//   column. Anything else (object, null, undefined) has nothing
+//   sensible to store or compare and is silently skipped, the same way
+//   a malformed schema block already is elsewhere in this pipeline.
+function pushFieldValue(blockType, instanceId, fieldKey, value, isDateField, out) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            pushFieldValue(blockType, instanceId, fieldKey, item, isDateField, out);
+        }
+        return;
+    }
+    if (typeof value === 'string' && isDateField) {
+        const epoch = parseDateValue(value);
+        if (epoch !== undefined) {
+            out.push({ blockType, instanceId, fieldKey, valueText: null, valueNumber: epoch, valueBool: null });
+        }
+        return;
+    }
+    if (typeof value === 'string') {
+        out.push({ blockType, instanceId, fieldKey, valueText: value, valueNumber: null, valueBool: null });
+    }
+    else if (typeof value === 'number') {
+        out.push({ blockType, instanceId, fieldKey, valueText: null, valueNumber: value, valueBool: null });
+    }
+    else if (typeof value === 'boolean') {
+        out.push({ blockType, instanceId, fieldKey, valueText: null, valueNumber: null, valueBool: value ? 1 : 0 });
+    }
+}
+// Reads schema.properties for the given instance's own type, keeping
+// only properties explicitly flagged "api": true (an unvalidated,
+// theme-authored JSON Schema keyword - same status as "format"/
+// "allowedBlocks", see docs/guide-theme-authoring.md and
+// services/validation.ts's own allowedBlockTypesOf) - and pairs each
+// with its actual value out of instance.settings via pushFieldValue.
+function extractInstanceApiFields(instance, schemaMap, out) {
+    const type = typeof instance.type === 'string' ? instance.type : undefined;
+    const id = typeof instance.id === 'string' ? instance.id : undefined;
+    if (!type || !id) {
+        return;
+    }
+    const properties = schemaMap[type]?.properties;
+    if (!properties || typeof properties !== 'object') {
+        return;
+    }
+    const settings = (instance.settings && typeof instance.settings === 'object' ? instance.settings : {});
+    for (const [key, propSchema] of Object.entries(properties)) {
+        const schema = propSchema;
+        if (schema?.api !== true) {
+            continue;
+        }
+        const isDateField = schema.type === 'string' && schema.format === 'date';
+        pushFieldValue(type, id, key, settings[key], isDateField, out);
+    }
+}
+// Built-in envelope fields, auto-indexed with no "api": true needed -
+// author/publishDate/tags are optional on every page (page.schema.json),
+// so indexing is presence-based rather than gated on a specific "type"
+// value: any page carrying one of these fields gets it indexed,
+// regardless of what its own type string is. block_type '__page__' is a
+// sentinel (never a real theme type, which always matches a *.liquid
+// filename) marking these rows as envelope-level rather than a real
+// section/block instance; instanceId is the page's own url - stable
+// and unique enough, since there's exactly one envelope per page.
+function extractEnvelopeApiFields(page, url) {
+    const rows = [];
+    pushFieldValue('__page__', url, 'author', page.author, false, rows);
+    pushFieldValue('__page__', url, 'publishDate', page.publishDate, true, rows);
+    pushFieldValue('__page__', url, 'tags', page.tags, false, rows);
+    return rows;
+}
+// Top-level page.sections entries are sections; every level of nested
+// .blocks (arbitrarily deep - instance.schema.json's blocks is self-
+// referential, same reasoning extractBody's own walk above already
+// documents) is a block, so which theme-schema map applies flips
+// exactly once, at the top, and stays fixed for everything nested
+// underneath.
+function extractApiFields(sections, sectionSchemas, blockSchemas) {
+    const rows = [];
+    const walk = (list, schemaMap) => {
+        if (!list) {
+            return;
+        }
+        for (const instance of list) {
+            extractInstanceApiFields(instance, schemaMap, rows);
+            walk(instance.blocks, blockSchemas);
+        }
+    };
+    walk(sections, sectionSchemas);
+    return rows;
+}
+function unlinkIfExists(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+// A fresh sqlite file is never actually left in WAL mode by this
+// module (nothing here turns that on), but cleaning up any stray
+// -wal/-shm sidecar files defensively costs nothing and avoids ever
+// leaving one behind next to an abandoned temp build.
+function cleanupSqliteArtifacts(path) {
+    unlinkIfExists(path);
+    unlinkIfExists(`${path}-wal`);
+    unlinkIfExists(`${path}-shm`);
+}
+async function rebuildIndexJob(config) {
+    mkdirSync(config.dataRoot, { recursive: true });
+    // Built into a fresh temp file, then renamed atomically over the
+    // real path (below) - not the old delete-then-recreate-in-place
+    // approach, which left a real window where a concurrent read saw
+    // either a missing file or one that exists but has no tables in it
+    // yet. POSIX rename() is atomic: a reader always sees either the
+    // complete old index or the complete new one, never an in-between
+    // state, and never has to retry an open that landed in the gap.
+    const tmpPath = `${config.searchIndexPath}.tmp-${randomUUID()}`;
+    cleanupSqliteArtifacts(tmpPath);
+    const themeSchemas = loadThemeSchemas(config.themeRoot);
+    try {
+        const driver = openNodeSqliteDriver(tmpPath);
+        try {
+            driver.exec('CREATE VIRTUAL TABLE pages_fts USING fts5(url UNINDEXED, title, body, page_type UNINDEXED)');
+            // A plain table, not FTS5 - page_fields holds typed, exact/range-
+            // comparable values (a price, a rating), the opposite of pages_fts's
+            // own free-text matching. One row per exposed field per instance
+            // (not one column per field name): a page can carry several
+            // instances of the same block type (several "product" blocks on one
+            // listing page), each with its own value, and different pages may
+            // expose entirely different field sets - a fixed column-per-field
+            // schema can't accommodate either. No foreign key back to
+            // pages_fts.url - this whole index is disposable and rebuilt wholly
+            // from scratch every time, same as pages_fts itself.
+            driver.exec('CREATE TABLE page_fields (url TEXT NOT NULL, block_type TEXT NOT NULL, instance_id TEXT NOT NULL, field_key TEXT NOT NULL, value_text TEXT, value_number REAL, value_bool INTEGER)');
+            // Composite, not a bare field_key index - field_key alone only
+            // narrows to one field's rows; leading with it here still serves
+            // that same narrowing (the leftmost-column rule), but the second
+            // column also covers the typed value comparison itself (an
+            // equality or range check) without a further per-row scan. url
+            // supports the self-join a multi-field query ANDs together
+            // (queryContent, query-content.ts) - with no index there, ANDing a
+            // second filter means scanning page_fields in full for every row
+            // the first filter matched.
+            driver.exec('CREATE INDEX page_fields_key_number ON page_fields (field_key, value_number)');
+            driver.exec('CREATE INDEX page_fields_key_text ON page_fields (field_key, value_text)');
+            driver.exec('CREATE INDEX page_fields_url ON page_fields (url)');
+            const insert = driver.prepare('INSERT INTO pages_fts (url, title, body, page_type) VALUES (?, ?, ?, ?)');
+            const insertField = driver.prepare('INSERT INTO page_fields (url, block_type, instance_id, field_key, value_text, value_number, value_bool) VALUES (?, ?, ?, ?, ?, ?, ?)');
+            // Menus are deliberately never walked here at all: they have no
+            // public URL to point a search result at.
+            const collections = [{ root: config.pagesRoot, toUrl: pagePathToUrl }];
+            driver.exec('BEGIN');
+            let filesExamined = 0;
+            for (const { root, toUrl } of collections) {
+                for (const relativePath of listFilesRecursively(root, root, '.json')) {
+                    // A genuine macrotask yield (setImmediate, not a microtask like
+                    // Promise.resolve()/queueMicrotask - Node drains every queued
+                    // microtask before the event loop ever reaches its I/O phases,
+                    // so a chain of only-microtask yields still fully blocks an
+                    // incoming HTTP request from being processed). Without this,
+                    // this loop's entire body - potentially thousands of files -
+                    // runs as one uninterruptible synchronous block: since Node is
+                    // single-threaded, that means every other request the server
+                    // is handling (auth, content reads, publishes) stalls for the
+                    // rebuild's whole duration, not just other search queries.
+                    // Counted once per file examined regardless of whether it
+                    // ends up skipped below, so the cadence tracks total work
+                    // done, not just files actually indexed.
+                    filesExamined += 1;
+                    if (filesExamined % YIELD_EVERY_N_FILES === 0) {
+                        await yieldToEventLoop();
+                    }
+                    let page;
+                    try {
+                        page = JSON.parse(readFileSync(join(root, relativePath), 'utf-8'));
+                    }
+                    catch {
+                        // A malformed individual file is skipped, not an all-or-nothing
+                        // abort: the index is explicitly disposable/best-effort, and
+                        // aborting the whole rebuild over one bad file would leave no
+                        // working index at all - strictly worse than skipping one page.
+                        continue;
+                    }
+                    // Never walks draftsRoot at all, and skips unpublished content
+                    // here - both halves of "drafts and unpublished content are
+                    // absent from the index" (G3) are true by construction, not by
+                    // a filter that could be gotten wrong.
+                    if (page.published === false) {
+                        continue;
+                    }
+                    const url = toUrl(relativePath);
+                    const title = typeof page.title === 'string' ? page.title : '';
+                    const pageType = typeof page.type === 'string' ? page.type : '';
+                    const body = extractBody(page.sections);
+                    insert.run(url, title, body, pageType);
+                    const apiFields = [
+                        ...extractApiFields(page.sections, themeSchemas.sections, themeSchemas.blocks),
+                        ...extractEnvelopeApiFields(page, url),
+                    ];
+                    for (const row of apiFields) {
+                        insertField.run(url, row.blockType, row.instanceId, row.fieldKey, row.valueText, row.valueNumber, row.valueBool);
+                    }
+                }
+            }
+            driver.exec('COMMIT');
+        }
+        finally {
+            driver.close();
+        }
+        renameSync(tmpPath, config.searchIndexPath);
+    }
+    catch (error) {
+        cleanupSqliteArtifacts(tmpPath);
+        throw error;
+    }
+}
+// Queued via enqueue() - two concurrent rebuilds could otherwise both
+// build their own temp file and both attempt the final rename; the
+// second rename would still win cleanly (rename() just replaces
+// whatever is there), but the first rebuild's now-orphaned temp file
+// would never get cleaned up. enqueue() is a generic, domain-agnostic
+// primitive, so reusing it for self-exclusion costs nothing.
+export function rebuildIndex(config) {
+    return enqueue(() => rebuildIndexJob(config));
+}
+// For startServer's own boot-time call: a search index is never
+// git-tracked (constraint 3 - a derived, disposable index), so a fresh
+// clone or a first-ever boot has no index file at all and GET
+// /search.json would stay permanently empty until some content write
+// happened to trigger reindex-on-write.ts, or a caller manually hit
+// POST /v1/search/rebuild. Guarded on existsSync rather than
+// unconditionally rebuilding on every restart - a currently-running
+// site's index is already kept fresh by every publish/unpublish/
+// delete/move/batch (reindex-on-write.ts), so an unconditional rebuild
+// here would just be redundant work on every ordinary restart.
+export function rebuildIndexIfMissing(config) {
+    if (existsSync(config.searchIndexPath)) {
+        return Promise.resolve();
+    }
+    return rebuildIndex(config);
+}

package/dist/server-config.d.ts

@@ -0,0 +1,23 @@
+export type Scope = 'content' | 'theme' | 'media';
+export interface TokenEntry {
+    hash: string;
+    scopes: Scope[];
+}
+export interface RateLimitConfig {
+    max: number;
+    windowMs: number;
+}
+export interface MediaConfig {
+    maxUploadBytes: number;
+}
+export interface ServerConfig {
+    port: number;
+    tokens: TokenEntry[];
+    rateLimit: RateLimitConfig;
+    trustProxy: boolean;
+    ipAllowlist: string[];
+    checkpointIntervalMs: number;
+    media: MediaConfig;
+    adminBaseUrl: string | undefined;
+}
+export declare function loadServerConfig(siteRoot: string): ServerConfig;

package/dist/server-config.js

@@ -0,0 +1,237 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { VHOST_DIR_NAME } from "./config.js";
+import { StartupCheckError } from "./services/startup-checks.js";
+const DEFAULT_PORT = 3000;
+const DEFAULT_RATE_LIMIT = { max: 60, windowMs: 60000 };
+// 10MB (docs/cms-build-plan.md's own suggested default) - comfortably
+// above a properly web-optimised image, well below an unoptimised raw
+// camera export.
+const DEFAULT_MEDIA_MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
+// The build plan's own literal example ("every 30 minutes"), adopted
+// as-is rather than re-litigated - its own [REVIEW] flag was about
+// whether checkpoints belong on main vs a dedicated branch (resolved:
+// main), not this number specifically.
+const DEFAULT_CHECKPOINT_INTERVAL_MS = 1_800_000;
+const VALID_SCOPES = new Set(['content', 'theme', 'media']);
+// sha256 digest, hex-encoded: exactly 64 lowercase hex characters.
+const HEX64_PATTERN = /^[0-9a-f]{64}$/;
+// A loose IPv4/IPv6-shaped typo-catcher, not a real IP parser -
+// exact-IP-only is a deliberate scope reduction (see ip-allowlist.ts),
+// so this doesn't need to be exhaustive either.
+const IP_SHAPE_PATTERN = /^[0-9a-fA-F:.]+$/;
+function parseTokens(value) {
+    if (value === undefined) {
+        // Absent entirely -> no configured tokens -> every scope check
+        // fails closed (401 on everything). The safe default, not an
+        // incidental side effect - see server-config.test.ts's explicit
+        // "no tokens configured" case.
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new StartupCheckError('invalid-token-config', 'site.config.json\'s "tokens" must be an array');
+    }
+    const seenHashes = new Set();
+    const tokens = [];
+    value.forEach((entry, index) => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            throw new StartupCheckError('invalid-token-config', `tokens[${index}] must be an object`);
+        }
+        const record = entry;
+        const hash = record.hash;
+        if (typeof hash !== 'string' || !HEX64_PATTERN.test(hash)) {
+            throw new StartupCheckError('invalid-token-config', `tokens[${index}].hash must be a 64-character hex-encoded sha256 digest`);
+        }
+        if (seenHashes.has(hash)) {
+            throw new StartupCheckError('invalid-token-config', `tokens[${index}].hash duplicates an earlier entry`);
+        }
+        seenHashes.add(hash);
+        const scopesValue = record.scopes;
+        if (!Array.isArray(scopesValue) || scopesValue.length === 0) {
+            throw new StartupCheckError('invalid-token-config', `tokens[${index}].scopes must be a non-empty array`);
+        }
+        const scopes = scopesValue.map((scope) => {
+            if (typeof scope !== 'string' || !VALID_SCOPES.has(scope)) {
+                throw new StartupCheckError('invalid-token-config', `tokens[${index}].scopes contains an unknown scope: ${JSON.stringify(scope)}`);
+            }
+            return scope;
+        });
+        tokens.push({ hash, scopes });
+    });
+    return tokens;
+}
+function parseRateLimit(value) {
+    if (value === undefined) {
+        // Absent entirely -> the default limit applies - matches tokens'/
+        // port's own "absence is not an error" philosophy.
+        return DEFAULT_RATE_LIMIT;
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new StartupCheckError('invalid-site-config', 'site.config.json\'s "rateLimit" must be an object');
+    }
+    const record = value;
+    const max = record.max;
+    if (typeof max !== 'number' || !Number.isInteger(max) || max < 1) {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "rateLimit.max" must be a positive integer, got ${JSON.stringify(max)}`);
+    }
+    const windowMs = record.windowMs;
+    if (typeof windowMs !== 'number' || !Number.isInteger(windowMs) || windowMs < 1) {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "rateLimit.windowMs" must be a positive integer, got ${JSON.stringify(windowMs)}`);
+    }
+    return { max, windowMs };
+}
+function parseMedia(value) {
+    if (value === undefined) {
+        // Absent entirely -> the default limit applies, matching every
+        // other optional-object field's own "absence is not an error"
+        // philosophy.
+        return { maxUploadBytes: DEFAULT_MEDIA_MAX_UPLOAD_BYTES };
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new StartupCheckError('invalid-site-config', 'site.config.json\'s "media" must be an object');
+    }
+    const record = value;
+    const maxUploadBytes = record.maxUploadBytes;
+    if (maxUploadBytes === undefined) {
+        return { maxUploadBytes: DEFAULT_MEDIA_MAX_UPLOAD_BYTES };
+    }
+    if (typeof maxUploadBytes !== 'number' || !Number.isInteger(maxUploadBytes) || maxUploadBytes < 1) {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "media.maxUploadBytes" must be a positive integer, got ${JSON.stringify(maxUploadBytes)}`);
+    }
+    return { maxUploadBytes };
+}
+function parseTrustProxy(value) {
+    if (value === undefined) {
+        // Absent -> false, matching a bare single-process, no-reverse-
+        // proxy deployment assumption unless an operator explicitly opts
+        // in.
+        return false;
+    }
+    if (typeof value !== 'boolean') {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "trustProxy" must be a boolean, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function parseIpAllowlist(value) {
+    if (value === undefined) {
+        // Absent -> [] -> a no-op (checklist H3), not "nothing is
+        // allowed" - see ip-allowlist.ts's isIpAllowed.
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new StartupCheckError('invalid-site-config', 'site.config.json\'s "ipAllowlist" must be an array');
+    }
+    value.forEach((entry, index) => {
+        if (typeof entry !== 'string' || entry.length === 0 || !IP_SHAPE_PATTERN.test(entry)) {
+            throw new StartupCheckError('invalid-site-config', `ipAllowlist[${index}] must be a non-empty IP-address-shaped string, got ${JSON.stringify(entry)}`);
+        }
+    });
+    return value;
+}
+// Undefined -> undefined: absence means the /admin redirect feature
+// is off entirely, not a default target to redirect to (there's no
+// sensible default admin URL to assume). Validated as a real absolute
+// http(s) URL, not just any non-empty string, since it becomes a
+// redirect target - rejects `javascript:`/`ftp:`/anything else before
+// it can ever reach a Location header.
+function parseAdminBaseUrl(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "adminBaseUrl" must be a non-empty string, got ${JSON.stringify(value)}`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "adminBaseUrl" must be a valid URL, got ${JSON.stringify(value)}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "adminBaseUrl" must be an http or https URL, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function parseCheckpointIntervalMs(value) {
+    if (value === undefined) {
+        return DEFAULT_CHECKPOINT_INTERVAL_MS;
+    }
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "checkpointIntervalMs" must be a positive integer, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+// Kept separate from SiteConfig (src/config.ts, pure filesystem paths)
+// and from BootedSite (src/boot.ts): this is site.config.json's
+// non-path settings. Later groups add fields here without needing to
+// restructure this module or its callers - the "media" field below is
+// exactly that: the max-upload-size setting anticipated here since
+// Phase 2 planning, now landed as Phase 4's local-storage foundation.
+//
+// Two different failure classes: the file being entirely absent is
+// not an error (defaults silently) - the whole Phase 1 test estate
+// has no site.config.json and shouldn't need one invented just to
+// boot. The file existing but being malformed IS an error (the
+// operator wrote it and got it wrong), consistent with
+// startup-checks.ts's fail-fast discipline. Token rotation requires a
+// restart, since this loads once at boot - matches the existing
+// "agent upgrade = restart" story already established for schema
+// migrations, a deliberate decision, not an accident.
+// PORT overrides site.config.json's own "port" (or its default) without
+// editing a file - the universal Node/12-factor convention, and how
+// several hosting platforms (Railway, Render, etc.) already inject the
+// port a process must bind. An invalid value is ignored, not a hard
+// failure - a stray non-numeric PORT shouldn't stop the whole site from
+// booting when the configured/default port would have worked fine.
+function resolvePort(configuredPort) {
+    const envPort = process.env.PORT;
+    if (envPort === undefined) {
+        return configuredPort;
+    }
+    const parsed = Number(envPort);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : configuredPort;
+}
+export function loadServerConfig(siteRoot) {
+    const configPath = join(siteRoot, VHOST_DIR_NAME, 'site.config.json');
+    let raw;
+    try {
+        raw = readFileSync(configPath, 'utf-8');
+    }
+    catch {
+        return {
+            port: resolvePort(DEFAULT_PORT),
+            tokens: [],
+            rateLimit: DEFAULT_RATE_LIMIT,
+            trustProxy: false,
+            ipAllowlist: [],
+            checkpointIntervalMs: DEFAULT_CHECKPOINT_INTERVAL_MS,
+            media: { maxUploadBytes: DEFAULT_MEDIA_MAX_UPLOAD_BYTES },
+            adminBaseUrl: undefined,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new StartupCheckError('invalid-site-config', `site.config.json is not valid JSON: ${detail}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new StartupCheckError('invalid-site-config', 'site.config.json must be a JSON object');
+    }
+    const record = parsed;
+    const port = record.port ?? DEFAULT_PORT;
+    if (typeof port !== 'number' || !Number.isInteger(port) || port < 0) {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "port" must be a non-negative integer, got ${JSON.stringify(record.port)}`);
+    }
+    const tokens = parseTokens(record.tokens);
+    const rateLimit = parseRateLimit(record.rateLimit);
+    const trustProxy = parseTrustProxy(record.trustProxy);
+    const ipAllowlist = parseIpAllowlist(record.ipAllowlist);
+    const checkpointIntervalMs = parseCheckpointIntervalMs(record.checkpointIntervalMs);
+    const media = parseMedia(record.media);
+    const adminBaseUrl = parseAdminBaseUrl(record.adminBaseUrl);
+    return { port: resolvePort(port), tokens, rateLimit, trustProxy, ipAllowlist, checkpointIntervalMs, media, adminBaseUrl };
+}

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+import { type FastifyInstance } from 'fastify';
+import type { BootedSite } from './boot.ts';
+import type { ServerConfig } from './server-config.ts';
+import type { DevTunnel } from './services/dev-tunnel.ts';
+export interface BuildServerOptions {
+    logger?: boolean;
+}
+export interface StartServerOptions extends BuildServerOptions {
+    tunnel?: boolean;
+    startTunnel?: (port: number) => Promise<DevTunnel>;
+}
+export declare function buildServer(booted: BootedSite, serverConfig: ServerConfig, options?: BuildServerOptions): FastifyInstance;
+export declare function startServer(siteRoot: string, options?: StartServerOptions): Promise<FastifyInstance>;