@velastack/cms 0.1.0 → 0.2.0

package/dist/backend/routes/release.js

@@ -0,0 +1,147 @@
+import { badRequest, isObjectRecord, isStringRecord, readJson, requireUser } from './context.js';
+const parseItems = (raw) => {
+    if (!Array.isArray(raw))
+        return 'items must be an array';
+    const out = [];
+    for (const r of raw) {
+        if (!isObjectRecord(r))
+            return 'each item must be an object';
+        const { kind, routeId, locale, params, tree } = r;
+        if (kind !== 'page' && kind !== 'layout' && kind !== 'site') {
+            return 'item.kind must be "page", "layout", or "site"';
+        }
+        if (!isObjectRecord(tree))
+            return 'item.tree must be an object';
+        if (kind === 'site') {
+            out.push({ kind: 'site', tree });
+            continue;
+        }
+        if (typeof routeId !== 'string' || routeId === '')
+            return 'item.routeId required';
+        if (typeof locale !== 'string' || locale === '')
+            return 'item.locale required';
+        if (kind === 'page') {
+            if (!isStringRecord(params))
+                return 'page item.params must be a string-keyed object';
+            out.push({ kind: 'page', routeId, locale, params, tree });
+        }
+        else {
+            out.push({ kind: 'layout', routeId, locale, tree });
+        }
+    }
+    return out;
+};
+const parseTarget = (raw) => {
+    if (!isObjectRecord(raw))
+        return 'object body required';
+    const { kind, routeId, locale, params } = raw;
+    if (kind === 'site')
+        return { kind: 'site' };
+    if (kind !== 'page' && kind !== 'layout' && kind !== 'page-delete') {
+        return 'kind must be "page", "layout", "page-delete", or "site"';
+    }
+    if (typeof routeId !== 'string' || routeId === '')
+        return 'routeId required';
+    if (typeof locale !== 'string' || locale === '')
+        return 'locale required';
+    if (kind === 'layout')
+        return { kind: 'layout', routeId, locale };
+    if (!isStringRecord(params))
+        return `${kind} params must be a string-keyed object`;
+    return { kind, routeId, locale, params };
+};
+export const getRelease = (ctx) => {
+    const user = requireUser(ctx);
+    const release = ctx.store.getOpenRelease(ctx.projectId, user.id);
+    return Response.json({ release: release ?? null });
+};
+export const postReleaseItems = async (ctx) => {
+    const user = requireUser(ctx);
+    const body = await readJson(ctx.event);
+    if (body === undefined)
+        return badRequest('invalid json');
+    if (!isObjectRecord(body))
+        return badRequest('object body required');
+    const items = parseItems(body.items);
+    if (typeof items === 'string')
+        return badRequest(items);
+    const release = ctx.store.addReleaseItems(ctx.projectId, user.id, items);
+    return Response.json({ release });
+};
+export const deleteReleaseItems = async (ctx) => {
+    const user = requireUser(ctx);
+    const body = await readJson(ctx.event);
+    if (body === undefined)
+        return badRequest('invalid json');
+    const target = parseTarget(body);
+    if (typeof target === 'string')
+        return badRequest(target);
+    const ok = ctx.store.discardReleaseItem(ctx.projectId, user.id, target);
+    if (!ok)
+        return new Response(null, { status: 404 });
+    return Response.json({ ok: true });
+};
+export const postReleasePublish = async (ctx) => {
+    const user = requireUser(ctx);
+    let name;
+    const text = await ctx.event.request.text();
+    if (text) {
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            return badRequest('invalid json');
+        }
+        if (!isObjectRecord(body))
+            return badRequest('object body required');
+        if (body.name != null) {
+            if (typeof body.name !== 'string')
+                return badRequest('name must be a string');
+            name = body.name;
+        }
+    }
+    const published = ctx.store.publishRelease(ctx.projectId, user.id, name);
+    if (!published)
+        return new Response('no open release to publish', { status: 404 });
+    return Response.json({ release: published });
+};
+export const postReleaseDiscard = (ctx) => {
+    const user = requireUser(ctx);
+    return Response.json({ ok: ctx.store.discardOpenRelease(ctx.projectId, user.id) });
+};
+export const postReleasePreviewKey = (ctx) => {
+    const user = requireUser(ctx);
+    const key = ctx.store.regeneratePreviewKey(ctx.projectId, user.id);
+    if (!key)
+        return new Response('no open release', { status: 404 });
+    return Response.json({ preview_key: key });
+};
+export const getReleaseHistory = (ctx) => {
+    requireUser(ctx);
+    const history = ctx.store
+        .getReleaseHistory(ctx.projectId)
+        .slice()
+        .sort((a, b) => (a.publishedAt < b.publishedAt ? 1 : -1));
+    return Response.json({ history });
+};
+export const postReleaseRevert = (ctx) => {
+    const user = requireUser(ctx);
+    const id = ctx.params.id;
+    if (!id)
+        return badRequest('id required');
+    const reverted = ctx.store.revertRelease(ctx.projectId, id, user.id);
+    if (!reverted)
+        return new Response('release not found', { status: 404 });
+    return Response.json({ release: reverted });
+};
+export const postReleaseHistoryPreviewKey = (ctx) => {
+    requireUser(ctx);
+    const id = ctx.params.id;
+    if (!id)
+        return badRequest('release id required');
+    const key = ctx.store.regeneratePublishedPreviewKey(ctx.projectId, id);
+    if (!key)
+        return new Response('release not found', { status: 404 });
+    return Response.json({ preview_key: key });
+};

package/dist/backend/routes/site.d.ts

@@ -0,0 +1,2 @@
+import type { RouteCtx } from './context.js';
+export declare const getSite: (ctx: RouteCtx) => Response;

package/dist/backend/routes/site.js

@@ -0,0 +1,40 @@
+/**
+ * `GET /site` — project-wide settings (branding, contact, social).
+ *
+ * One tree per project: no locale, no params. Mirrors `/docs` for the cache,
+ * preview, and version contract, and always returns 200 (an unset site is an
+ * empty tree, not a 404).
+ */
+import { mergeTree } from '../../core/path.js';
+export const getSite = (ctx) => {
+    const { event, projectId, store, respond } = ctx;
+    const previewKey = event.url.searchParams.get('preview');
+    const versionKey = event.url.searchParams.get('version');
+    if (versionKey) {
+        const release = store.findPublishedReleaseByPreviewKey(projectId, versionKey);
+        if (!release)
+            return new Response('release not found', { status: 404 });
+        const snap = store.buildStateAtRelease(projectId, release.id);
+        if (!snap)
+            return new Response('release not found', { status: 404 });
+        return respond.serveImmutableJson(event, { contents: snap.siteSnap });
+    }
+    if (previewKey) {
+        const base = store.getPublishedSiteTree(projectId);
+        const release = store.findOpenReleaseByPreviewKey(projectId, previewKey);
+        let contents = { ...base };
+        if (release) {
+            for (const item of release.items) {
+                if (item.kind !== 'site')
+                    continue;
+                contents = mergeTree(contents, item.tree);
+            }
+        }
+        return Response.json({ contents });
+    }
+    const cacheCheck = respond.tryPublicCache(event, projectId, 'site');
+    if (cacheCheck.hit)
+        return cacheCheck.response;
+    const base = store.getPublishedSiteTree(projectId);
+    return respond.servePublicJson(event, projectId, 'site', cacheCheck, { contents: base });
+};

package/dist/backend/routes/table.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The route table.
+ *
+ * `auth` semantics:
+ * - `public`   anonymous callers are served published content
+ * - `required` no editor is a 403
+ * - `exempt`   skips the cross-project check, so an editor holding a session for
+ *              one project can still reach another's login form and log out
+ */
+import type { Route } from '../router.js';
+export declare const ROUTES: Route[];

package/dist/backend/routes/table.js

@@ -0,0 +1,72 @@
+import { getDocs } from './docs.js';
+import { getSite } from './site.js';
+import { deletePages, getPages, postPages, postPagesRename } from './pages.js';
+import { getUser, postLogout } from './user.js';
+import { getLogin, getLoginSuccess, postLogin } from './login.js';
+import { deleteReleaseItems, getRelease, getReleaseHistory, postReleaseDiscard, postReleaseHistoryPreviewKey, postReleaseItems, postReleasePreviewKey, postReleasePublish, postReleaseRevert } from './release.js';
+import { deleteMediaItem, getMedia, getUpload, postMedia } from './media.js';
+import { postTestReset } from './test-reset.js';
+export const ROUTES = [
+    { method: 'GET', segments: ['docs'], auth: 'public', handler: getDocs },
+    { method: 'GET', segments: ['site'], auth: 'public', handler: getSite },
+    { method: 'GET', segments: ['pages'], auth: 'public', handler: getPages },
+    { method: 'POST', segments: ['pages'], auth: 'required', handler: postPages },
+    { method: 'DELETE', segments: ['pages'], auth: 'required', handler: deletePages },
+    { method: 'POST', segments: ['pages', 'rename'], auth: 'required', handler: postPagesRename },
+    { method: 'GET', segments: ['user'], auth: 'required', handler: getUser },
+    { method: 'POST', segments: ['logout'], auth: 'exempt', handler: postLogout },
+    { method: 'GET', segments: ['iframe', 'login'], auth: 'exempt', handler: getLogin },
+    { method: 'POST', segments: ['iframe', 'login'], auth: 'exempt', handler: postLogin },
+    {
+        method: 'GET',
+        segments: ['iframe', 'login', 'success'],
+        auth: 'exempt',
+        handler: getLoginSuccess
+    },
+    { method: 'GET', segments: ['release'], auth: 'required', handler: getRelease },
+    { method: 'POST', segments: ['release', 'items'], auth: 'required', handler: postReleaseItems },
+    {
+        method: 'DELETE',
+        segments: ['release', 'items'],
+        auth: 'required',
+        handler: deleteReleaseItems
+    },
+    {
+        method: 'POST',
+        segments: ['release', 'publish'],
+        auth: 'required',
+        handler: postReleasePublish
+    },
+    {
+        method: 'POST',
+        segments: ['release', 'discard'],
+        auth: 'required',
+        handler: postReleaseDiscard
+    },
+    {
+        method: 'POST',
+        segments: ['release', 'preview-key'],
+        auth: 'required',
+        handler: postReleasePreviewKey
+    },
+    { method: 'GET', segments: ['release', 'history'], auth: 'required', handler: getReleaseHistory },
+    {
+        method: 'POST',
+        segments: ['release', 'history', ':id', 'revert'],
+        auth: 'required',
+        handler: postReleaseRevert
+    },
+    {
+        method: 'POST',
+        segments: ['release', 'history', ':id', 'preview-key'],
+        auth: 'required',
+        handler: postReleaseHistoryPreviewKey
+    },
+    { method: 'GET', segments: ['media'], auth: 'required', handler: getMedia },
+    { method: 'POST', segments: ['media'], auth: 'required', handler: postMedia },
+    { method: 'DELETE', segments: ['media', ':id'], auth: 'required', handler: deleteMediaItem },
+    // Served from the mount as well as (optionally) the origin root, so a
+    // single-tenant app needs only one mount to be self-contained.
+    { method: 'GET', segments: ['uploads', ':filename'], auth: 'public', handler: getUpload },
+    { method: 'POST', segments: ['__test_reset__'], auth: 'public', handler: postTestReset }
+];

package/dist/backend/routes/test-reset.d.ts

@@ -0,0 +1,15 @@
+import type { PageEntry } from '../../core/page-entry.js';
+import type { Tree } from '../../core/path.js';
+import { type RouteCtx } from './context.js';
+export type SeedInput = {
+    layoutDocs?: Record<string, unknown>;
+    pageDocs?: Record<string, unknown>;
+};
+/** Normalise either seed shape into `[locale][routeId]` buckets. */
+export declare const normalizeSeed: (seed: SeedInput) => {
+    layouts: Record<string, Record<string, Tree>>;
+    pages: Record<string, Record<string, PageEntry[]>>;
+};
+/** Remove only files this backend could have written. */
+export declare const clearUploads: (uploadDir: string) => Promise<void>;
+export declare const postTestReset: (ctx: RouteCtx) => Promise<Response>;

package/dist/backend/routes/test-reset.js

@@ -0,0 +1,112 @@
+/**
+ * `POST /__test_reset__` — wipe one project's CMS data and optionally seed it.
+ *
+ * Off unless the host sets `testReset`. It exists so an integration suite (or a
+ * developer poking at `vela dev`) can stand up a known fixture in one
+ * round-trip; the in-process test client calls the same code path through
+ * `backend.testing.reset`, which keeps the two honest.
+ *
+ * One deliberate change from the original: that version did
+ * `rm(uploadDir(), { recursive: true, force: true })` — a recursive delete of a
+ * host-configured directory, on an unauthenticated POST. Here only files whose
+ * names this backend could have generated are unlinked, and never the directory
+ * itself, so a misconfigured `uploadDir` cannot be destroyed.
+ */
+import { readdir, unlink } from 'node:fs/promises';
+import { DEFAULT_LOCALE } from '../store/queries.js';
+import { isSafeUploadFilename } from '../storage.js';
+import { badRequest, isObjectRecord, readJson } from './context.js';
+/**
+ * Two accepted seed shapes, told apart by inspecting the first level:
+ * flat (`{ '/': {...} }`, nested under the default locale) or per-locale
+ * (`{ en: { '/': {...} } }`).
+ */
+const isLayoutFlatShape = (m) => {
+    for (const v of Object.values(m)) {
+        if (!isObjectRecord(v))
+            return true;
+        const keys = Object.keys(v);
+        if (keys.length === 0)
+            return true;
+        if (!keys.every((k) => k.startsWith('/')))
+            return true;
+    }
+    return false;
+};
+const isPagesFlatShape = (m) => {
+    for (const v of Object.values(m)) {
+        if (Array.isArray(v))
+            return true;
+    }
+    return false;
+};
+/** Normalise either seed shape into `[locale][routeId]` buckets. */
+export const normalizeSeed = (seed) => {
+    const layouts = {};
+    const pages = {};
+    if (isObjectRecord(seed.layoutDocs)) {
+        if (isLayoutFlatShape(seed.layoutDocs)) {
+            const bucket = (layouts[DEFAULT_LOCALE] ??= {});
+            for (const [k, v] of Object.entries(seed.layoutDocs)) {
+                if (isObjectRecord(v))
+                    bucket[k] = v;
+            }
+        }
+        else {
+            for (const [locale, byRoute] of Object.entries(seed.layoutDocs)) {
+                if (!isObjectRecord(byRoute))
+                    continue;
+                const bucket = (layouts[locale] ??= {});
+                for (const [k, v] of Object.entries(byRoute)) {
+                    if (isObjectRecord(v))
+                        bucket[k] = v;
+                }
+            }
+        }
+    }
+    if (isObjectRecord(seed.pageDocs)) {
+        if (isPagesFlatShape(seed.pageDocs)) {
+            const bucket = (pages[DEFAULT_LOCALE] ??= {});
+            for (const [k, v] of Object.entries(seed.pageDocs)) {
+                if (Array.isArray(v))
+                    bucket[k] = v;
+            }
+        }
+        else {
+            for (const [locale, byRoute] of Object.entries(seed.pageDocs)) {
+                if (!isObjectRecord(byRoute))
+                    continue;
+                const bucket = (pages[locale] ??= {});
+                for (const [k, v] of Object.entries(byRoute)) {
+                    if (Array.isArray(v))
+                        bucket[k] = v;
+                }
+            }
+        }
+    }
+    return { layouts, pages };
+};
+/** Remove only files this backend could have written. */
+export const clearUploads = async (uploadDir) => {
+    let names;
+    try {
+        names = await readdir(uploadDir);
+    }
+    catch {
+        return;
+    }
+    await Promise.all(names.filter(isSafeUploadFilename).map((n) => unlink(`${uploadDir}/${n}`).catch(() => { })));
+};
+export const postTestReset = async (ctx) => {
+    const body = await readJson(ctx.event);
+    if (body !== undefined && !isObjectRecord(body))
+        return badRequest('invalid json');
+    ctx.store.__resetProjectForTests(ctx.projectId);
+    ctx.cache.clear();
+    await clearUploads(ctx.storage.dir());
+    const { layouts, pages } = normalizeSeed((body ?? {}));
+    if (Object.keys(layouts).length > 0 || Object.keys(pages).length > 0) {
+        ctx.store.seedPublishedDocs(ctx.projectId, layouts, pages);
+    }
+    return new Response(null, { status: 204 });
+};

package/dist/backend/routes/user.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `GET /user` and `POST /logout`.
+ *
+ * Resolution and project authorization both happen in the router before a
+ * handler runs, so `/user` is a pure read of what it decided.
+ */
+import { type RouteCtx } from './context.js';
+export declare const getUser: (ctx: RouteCtx) => Response;
+/**
+ * Idempotent — safe to call without being signed in. Clears the cookie with
+ * the same attributes it was set with, so the browser accepts the expiry, and
+ * lets the adapter drop server-side session state.
+ */
+export declare const postLogout: (ctx: RouteCtx) => Promise<Response>;

package/dist/backend/routes/user.js

@@ -0,0 +1,21 @@
+/**
+ * `GET /user` and `POST /logout`.
+ *
+ * Resolution and project authorization both happen in the router before a
+ * handler runs, so `/user` is a pure read of what it decided.
+ */
+import { requireUser } from './context.js';
+export const getUser = (ctx) => {
+    const user = requireUser(ctx);
+    return Response.json({ user: { id: user.id, name: user.name, email: user.email } });
+};
+/**
+ * Idempotent — safe to call without being signed in. Clears the cookie with
+ * the same attributes it was set with, so the browser accepts the expiry, and
+ * lets the adapter drop server-side session state.
+ */
+export const postLogout = async (ctx) => {
+    await ctx.auth.logout?.(ctx.event, ctx.authCtx);
+    ctx.clearSessionCookie();
+    return new Response(null, { status: 204 });
+};

package/dist/backend/storage.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Filesystem helpers for the media library, bound to one upload directory.
+ *
+ * The directory is supplied by the host rather than derived here. Uploads must
+ * live outside `static/`, which is a build-time input — a file written there at
+ * runtime is served by Vite in development and by nothing at all in production.
+ * A directory that outlives a release (the app's data directory) is the right
+ * answer, and only the host knows where that is.
+ */
+export declare const createStorage: (uploadDir: string) => {
+    /** The directory uploaded bytes are written to. */
+    dir: () => string;
+    /** The path an uploaded file is stored at. Callers pass a validated filename. */
+    path: (filename: string) => string;
+};
+export type CmsStorage = ReturnType<typeof createStorage>;
+export declare const isSafeUploadFilename: (name: string) => boolean;
+export declare const uploadContentType: (filename: string) => string;

package/dist/backend/storage.js

@@ -0,0 +1,45 @@
+import { join } from 'node:path';
+/**
+ * Filesystem helpers for the media library, bound to one upload directory.
+ *
+ * The directory is supplied by the host rather than derived here. Uploads must
+ * live outside `static/`, which is a build-time input — a file written there at
+ * runtime is served by Vite in development and by nothing at all in production.
+ * A directory that outlives a release (the app's data directory) is the right
+ * answer, and only the host knows where that is.
+ */
+export const createStorage = (uploadDir) => ({
+    /** The directory uploaded bytes are written to. */
+    dir: () => uploadDir,
+    /** The path an uploaded file is stored at. Callers pass a validated filename. */
+    path: (filename) => join(uploadDir, filename)
+});
+/**
+ * Filenames this app generates: sixteen hex characters and an extension. The
+ * pattern is deliberately a little wider than that, so a name from an older
+ * upload still resolves, and deliberately excludes `/` and `.` so that a
+ * request can only ever name a file directly inside {@link uploadDir}.
+ */
+const SAFE_FILENAME = /^[a-zA-Z0-9_-]{1,64}\.[a-zA-Z0-9]{1,8}$/;
+export const isSafeUploadFilename = (name) => SAFE_FILENAME.test(name);
+/**
+ * Content type for a stored upload, by extension.
+ *
+ * Only the types `POST /media` accepts are named. Anything else is served as
+ * bytes rather than guessed at — the browser is told not to sniff, so an
+ * unrecognized extension downloads instead of executing.
+ */
+const EXT_TO_MIME = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.avif': 'image/avif'
+};
+export const uploadContentType = (filename) => {
+    const dot = filename.lastIndexOf('.');
+    const ext = dot === -1 ? '' : filename.slice(dot).toLowerCase();
+    return EXT_TO_MIME[ext] ?? 'application/octet-stream';
+};

package/dist/backend/store/cache.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Per-instance LRU for hot read responses.
+ *
+ * Keys always include the project's `cms_version`, so a publish makes every
+ * stale entry unreachable and no active eviction is needed. Positive-only: 404s
+ * are never cached, so a flood of requests for empty tenants can't evict real
+ * content.
+ *
+ * Hand-rolled rather than pulling in `lru-cache`. This is ~30 lines and only
+ * `@velastack/cms/backend` ever touches it — a dependency here would be
+ * installed by every consumer of the components and the SSR read path too,
+ * none of whom run a backend.
+ *
+ * In a clustered deployment each worker keeps its own cache; cross-worker hit
+ * rate is recovered by the CDN in front, which the `Cache-Control` and `ETag`
+ * headers are sized for.
+ */
+export type ReadCacheKey = {
+    projectId: string;
+    cmsVersion: number;
+    scope: string;
+};
+export type ReadCache = {
+    get(key: ReadCacheKey): string | undefined;
+    set(key: ReadCacheKey, value: string): void;
+    clear(): void;
+};
+export type ReadCacheOptions = {
+    /** Entries retained before the least-recently-used is evicted. */
+    max?: number;
+    /** Per-entry lifetime in milliseconds. */
+    ttlMs?: number;
+};
+export declare const createReadCache: (options?: ReadCacheOptions) => ReadCache;

package/dist/backend/store/cache.js

@@ -0,0 +1,38 @@
+const buildKey = ({ projectId, cmsVersion, scope }) => `${projectId}:${cmsVersion}:${scope}`;
+export const createReadCache = (options = {}) => {
+    const max = options.max ?? 50_000;
+    const ttlMs = options.ttlMs ?? 5 * 60 * 1000;
+    // A Map iterates in insertion order, so the first key is the oldest. `get`
+    // re-inserts on a hit, which is what makes the eviction order LRU rather
+    // than FIFO.
+    const entries = new Map();
+    return {
+        get(key) {
+            const k = buildKey(key);
+            const hit = entries.get(k);
+            if (!hit)
+                return undefined;
+            if (hit.expiresAt <= Date.now()) {
+                entries.delete(k);
+                return undefined;
+            }
+            entries.delete(k);
+            entries.set(k, hit);
+            return hit.value;
+        },
+        set(key, value) {
+            const k = buildKey(key);
+            entries.delete(k);
+            entries.set(k, { value, expiresAt: Date.now() + ttlMs });
+            while (entries.size > max) {
+                const oldest = entries.keys().next();
+                if (oldest.done)
+                    break;
+                entries.delete(oldest.value);
+            }
+        },
+        clear() {
+            entries.clear();
+        }
+    };
+};

package/dist/backend/store/db.d.ts

@@ -0,0 +1,10 @@
+import { type SqliteDb } from './sqlite.js';
+/**
+ * Open the CMS database and bring its schema up to date.
+ *
+ * Unlike the version this was lifted from, there is no module-level singleton
+ * and no `CMS_DB_PATH` lookup: the path is supplied by the host, which is what
+ * lets one process host two backends and lets each test file hold its own
+ * `':memory:'` database.
+ */
+export declare const openDatabase: (dbPath: string) => SqliteDb;

package/dist/backend/store/db.js

@@ -0,0 +1,29 @@
+import { dirname } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { loadDriver } from './sqlite.js';
+import { runMigrations } from './migrate.js';
+import { MIGRATIONS } from './migrations/index.js';
+/**
+ * Open the CMS database and bring its schema up to date.
+ *
+ * Unlike the version this was lifted from, there is no module-level singleton
+ * and no `CMS_DB_PATH` lookup: the path is supplied by the host, which is what
+ * lets one process host two backends and lets each test file hold its own
+ * `':memory:'` database.
+ */
+export const openDatabase = (dbPath) => {
+    const Driver = loadDriver();
+    if (dbPath !== ':memory:') {
+        mkdirSync(dirname(dbPath), { recursive: true });
+    }
+    const db = new Driver(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('synchronous = NORMAL');
+    db.pragma('cache_size = -65536');
+    db.pragma('mmap_size = 268435456');
+    db.pragma('foreign_keys = ON');
+    db.pragma('temp_store = MEMORY');
+    db.pragma('busy_timeout = 5000');
+    runMigrations(db, MIGRATIONS);
+    return db;
+};

package/dist/backend/store/migrate.d.ts

@@ -0,0 +1,10 @@
+import type { SqliteDb } from './sqlite.js';
+import type { Migration } from './migrations/index.js';
+/**
+ * Apply any unapplied migrations, in order, each in its own transaction, and
+ * record it in `_migrations` so re-runs are no-ops.
+ *
+ * Safe to call from every worker at boot — SQLite's writer lock serialises the
+ * work and later workers find the rows already present.
+ */
+export declare const runMigrations: (db: SqliteDb, migrations: Migration[]) => void;

package/dist/backend/store/migrate.js

@@ -0,0 +1,30 @@
+/**
+ * Apply any unapplied migrations, in order, each in its own transaction, and
+ * record it in `_migrations` so re-runs are no-ops.
+ *
+ * Safe to call from every worker at boot — SQLite's writer lock serialises the
+ * work and later workers find the rows already present.
+ */
+export const runMigrations = (db, migrations) => {
+    db.exec(`
+		CREATE TABLE IF NOT EXISTS _migrations (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			name TEXT NOT NULL UNIQUE,
+			applied_at TEXT NOT NULL
+		);
+	`);
+    const applied = new Set(db
+        .prepare('SELECT name FROM _migrations')
+        .all()
+        .map((r) => r.name));
+    const insert = db.prepare('INSERT INTO _migrations (name, applied_at) VALUES (?, ?)');
+    for (const { name, sql } of migrations) {
+        if (applied.has(name))
+            continue;
+        const tx = db.transaction(() => {
+            db.exec(sql);
+            insert.run(name, new Date().toISOString());
+        });
+        tx();
+    }
+};