simplycms 0.4.0

package/src/plugin-sdk/server/table-db.ts

@@ -0,0 +1,149 @@
+import { sql, type SQL } from 'drizzle-orm';
+import {
+  withStorefrontDb,
+  withStoreOperatorDb,
+  type ActorDb,
+  type JsonValue,
+} from 'simplycms/storefront/loaders';
+import { assertColumn, assertKnownPlugin, assertOwnTable } from './guard';
+
+/**
+ * Виконання запитів до ВЛАСНОЇ таблиці плагіна (рішення B9).
+ *
+ * 🔴 SQL тут будується рядком, а не Drizzle-схемою, і це неминуче: таблиці
+ * `plg_*` живуть у міграціях плагіна, ядро їхніх колонок не знає за
+ * визначенням. Тому кожен ідентифікатор проходить `assertOwnTable`/
+ * `assertColumn`, а кожне ЗНАЧЕННЯ їде параметром — інтерполяції значень у
+ * цьому модулі немає жодної.
+ */
+
+/** Скаляр, який порт погоджується покласти в колонку плагіна. */
+export type PluginCell = string | number | boolean | null;
+
+/**
+ * Рядок таблиці плагіна, як його бачить ядро: плоский і нетипізований.
+ *
+ * 🔴 Значення саме `JsonValue`, а не `unknown`: результат serverFn їде на
+ * клієнт серіалізацією, і `unknown` там — не «поки не знаю тип», а «може не
+ * пережити дорогу». TanStack Start це перевіряє типом і не дає зібратись.
+ */
+export type PluginRow = Record<string, JsonValue>;
+
+export interface PluginListQuery {
+  eq?: Record<string, PluginCell>;
+  orderBy?: string;
+  ascending?: boolean;
+}
+
+/** `select * from <таблиця плагіна>` із простими фільтрами. */
+export async function selectPluginRows(
+  pluginName: string,
+  table: string,
+  query: PluginListQuery = {},
+): Promise<PluginRow[]> {
+  const name = await guardedTable(pluginName, table);
+
+  const parts: SQL[] = [sql`select * from ${sql.identifier(name)}`];
+
+  const conditions = Object.entries(query.eq ?? {}).map(
+    ([column, value]) =>
+      sql`${sql.identifier(assertColumn(column))} = ${value}`,
+  );
+  if (conditions.length > 0) {
+    parts.push(sql` where ${sql.join(conditions, sql` and `)}`);
+  }
+
+  if (query.orderBy) {
+    const direction = query.ascending === false ? sql`desc` : sql`asc`;
+    parts.push(
+      sql` order by ${sql.identifier(assertColumn(query.orderBy))} ${direction}`,
+    );
+  }
+
+  return withStorefrontDb((db) => run(db, sql.join(parts, sql``)));
+}
+
+/**
+ * Вставка рядка. Пише роль `app_admin`, і лише після серверної перевірки
+ * ролі викликача — див. `./index`.
+ */
+export async function insertPluginRow(
+  pluginName: string,
+  table: string,
+  row: Record<string, PluginCell>,
+): Promise<PluginRow> {
+  const name = await guardedTable(pluginName, table);
+  const columns = Object.keys(row).map(assertColumn);
+  if (columns.length === 0) {
+    throw new Error('[plugin-sdk] insert без жодної колонки');
+  }
+
+  const query = sql`insert into ${sql.identifier(name)} (${sql.join(
+    columns.map((column) => sql.identifier(column)),
+    sql`, `,
+  )}) values (${sql.join(
+    columns.map((column) => sql`${row[column]}`),
+    sql`, `,
+  )}) returning *`;
+
+  return one(await withStoreOperatorDb((db) => run(db, query)), 'insert');
+}
+
+/** Оновлення рядка за `id`. */
+export async function updatePluginRow(
+  pluginName: string,
+  table: string,
+  id: string,
+  patch: Record<string, PluginCell>,
+): Promise<PluginRow> {
+  const name = await guardedTable(pluginName, table);
+  const columns = Object.keys(patch).map(assertColumn);
+  if (columns.length === 0) {
+    throw new Error('[plugin-sdk] update без жодної колонки');
+  }
+
+  const query = sql`update ${sql.identifier(name)} set ${sql.join(
+    columns.map((column) => sql`${sql.identifier(column)} = ${patch[column]}`),
+    sql`, `,
+  )} where ${sql.identifier('id')} = ${id} returning *`;
+
+  return one(await withStoreOperatorDb((db) => run(db, query)), 'update');
+}
+
+/** Видалення рядка за `id`. */
+export async function deletePluginRow(
+  pluginName: string,
+  table: string,
+  id: string,
+): Promise<void> {
+  const name = await guardedTable(pluginName, table);
+  await withStoreOperatorDb((db) =>
+    run(
+      db,
+      sql`delete from ${sql.identifier(name)} where ${sql.identifier('id')} = ${id}`,
+    ),
+  );
+}
+
+/** Обидва рубежі межі даних плагіна разом — щоб їх не можна було забути. */
+async function guardedTable(
+  pluginName: string,
+  table: string,
+): Promise<string> {
+  const name = assertOwnTable(pluginName, table);
+  await assertKnownPlugin(pluginName);
+  return name;
+}
+
+async function run(db: ActorDb, query: SQL): Promise<PluginRow[]> {
+  const result = await db.execute(query);
+  return result.rows as PluginRow[];
+}
+
+function one(rows: PluginRow[], operation: string): PluginRow {
+  const [row] = rows;
+  if (!row) {
+    throw new Error(`[plugin-sdk] ${operation}: порожня відповідь`);
+  }
+  return row;
+}

package/src/plugin-sdk/types.ts

@@ -0,0 +1,70 @@
+import type { ComponentType } from 'react';
+import type { ZodObject, ZodRawShape } from 'zod';
+import type { Locale } from 'simplycms/i18n';
+import type {
+  HookHandler,
+  PluginManifest,
+  PluginModule,
+} from 'simplycms/plugins/types';
+
+/**
+ * Компонент слота. `context` — те, що передав `<PluginSlot context={…}>`
+ * у точці розширення (наприклад, товар у `product.detail.after`); форма
+ * контексту — контракт конкретного слота, SDK її не типізує.
+ */
+export type SlotComponent = ComponentType<{ context?: unknown }>;
+
+/**
+ * Каталог повідомлень плагіна — дзеркало `ThemeModule.messages` (контракт
+ * тем v2.1). Ключі зобовʼязані мати префікс `plugin.<name>.` — колізії з
+ * замкненим `MessageKey` ядра і між плагінами виключаються неймспейсом.
+ */
+export type PluginMessages = Partial<Record<Locale, Record<string, string>>>;
+
+/**
+ * Декларативний контракт плагіна (спека §7, обсяг v1 — план Фази 3).
+ *
+ * Межі v1, зафіксовані планом: `hooks` реєструються в той самий
+ * `HookRegistry`, що й слоти, але ядро НЕ емить бізнес-подій
+ * (`order.created` тощо) — робочі точки розширення сьогодні лише слоти;
+ * `adminRoutes`/`migrations`/`edgeFunctions`/`buckets` — декларації для
+ * CLI й людини, рантайм їх не інтерпретує.
+ */
+export interface PluginDefinition {
+  /** Машинне імʼя: `[a-z][a-z0-9-]*`. Ключ у БД, префікс таблиць і ключів i18n. */
+  name: string;
+  displayName: string;
+  version: string;
+  /** Діапазон сумісності з ядром; перевіряється `satisfies` (warn-режим на 0.x). */
+  engines: { simplycms: string };
+  /** Метадані реєстру/маркетплейсу — англійською (показуються з БД-рядка, не з каталогу). */
+  description?: string;
+  author?: string;
+  /** Zod-схема налаштувань; форму рендерить адмінка (`z.toJSONSchema`). */
+  settings?: ZodObject<ZodRawShape>;
+  /** Слот → компонент. Реєструється як хендлер, що рендерить компонент. */
+  slots?: Record<string, SlotComponent>;
+  /** Хук → обробник. Виконується там, де ядро кличе `execute` (зараз — лише PluginSlot). */
+  hooks?: Record<string, HookHandler>;
+  messages?: PluginMessages;
+  /** Тека роутів адмінки відносно кореня пакета (конвенція: './routes'). */
+  adminRoutes?: string;
+  /** Імена SQL-файлів у `migrations/` пакета (конвенція: `<ts>_plg_<name>_<slug>.sql`). */
+  migrations?: string[];
+  /** Декларація Edge Functions — без автоматизації у v1 (спека §9). */
+  edgeFunctions?: string[];
+  /** Декларація storage-бакетів — без автоматизації у v1 (спека §9). */
+  buckets?: string[];
+}
+
+/**
+ * Результат `definePlugin`: структурно задовольняє чинний `PluginModule`
+ * (`register`/`unregister` згенеровані з декларацій), тож
+ * `bootstrapPlugins`/`PluginLoader` працюють без змін контракту.
+ */
+export interface SdkPluginModule extends PluginModule {
+  manifest: PluginManifest;
+  definition: PluginDefinition;
+  /** Дублює `definition.messages` на верхньому рівні — симетрія з `ThemeModule.messages`. */
+  messages?: PluginMessages;
+}

package/src/plugin-sdk/usePluginConfig.ts

@@ -0,0 +1,105 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import type { z, ZodObject, ZodRawShape } from 'zod';
+import type { JsonValue } from 'simplycms/storefront/loaders';
+import {
+  pluginConfigRead,
+  pluginConfigWrite,
+} from 'simplycms/plugin-sdk/server';
+
+/**
+ * Читання й запис ВЛАСНОГО конфіга плагіна (рядок `plugins.config`) —
+ * замикає цикл налаштувань: автор декларує Zod-схему в `definePlugin`,
+ * адмінка редагує форму, плагін читає значення цим хуком.
+ *
+ * Схема тут — і валідація, і джерело дефолтів: порожній/битий config
+ * парситься через `schema.safeParse`, тож поля з `.default()` завжди
+ * матеріалізовані. Битий config → дефолти + console.warn, не падіння.
+ *
+ * 🔴 Транспорт — serverFn (рішення B9): браузер до БД не звертається. Запис
+ * дозволений лише адміну, і перевіряє це СЕРВЕР — `save` віддає `false`,
+ * коли права немає.
+ */
+
+export interface PluginConfigResult<S extends ZodObject<ZodRawShape>> {
+  /** Розпарсений конфіг із матеріалізованими дефолтами; `null` — ще вантажиться. */
+  config: z.output<S> | null;
+  loading: boolean;
+  /** Зберегти конфіг (лише адмін). `false` — сервер відмовив у праві. */
+  save: (next: z.input<S>) => Promise<boolean>;
+}
+
+export function usePluginConfig<S extends ZodObject<ZodRawShape>>(
+  pluginName: string,
+  schema: S,
+): PluginConfigResult<S> {
+  const [raw, setRaw] = useState<unknown>(undefined);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        const result = await pluginConfigRead({ data: { plugin: pluginName } });
+        if (cancelled) return;
+        if (!result.found) {
+          // Рядка немає — типово розсинхрон ключа конфігу з manifest.name
+          // (хук читає за manifest-імʼям, а рядок створює bootstrap за
+          // ключем конфігу). Мовчати не можна: адмінка «успішно» зберігала б
+          // налаштування, які плагін ніколи не побачить.
+          console.warn(
+            `[plugin-sdk] usePluginConfig("${pluginName}"): рядка plugins із таким name немає — віддаю дефолти схеми`,
+          );
+        }
+        setRaw(result.config ?? {});
+      } catch (error) {
+        if (cancelled) return;
+        console.warn(`[plugin-sdk] usePluginConfig("${pluginName}"):`, error);
+        setRaw({});
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [pluginName]);
+
+  const config = useMemo(() => {
+    if (loading) return null;
+    const parsed = schema.safeParse(raw ?? {});
+    if (parsed.success) return parsed.data;
+    console.warn(
+      `[plugin-sdk] usePluginConfig("${pluginName}"): config не пройшов схему — дефолти`,
+    );
+    const fallback = schema.safeParse({});
+    return fallback.success ? fallback.data : null;
+  }, [loading, raw, schema, pluginName]);
+
+  const save = useCallback(
+    async (next: z.input<S>): Promise<boolean> => {
+      // Валідуємо ДО запиту: битий конфіг не має шансу лягти в БД навіть у
+      // адміна — саме схема плагіна тут єдиний опис форми значення.
+      const parsed = schema.safeParse(next);
+      if (!parsed.success) {
+        console.warn(
+          `[plugin-sdk] usePluginConfig("${pluginName}"): save відхилено схемою`,
+        );
+        return false;
+      }
+
+      const written = await pluginConfigWrite({
+        data: {
+          plugin: pluginName,
+          // Значення вже пройшло схему плагіна — далі його форму описує
+          // тільки JSON, бо саме ним воно їде на сервер.
+          config: parsed.data as Record<string, JsonValue>,
+        },
+      });
+      if (written) setRaw(parsed.data);
+      return written;
+    },
+    [pluginName, schema],
+  );
+
+  return { config, loading, save };
+}

package/src/plugin-sdk/usePluginT.ts

@@ -0,0 +1,33 @@
+import { useCallback } from 'react';
+import { interpolate, useLocale, type MessageParams } from 'simplycms/i18n';
+import type { PluginMessages } from './types';
+
+/**
+ * Транслятор каталогу ПЛАГІНА (не ядра) — двійник `useThemeT`.
+ *
+ * Ланцюжок fallback — `messages[locale][key] → messages.uk[key] → сам key`;
+ * підстановка `{param}` — та сама `interpolate` з `simplycms/i18n`.
+ *
+ * Каталог передається АРГУМЕНТОМ (компонент плагіна імпортує власний
+ * `messages.ts`), а не читається з реєстру плагінів: реєстр наповнюється в
+ * клієнтському `useEffect` (`bootstrapPlugins`), і читання з нього на SSR
+ * віддало б сирі ключі — рівно гідраційна пастка, задокументована в
+ * `useThemeT.ts`. Статичний імпорт каталогу SSR-стабільний за побудовою.
+ *
+ * Generic `K` — локальний union плагіна
+ * (`export type FaqKey = keyof typeof messages.uk` у `messages.ts` плагіна),
+ * НЕ `MessageKey` ядра: SDK про ключі конкретного плагіна нічого не знає.
+ */
+export function usePluginT<K extends string = string>(
+  messages: PluginMessages | undefined,
+): (key: K, params?: MessageParams) => string {
+  const locale = useLocale();
+
+  return useCallback(
+    (key: K, params?: MessageParams): string => {
+      const template = messages?.[locale]?.[key] ?? messages?.uk?.[key] ?? key;
+      return interpolate(template, params);
+    },
+    [messages, locale],
+  );
+}

package/src/plugin-sdk/usePluginTable.ts

@@ -0,0 +1,90 @@
+import { useMemo } from 'react';
+import {
+  pluginTableInsert,
+  pluginTableList,
+  pluginTableRemove,
+  pluginTableUpdate,
+} from 'simplycms/plugin-sdk/server';
+
+/**
+ * Порт даних плагіна: вузький CRUD-фасад над ВЛАСНИМИ таблицями
+ * (`plg_<name>_*`, спека §7/§9, рішення B9).
+ *
+ * Це і є межа довіри в дії: плагін не імпортує ні Supabase, ні `simplycms/db`
+ * (dependency-lint це забороняє) — він називає таблицю й фільтри, а транспорт
+ * лишається справою ядра. Форма порту НЕ дзеркалить жодного бекенда: у v1 під
+ * ним був PostgREST, зараз — serverFn поверх Postgres, і жоден плагін від цієї
+ * заміни не змінився.
+ *
+ * 🔴 Імʼя плагіна — ОБОВʼЯЗКОВИЙ перший аргумент, і не для зручності:
+ * без нього сервер не може відрізнити «власну» таблицю від сусідньої. Гард
+ * `plg_`-префікса в браузері нічого не вартий — рішення ухвалює хендлер
+ * (`plugin-sdk/server/guard.ts`).
+ *
+ * Типи рядків — generic-параметр викликача: таблиці плагіна свідомо НЕ
+ * входять у схему ядра, тож узгодженість типу з реальною схемою —
+ * відповідальність автора плагіна.
+ */
+
+/** Скаляр, який порт погоджується покласти в колонку. */
+type Cell = string | number | boolean | null;
+
+export interface PluginTablePort<Row extends Record<string, unknown>> {
+  list(options?: {
+    orderBy?: string;
+    ascending?: boolean;
+    eq?: Partial<Row>;
+  }): Promise<Row[]>;
+  insert(row: Partial<Row>): Promise<Row>;
+  update(id: string, patch: Partial<Row>): Promise<Row>;
+  remove(id: string): Promise<void>;
+}
+
+/** Звузити довільний обʼєкт рядка до скалярів, які приймає транспорт. */
+function toCells(row: Record<string, unknown>): Record<string, Cell> {
+  return Object.fromEntries(
+    Object.entries(row).map(([column, value]) => [
+      column,
+      (value ?? null) as Cell,
+    ]),
+  );
+}
+
+/** CRUD-порт до однієї таблиці плагіна. */
+export function usePluginTable<Row extends Record<string, unknown>>(
+  pluginName: string,
+  table: string,
+): PluginTablePort<Row> {
+  return useMemo<PluginTablePort<Row>>(
+    () => ({
+      async list(options) {
+        const rows = await pluginTableList({
+          data: {
+            plugin: pluginName,
+            table,
+            eq: options?.eq ? toCells(options.eq) : undefined,
+            orderBy: options?.orderBy,
+            ascending: options?.ascending,
+          },
+        });
+        return rows as Row[];
+      },
+      async insert(row) {
+        const created = await pluginTableInsert({
+          data: { plugin: pluginName, table, row: toCells(row) },
+        });
+        return created as Row;
+      },
+      async update(id, patch) {
+        const updated = await pluginTableUpdate({
+          data: { plugin: pluginName, table, id, patch: toCells(patch) },
+        });
+        return updated as Row;
+      },
+      async remove(id) {
+        await pluginTableRemove({ data: { plugin: pluginName, table, id } });
+      },
+    }),
+    [pluginName, table],
+  );
+}

package/src/plugins/HookRegistry.ts

@@ -0,0 +1,125 @@
+import type {
+  HookHandler,
+  HookRegistryInterface,
+  RegisteredHook,
+} from './types';
+
+class HookRegistry implements HookRegistryInterface {
+  private hooks: Map<string, RegisteredHook[]> = new Map();
+  private listeners: Set<() => void> = new Set();
+  private version = 0;
+
+  /**
+   * Підписка на зміни реєстру (джерело для `useSyncExternalStore`).
+   * Стрілкові властивості, а не методи класу: React вимагає СТАБІЛЬНІ
+   * референції `subscribe`/`getSnapshot` між рендерами.
+   */
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  /**
+   * Синхронний снапшот — монотонна версія реєстру (число, стабільне за
+   * значенням). Повертати сам вміст хуків не можна: `getHandlers` віддає новий
+   * масив на кожен виклик, і React зациклив би рендери.
+   */
+  getVersion = (): number => this.version;
+
+  /** Нотифікація підписників: версія росте на будь-якій мутації реєстру. */
+  private notify(): void {
+    this.version += 1;
+    for (const listener of this.listeners) listener();
+  }
+
+  register<TContext = unknown, TResult = unknown>(
+    hookName: string,
+    pluginName: string,
+    handler: HookHandler<TContext, TResult>,
+    priority: number = 10,
+  ): void {
+    const existing = this.hooks.get(hookName) || [];
+
+    // Remove any existing handler from the same plugin
+    const filtered = existing.filter((h) => h.pluginName !== pluginName);
+
+    filtered.push({
+      pluginName,
+      handler: handler as HookHandler,
+      priority,
+    });
+
+    // Sort by priority (lower = earlier)
+    filtered.sort((a, b) => a.priority - b.priority);
+
+    this.hooks.set(hookName, filtered);
+    this.notify();
+  }
+
+  unregister(hookName: string, pluginName: string): void {
+    const existing = this.hooks.get(hookName);
+    if (!existing) return;
+
+    const filtered = existing.filter((h) => h.pluginName !== pluginName);
+    if (filtered.length === existing.length) return;
+
+    if (filtered.length === 0) {
+      this.hooks.delete(hookName);
+    } else {
+      this.hooks.set(hookName, filtered);
+    }
+    this.notify();
+  }
+
+  async execute<TContext = unknown, TResult = unknown>(
+    hookName: string,
+    context: TContext,
+  ): Promise<TResult[]> {
+    const handlers = this.hooks.get(hookName) || [];
+    const results: TResult[] = [];
+
+    for (const { handler } of handlers) {
+      try {
+        const result = await handler(context);
+        if (result !== undefined && result !== null) {
+          results.push(result as TResult);
+        }
+      } catch (error) {
+        console.error(`Error executing hook "${hookName}" from plugin:`, error);
+      }
+    }
+
+    return results;
+  }
+
+  getHandlers<TContext = unknown, TResult = unknown>(
+    hookName: string,
+  ): RegisteredHook<TContext, TResult>[] {
+    return (this.hooks.get(hookName) || []) as RegisteredHook<
+      TContext,
+      TResult
+    >[];
+  }
+
+  getRegisteredHooks(): string[] {
+    return Array.from(this.hooks.keys());
+  }
+
+  getPluginsForHook(hookName: string): string[] {
+    const handlers = this.hooks.get(hookName) || [];
+    return handlers.map((h) => h.pluginName);
+  }
+
+  clear(): void {
+    if (this.hooks.size === 0) return;
+    this.hooks.clear();
+    this.notify();
+  }
+}
+
+// Singleton instance
+export const hookRegistry = new HookRegistry();
+
+export default HookRegistry;

package/src/plugins/PluginLoader.ts

@@ -0,0 +1,69 @@
+import { listActivePlugins } from 'simplycms/plugins/server';
+import { hookRegistry } from './HookRegistry';
+import type { Plugin, PluginModule } from './types';
+
+// Map of available plugins (populated by dynamic imports on bootstrap)
+const pluginModules: Map<string, PluginModule> = new Map();
+
+// Register a plugin module (called during app initialization)
+export function registerPluginModule(name: string, module: PluginModule): void {
+  pluginModules.set(name, module);
+}
+
+// Get all registered plugin modules
+export function getRegisteredPluginModules(): Map<string, PluginModule> {
+  return pluginModules;
+}
+
+/**
+ * Зняти всі хуки плагіна з реєстру. `getRegisteredHooks()` віддає снапшот імен,
+ * тому мутація реєстру під час обходу безпечна.
+ */
+export function removePluginHooks(pluginName: string): void {
+  for (const hookName of hookRegistry.getRegisteredHooks()) {
+    hookRegistry.unregister(hookName, pluginName);
+  }
+}
+
+/**
+ * Увімкнути в реєстрі хуки плагінів, позначених активними в БД.
+ *
+ * 🔴 Список приходить serverFn-ом (`simplycms/plugins/server`), а не запитом
+ * із браузера: у контурі v2 браузер до БД не звертається взагалі. Тут же й
+ * причина, чому модуль більше не приймає Supabase-клієнта.
+ *
+ * Активний у БД, але невідомий модуль (магазин видалив пакет, рядок лишився)
+ * не валить застосунок — помилка логується, плагін пропускається (спека §8).
+ */
+export async function loadPlugins(): Promise<Plugin[]> {
+  let plugins: Plugin[];
+  try {
+    plugins = await listActivePlugins();
+  } catch (error) {
+    console.error('Error loading plugins:', error);
+    return [];
+  }
+
+  const loadedPlugins: Plugin[] = [];
+
+  for (const plugin of plugins) {
+    const pluginModule = pluginModules.get(plugin.name);
+
+    if (!pluginModule) {
+      console.error(
+        `Plugin module "${plugin.name}" not found in registry — skipped`,
+      );
+      continue;
+    }
+
+    try {
+      pluginModule.register(hookRegistry);
+      loadedPlugins.push(plugin);
+    } catch (err) {
+      console.error(`Error loading plugin "${plugin.name}":`, err);
+      removePluginHooks(plugin.name);
+    }
+  }
+
+  return loadedPlugins;
+}