@nuasite/cms-sidecar 0.43.0-beta.1

package/dist/types/server.js

@@ -0,0 +1,598 @@
+import { hashSource, KeyedMutex } from './concurrency';
+import { STATUS_BY_CODE, } from './types';
+/** Features the sidecar advertises so older/newer clients can degrade gracefully. */
+export const SIDECAR_FEATURES = [
+    'collections',
+    'entries.fields-projection',
+    'entries.draft-filter',
+    'entries.pagination',
+    'entry.crud',
+    'entry.rename',
+    'entry.array',
+    'entry.optimistic-concurrency',
+    'pages.crud',
+    'pages.list',
+    'pages.layouts',
+    'redirects.crud',
+    'media',
+];
+const API_PREFIX = '/cms/v1';
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 1000;
+// ============================================================================
+// Response helpers
+// ============================================================================
+function json(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json; charset=utf-8' },
+    });
+}
+function error(code, message, sourcePath) {
+    const body = { error: message, code };
+    if (sourcePath !== undefined)
+        body.sourcePath = sourcePath;
+    return json(body, STATUS_BY_CODE[code]);
+}
+/**
+ * Map a cms-core `MutationResult` to an HTTP response. A failed result becomes a
+ * typed `ApiError`: "not found" → 404, everything else (validation, already
+ * exists, write failures) → the supplied default code.
+ */
+function mutationResponse(result, fallback = 'validation') {
+    if (result.success)
+        return json(result);
+    const message = result.error ?? 'Mutation failed';
+    const code = /not found/i.test(message) ? 'not_found' : fallback;
+    return error(code, message, result.sourcePath);
+}
+async function parseJson(req) {
+    try {
+        const value = (await req.json());
+        return { ok: true, value };
+    }
+    catch {
+        return { ok: false, response: error('validation', 'Invalid JSON body') };
+    }
+}
+function parseEntriesQuery(url) {
+    const fields = url.searchParams.get('fields') ?? undefined;
+    const rawDraft = url.searchParams.get('draft');
+    const draft = rawDraft === 'true' || rawDraft === 'all' ? rawDraft : 'false';
+    const rawLimit = url.searchParams.get('limit');
+    let limit;
+    if (rawLimit !== null) {
+        const parsed = Number.parseInt(rawLimit, 10);
+        if (Number.isFinite(parsed) && parsed > 0)
+            limit = Math.min(parsed, MAX_LIMIT);
+    }
+    const cursor = url.searchParams.get('cursor') ?? undefined;
+    return { fields, draft, limit, cursor };
+}
+// ============================================================================
+// Entry projection (fields)
+// ============================================================================
+/**
+ * Project a scanned `CollectionEntryInfo` down to the requested `fields`.
+ *
+ * - absent: light header (slug/title/draft/pathname/sourcePath), never the body.
+ * - `*`: all frontmatter (via `data`), still no body.
+ * - `a,b`: those frontmatter keys (plus the always-present slug/sourcePath).
+ *
+ * The body lives only behind the entry-detail route, so a list stays small even
+ * for large/data collections.
+ */
+function projectEntry(entry, fields) {
+    if (fields === '*') {
+        // All frontmatter, still no body. `data` already carries the full frontmatter.
+        const projected = { slug: entry.slug, sourcePath: entry.sourcePath };
+        if (entry.title !== undefined)
+            projected.title = entry.title;
+        if (entry.draft !== undefined)
+            projected.draft = entry.draft;
+        if (entry.pathname !== undefined)
+            projected.pathname = entry.pathname;
+        if (entry.data !== undefined)
+            projected.data = entry.data;
+        return projected;
+    }
+    if (fields === undefined || fields.trim() === '') {
+        const projected = { slug: entry.slug, sourcePath: entry.sourcePath };
+        if (entry.title !== undefined)
+            projected.title = entry.title;
+        if (entry.draft !== undefined)
+            projected.draft = entry.draft;
+        if (entry.pathname !== undefined)
+            projected.pathname = entry.pathname;
+        return projected;
+    }
+    const keys = fields.split(',').map(k => k.trim()).filter(Boolean);
+    // slug + sourcePath are always-present identity fields.
+    const projected = { slug: entry.slug, sourcePath: entry.sourcePath };
+    const data = {};
+    for (const key of keys) {
+        switch (key) {
+            case 'slug':
+            case 'sourcePath':
+                break;
+            case 'title':
+                if (entry.title !== undefined)
+                    projected.title = entry.title;
+                break;
+            case 'draft':
+                if (entry.draft !== undefined)
+                    projected.draft = entry.draft;
+                break;
+            case 'pathname':
+                if (entry.pathname !== undefined)
+                    projected.pathname = entry.pathname;
+                break;
+            default: {
+                const value = entry.data?.[key];
+                if (value !== undefined)
+                    data[key] = value;
+            }
+        }
+    }
+    if (Object.keys(data).length > 0)
+        projected.data = data;
+    return projected;
+}
+/** Apply the draft filter to a scanned entry list. */
+function filterByDraft(entries, draft) {
+    if (draft === 'all')
+        return entries;
+    const wantDraft = draft === 'true';
+    return entries.filter(e => (e.draft === true) === wantDraft);
+}
+/**
+ * Opaque-but-real cursor: a base64url offset into the (stably scan-ordered) entry
+ * list. We never silently cap — when more remain, the next cursor is returned and
+ * `hasMore` is set; absent a cursor we start at offset 0.
+ */
+function decodeCursor(cursor) {
+    if (!cursor)
+        return 0;
+    try {
+        const decoded = Buffer.from(cursor, 'base64url').toString('utf-8');
+        const offset = Number.parseInt(decoded, 10);
+        return Number.isFinite(offset) && offset >= 0 ? offset : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function encodeCursor(offset) {
+    return Buffer.from(String(offset), 'utf-8').toString('base64url');
+}
+// ============================================================================
+// Page list (sidecar-layer fs walk; cms-core has no page-listing capability)
+// ============================================================================
+const PAGE_EXTENSIONS = ['.astro', '.md', '.mdx'];
+/**
+ * Walk `src/pages` through the `CmsFileSystem` port and derive static page
+ * routes. Skips underscore/dot files, dynamic segments (`[...]`) and non-page
+ * extensions — mirroring the dev server's filesystem page discovery. Yields
+ * `pathname` only; an SEO `title` would require the render manifest (out of scope).
+ */
+async function listPages(fs) {
+    const pathnames = [];
+    async function walk(dir, urlPrefix) {
+        const entries = await fs.list(dir);
+        for (const entry of entries) {
+            if (entry.name.startsWith('_') || entry.name.startsWith('.'))
+                continue;
+            if (entry.name.includes('['))
+                continue;
+            const full = `${dir}/${entry.name}`;
+            if (entry.isDirectory) {
+                await walk(full, `${urlPrefix}${entry.name}/`);
+                continue;
+            }
+            const dot = entry.name.lastIndexOf('.');
+            const ext = dot >= 0 ? entry.name.slice(dot) : '';
+            if (!PAGE_EXTENSIONS.includes(ext))
+                continue;
+            const baseName = entry.name.slice(0, entry.name.length - ext.length);
+            const pathname = baseName === 'index'
+                ? (urlPrefix.replace(/\/$/, '') || '/')
+                : `${urlPrefix}${baseName}`;
+            pathnames.push(pathname);
+        }
+    }
+    await walk('src/pages', '/');
+    pathnames.sort((a, b) => a.localeCompare(b));
+    return pathnames.map(pathname => ({ pathname }));
+}
+export function createServer(opts) {
+    const { core, fs, root, coreVersion } = opts;
+    const contentDir = opts.contentDir ?? 'src/content';
+    const maxUploadSize = opts.maxUploadSize ?? 20 * 1024 * 1024;
+    const mutex = new KeyedMutex();
+    async function scanList() {
+        const map = await core.scanCollections();
+        return Object.values(map);
+    }
+    async function resolveCollection(name) {
+        const map = await core.scanCollections();
+        return map[name] ?? null;
+    }
+    // --- Entry detail (assembles the CollectionEntry wire shape) ---
+    async function entryDetail(collection, slug) {
+        const result = await core.getEntry(collection, slug);
+        if (!result)
+            return error('not_found', `Entry not found: ${collection}/${slug}`);
+        const def = await resolveCollection(collection);
+        // frontmatter values are stringified for the line-keyed wire shape; line
+        // numbers are not tracked headlessly (the inline widget owns line-precise edits).
+        const frontmatter = {};
+        for (const [key, value] of Object.entries(result.frontmatter)) {
+            frontmatter[key] = { value: typeof value === 'string' ? value : JSON.stringify(value), line: 0 };
+        }
+        const entry = {
+            collectionName: def?.name ?? collection,
+            collectionSlug: slug,
+            sourcePath: result.sourcePath,
+            frontmatter,
+            body: result.content,
+            bodyStartLine: 0,
+        };
+        return json(entry);
+    }
+    // --- PATCH entry (optimistic concurrency + per-file mutex) ---
+    async function patchEntry(collection, slug, body) {
+        const existing = await core.getEntry(collection, slug);
+        if (!existing)
+            return error('not_found', `Entry not found: ${collection}/${slug}`);
+        const sourcePath = existing.sourcePath;
+        return mutex.runExclusive(sourcePath, async () => {
+            // Re-hash under the lock so a concurrent writer cannot slip in between.
+            const serverHash = await hashSource(fs, sourcePath);
+            if (body.baseHash !== undefined && serverHash !== null && body.baseHash !== serverHash) {
+                const current = await core.getEntry(collection, slug);
+                const conflict = {
+                    code: 'conflict',
+                    serverHash,
+                    serverFrontmatter: current?.frontmatter ?? existing.frontmatter,
+                };
+                if (current && current.content !== '')
+                    conflict.serverBody = current.content;
+                return json(conflict, STATUS_BY_CODE.conflict);
+            }
+            const result = await core.updateEntry({
+                collection,
+                slug,
+                frontmatter: body.frontmatter,
+                body: body.body,
+            });
+            if (!result.success)
+                return mutationResponse(result);
+            const newHash = await hashSource(fs, result.sourcePath ?? sourcePath);
+            const enriched = { ...result };
+            if (newHash !== null)
+                enriched.sourceHash = newHash;
+            return json(enriched);
+        });
+    }
+    async function fetchHandler(req) {
+        const url = new URL(req.url);
+        let pathname = url.pathname;
+        if (pathname.length > 1 && pathname.endsWith('/'))
+            pathname = pathname.slice(0, -1);
+        // /health is unversioned (liveness probe).
+        if (pathname === '/health' && req.method === 'GET') {
+            return json({ ok: true, coreVersion, root });
+        }
+        if (!pathname.startsWith(API_PREFIX)) {
+            return error('not_found', `No route: ${req.method} ${pathname}`);
+        }
+        const rest = pathname.slice(API_PREFIX.length) || '/';
+        const segments = rest.split('/').filter(Boolean).map(decodeURIComponent);
+        const method = req.method;
+        return route(method, segments, req, url);
+    }
+    async function route(method, segments, req, url) {
+        const [head, ...tail] = segments;
+        switch (head) {
+            case 'health':
+                if (method === 'GET')
+                    return json({ ok: true, coreVersion, root });
+                break;
+            case 'project':
+                if (method === 'GET') {
+                    const [collections, pages] = await Promise.all([scanList(), listPages(fs)]);
+                    const capabilities = { coreVersion, features: [...SIDECAR_FEATURES] };
+                    const model = { collections, pages, capabilities };
+                    return json(model);
+                }
+                break;
+            case 'collections':
+                return routeCollections(method, tail, req, url);
+            case 'pages':
+                return routePages(method, tail, req);
+            case 'redirects':
+                return routeRedirects(method, tail, req);
+            case 'media':
+                return routeMedia(method, tail, req, url);
+        }
+        return error('not_found', `No route: ${method} /cms/v1/${segments.join('/')}`);
+    }
+    async function routeCollections(method, tail, req, url) {
+        // GET /collections
+        if (tail.length === 0) {
+            if (method === 'GET')
+                return json(await scanList());
+            return error('unsupported', `Unsupported: ${method} /collections`);
+        }
+        const [collection, sub, slug, action] = tail;
+        // /collections/:c/entries[...]
+        if (sub === 'entries' && collection) {
+            // GET /collections/:c/entries  (sparse list)
+            if (slug === undefined) {
+                if (method === 'GET')
+                    return listEntries(collection, url);
+                if (method === 'POST')
+                    return createEntry(collection, req);
+                return error('unsupported', `Unsupported: ${method} /collections/${collection}/entries`);
+            }
+            // /collections/:c/entries/:slug[...]
+            if (action === undefined) {
+                if (method === 'GET')
+                    return entryDetail(collection, slug);
+                if (method === 'PATCH')
+                    return updateEntryRoute(collection, slug, req);
+                if (method === 'DELETE')
+                    return deleteEntryRoute(collection, slug);
+                return error('unsupported', `Unsupported: ${method} /collections/${collection}/entries/${slug}`);
+            }
+            if (action === 'rename' && method === 'POST')
+                return renameEntryRoute(collection, slug, req);
+            if (action === 'array' && method === 'POST')
+                return addArrayRoute(collection, slug, req);
+            if (action === 'array' && method === 'DELETE')
+                return removeArrayRoute(collection, slug, req);
+        }
+        return error('not_found', `No route: ${method} /cms/v1/collections/${tail.join('/')}`);
+    }
+    async function listEntries(collection, url) {
+        const def = await resolveCollection(collection);
+        if (!def)
+            return error('not_found', `Collection not found: ${collection}`);
+        const query = parseEntriesQuery(url);
+        const all = def.entries ?? [];
+        const filtered = filterByDraft(all, query.draft);
+        const offset = decodeCursor(query.cursor);
+        const limit = query.limit ?? DEFAULT_LIMIT;
+        const page = filtered.slice(offset, offset + limit);
+        const hasMore = offset + limit < filtered.length;
+        const entries = page.map(e => projectEntry(e, query.fields));
+        const result = { entries, hasMore };
+        if (hasMore)
+            result.cursor = encodeCursor(offset + limit);
+        return json(result);
+    }
+    async function createEntry(collection, req) {
+        const parsed = await parseJson(req);
+        if (!parsed.ok)
+            return parsed.response;
+        const body = parsed.value;
+        if (typeof body.slug !== 'string' || body.slug.trim() === '') {
+            return error('validation', 'A non-empty "slug" is required');
+        }
+        if (body.frontmatter === undefined || typeof body.frontmatter !== 'object') {
+            return error('validation', 'A "frontmatter" object is required');
+        }
+        const result = await core.createEntry({
+            collection,
+            slug: body.slug,
+            frontmatter: body.frontmatter,
+            body: body.body,
+            fileExtension: body.fileExtension,
+        });
+        if (!result.success)
+            return mutationResponse(result);
+        const newHash = result.sourcePath ? await hashSource(fs, result.sourcePath) : null;
+        const enriched = { ...result };
+        if (newHash !== null)
+            enriched.sourceHash = newHash;
+        return json(enriched);
+    }
+    async function updateEntryRoute(collection, slug, req) {
+        const parsed = await parseJson(req);
+        if (!parsed.ok)
+            return parsed.response;
+        return patchEntry(collection, slug, parsed.value);
+    }
+    async function deleteEntryRoute(collection, slug) {
+        const existing = await core.getEntry(collection, slug);
+        if (!existing)
+            return error('not_found', `Entry not found: ${collection}/${slug}`);
+        return mutex.runExclusive(existing.sourcePath, async () => {
+            const result = await core.deleteEntry(collection, slug);
+            return mutationResponse(result);
+        });
+    }
+    async function renameEntryRoute(collection, slug, req) {
+        const parsed = await parseJson(req);
+        if (!parsed.ok)
+            return parsed.response;
+        if (typeof parsed.value.to !== 'string' || parsed.value.to.trim() === '') {
+            return error('validation', 'A non-empty "to" slug is required');
+        }
+        const existing = await core.getEntry(collection, slug);
+        if (!existing)
+            return error('not_found', `Entry not found: ${collection}/${slug}`);
+        return mutex.runExclusive(existing.sourcePath, async () => {
+            const result = await core.renameEntry(collection, slug, parsed.value.to);
+            if (!result.success)
+                return mutationResponse(result);
+            const newHash = result.sourcePath ? await hashSource(fs, result.sourcePath) : null;
+            const enriched = { ...result };
+            if (newHash !== null)
+                enriched.sourceHash = newHash;
+            return json(enriched);
+        });
+    }
+    async function addArrayRoute(collection, slug, req) {
+        const parsed = await parseJson(req);
+        if (!parsed.ok)
+            return parsed.response;
+        const body = parsed.value;
+        if (typeof body.field !== 'string' || body.field.trim() === '') {
+            return error('validation', 'A non-empty "field" is required');
+        }
+        const existing = await core.getEntry(collection, slug);
+        if (!existing)
+            return error('not_found', `Entry not found: ${collection}/${slug}`);
+        return mutex.runExclusive(existing.sourcePath, async () => {
+            const result = await core.addArrayItem({ collection, slug, field: body.field, value: body.value, index: body.index });
+            return mutationResponse(result);
+        });
+    }
+    async function removeArrayRoute(collection, slug, req) {
+        const parsed = await parseJson(req);
+        if (!parsed.ok)
+            return parsed.response;
+        const body = parsed.value;
+        if (typeof body.field !== 'string' || body.field.trim() === '') {
+            return error('validation', 'A non-empty "field" is required');
+        }
+        if (typeof body.index !== 'number' || !Number.isInteger(body.index)) {
+            return error('validation', 'An integer "index" is required');
+        }
+        const existing = await core.getEntry(collection, slug);
+        if (!existing)
+            return error('not_found', `Entry not found: ${collection}/${slug}`);
+        return mutex.runExclusive(existing.sourcePath, async () => {
+            const result = await core.removeArrayItem({ collection, slug, field: body.field, index: body.index });
+            return mutationResponse(result);
+        });
+    }
+    async function routePages(method, tail, req) {
+        const [sub] = tail;
+        // GET /pages  → fs-derived page list (cms-core has no page listing).
+        if (sub === undefined) {
+            if (method === 'GET')
+                return json({ pages: await listPages(fs) });
+            if (method === 'POST') {
+                const parsed = await parseJson(req);
+                if (!parsed.ok)
+                    return parsed.response;
+                const result = await core.createPage(parsed.value);
+                return result.success ? json(result) : error('validation', result.error ?? 'Failed to create page');
+            }
+            if (method === 'DELETE') {
+                const parsed = await parseJson(req);
+                if (!parsed.ok)
+                    return parsed.response;
+                const result = await core.deletePage(parsed.value);
+                if (result.success)
+                    return json(result);
+                const code = /not found/i.test(result.error ?? '') ? 'not_found' : 'validation';
+                return error(code, result.error ?? 'Failed to delete page');
+            }
+            return error('unsupported', `Unsupported: ${method} /pages`);
+        }
+        // GET /pages/layouts
+        if (sub === 'layouts' && method === 'GET') {
+            return json({ layouts: await core.getLayouts() });
+        }
+        // POST /pages/duplicate
+        if (sub === 'duplicate' && method === 'POST') {
+            const parsed = await parseJson(req);
+            if (!parsed.ok)
+                return parsed.response;
+            const result = await core.duplicatePage(parsed.value);
+            if (result.success)
+                return json(result);
+            const code = /not found/i.test(result.error ?? '') ? 'not_found' : 'validation';
+            return error(code, result.error ?? 'Failed to duplicate page');
+        }
+        return error('not_found', `No route: ${method} /cms/v1/pages/${tail.join('/')}`);
+    }
+    async function routeRedirects(method, tail, req) {
+        const [sub] = tail;
+        if (sub === undefined) {
+            if (method === 'GET')
+                return json(await core.listRedirects());
+            if (method === 'POST') {
+                const parsed = await parseJson(req);
+                if (!parsed.ok)
+                    return parsed.response;
+                const result = await core.addRedirect(parsed.value);
+                return result.success ? json(result) : error('validation', result.error ?? 'Failed to add redirect');
+            }
+            if (method === 'PATCH') {
+                const parsed = await parseJson(req);
+                if (!parsed.ok)
+                    return parsed.response;
+                const result = await core.updateRedirect(parsed.value);
+                return result.success ? json(result) : error('validation', result.error ?? 'Failed to update redirect');
+            }
+            if (method === 'DELETE') {
+                const parsed = await parseJson(req);
+                if (!parsed.ok)
+                    return parsed.response;
+                const result = await core.deleteRedirect(parsed.value);
+                return result.success ? json(result) : error('validation', result.error ?? 'Failed to delete redirect');
+            }
+            return error('unsupported', `Unsupported: ${method} /redirects`);
+        }
+        return error('not_found', `No route: ${method} /cms/v1/redirects/${tail.join('/')}`);
+    }
+    async function routeMedia(method, tail, req, url) {
+        const adapter = core.media;
+        if (!adapter)
+            return error('unsupported', 'Media storage not configured');
+        const [id] = tail;
+        // GET /media
+        if (id === undefined && method === 'GET') {
+            const rawLimit = url.searchParams.get('limit');
+            const parsedLimit = rawLimit !== null ? Number.parseInt(rawLimit, 10) : Number.NaN;
+            const limit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? Math.min(parsedLimit, MAX_LIMIT) : DEFAULT_LIMIT;
+            const result = await adapter.list({
+                limit,
+                cursor: url.searchParams.get('cursor') ?? undefined,
+                folder: url.searchParams.get('folder') ?? undefined,
+            });
+            return json(result);
+        }
+        // POST /media  (multipart upload, or JSON create-folder)
+        if (id === undefined && method === 'POST') {
+            const contentType = req.headers.get('content-type') ?? '';
+            if (contentType.includes('application/json')) {
+                const parsed = await parseJson(req);
+                if (!parsed.ok)
+                    return parsed.response;
+                if (!adapter.createFolder)
+                    return error('unsupported', 'Folder creation not supported by this adapter');
+                if (typeof parsed.value.folder !== 'string' || parsed.value.folder.includes('..')) {
+                    return error('validation', 'A valid "folder" is required');
+                }
+                const result = await adapter.createFolder(parsed.value.folder);
+                return result.success ? json(result) : error('io_error', result.error ?? 'Failed to create folder');
+            }
+            if (!contentType.includes('multipart/form-data')) {
+                return error('validation', 'Expected multipart/form-data or application/json');
+            }
+            const form = await req.formData();
+            const file = form.get('file');
+            if (!(file instanceof File))
+                return error('validation', 'No "file" found in the form data');
+            if (file.size > maxUploadSize) {
+                return error('validation', `File too large (max ${Math.round(maxUploadSize / (1024 * 1024))} MB)`);
+            }
+            const buffer = Buffer.from(await file.arrayBuffer());
+            const folder = url.searchParams.get('folder') ?? undefined;
+            const result = await adapter.upload(buffer, file.name, file.type || 'application/octet-stream', { folder });
+            return result.success ? json(result) : error('io_error', result.error ?? 'Upload failed');
+        }
+        // DELETE /media/:id
+        if (id !== undefined && method === 'DELETE') {
+            const result = await adapter.delete(id);
+            return result.success ? json({ success: true }) : error('io_error', result.error ?? 'Delete failed');
+        }
+        return error('not_found', `No route: ${method} /cms/v1/media${id ? `/${id}` : ''}`);
+    }
+    return { fetch: fetchHandler };
+}