@velora-cms/server 0.11.0

package/dist/plugins/seed-template-content.js

@@ -0,0 +1,198 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { ContentService } from "@velora-cms/content-service";
+// Session 149, Task 2 — D1: sample content is a PACKAGE DATA FILE
+// (sample-content.json, next to manifest.json at the artifact root —
+// packages/velora-plugin/src/copy-sample-content.ts puts it there at
+// build time), read from the STORED package dir (plain readFileSync —
+// the file is never tar-extracted separately) and seeded HOST-SIDE,
+// AFTER PluginRegistryService.install() has already returned. The S88
+// documentTypes install path (plugin-registry-service.ts) stays
+// untouched by this module — it is invoked by the two install
+// orchestrators (install-built-package.ts, install-from-marketplace.ts)
+// instead, never from inside install() itself.
+// Deliberately local to this module, not packages/api-schemas — this is
+// PACKAGE DATA (an artifact-internal file format), not an API surface.
+const SampleContentNodeSchema = z
+    .object({
+    documentType: z.string().min(1),
+    slug: z.string().min(1),
+    parent: z.string().nullable(),
+    data: z.record(z.string(), z.unknown()),
+})
+    .strict();
+const SampleContentFileSchema = z
+    .object({
+    nodes: z.array(SampleContentNodeSchema),
+})
+    .strict();
+/**
+ * Seeds a template plugin's sample-content.json as real, published
+ * content — creation order in the file IS the seed order (parents
+ * precede children per D1's documented contract), and every node is
+ * created THEN published, so it lands as version 1, currently published,
+ * matching the immutable-versioning path exactly the way a human editor
+ * publishing through the admin UI would produce.
+ *
+ * D2 governs every early return here: idempotent-by-skip (no duplicates
+ * on a second install/second call) and non-fatal (a seeding problem never
+ * unwinds an otherwise-successful plugin install — the caller's install
+ * stands regardless of what this function returns).
+ */
+export async function seedTemplateSampleContent(deps, pluginId, storedPackageDir, createdBy) {
+    const filePath = join(storedPackageDir, "sample-content.json");
+    if (!existsSync(filePath)) {
+        return "none"; // Most plugins never ship this file — not worth a log line.
+    }
+    // Guard: only template-type manifests get seeded, even if a
+    // sample-content.json somehow sits next to a differently-typed
+    // package's manifest.json. Missing row is defensive only — the caller
+    // always invokes this after a successful install, so the row exists in
+    // practice.
+    const registryRow = await deps.prisma.pluginRegistry.findUnique({ where: { pluginId } });
+    if (!registryRow || registryRow.type !== "template") {
+        return "none";
+    }
+    let sampleContent;
+    try {
+        const raw = JSON.parse(readFileSync(filePath, "utf8"));
+        const result = SampleContentFileSchema.safeParse(raw);
+        if (!result.success) {
+            console.error(`[seed-template-content] "${pluginId}"'s sample-content.json failed validation: ${result.error.message}`);
+            return "invalid";
+        }
+        sampleContent = result.data;
+    }
+    catch (error) {
+        console.error(`[seed-template-content] "${pluginId}"'s sample-content.json is not valid JSON:`, error);
+        return "invalid";
+    }
+    // Name -> minted id, via THIS plugin's own tracked document types —
+    // never a bare name lookup across every document type in the system,
+    // which could silently match an unrelated plugin's same-named type.
+    const tracked = await deps.prisma.pluginDocumentType.findMany({ where: { pluginId } });
+    const idByTypeName = new Map();
+    for (const row of tracked) {
+        const documentType = await deps.adapter.getDocumentType(row.documentTypeId);
+        if (documentType) {
+            idByTypeName.set(documentType.name, documentType.id);
+        }
+    }
+    const unknownTypeNames = [...new Set(sampleContent.nodes.map((node) => node.documentType))].filter((name) => !idByTypeName.has(name));
+    if (unknownTypeNames.length > 0) {
+        console.error(`[seed-template-content] "${pluginId}"'s sample-content.json references document type name(s) not declared ` +
+            `by this plugin: ${unknownTypeNames.join(", ")}`);
+        return "invalid";
+    }
+    // Structural validation, BEFORE any create: creation order in the file
+    // IS the seed order (D1), so a node's parent slug must already have been
+    // seen — i.e. declared strictly earlier in the array. Without this check,
+    // the create loop below resolves an unresolved parent slug via
+    // `nodeIdBySlug.get(parent) ?? null`, which silently roots the node
+    // instead of failing (catching an unknown parent only by luck, if that
+    // document type happens to reject root placement) — and a duplicate slug
+    // silently mis-parents later nodes, since every lookup map below is
+    // slug-keyed globally. Both are caught here, in one pass, before the
+    // loop that actually creates anything runs.
+    const seenSlugs = new Set();
+    for (const node of sampleContent.nodes) {
+        if (seenSlugs.has(node.slug)) {
+            console.error(`[seed-template-content] "${pluginId}"'s sample-content.json declares slug "${node.slug}" more than once`);
+            return "invalid";
+        }
+        if (node.parent !== null && !seenSlugs.has(node.parent)) {
+            console.error(`[seed-template-content] "${pluginId}"'s sample-content.json node "${node.slug}" declares parent "${node.parent}", ` +
+                `which does not name a slug declared earlier in the file`);
+            return "invalid";
+        }
+        seenSlugs.add(node.slug);
+    }
+    // Skip-if-exists: any ROOT node already at its declared path means a
+    // previous install/seed run already created this tree — re-seeding
+    // would create duplicates, so the whole step is skipped, not merged or
+    // partially retried.
+    for (const node of sampleContent.nodes) {
+        if (node.parent === null) {
+            const path = `/${node.slug}`;
+            if (await deps.adapter.getContentNodeByPath(path)) {
+                console.log(`[seed-template-content] "${pluginId}" sample content already exists at "${path}" — skipping`);
+                return "skipped";
+            }
+        }
+    }
+    // D2: the requesting admin's id where the caller has one; otherwise the
+    // first admin user (the seed-sandbox precedent — a REAL uuid; a
+    // placeholder string writes fine here but 500s every later GET of this
+    // content, per the S102-era gotcha). No admin at all -> skip, warn, and
+    // change nothing, exactly like the already-exists case above — there is
+    // no "system" user to attribute sample content to.
+    let resolvedCreatedBy = createdBy;
+    if (!resolvedCreatedBy) {
+        const firstAdmin = await deps.prisma.user.findFirst({
+            where: { role: "admin" },
+            orderBy: { createdAt: "asc" },
+        });
+        if (!firstAdmin) {
+            console.warn(`[seed-template-content] "${pluginId}" — no admin user exists to attribute sample content to; skipping seeding`);
+            return "skipped";
+        }
+        resolvedCreatedBy = firstAdmin.id;
+    }
+    // Deliberately un-wired: this ContentService is `new`-ed straight from
+    // the adapter, not read off app.ts's contentDb — so it never gets
+    // setOnContentEvent(createHookDispatcher(...)) called on it (S159). No
+    // content:afterPublish hook fires for the publishContent() calls below;
+    // template seeding is a one-shot data burst, not an editorial action a
+    // plugin should react to. Every path that reaches this function
+    // (install-from-marketplace.ts directly, install-built-package.ts —
+    // which the wizard's starter step also goes through) constructs its
+    // own instance the same un-wired way, so none of them fire hooks during
+    // seeding either. Contrast: a later EDITORIAL publish — a human
+    // republishing one of these seeded nodes through /api/content — goes
+    // through the app's own wired contentDb.contentService and DOES fire
+    // hooks.
+    const contentService = new ContentService(deps.adapter);
+    const nodeIdBySlug = new Map();
+    const pathBySlug = new Map();
+    const depthBySlug = new Map();
+    const nextSortOrderByParentSlug = new Map();
+    let created = 0;
+    try {
+        for (const node of sampleContent.nodes) {
+            const documentTypeId = idByTypeName.get(node.documentType);
+            const parentId = node.parent === null ? null : (nodeIdBySlug.get(node.parent) ?? null);
+            const parentPath = node.parent === null ? undefined : pathBySlug.get(node.parent);
+            const path = parentPath ? `${parentPath}/${node.slug}` : `/${node.slug}`;
+            const depth = node.parent === null ? 0 : (depthBySlug.get(node.parent) ?? 0) + 1;
+            const sortOrder = nextSortOrderByParentSlug.get(node.parent) ?? 0;
+            nextSortOrderByParentSlug.set(node.parent, sortOrder + 1);
+            const { node: createdNode } = await contentService.createContent({
+                documentTypeId,
+                parentId,
+                path,
+                depth,
+                sortOrder,
+                locale: "en",
+                isDefaultLocale: true,
+                data: node.data,
+                createdBy: resolvedCreatedBy,
+            });
+            await contentService.publishContent(createdNode.id);
+            nodeIdBySlug.set(node.slug, createdNode.id);
+            pathBySlug.set(node.slug, path);
+            depthBySlug.set(node.slug, depth);
+            created++;
+        }
+    }
+    catch (error) {
+        // D2: non-fatal — the install already stands by the time this runs,
+        // and the never-lose-data ethos cuts the other way here: don't tear
+        // down a healthy install over sample data. Whatever nodes were
+        // created before the failure are left in place (createContent +
+        // publishContent are each already immutable/atomic per node).
+        console.error(`[seed-template-content] seeding sample content for "${pluginId}" failed after creating ${created} node(s):`, error);
+        return "invalid";
+    }
+    return { created };
+}

package/dist/plugins/server-serializers.d.ts

@@ -0,0 +1,3 @@
+import { type DataTypeSerializer } from "@velora-cms/plugin-sdk/datatypes";
+export declare function getServerSerializer(editorId: string): DataTypeSerializer | null;
+export declare function registerServerSerializer(editorId: string, serializer: DataTypeSerializer): void;

package/dist/plugins/server-serializers.js

@@ -0,0 +1,16 @@
+// The server process's one datatype-serializer lookup (Session 111).
+// Seeded with the built-ins from the React-free datatypes subpath; a
+// remote/third-party plugin's serializer is unreachable server-side
+// (Module Federation remotes only load in the browser — Session 69's
+// scoping), so lookups for unknown editor ids return null and the
+// pipeline passes the stored value through. registerServerSerializer
+// exists for server-side registration (integration tests today; Session
+// 112's serializer contributions are its intended real consumer).
+import { BUILT_IN_SERIALIZERS } from "@velora-cms/plugin-sdk/datatypes";
+const registry = new Map(Object.entries(BUILT_IN_SERIALIZERS));
+export function getServerSerializer(editorId) {
+    return registry.get(editorId) ?? null;
+}
+export function registerServerSerializer(editorId, serializer) {
+    registry.set(editorId, serializer);
+}

package/dist/plugins/simple-storage-api.d.ts

@@ -0,0 +1,9 @@
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+import type { PluginRegistryService } from "./plugin-registry-service.js";
+export declare class SimpleStorageAPI {
+    private readonly adapter;
+    private readonly registry;
+    constructor(adapter: DatabaseAdapter, registry: PluginRegistryService);
+    get(contentId: string, fieldId: string, pluginId: string): Promise<unknown>;
+    set(contentId: string, fieldId: string, pluginId: string, value: unknown): Promise<void>;
+}

package/dist/plugins/simple-storage-api.js

@@ -0,0 +1,26 @@
+// SimpleStorageAPI: the JSON key-value storage tier plugins default to
+// (get/set by contentId+fieldId), as opposed to the opt-in, reviewed
+// StructuredStorageAPI tier for relational needs.
+// A thin pass-through: gate on the plugin being installed+active (the
+// registry state a disabled plugin has no business touching storage
+// through), then delegate to the adapter. All persistence logic lives in
+// DatabaseAdapter.get/setPluginFieldValue — this class exists only to
+// make the registry check impossible to forget at a call site, matching
+// the "either tier goes through [this], never raw SQL" rule
+// (plugin-sdk.md); business logic here never touches SQL directly.
+export class SimpleStorageAPI {
+    adapter;
+    registry;
+    constructor(adapter, registry) {
+        this.adapter = adapter;
+        this.registry = registry;
+    }
+    async get(contentId, fieldId, pluginId) {
+        await this.registry.requireActivePlugin(pluginId);
+        return this.adapter.getPluginFieldValue(contentId, fieldId, pluginId);
+    }
+    async set(contentId, fieldId, pluginId, value) {
+        await this.registry.requireActivePlugin(pluginId);
+        await this.adapter.setPluginFieldValue(contentId, fieldId, pluginId, value);
+    }
+}

package/dist/plugins/snapshot-groups.d.ts

@@ -0,0 +1,16 @@
+import type { PrismaClient } from "@prisma/client";
+import type { SnapshotGroup } from "@velora-cms/api-schemas";
+export interface SnapshotRowFacts {
+    snapshotGroupId: string;
+    tableName: string;
+    trigger: string | null;
+    createdAt: Date;
+}
+export declare function deriveSnapshotGroups(rows: SnapshotRowFacts[]): SnapshotGroup[];
+export declare function listSnapshotGroups(prisma: PrismaClient, pluginId: string, page: {
+    cursor?: string;
+    limit: number;
+}): Promise<{
+    items: SnapshotGroup[];
+    nextCursor: string | null;
+}>;

package/dist/plugins/snapshot-groups.js

@@ -0,0 +1,81 @@
+// S154 Task 4: snapshot GROUPS are derived, not tracked — there is no
+// SnapshotGroup table. A group is every PluginStructuredSnapshot row
+// sharing one snapshotGroupId (one snapshotPluginTables() call writes one
+// row per tracked table, all under the same group id and trigger).
+//
+// The "complete vs partial" status is the whole point of Task 4: it
+// compares a group's own tableNames against the UNION of distinct
+// tableNames across ALL of the plugin's snapshot rows (every group, not
+// just this one) — never against the plugin's CURRENT tracked-table count.
+// PluginStructuredTable (the live tracking table) gets wiped by
+// dropPluginTables() at uninstall, which is exactly when a group listing
+// matters most, so it can't be the denominator. The union of everything
+// this plugin ever snapshotted is the only count that survives that wipe
+// and stays honest across a failed-then-retried uninstall (S87's wedge):
+// an earlier attempt that captured all N tables reads "complete", a later
+// retry that could only re-capture the tables still physically present
+// (Task 3's tolerant skip-a-missing-table behavior) reads "partial" —
+// never a false "complete" claim for a group that's missing rows another
+// group in the same plugin's history actually has.
+export function deriveSnapshotGroups(rows) {
+    const totalTableCount = new Set(rows.map((row) => row.tableName)).size;
+    const rowsByGroup = new Map();
+    for (const row of rows) {
+        const bucket = rowsByGroup.get(row.snapshotGroupId);
+        if (bucket) {
+            bucket.push(row);
+        }
+        else {
+            rowsByGroup.set(row.snapshotGroupId, [row]);
+        }
+    }
+    const groups = [];
+    for (const [snapshotGroupId, groupRows] of rowsByGroup) {
+        const tableNames = [...new Set(groupRows.map((row) => row.tableName))].sort();
+        const takenAtMs = Math.min(...groupRows.map((row) => row.createdAt.getTime()));
+        groups.push({
+            snapshotGroupId,
+            takenAt: new Date(takenAtMs).toISOString(),
+            // Every row written by one snapshotPluginTables() call carries the
+            // same trigger — reading it off the first row in the bucket is safe,
+            // not an arbitrary pick among differing values.
+            trigger: groupRows[0].trigger,
+            tableNames,
+            totalTableCount,
+            status: tableNames.length === totalTableCount ? "complete" : "partial",
+        });
+    }
+    // Newest first.
+    groups.sort((a, b) => new Date(b.takenAt).getTime() - new Date(a.takenAt).getTime());
+    return groups;
+}
+// The DB read + in-memory pagination over derived groups. Deliberately ONE
+// indexed findMany (PluginStructuredSnapshot.pluginId is indexed) rather
+// than a `GROUP BY snapshotGroupId` query plus a second query per page:
+// the per-plugin group count is bounded by how many times an admin has
+// attempted to uninstall that plugin, not by content or row volume, so
+// pulling every row for one plugin and deriving+paginating groups in
+// memory is honest — this can never become an unbounded scan the way
+// loading a whole content subtree would be. The wire contract still
+// exposes cursor+limit (not just "return everything") so the route stays
+// pagination-shaped like every other list endpoint in this codebase, and
+// so a future plugin with a genuinely large uninstall-retry history
+// doesn't require a client-visible contract change to fix.
+export async function listSnapshotGroups(prisma, pluginId, page) {
+    const rows = await prisma.pluginStructuredSnapshot.findMany({
+        where: { pluginId },
+        select: { snapshotGroupId: true, tableName: true, trigger: true, createdAt: true },
+    });
+    const allGroups = deriveSnapshotGroups(rows);
+    let startIndex = 0;
+    if (page.cursor) {
+        const cursorIndex = allGroups.findIndex((group) => group.snapshotGroupId === page.cursor);
+        // A cursor that doesn't match any derived group (stale link, or the
+        // underlying rows are gone) walks to the end rather than silently
+        // restarting the page from the top.
+        startIndex = cursorIndex === -1 ? allGroups.length : cursorIndex + 1;
+    }
+    const items = allGroups.slice(startIndex, startIndex + page.limit);
+    const nextCursor = startIndex + items.length < allGroups.length ? (items[items.length - 1]?.snapshotGroupId ?? null) : null;
+    return { items, nextCursor };
+}

package/dist/plugins/structured-query-builder.d.ts

@@ -0,0 +1,21 @@
+import type { StructuredQueryOptions } from "@velora-cms/db-adapter";
+export declare class InvalidStructuredQueryError extends Error {
+    constructor(message: string);
+}
+export declare class StructuredQueryBuilder<T = Record<string, unknown>> implements PromiseLike<T[]> {
+    private readonly runQuery;
+    private whereConditions;
+    private orderBySpec?;
+    private limitValue?;
+    private paginateOptions?;
+    constructor(runQuery: (options: StructuredQueryOptions) => Promise<Record<string, unknown>[]>);
+    where(conditions: Record<string, unknown>): this;
+    orderBy(column: string, direction?: "asc" | "desc"): this;
+    limit(n: number): this;
+    paginate(options: {
+        cursor?: string;
+        limit: number;
+    }): this;
+    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    private exec;
+}

package/dist/plugins/structured-query-builder.js

@@ -0,0 +1,60 @@
+export class InvalidStructuredQueryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidStructuredQueryError";
+    }
+}
+// Plugin-facing fluent query builder for StructuredStorageAPI.query().
+// Deliberately dialect-unaware and DB-unaware — it just accumulates
+// where/orderBy/limit/paginate state and, on await, hands a single
+// StructuredQueryOptions object to whatever `runQuery` function its
+// caller supplied. This is what lets the exact same builder be used
+// both by the top-level StructuredStorageAPI (Task 8) and by
+// StructuredStorageTransaction (Task 7) — only `runQuery`'s
+// implementation differs between the two.
+export class StructuredQueryBuilder {
+    runQuery;
+    whereConditions = {};
+    orderBySpec;
+    limitValue;
+    paginateOptions;
+    constructor(runQuery) {
+        this.runQuery = runQuery;
+    }
+    where(conditions) {
+        this.whereConditions = { ...this.whereConditions, ...conditions };
+        return this;
+    }
+    orderBy(column, direction = "asc") {
+        this.orderBySpec = { column, direction };
+        return this;
+    }
+    limit(n) {
+        this.limitValue = n;
+        return this;
+    }
+    paginate(options) {
+        this.paginateOptions = options;
+        return this;
+    }
+    then(onfulfilled, onrejected) {
+        return this.exec().then(onfulfilled, onrejected);
+    }
+    async exec() {
+        if (this.orderBySpec && this.paginateOptions) {
+            throw new InvalidStructuredQueryError("orderBy() and paginate() cannot be used together");
+        }
+        if (this.limitValue === undefined && this.paginateOptions === undefined) {
+            throw new InvalidStructuredQueryError("call limit(n) or paginate({ cursor, limit }) before awaiting a query");
+        }
+        const options = this.paginateOptions
+            ? {
+                where: this.whereConditions,
+                cursor: this.paginateOptions.cursor,
+                limit: this.paginateOptions.limit,
+            }
+            : { where: this.whereConditions, orderBy: this.orderBySpec, limit: this.limitValue };
+        const rows = await this.runQuery(options);
+        return rows;
+    }
+}

package/dist/plugins/structured-snapshot-service.d.ts

@@ -0,0 +1,16 @@
+import type { PrismaClient } from "@prisma/client";
+import type { DatabaseAdapter } from "@velora-cms/db-adapter";
+import type { RestorePlanEntry } from "@velora-cms/api-schemas";
+export declare class StructuredSnapshotService {
+    private readonly adapter;
+    private readonly prisma;
+    constructor(adapter: DatabaseAdapter, prisma: PrismaClient);
+    snapshotPluginTables(pluginId: string, trigger?: string): Promise<string>;
+    restoreSnapshot(snapshotGroupId: string): Promise<void>;
+    dropPluginTables(pluginId: string): Promise<void>;
+    planRestore(pluginId: string): Promise<RestorePlanEntry[]>;
+    restorePluginData(pluginId: string): Promise<{
+        preRestoreSnapshotGroupId: string | null;
+        restoredTables: string[];
+    }>;
+}