@velora-cms/plugin-sdk 0.9.0

package/dist/manifest-schema.js

@@ -0,0 +1,348 @@
+import { z } from "zod";
+import { CreateDocumentTypeRequestSchema } from "@velora-cms/api-schemas";
+// Runtime mirror of manifest.ts — the same contract, enforced for
+// manifests that arrive as VALUES (Module Federation remotes, sideloaded
+// plugins, the future `velora-plugin validate` CLI) where the compiler
+// can't help. The contribution matrix is enforced by .strict() objects:
+// each per-type contributions schema declares only its allowed keys, so
+// a disallowed contribution fails as an unrecognized key with a clear
+// path like `contributions.adminSections`.
+//
+// Lives in the SDK, not @velora-cms/api-schemas, deliberately: the manifest
+// carries React components and functions (api-schemas must never know
+// React), and third-party tooling needs this validator from the
+// published package.
+// Zod 4: z.function() is not a schema — validate callables with
+// z.custom. The type parameter is the CONTRACT type from manifest.ts,
+// which is what makes the compile-time sync assertion at the bottom of
+// this file hold. React components may be functions OR objects
+// (React.memo/forwardRef produce exotic objects).
+const callable = (label) => z.custom((value) => typeof value === "function", { message: `${label} must be a function` });
+const componentSchema = z.custom((value) => typeof value === "function" || (typeof value === "object" && value !== null), { message: "must be a React component" });
+// A JSON Schema document is a plain object (DataTypePlugin.schema is the
+// JSONSchema7 object interface, not the boolean shorthand).
+const jsonSchemaSchema = z.custom((value) => typeof value === "object" && value !== null && !Array.isArray(value), { message: "must be a JSON Schema object" });
+// A plugin-declared request schema must be a REAL Zod schema instance
+// (z.object(...), z.string(), etc. — every Zod schema extends the base
+// ZodType class), not just an object that looks like one — plugin-api-
+// routes.ts calls .safeParse() on it directly at request time.
+const zodSchemaField = z.instanceof(z.ZodType);
+// Reverse-domain id per the documented contract, e.g. "com.vendor.name".
+const pluginIdSchema = z
+    .string()
+    .regex(/^[a-z0-9-]+(\.[a-z0-9-]+)+$/i, "must be a reverse-domain id like com.vendor.plugin");
+const dialectSchema = z.enum(["postgresql", "mysql", "sqlite", "mssql", "mongodb"]);
+const databaseCompatibilitySchema = z
+    .object({
+    storageType: z.enum(["simple", "structured"]),
+    // A plugin supporting zero databases can never be installed anywhere.
+    supported: z.array(dialectSchema).min(1),
+    unsupportedReason: z.partialRecord(dialectSchema, z.string()).optional(),
+})
+    .strict();
+const permissionsSchema = z
+    .object({
+    needsStructuredData: z.boolean(),
+    needsExternalNetwork: z.boolean(),
+    needsFileSystemAccess: z.boolean(),
+})
+    .strict();
+const pluginMigrationSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    up: callable("up"),
+    down: callable("down"),
+})
+    .strict();
+const migrationHooksSchema = z
+    .object({
+    beforeMigration: callable("beforeMigration").optional(),
+    transformRow: callable("transformRow").optional(),
+    afterMigration: callable("afterMigration").optional(),
+    validateMigration: callable("validateMigration").optional(),
+})
+    .strict();
+const HOOK_EVENTS = [
+    "content:beforeSave",
+    "content:afterSave",
+    "content:beforePublish",
+    "content:afterPublish",
+    "content:afterTrash",
+    "content:afterRestore",
+    "content:beforeDelete",
+    "media:afterUpload",
+    "user:afterLogin",
+    "api:beforeResponse",
+];
+// z.partialRecord, not z.record: with enum keys, Zod 4's record is
+// exhaustive (it would demand a handler for all ten events).
+const hooksSchema = z.partialRecord(z.enum(HOOK_EVENTS), callable("hook handler"));
+// The DataTypePlugin contract's structural shape — shared by manifests
+// (dataTypes contributions arriving as data) and definePlugin (which
+// fronts it with friendlier required-view messages).
+export const DataTypePluginSchema = z
+    .object({
+    id: pluginIdSchema,
+    name: z.string().min(1),
+    icon: z.string().min(1),
+    version: z.string().min(1),
+    type: z.literal("datatype"),
+    schema: jsonSchemaSchema,
+    settingsSchema: jsonSchemaSchema,
+    defaultSettings: z.record(z.string(), z.unknown()),
+    views: z
+        .object({
+        input: componentSchema,
+        readOnly: componentSchema,
+        settings: componentSchema,
+        preview: componentSchema.optional(),
+    })
+        .strict(),
+    serialize: callable("serialize"),
+    deserialize: callable("deserialize"),
+})
+    .strict();
+const adminSectionSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    icon: z.string().min(1),
+    view: componentSchema,
+    adminOnly: z.boolean().optional(),
+})
+    .strict();
+const dashboardWidgetSchema = z
+    .object({ id: z.string().min(1), name: z.string().min(1), view: componentSchema })
+    .strict();
+const apiRouteSchema = z
+    .object({
+    method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+    path: z.string().min(1).refine((p) => p.startsWith("/"), { message: 'path must start with "/"' }),
+    access: z.enum(["admin", "apiKey", "public"]).optional(),
+    schema: z
+        .object({
+        body: zodSchemaField.optional(),
+        querystring: zodSchemaField.optional(),
+        params: zodSchemaField.optional(),
+    })
+        .strict()
+        .optional(),
+    handler: callable("handler"),
+})
+    .strict();
+const customFormatContributionSchema = z.object({
+    name: z.string().regex(/^[a-z0-9-]+$/),
+    build: callable("build"),
+}).strict();
+const serializerContributionSchema = z
+    .object({
+    extendContentResponse: callable("extendContentResponse").optional(),
+    customFormats: z.array(customFormatContributionSchema).optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const names = (value.customFormats ?? []).map((format) => format.name);
+    if (new Set(names).size !== names.length) {
+        ctx.addIssue({ code: "custom", message: "customFormats names must be unique within a manifest" });
+    }
+});
+const scheduledTaskSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    cron: z.string().min(1),
+    run: callable("run"),
+})
+    .strict();
+const mediaProcessorSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    process: callable("process"),
+})
+    .strict();
+const settingsPageSchema = z
+    .object({ id: z.string().min(1), name: z.string().min(1), view: componentSchema })
+    .strict();
+const contentTreeActionSchema = z
+    .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    onSelect: callable("onSelect"),
+})
+    .strict();
+const editorToolbarSchema = z
+    .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    icon: z.string().min(1),
+    onClick: callable("onClick"),
+})
+    .strict();
+const exposedServiceSchema = z
+    .object({ id: z.string().min(1), name: z.string().min(1), service: z.unknown() })
+    .strict();
+const bundledTemplateSchema = z
+    .object({
+    name: z.string().min(1),
+    description: z.string().optional(),
+    repository: z.string().optional(),
+})
+    .strict();
+// Both the record KEY (kebab-cased into the CSS custom-property name by
+// @velora-cms/design-tokens's flatten()) and the VALUE (emitted verbatim after
+// the colon) end up spliced into a shared, admin-wide `[data-theme] { ... }`
+// block at runtime (see theme-css.ts's themeOverridesToCss). Braces,
+// semicolons, and control characters are never legitimate in a single CSS
+// identifier or value, and would otherwise let an installed theme plugin
+// break out of its declaration and inject arbitrary rules. This is a belt
+// to theme-css.ts's own runtime filter, enforced earlier at manifest
+// validation time.
+const safeCssTokenSchema = z
+    .string()
+    .max(200)
+    .regex(new RegExp('^[^{};\\u0000-\\u001f\\u007f]+$'), "must not contain CSS-escaping characters");
+// themeTokens: minimal strict mirror of ThemeTokenOverrides — only
+// color/radius keys exist (themes are cosmetic by construction);
+// design-tokens has no Zod and shouldn't gain one, so token values are
+// validated shallowly here.
+const themeTokensSchema = z
+    .object({
+    color: z.record(safeCssTokenSchema, z.record(safeCssTokenSchema, safeCssTokenSchema)).optional(),
+    radius: z.record(safeCssTokenSchema, safeCssTokenSchema).optional(),
+})
+    .strict();
+// --- per-type contribution surfaces (the matrix, one .strict() each) -------
+const dataTypeContributionsSchema = z
+    .object({
+    dataTypes: z.array(DataTypePluginSchema).optional(),
+    mediaProcessors: z.array(mediaProcessorSchema).optional(),
+    settingsPages: z.array(settingsPageSchema).optional(),
+})
+    .strict();
+const sectionContributionsSchema = z
+    .object({
+    dataTypes: z.array(DataTypePluginSchema).optional(),
+    adminSections: z.array(adminSectionSchema).optional(),
+    dashboardWidgets: z.array(dashboardWidgetSchema).optional(),
+    apiRoutes: z.array(apiRouteSchema).optional(),
+    hooks: hooksSchema.optional(),
+    scheduledTasks: z.array(scheduledTaskSchema).optional(),
+    settingsPages: z.array(settingsPageSchema).optional(),
+    documentTypes: z.array(CreateDocumentTypeRequestSchema).optional(),
+    bundledTemplate: bundledTemplateSchema.optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    // Two apiRoutes entries sharing a (method, path) pair within one
+    // manifest would silently last-wins in plugin-api-routes.ts's
+    // dispatcher — a validation error, not a runtime surprise, same
+    // reasoning as document-type-api.schema.ts's duplicate-field-id check.
+    const seen = new Set();
+    (value.apiRoutes ?? []).forEach((route, index) => {
+        const key = `${route.method} ${route.path}`;
+        if (seen.has(key)) {
+            ctx.addIssue({
+                code: "custom",
+                message: `Duplicate apiRoute "${key}" — method+path pairs must be unique within a manifest`,
+                path: ["apiRoutes", index],
+            });
+        }
+        seen.add(key);
+    });
+});
+const templateContributionsSchema = z
+    .object({
+    documentTypes: z.array(CreateDocumentTypeRequestSchema).optional(),
+})
+    .strict();
+const themeContributionsSchema = z
+    .object({
+    themeTokens: themeTokensSchema.optional(),
+})
+    .strict();
+const integrationContributionsSchema = z
+    .object({
+    hooks: hooksSchema.optional(),
+    settingsPages: z.array(settingsPageSchema).optional(),
+    exposedServices: z.array(exposedServiceSchema).optional(),
+    serializers: serializerContributionSchema.optional(),
+})
+    .strict();
+const utilityContributionsSchema = z
+    .object({
+    dashboardWidgets: z.array(dashboardWidgetSchema).optional(),
+    hooks: hooksSchema.optional(),
+    scheduledTasks: z.array(scheduledTaskSchema).optional(),
+    mediaProcessors: z.array(mediaProcessorSchema).optional(),
+    settingsPages: z.array(settingsPageSchema).optional(),
+    contentTreeActions: z.array(contentTreeActionSchema).optional(),
+    editorToolbar: z.array(editorToolbarSchema).optional(),
+    serializers: serializerContributionSchema.optional(),
+})
+    .strict();
+const bundleContributionsSchema = z
+    .object({
+    bundledPlugins: z.array(pluginIdSchema).optional(),
+    bundledTemplate: bundledTemplateSchema.optional(),
+})
+    .strict();
+// --- the manifest -----------------------------------------------------------
+const baseFields = {
+    id: pluginIdSchema,
+    name: z.string().min(1),
+    // Non-empty for now; strict semver checking belongs to
+    // `velora-plugin validate` (Month 7).
+    version: z.string().min(1),
+    description: z.string().min(1),
+    author: z.string().min(1),
+    license: z.string().min(1),
+    price: z.number().nonnegative().optional(),
+    // Optional by design: sideloaded/dev plugins are unsigned (Tier 2).
+    signature: z.string().optional(),
+    cmsVersion: z.string().min(1),
+    pluginDependencies: z.array(pluginIdSchema).optional(),
+    databaseCompatibility: databaseCompatibilitySchema,
+    permissions: permissionsSchema,
+    migrations: z.array(pluginMigrationSchema).optional(),
+    onInstall: callable("onInstall").optional(),
+    onUninstall: callable("onUninstall").optional(),
+    onActivate: callable("onActivate").optional(),
+    onDeactivate: callable("onDeactivate").optional(),
+    onUpdate: callable("onUpdate").optional(),
+    migrationHooks: migrationHooksSchema.optional(),
+};
+export const CMSPluginSchema = z.discriminatedUnion("type", [
+    z.object({ ...baseFields, type: z.literal("datatype"), contributions: dataTypeContributionsSchema }).strict(),
+    z.object({ ...baseFields, type: z.literal("section"), contributions: sectionContributionsSchema }).strict(),
+    z.object({ ...baseFields, type: z.literal("template"), contributions: templateContributionsSchema }).strict(),
+    z.object({ ...baseFields, type: z.literal("theme"), contributions: themeContributionsSchema }).strict(),
+    z
+        .object({ ...baseFields, type: z.literal("integration"), contributions: integrationContributionsSchema })
+        .strict(),
+    z.object({ ...baseFields, type: z.literal("utility"), contributions: utilityContributionsSchema }).strict(),
+    z.object({ ...baseFields, type: z.literal("bundle"), contributions: bundleContributionsSchema }).strict(),
+]);
+// Shared by validatePluginManifest and definePlugin — one formatting
+// convention for every validation surface: `path: message`.
+export function formatIssues(issues) {
+    return issues.map((issue) => {
+        const path = issue.path.join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    });
+}
+/**
+ * Validate an untrusted value as a CMSPlugin manifest. The registry's
+ * install() (Session 62) and `velora-plugin validate` (Month 7) both go
+ * through this — errors come back as readable `path: message` strings
+ * (e.g. `contributions.adminSections: Unrecognized key ...` for a
+ * contribution-matrix violation).
+ */
+export function validatePluginManifest(value) {
+    const result = CMSPluginSchema.safeParse(value);
+    if (result.success) {
+        return { ok: true, manifest: result.data };
+    }
+    return { ok: false, errors: formatIssues(result.error.issues) };
+}