create-nextblock 0.2.78 → 0.8.0

package/templates/nextblock-template/lib/cms-transfer/types.ts

@@ -0,0 +1,145 @@
+import type { Json } from "@nextblock-cms/db";
+
+export type CmsContentType = "pages" | "posts" | "products";
+export type CmsImportConflictMode = "create_new" | "overwrite_existing";
+export type CmsImportApplyMode = "draft" | "live";
+
+export interface CmsImportOptions {
+  conflictMode: CmsImportConflictMode;
+  applyMode: CmsImportApplyMode;
+  ignoreBlankFields?: boolean;
+  skipUnavailableProductContent?: boolean;
+}
+
+export interface CmsImportMessage {
+  row: number;
+  type: "error" | "warning";
+  message: string;
+}
+
+export interface CmsImportPreviewItem {
+  row: number;
+  action: "create" | "update" | "skip";
+  identifier: string;
+  contentType: CmsContentType;
+}
+
+export interface CmsImportSummary {
+  success: boolean;
+  totalRows: number;
+  created: number;
+  updated: number;
+  skipped: number;
+  errors: CmsImportMessage[];
+  warnings: CmsImportMessage[];
+  preview: CmsImportPreviewItem[];
+}
+
+export interface CmsTransferActionResult {
+  success: boolean;
+  error?: string;
+  fileName?: string;
+  mimeType?: string;
+  content?: string;
+}
+
+export interface CmsBackupBundleV1 {
+  version: 1;
+  exported_at: string;
+  languages: Array<{
+    id: number;
+    code: string;
+    name: string | null;
+  }>;
+  content: {
+    pages: BackupPageRecord[];
+    posts: BackupPostRecord[];
+    products: BackupProductRecord[];
+  };
+  // Optional for backward compatibility with bundles exported before the
+  // Blocks Library was added to the content backup.
+  custom_blocks?: BackupCustomBlockRecord[];
+}
+
+export interface BackupBlockRecord {
+  language_id?: number;
+  block_type: string;
+  content: Json;
+  order?: number;
+}
+
+export interface BackupCustomBlockRecord {
+  slug: string;
+  name: string;
+  description?: string;
+  fields: Json;
+  layout_schema: Json;
+  is_original?: boolean;
+}
+
+export interface BackupPageRecord {
+  id?: number | string | null;
+  translation_group_id?: string | null;
+  language_code: string;
+  title: string;
+  slug: string;
+  status: string;
+  meta_title?: string | null;
+  meta_description?: string | null;
+  feature_image_id?: string | null;
+  feature_image_object_key?: string | null;
+  blocks: BackupBlockRecord[];
+}
+
+export interface BackupPostRecord extends BackupPageRecord {
+  label?: string | null;
+  excerpt?: string | null;
+  subtitle?: string | null;
+  published_at?: string | null;
+}
+
+export interface BackupProductVariantRecord {
+  id?: string | null;
+  sku: string;
+  upc?: string | null;
+  price: number;
+  prices?: Record<string, number>;
+  sale_price?: number | null;
+  sale_prices?: Record<string, number | null> | null;
+  stock_quantity: number;
+  main_media_id?: string | null;
+  main_media_object_key?: string | null;
+  attribute_term_ids?: string[];
+}
+
+export interface BackupProductRecord {
+  id?: string | null;
+  translation_group_id?: string | null;
+  language_code: string;
+  product_type: string;
+  payment_provider: string;
+  title: string;
+  slug: string;
+  sku: string;
+  upc?: string | null;
+  status: string;
+  price: number;
+  prices?: Record<string, number>;
+  sale_price?: number | null;
+  sale_prices?: Record<string, number | null> | null;
+  stock: number;
+  is_taxable: boolean;
+  meta_title?: string | null;
+  meta_description?: string | null;
+  short_description?: string | null;
+  description_json?: Json;
+  description_blocks: BackupBlockRecord[];
+  category_slugs?: string[];
+  media_ids?: string[];
+  media_object_keys?: string[];
+  variants?: BackupProductVariantRecord[];
+  freemius_product_id?: string | null;
+  freemius_plan_id?: string | null;
+  trial_period_days?: number;
+  trial_requires_payment_method?: boolean;
+}

package/templates/nextblock-template/lib/cortex-widget-registry.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('@nextblock-cms/utils', async () => {
+  const { z } = await import('zod');
+  const fieldKeyPattern = /^[a-z][a-z0-9_]*$/;
+  const slugPattern = /^[a-z][a-z0-9-]*$/;
+  const customBlockFieldKeySchema = z.string().trim().min(1).max(80).regex(fieldKeyPattern);
+  const customBlockSlugSchema = z.string().trim().min(1).max(120).regex(slugPattern);
+  const fieldBaseSchema = z.strictObject({
+    description: z.string().trim().max(500).optional(),
+    key: customBlockFieldKeySchema,
+    label: z.string().trim().min(1).max(120),
+    required: z.boolean().default(false),
+  });
+  const fieldSchema = z.discriminatedUnion('type', [
+    fieldBaseSchema.extend({
+      default_value: z.string().max(5000).optional(),
+      max_length: z.number().int().positive().max(10000).optional(),
+      min_length: z.number().int().min(0).max(10000).optional(),
+      placeholder: z.string().max(250).optional(),
+      type: z.literal('text'),
+    }),
+    fieldBaseSchema.extend({
+      default_value: z.string().max(50000).optional(),
+      placeholder: z.string().max(250).optional(),
+      type: z.literal('rich-text'),
+    }),
+    fieldBaseSchema.extend({
+      accept: z.array(z.string()).max(20).optional(),
+      default_value: z
+        .strictObject({
+          alt: z.string().max(300).optional(),
+          file_name: z.string().trim().min(1).max(255).optional(),
+          file_type: z.string().trim().min(1).max(120).optional(),
+          height: z.number().int().positive().optional(),
+          object_key: z.string().trim().min(1).max(1024),
+          size_bytes: z.number().int().positive().optional(),
+          url: z.string().trim().min(1).max(2048),
+          width: z.number().int().positive().optional(),
+        })
+        .optional(),
+      max_bytes: z.number().int().positive().max(50 * 1024 * 1024).optional(),
+      type: z.literal('image_r2'),
+    }),
+    fieldBaseSchema.extend({
+      default_value: z.union([z.string(), z.array(z.string()), z.null()]).optional(),
+      display_column: z.string().trim().min(1).max(80).default('title'),
+      filters: z.record(z.string(), z.unknown()).optional(),
+      multiple: z.boolean().default(false),
+      table: z.string().trim().min(1).max(80).regex(fieldKeyPattern),
+      type: z.literal('db_relation'),
+      value_column: z.string().trim().min(1).max(80).default('id'),
+    }),
+  ]);
+  const elementSchema = z.enum([
+    'article',
+    'aside',
+    'blockquote',
+    'div',
+    'figure',
+    'figcaption',
+    'h2',
+    'h3',
+    'img',
+    'p',
+    'section',
+    'span',
+  ]);
+  const layoutNodeSchema: any = z.lazy(() =>
+    z.discriminatedUnion('type', [
+      z.strictObject({
+        as: elementSchema.optional(),
+        children: z.array(layoutNodeSchema).max(200).default([]),
+        className: z.string().trim().max(4000).optional(),
+        type: z.literal('container'),
+      }),
+      z.strictObject({
+        as: elementSchema.optional(),
+        className: z.string().trim().max(4000).optional(),
+        emptyFallback: z.string().max(300).optional(),
+        field_key: customBlockFieldKeySchema,
+        type: z.literal('field_render'),
+      }),
+    ])
+  );
+  const customBlockDefinitionCreateSchema = z.strictObject({
+    description: z.string().trim().max(1000).default(''),
+    fields: z.array(fieldSchema).max(80).default([]),
+    is_original: z.boolean().default(true),
+    layout_schema: layoutNodeSchema,
+    name: z.string().trim().min(1).max(160),
+    slug: customBlockSlugSchema,
+  });
+  const customBlockDefinitionRowSchema = customBlockDefinitionCreateSchema.safeExtend({
+    id: z.string().uuid(),
+    is_original: z.boolean(),
+  });
+
+  return {
+    customBlockDefinitionCreateSchema,
+    customBlockDefinitionRowSchema,
+    customBlockFieldKeySchema,
+    customBlockSlugSchema,
+  };
+});
+
+import { buildCortexProfileCardVerificationDefinition } from './cortex-widget-schema';
+import {
+  CortexWidgetRegistryInsertError,
+  buildCortexWidgetDefinitionInsertPayload,
+  insertCortexWidgetDefinition,
+} from './cortex-widget-registry';
+
+class MockInsertQuery {
+  payload: unknown;
+
+  constructor(
+    private readonly result: {
+      data: unknown;
+      error: { code?: string; message?: string } | null;
+    }
+  ) {}
+
+  insert(payload: unknown) {
+    this.payload = payload;
+    return this;
+  }
+
+  select() {
+    return this;
+  }
+
+  single() {
+    return Promise.resolve(this.result);
+  }
+}
+
+describe('cortex widget registry insert', () => {
+  it('builds a strict atomic insert payload for custom_block_definitions', () => {
+    const definition = buildCortexProfileCardVerificationDefinition();
+    const payload = buildCortexWidgetDefinitionInsertPayload(definition);
+
+    expect(payload).toMatchObject({
+      description: definition.description,
+      is_original: true,
+      name: definition.name,
+      slug: definition.slug,
+    });
+    expect(payload.fields).toEqual(definition.fields);
+    expect(payload.layout_schema).toEqual(definition.layout_schema);
+  });
+
+  it('inserts the generated widget definition and parses the returned row', async () => {
+    const definition = buildCortexProfileCardVerificationDefinition();
+    const query = new MockInsertQuery({
+      data: {
+        ...buildCortexWidgetDefinitionInsertPayload(definition),
+        id: '66666666-6666-4666-8666-666666666666',
+      },
+      error: null,
+    });
+    const supabase = {
+      from: (table: string) => {
+        expect(table).toBe('custom_block_definitions');
+        return query;
+      },
+    };
+
+    const inserted = await insertCortexWidgetDefinition(supabase as any, definition);
+
+    expect(query.payload).toMatchObject({
+      is_original: true,
+      slug: 'cortex-profile-card',
+    });
+    expect(inserted).toMatchObject({
+      id: '66666666-6666-4666-8666-666666666666',
+      is_original: true,
+      slug: 'cortex-profile-card',
+    });
+  });
+
+  it('maps unique slug failures to a 409 registry error', async () => {
+    const definition = buildCortexProfileCardVerificationDefinition();
+    const query = new MockInsertQuery({
+      data: null,
+      error: {
+        code: '23505',
+        message: 'duplicate key value violates unique constraint',
+      },
+    });
+
+    await expect(
+      insertCortexWidgetDefinition({ from: () => query } as any, definition)
+    ).rejects.toMatchObject<CortexWidgetRegistryInsertError>({
+      code: '23505',
+      status: 409,
+    });
+  });
+});

package/templates/nextblock-template/lib/cortex-widget-registry.ts

@@ -0,0 +1,88 @@
+import type { Database, Json } from '@nextblock-cms/db';
+import {
+  customBlockDefinitionCreateSchema,
+  customBlockDefinitionRowSchema,
+  type CustomBlockDefinition,
+} from '@nextblock-cms/utils';
+
+import type { CortexWidgetDefinition } from './cortex-widget-schema';
+
+export const CORTEX_WIDGET_DEFINITION_SELECT =
+  'id, slug, name, description, fields, layout_schema, is_original';
+
+type CustomBlockDefinitionInsert =
+  Database['public']['Tables']['custom_block_definitions']['Insert'];
+
+type SupabaseInsertClient = {
+  from: (table: string) => any;
+};
+
+export class CortexWidgetRegistryInsertError extends Error {
+  readonly code?: string;
+  readonly status: number;
+
+  constructor(message: string, params?: { code?: string; status?: number }) {
+    super(message);
+    this.name = 'CortexWidgetRegistryInsertError';
+    this.code = params?.code;
+    this.status = params?.status ?? 500;
+  }
+}
+
+function toJson(value: unknown): Json {
+  return JSON.parse(JSON.stringify(value)) as Json;
+}
+
+function getInsertErrorStatus(code?: string) {
+  if (code === '23505') {
+    return 409;
+  }
+
+  if (code === '42501') {
+    return 403;
+  }
+
+  return 500;
+}
+
+export function buildCortexWidgetDefinitionInsertPayload(
+  definition: CortexWidgetDefinition
+): CustomBlockDefinitionInsert {
+  const parsed = customBlockDefinitionCreateSchema.parse({
+    ...definition,
+    is_original: true,
+  });
+
+  return {
+    description: parsed.description,
+    fields: toJson(parsed.fields),
+    is_original: true,
+    layout_schema: toJson(parsed.layout_schema),
+    name: parsed.name,
+    slug: parsed.slug,
+  };
+}
+
+export async function insertCortexWidgetDefinition(
+  supabase: SupabaseInsertClient,
+  definition: CortexWidgetDefinition
+): Promise<CustomBlockDefinition> {
+  const payload = buildCortexWidgetDefinitionInsertPayload(definition);
+  const { data, error } = await supabase
+    .from('custom_block_definitions')
+    .insert(payload)
+    .select(CORTEX_WIDGET_DEFINITION_SELECT)
+    .single();
+
+  if (error || !data) {
+    throw new CortexWidgetRegistryInsertError(
+      error?.message ?? 'Failed to insert Cortex custom block definition.',
+      {
+        code: error?.code,
+        status: getInsertErrorStatus(error?.code),
+      }
+    );
+  }
+
+  return customBlockDefinitionRowSchema.parse(data);
+}

package/templates/nextblock-template/lib/cortex-widget-schema.test.tsx

@@ -0,0 +1,237 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('@nextblock-cms/utils', async () => {
+  const { z } = await import('zod');
+  const fieldKeyPattern = /^[a-z][a-z0-9_]*$/;
+  const slugPattern = /^[a-z][a-z0-9-]*$/;
+  const customBlockFieldKeySchema = z.string().trim().min(1).max(80).regex(fieldKeyPattern);
+  const customBlockSlugSchema = z.string().trim().min(1).max(120).regex(slugPattern);
+  const fieldBaseSchema = z.strictObject({
+    description: z.string().trim().max(500).optional(),
+    key: customBlockFieldKeySchema,
+    label: z.string().trim().min(1).max(120),
+    required: z.boolean().default(false),
+  });
+  const fieldSchema = z.discriminatedUnion('type', [
+    fieldBaseSchema.extend({
+      default_value: z.string().max(5000).optional(),
+      max_length: z.number().int().positive().max(10000).optional(),
+      min_length: z.number().int().min(0).max(10000).optional(),
+      placeholder: z.string().max(250).optional(),
+      type: z.literal('text'),
+    }),
+    fieldBaseSchema.extend({
+      default_value: z.string().max(50000).optional(),
+      placeholder: z.string().max(250).optional(),
+      type: z.literal('rich-text'),
+    }),
+    fieldBaseSchema.extend({
+      accept: z.array(z.string()).max(20).optional(),
+      default_value: z
+        .strictObject({
+          alt: z.string().max(300).optional(),
+          file_name: z.string().trim().min(1).max(255).optional(),
+          file_type: z.string().trim().min(1).max(120).optional(),
+          height: z.number().int().positive().optional(),
+          object_key: z.string().trim().min(1).max(1024),
+          size_bytes: z.number().int().positive().optional(),
+          url: z.string().trim().min(1).max(2048),
+          width: z.number().int().positive().optional(),
+        })
+        .optional(),
+      max_bytes: z.number().int().positive().max(50 * 1024 * 1024).optional(),
+      type: z.literal('image_r2'),
+    }),
+    fieldBaseSchema.extend({
+      default_value: z.union([z.string(), z.array(z.string()), z.null()]).optional(),
+      display_column: z.string().trim().min(1).max(80).default('title'),
+      filters: z.record(z.string(), z.unknown()).optional(),
+      multiple: z.boolean().default(false),
+      table: z.string().trim().min(1).max(80).regex(fieldKeyPattern),
+      type: z.literal('db_relation'),
+      value_column: z.string().trim().min(1).max(80).default('id'),
+    }),
+  ]);
+  const elementSchema = z.enum([
+    'article',
+    'aside',
+    'blockquote',
+    'div',
+    'figure',
+    'figcaption',
+    'h2',
+    'h3',
+    'img',
+    'p',
+    'section',
+    'span',
+  ]);
+  const layoutNodeSchema: any = z.lazy(() =>
+    z.discriminatedUnion('type', [
+      z.strictObject({
+        as: elementSchema.optional(),
+        children: z.array(layoutNodeSchema).max(200).default([]),
+        className: z.string().trim().max(4000).optional(),
+        type: z.literal('container'),
+      }),
+      z.strictObject({
+        as: elementSchema.optional(),
+        className: z.string().trim().max(4000).optional(),
+        emptyFallback: z.string().max(300).optional(),
+        field_key: customBlockFieldKeySchema,
+        type: z.literal('field_render'),
+      }),
+    ])
+  );
+  const collectKeys = (node: any): string[] =>
+    node.type === 'field_render' ? [node.field_key] : node.children.flatMap(collectKeys);
+  const customBlockDefinitionCreateSchema = z
+    .strictObject({
+      description: z.string().trim().max(1000).default(''),
+      fields: z.array(fieldSchema).max(80).default([]),
+      is_original: z.boolean().default(true),
+      layout_schema: layoutNodeSchema,
+      name: z.string().trim().min(1).max(160),
+      slug: customBlockSlugSchema,
+    })
+    .superRefine((definition, context) => {
+      const fieldKeys = new Set(definition.fields.map((field) => field.key));
+      for (const fieldKey of collectKeys(definition.layout_schema)) {
+        if (!fieldKeys.has(fieldKey)) {
+          context.addIssue({
+            code: 'custom',
+            message: `Layout references unknown field "${fieldKey}".`,
+            path: ['layout_schema'],
+          });
+        }
+      }
+    });
+
+  return {
+    customBlockDefinitionCreateSchema,
+    customBlockFieldKeySchema,
+    customBlockSlugSchema,
+  };
+});
+
+import { DynamicLayoutEngine } from '../components/renderers/DynamicLayoutEngine';
+import {
+  buildCortexProfileCardVerificationDefinition,
+  buildCortexWidgetBuilderPrompt,
+  buildCortexWidgetBuilderSystemPrompt,
+  cortexWidgetDefinitionSchema,
+  validateCortexWidgetDefinitionOutput,
+} from './cortex-widget-schema';
+
+describe('cortex widget schema', () => {
+  it('validates a recursive multi-tier profile card widget', () => {
+    const definition = buildCortexProfileCardVerificationDefinition();
+
+    expect(definition.slug).toBe('cortex-profile-card');
+    expect(definition.is_original).toBe(true);
+    expect(definition.fields.map((field) => field.type)).toEqual([
+      'image_r2',
+      'text',
+      'text',
+      'rich-text',
+      'db_relation',
+    ]);
+    expect(definition.layout_schema.type).toBe('container');
+    if (definition.layout_schema.type !== 'container') {
+      throw new Error('Expected verification layout to be a container.');
+    }
+    expect(definition.layout_schema.children[0]?.type).toBe('container');
+  });
+
+  it('renders the generated recursive layout without runtime compilation', () => {
+    const definition = buildCortexProfileCardVerificationDefinition();
+    const html = renderToStaticMarkup(
+      <DynamicLayoutEngine
+        definition={{
+          fields: definition.fields,
+          id: '55555555-5555-4555-8555-555555555555',
+          layout_schema: definition.layout_schema,
+          name: definition.name,
+          slug: definition.slug,
+        }}
+        data={{
+          customer_list: ['profile-1', 'profile-2'],
+          profile_name: 'Ada Lovelace',
+          profile_photo: {
+            alt: 'Ada Lovelace',
+            object_key: 'cortex/profile-card/ada.webp',
+            url: 'https://cdn.nextblock.dev/cortex/profile-card/ada.webp',
+          },
+          profile_role: 'Principal Architect',
+          profile_summary: '<p>Builds analytical systems with human taste.</p>',
+          resolved_relations: {
+            customer_list: [
+              {
+                record: { full_name: 'Analytical Engine Society', id: 'profile-1' },
+                table: 'profiles',
+                value: 'profile-1',
+              },
+              {
+                record: { full_name: 'Difference Labs', id: 'profile-2' },
+                table: 'profiles',
+                value: 'profile-2',
+              },
+            ],
+          },
+        }}
+      />
+    );
+
+    expect(html).toContain('mx-auto max-w-3xl p-4');
+    expect(html).toContain('src="https://cdn.nextblock.dev/cortex/profile-card/ada.webp"');
+    expect(html).toContain('Ada Lovelace');
+    expect(html).toContain('Principal Architect');
+    expect(html).toContain('Analytical Engine Society, Difference Labs');
+  });
+
+  it('rejects layout fields that are not declared', () => {
+    expect(() =>
+      validateCortexWidgetDefinitionOutput({
+        description: '',
+        fields: [{ key: 'headline', label: 'Headline', required: true, type: 'text' }],
+        is_original: true,
+        layout_schema: {
+          field_key: 'missing_field',
+          type: 'field_render',
+        },
+        name: 'Broken Widget',
+        slug: 'broken-widget',
+      })
+    ).toThrow(/unknown field/);
+  });
+
+  it('keeps the prompt constrained to raw JSON, Tailwind classes, and data rows', () => {
+    const systemPrompt = buildCortexWidgetBuilderSystemPrompt();
+    const userPrompt = buildCortexWidgetBuilderPrompt({
+      prompt:
+        'Synthesize a multi-tier profile card with an inner flex column housing an R2 picture asset slot and a customer list relation link.',
+    });
+
+    expect(systemPrompt).toContain('Return ONLY one clean raw JSON object');
+    expect(systemPrompt).toContain('Tailwind utility classes');
+    expect(systemPrompt).toContain('Never emit TSX');
+    expect(userPrompt).toContain('multi-tier profile card');
+  });
+
+  it('exposes a recursive Zod layout schema for constrained decoding', () => {
+    const parsed = cortexWidgetDefinitionSchema.parse(
+      buildCortexProfileCardVerificationDefinition()
+    );
+
+    expect(parsed.layout_schema).toMatchObject({
+      type: 'container',
+      children: expect.arrayContaining([
+        expect.objectContaining({
+          type: 'container',
+        }),
+      ]),
+    });
+  });
+});