@velastack/cms 0.1.0 → 0.2.0

package/dist/backend/http.js

@@ -0,0 +1,79 @@
+/**
+ * Cache-Control for public CMS reads. Short browser TTL keeps editors close
+ * to fresh after publish; `stale-while-revalidate` smooths cache misses; the
+ * larger `s-maxage` lets a CDN hold the cached copy longer than browsers do.
+ */
+const PUBLIC_CC = 'public, max-age=10, stale-while-revalidate=300, s-maxage=300';
+/** `?version=<key>` reads are bound to a published release id and never
+ * change — safe to cache forever. */
+const IMMUTABLE_CC = 'public, max-age=31536000, immutable';
+const JSON_TYPE = 'application/json; charset=utf-8';
+/**
+ * Bind the cache-aware responders to one store and one read cache.
+ *
+ * The bodies are a verbatim move: the header values, the ETag basis, the
+ * positive-only caching, and the branch order are the contract the shipped
+ * client already depends on, so none of it is re-derived here.
+ *
+ * Note these take a duck-typed `{ request, setHeaders }` rather than a full
+ * `RequestEvent`, which is what lets the tests drive them directly.
+ */
+export const createResponders = (store, cache) => {
+    /**
+     * Check the LRU and `If-None-Match` for a public read. On hit/304 returns a
+     * ready Response. On miss returns `{ hit: false, version, etag }` so the
+     * caller can pass them back into `servePublicJson` / `servePublicNotFound`
+     * without re-reading `cms_version` (avoiding a publish-races-read TOCTOU).
+     */
+    const tryPublicCache = (event, projectId, scope) => {
+        const version = store.getCmsVersion(projectId);
+        const etag = `"${version}"`;
+        const ifNoneMatch = event.request.headers.get('if-none-match');
+        if (ifNoneMatch === etag) {
+            event.setHeaders({ 'cache-control': PUBLIC_CC, etag });
+            return { hit: true, response: new Response(null, { status: 304 }) };
+        }
+        const cached = cache.get({ projectId, cmsVersion: version, scope });
+        if (cached !== undefined) {
+            event.setHeaders({ 'cache-control': PUBLIC_CC, etag, 'content-type': JSON_TYPE });
+            return { hit: true, response: new Response(cached, { status: 200 }) };
+        }
+        return { hit: false, version, etag };
+    };
+    /** Serve and LRU-cache a 200 JSON response for a public read. */
+    const servePublicJson = (event, projectId, scope, pass, payload) => {
+        const body = JSON.stringify(payload);
+        cache.set({ projectId, cmsVersion: pass.version, scope }, body);
+        event.setHeaders({
+            'cache-control': PUBLIC_CC,
+            etag: pass.etag,
+            'content-type': JSON_TYPE
+        });
+        return new Response(body, { status: 200 });
+    };
+    /**
+     * Serve a 404 for a public read. We set Cache-Control + ETag so the CDN /
+     * browser can negative-cache briefly, but do NOT populate the LRU — the cache
+     * is positive-only so empty-tenant flooding can't poison it.
+     */
+    const servePublicNotFound = (event, pass) => {
+        event.setHeaders({ 'cache-control': PUBLIC_CC, etag: pass.etag });
+        return new Response(null, { status: 404 });
+    };
+    /** Serve a JSON 200 for `?version=<key>` — immutable per release. */
+    const serveImmutableJson = (event, payload) => {
+        event.setHeaders({ 'cache-control': IMMUTABLE_CC, 'content-type': JSON_TYPE });
+        return new Response(JSON.stringify(payload), { status: 200 });
+    };
+    const serveImmutableNotFound = (event) => {
+        event.setHeaders({ 'cache-control': IMMUTABLE_CC });
+        return new Response(null, { status: 404 });
+    };
+    return {
+        tryPublicCache,
+        servePublicJson,
+        servePublicNotFound,
+        serveImmutableJson,
+        serveImmutableNotFound
+    };
+};

package/dist/backend/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `@velastack/cms/backend` — the CMS HTTP API, mountable at any path.
+ *
+ * ```ts
+ * // src/lib/server/cms.ts
+ * import { createCmsBackend } from '@velastack/cms/backend';
+ * export const cms = createCmsBackend();
+ *
+ * // src/routes/cms/[...path]/+server.ts
+ * import { cms } from '../server/cms';
+ * export const prerender = false;
+ * export const fallback = cms.handler;
+ * ```
+ *
+ * Multi-tenant is the same file with a `resolveProject`:
+ *
+ * ```ts
+ * createCmsBackend({ resolveProject: (event) => event.params.project_id ?? null });
+ * ```
+ *
+ * Requires `better-sqlite3`, declared as an optional peer dependency — projects
+ * that only use the components and the SSR read path never install it.
+ *
+ * Two things a cross-origin deployment must get right. `cors` is off by
+ * default; enabling it with an `origin` predicate that returns `true`
+ * unconditionally lets any site drive the mutating endpoints with a signed-in
+ * editor's cookie, because SvelteKit's CSRF check only guards form content
+ * types and these are JSON. And SvelteKit *does* guard `multipart/form-data`,
+ * so a cross-origin `POST /media` needs the site's origin in
+ * `kit.csrf.trustedOrigins` — that check is production-only, so it will not
+ * show up in `vela dev`.
+ */
+export { createCmsBackend, type CmsBackend } from './factory.js';
+export { localEditors, type LocalEditorsOptions } from './auth/local-editors.js';
+export { createEditorStore, type CmsEditorStore, type CreateEditorInput, type CmsSessionToken } from './auth/editors.js';
+export { hashPassword, verifyPassword, type ScryptParams } from './auth/scrypt.js';
+export { createCmsTestClient, type CmsTestClient, type TestResponse } from './testing/harness.js';
+export { createTestFixture, TEST_SCRYPT, type TestFixture, type TestFixtureOptions } from './testing/fixtures.js';
+export type { CmsAuthAdapter, CmsAuthContext, CmsBackendOptions, CmsCookieOptions, CmsCorsOptions, CmsEditor, CmsSessionGrant } from './types.js';
+export type { SqliteDb, SqliteStatement } from './store/sqlite.js';
+export type { Migration } from './store/migrations/index.js';
+export { MIGRATIONS } from './store/migrations/index.js';
+export type { DocsResponse, MediaItem, OpenRelease, PageMapEntry, PageMapRoute, PagesResponse, PagesRoute, PublishedRelease, ReleaseItem, SiteResponse } from '../core/wire.js';
+export type { PageDeleteOutcome, PageEntry } from '../core/page-entry.js';
+export type { Tree } from '../core/path.js';

package/dist/backend/index.js

@@ -0,0 +1,39 @@
+/**
+ * `@velastack/cms/backend` — the CMS HTTP API, mountable at any path.
+ *
+ * ```ts
+ * // src/lib/server/cms.ts
+ * import { createCmsBackend } from '@velastack/cms/backend';
+ * export const cms = createCmsBackend();
+ *
+ * // src/routes/cms/[...path]/+server.ts
+ * import { cms } from '../server/cms';
+ * export const prerender = false;
+ * export const fallback = cms.handler;
+ * ```
+ *
+ * Multi-tenant is the same file with a `resolveProject`:
+ *
+ * ```ts
+ * createCmsBackend({ resolveProject: (event) => event.params.project_id ?? null });
+ * ```
+ *
+ * Requires `better-sqlite3`, declared as an optional peer dependency — projects
+ * that only use the components and the SSR read path never install it.
+ *
+ * Two things a cross-origin deployment must get right. `cors` is off by
+ * default; enabling it with an `origin` predicate that returns `true`
+ * unconditionally lets any site drive the mutating endpoints with a signed-in
+ * editor's cookie, because SvelteKit's CSRF check only guards form content
+ * types and these are JSON. And SvelteKit *does* guard `multipart/form-data`,
+ * so a cross-origin `POST /media` needs the site's origin in
+ * `kit.csrf.trustedOrigins` — that check is production-only, so it will not
+ * show up in `vela dev`.
+ */
+export { createCmsBackend } from './factory.js';
+export { localEditors } from './auth/local-editors.js';
+export { createEditorStore } from './auth/editors.js';
+export { hashPassword, verifyPassword } from './auth/scrypt.js';
+export { createCmsTestClient } from './testing/harness.js';
+export { createTestFixture, TEST_SCRYPT } from './testing/fixtures.js';
+export { MIGRATIONS } from './store/migrations/index.js';

package/dist/backend/router.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Path dispatch for the catch-all mount.
+ *
+ * Every endpoint arrives at one `+server.ts` as a rest parameter, so the route
+ * table lives here rather than in the filesystem. That is the whole point of
+ * the design: adding or changing an endpoint is a package release, and the
+ * application's mount file never changes.
+ */
+import type { RequestEvent } from '@sveltejs/kit';
+import type { RouteCtx, RouteHandler } from './routes/context.js';
+/**
+ * `public`   — anonymous callers are served (published content only).
+ * `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. Reproduces `isAuthEndpoint` from the hook this replaces.
+ */
+export type RouteAuth = 'public' | 'required' | 'exempt';
+export type Route = {
+    method: 'GET' | 'POST' | 'DELETE';
+    /** Path segments; a leading `:` captures. */
+    segments: string[];
+    auth: RouteAuth;
+    handler: RouteHandler;
+};
+export type RouteMatch = {
+    route: Route;
+    params: Record<string, string>;
+};
+export type RouteLookup = {
+    kind: 'match';
+    match: RouteMatch;
+} | {
+    kind: 'method-not-allowed';
+    allowed: string[];
+} | {
+    kind: 'not-found';
+};
+/** Split a rest-parameter value into path segments. */
+export declare const splitPath: (path: string) => string[];
+/**
+ * Resolve a method + path against the table.
+ *
+ * A path that matches some route but not this method is a 405 with `Allow`,
+ * not a 404 — the distinction matters for anyone debugging a mount.
+ */
+export declare const lookupRoute: (routes: Route[], method: string, segments: string[]) => RouteLookup;
+export declare const methodNotAllowed: (allowed: string[]) => Response;
+export declare const notFound: () => Response;
+export type { RouteCtx, RouteHandler };
+/** Narrow a raw method string, mapping HEAD onto GET as SvelteKit does. */
+export declare const normalizeMethod: (event: RequestEvent) => string;

package/dist/backend/router.js

@@ -0,0 +1,57 @@
+const segmentsMatch = (pattern, actual) => {
+    if (pattern.length !== actual.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < pattern.length; i++) {
+        const p = pattern[i];
+        if (p.startsWith(':')) {
+            if (actual[i] === '')
+                return null;
+            params[p.slice(1)] = decodeURIComponent(actual[i]);
+        }
+        else if (p !== actual[i]) {
+            return null;
+        }
+    }
+    return params;
+};
+/** Split a rest-parameter value into path segments. */
+export const splitPath = (path) => path.split('/').filter(Boolean);
+/**
+ * Resolve a method + path against the table.
+ *
+ * A path that matches some route but not this method is a 405 with `Allow`,
+ * not a 404 — the distinction matters for anyone debugging a mount.
+ */
+export const lookupRoute = (routes, method, segments) => {
+    const byPath = [];
+    for (const route of routes) {
+        const params = segmentsMatch(route.segments, segments);
+        if (params)
+            byPath.push({ route, params });
+    }
+    if (byPath.length === 0)
+        return { kind: 'not-found' };
+    // A literal segment beats a capture, so `/media` never shadows `/media/:id`
+    // and vice versa.
+    const specificity = (r) => r.segments.filter((s) => !s.startsWith(':')).length;
+    byPath.sort((a, b) => specificity(b.route) - specificity(a.route));
+    const hit = byPath.find((c) => c.route.method === method);
+    if (hit)
+        return { kind: 'match', match: { route: hit.route, params: hit.params } };
+    const methods = [...new Set(byPath.map((c) => c.route.method))];
+    if (methods.includes('GET'))
+        methods.push('HEAD');
+    methods.push('OPTIONS');
+    return { kind: 'method-not-allowed', allowed: methods };
+};
+export const methodNotAllowed = (allowed) => new Response(`Method not allowed. Allowed: ${allowed.join(', ')}`, {
+    status: 405,
+    headers: { allow: allowed.join(', '), 'content-type': 'text/plain; charset=utf-8' }
+});
+export const notFound = () => new Response('Not found', {
+    status: 404,
+    headers: { 'content-type': 'text/plain; charset=utf-8' }
+});
+/** Narrow a raw method string, mapping HEAD onto GET as SvelteKit does. */
+export const normalizeMethod = (event) => event.request.method === 'HEAD' ? 'GET' : event.request.method;

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

@@ -0,0 +1,46 @@
+/**
+ * What every route handler receives.
+ *
+ * Handlers used to read `event.locals.cmsUser` and `event.params.project_id`,
+ * both of which are conventions of one particular application. Passing them
+ * explicitly is what makes the same handler work at `/cms` and at
+ * `/v1/projects/[project_id]/cms` without knowing which it is.
+ */
+import type { RequestEvent } from '@sveltejs/kit';
+import type { CmsStore } from '../store/queries.js';
+import type { ReadCache } from '../store/cache.js';
+import type { CmsResponders } from '../http.js';
+import type { CmsStorage } from '../storage.js';
+import type { CmsAuthAdapter, CmsAuthContext, CmsEditor } from '../types.js';
+export type RouteCtx = {
+    event: RequestEvent;
+    /** The tenant this request is for. `'default'` in a single-tenant mount. */
+    projectId: string;
+    /** The signed-in editor, or `null`. Routes declared `required` never see null. */
+    user: CmsEditor | null;
+    /** Captured `:name` segments from the route pattern. */
+    params: Record<string, string>;
+    store: CmsStore;
+    cache: ReadCache;
+    respond: CmsResponders;
+    storage: CmsStorage;
+    auth: CmsAuthAdapter;
+    authCtx: CmsAuthContext;
+    /** Absolute-or-root-relative URL for an uploaded file, per the host's
+     * configured media base. */
+    mediaUrl: (filename: string) => string;
+    /** The path the backend is mounted at, without a trailing slash. */
+    mountPath: string;
+    frameAncestors: string;
+    setSessionCookie: (token: string, expiresAt: Date) => void;
+    clearSessionCookie: () => void;
+};
+export type RouteHandler = (ctx: RouteCtx) => Response | Promise<Response>;
+/** The signed-in editor, for routes the table declares `required`. */
+export declare const requireUser: (ctx: RouteCtx) => CmsEditor;
+export declare const badRequest: (message: string) => Response;
+export declare const forbidden: () => Response;
+export declare const isObjectRecord: (v: unknown) => v is Record<string, unknown>;
+export declare const isStringRecord: (v: unknown) => v is Record<string, string>;
+/** Parse a JSON body, or `undefined` when it is absent or malformed. */
+export declare const readJson: (event: RequestEvent) => Promise<unknown | undefined>;

package/dist/backend/routes/context.js

@@ -0,0 +1,30 @@
+/** The signed-in editor, for routes the table declares `required`. */
+export const requireUser = (ctx) => {
+    if (!ctx.user)
+        throw new Error('route requires a user but the router allowed an anonymous call');
+    return ctx.user;
+};
+export const badRequest = (message) => new Response(message, { status: 400, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+export const forbidden = () => new Response(null, { status: 403 });
+export const isObjectRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+export const isStringRecord = (v) => {
+    if (!isObjectRecord(v))
+        return false;
+    for (const val of Object.values(v)) {
+        if (typeof val !== 'string')
+            return false;
+    }
+    return true;
+};
+/** Parse a JSON body, or `undefined` when it is absent or malformed. */
+export const readJson = async (event) => {
+    const text = await event.request.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};

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

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

package/dist/backend/routes/docs.js

@@ -0,0 +1,150 @@
+/**
+ * `GET /docs` — the hot read path.
+ *
+ * Ported from the original route handler with its three modes and their cache
+ * semantics unchanged: `?version=` reads an immutable release snapshot,
+ * `?preview=` overlays the caller's open release and bypasses every cache
+ * layer, and a plain read goes through the per-project LRU with an ETag keyed
+ * on `cms_version`. `?version` wins when both are present, by branch order.
+ */
+import { mergeTree } from '../../core/path.js';
+import { findPageEntry } from '../../core/page-entry.js';
+import { DEFAULT_LOCALE } from '../store/queries.js';
+import { badRequest } from './context.js';
+const parseParams = (raw) => {
+    if (raw == null || raw === '')
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        const out = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v !== 'string')
+                return null;
+            out[k] = v;
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+};
+const paramsEqual = (a, b) => {
+    const aKeys = Object.keys(a);
+    if (aKeys.length !== Object.keys(b).length)
+        return false;
+    for (const k of aKeys)
+        if (a[k] !== b[k])
+            return false;
+    return true;
+};
+/** Stable cache scope key for one /docs request. Mirrors the params hash shape
+ * from the store so the LRU partitions cleanly per scope. */
+const cacheScope = (kind, locale, routeId, params) => {
+    if (kind === 'layout')
+        return `docs:layout:${locale}:${routeId}`;
+    const keys = Object.keys(params).sort();
+    const sorted = {};
+    for (const k of keys)
+        sorted[k] = params[k];
+    return `docs:page:${locale}:${routeId}:${JSON.stringify(sorted)}`;
+};
+export const getDocs = (ctx) => {
+    const { event, projectId, store, respond } = ctx;
+    const url = event.url;
+    const kind = url.searchParams.get('kind');
+    if (kind !== 'page' && kind !== 'layout') {
+        return badRequest('kind must be "page" or "layout"');
+    }
+    const routeId = url.searchParams.get('routeId');
+    if (!routeId)
+        return badRequest('routeId required');
+    const params = parseParams(url.searchParams.get('params'));
+    if (!params)
+        return badRequest('params must be a JSON object of strings');
+    const locale = url.searchParams.get('locale') ?? DEFAULT_LOCALE;
+    const previewKey = url.searchParams.get('preview');
+    const versionKey = 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 });
+        if (kind === 'page') {
+            const entry = findPageEntry(snap.pageSnap[locale]?.[routeId], params);
+            if (entry?.tombstone)
+                return respond.serveImmutableJson(event, entry.tombstone);
+            const contents = entry?.published ?? null;
+            if (!contents)
+                return respond.serveImmutableNotFound(event);
+            return respond.serveImmutableJson(event, { contents });
+        }
+        const contents = snap.layoutSnap[locale]?.[routeId] ?? null;
+        if (!contents)
+            return respond.serveImmutableNotFound(event);
+        return respond.serveImmutableJson(event, { contents });
+    }
+    // Preview path: editor-only, low volume, bypass all cache layers.
+    if (previewKey) {
+        const base = kind === 'page' ? store.getPublishedPageEntry(projectId, locale, routeId, params) : null;
+        const layoutBase = kind === 'layout' ? store.getPublishedLayoutTree(projectId, locale, routeId) : null;
+        const release = store.findOpenReleaseByPreviewKey(projectId, previewKey);
+        if (release) {
+            if (kind === 'page') {
+                const pageDelete = release.items.find((i) => i.kind === 'page-delete' &&
+                    i.routeId === routeId &&
+                    i.locale === locale &&
+                    paramsEqual(i.params, params));
+                if (pageDelete && pageDelete.kind === 'page-delete') {
+                    if (pageDelete.outcome)
+                        return Response.json(pageDelete.outcome);
+                    return new Response(null, { status: 404 });
+                }
+            }
+            let contents = base?.published
+                ? { ...base.published }
+                : layoutBase
+                    ? { ...layoutBase }
+                    : null;
+            for (const item of release.items) {
+                if (item.kind !== kind || item.routeId !== routeId)
+                    continue;
+                if (item.locale !== locale)
+                    continue;
+                if (kind === 'page' && item.kind === 'page' && !paramsEqual(item.params, params))
+                    continue;
+                contents = mergeTree(contents ?? {}, item.tree);
+            }
+            if (!contents) {
+                if (base?.tombstone)
+                    return Response.json(base.tombstone);
+                return new Response(null, { status: 404 });
+            }
+            return Response.json({ contents });
+        }
+        // Preview key didn't match — fall through to the public path so we
+        // still serve published content (and apply caching).
+    }
+    const scope = cacheScope(kind, locale, routeId, params);
+    const cacheCheck = respond.tryPublicCache(event, projectId, scope);
+    if (cacheCheck.hit)
+        return cacheCheck.response;
+    let base;
+    let baseTombstone;
+    if (kind === 'page') {
+        const entry = store.getPublishedPageEntry(projectId, locale, routeId, params);
+        base = entry?.published;
+        baseTombstone = entry?.tombstone;
+    }
+    else {
+        base = store.getPublishedLayoutTree(projectId, locale, routeId) ?? undefined;
+    }
+    if (baseTombstone)
+        return respond.servePublicJson(event, projectId, scope, cacheCheck, baseTombstone);
+    if (!base)
+        return respond.servePublicNotFound(event, cacheCheck);
+    return respond.servePublicJson(event, projectId, scope, cacheCheck, { contents: base });
+};

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

@@ -0,0 +1,19 @@
+/**
+ * The sign-in flow the admin bar embeds in an iframe.
+ *
+ * This replaces five files in the original — two `+page.server.ts`, two
+ * `+page.svelte`, and a `+layout.server.ts` — plus a zod schema, and drops
+ * `sveltekit-superforms`, `zod`, and four shadcn components from the surface an
+ * application has to vendor. Serving plain HTML from the handler means the
+ * login works identically in an app with any UI kit, or none.
+ *
+ * The flow: the admin bar opens `<endpoint>/iframe/login` in an iframe, the
+ * form posts back to the same URL, and on success the page tells the parent
+ * window so the bar can re-fetch `/user` without a reload.
+ */
+import type { RouteCtx } from './context.js';
+export declare const getLogin: (ctx: RouteCtx) => Response;
+export declare const postLogin: (ctx: RouteCtx) => Promise<Response>;
+/** Kept so the admin bar's historical `/iframe/login/success` URL still
+ * resolves; the POST above renders the same screen inline. */
+export declare const getLoginSuccess: (ctx: RouteCtx) => Response;