@reformer/builder 1.0.0-beta.1 → 2.0.0

package/README.md

@@ -19,6 +19,9 @@ npm i -D @reformer/builder
 npx reformer-builder            # поднимет локальный сервер и откроет браузер
 npx reformer-builder --port 5000
 npx reformer-builder --no-open  # не открывать браузер автоматически
+
+# локальная кастомизация клиента: свой каталог компонентов и/или конфиг билдера
+npx reformer-builder --catalog ./component-catalog.json --config ./reformer-builder.config.json
 ```
 
 Или добавьте скрипт в свой `package.json`:
@@ -37,13 +40,18 @@ npm run builder
 
 ### Опции CLI
 
-| Опция            | По умолчанию | Описание                                        |
-| ---------------- | ------------ | ----------------------------------------------- |
-| `-p, --port <n>` | `4321`       | Порт (если занят — берётся следующий свободный) |
-| `--host <h>`     | `127.0.0.1`  | Хост                                            |
-| `--no-open`      | —            | Не открывать браузер автоматически              |
-| `-h, --help`     | —            | Справка                                         |
-| `-v, --version`  | —            | Версия                                          |
+| Опция              | По умолчанию | Описание                                            |
+| ------------------ | ------------ | --------------------------------------------------- |
+| `-p, --port <n>`   | `4321`       | Порт (если занят — берётся следующий свободный)     |
+| `--host <h>`       | `127.0.0.1`  | Хост                                                |
+| `--no-open`        | —            | Не открывать браузер автоматически                  |
+| `--catalog <path>` | —            | JSON-каталог компонентов (замещает вшитый)          |
+| `--config <path>`  | —            | JSON-конфиг билдера (палитра, UI, брендинг, проект) |
+| `-h, --help`       | —            | Справка                                             |
+| `-v, --version`    | —            | Версия                                              |
+
+Без `--catalog`/`--config` билдер пытается подхватить `component-catalog.json` и
+`reformer-builder.config.json` из текущей папки; если их нет — работает на вшитых дефолтах.
 
 ## Режимы работы
 
@@ -63,7 +71,61 @@ npm run builder
 
 Каталог **вшивается в бандл на этапе сборки** билдера (Vite инлайнит импорт
 `@reformer/ui-kit/catalog`), поэтому опубликованный `@reformer/builder` самодостаточен и
-показывает набор компонентов той версии `@reformer/ui-kit`, с которой был собран.
+показывает набор компонентов той версии `@reformer/ui-kit`, с которой был собран. Этот вшитый
+каталог можно **переопределить при локальном старте** флагом `--catalog` (см. ниже) — без
+пересборки билдера.
+
+## Локальная кастомизация (`--catalog` / `--config`)
+
+Клиент может передать при локальном старте два JSON-файла — они читаются launcher'ом и
+применяются в браузере на бутстрапе. Оба **опциональны**: если файла нет — берутся встроенные
+дефолты (билдер стартует и работает как обычно). Если переданный файл невалиден — билдер
+показывает экран с ошибкой валидации (не запускается с частичной конфигурацией).
+
+- **`--catalog <path>`** — JSON-каталог компонентов по тому же контракту, что
+  `@reformer/ui-kit/catalog` (`{ version, components: [{ name, role, propsSchema, category? }] }`).
+  Замещает вшитый каталог: палитра и инспектор строятся из него.
+- **`--config <path>`** — конфиг поведения самого билдера. Все секции опциональны:
+
+```jsonc
+{
+  "$schema": "./node_modules/@reformer/builder/runtime-config.schema.json",
+  "version": "1.0",
+  // Брендинг оболочки
+  "branding": {
+    "productName": "Acme Forms",
+    "title": "Acme Builder",
+    "logoUrl": "data:image/svg+xml;...",
+  },
+  // Палитра: категории, порядок разделов, свёрнутые по умолчанию, глифы-бейджи
+  "palette": {
+    "categoryByName": { "AcmeRating": "Поля ввода" },
+    "order": ["Поля ввода", "Выбор и переключатели", "Контейнеры", "Действия"],
+    "collapsedByDefault": ["HTML", "Типографика"],
+    "glyphs": { "AcmeRating": "Ar" },
+  },
+  // Доступные компоненты: whitelist/blacklist + тоглы синтетических записей билдера
+  "components": {
+    "exclude": ["Chart", "Carousel"],
+    "synthetic": {
+      "html": true,
+      "htmlTags": ["div", "section", "fieldset"],
+      "formArray": true,
+      "wizard": false,
+    },
+  },
+  // Дефолты интерфейса при старте
+  "ui": { "theme": "light", "leftPanel": "palette", "rightOpen": true, "preview": "wire" },
+  // Работа с проектом (Mode B discovery) + стартовая схема Mode A (null — пустая форма)
+  "project": { "ignoreDirs": ["fixtures"], "seedSchema": null },
+}
+```
+
+Семантика слияния: карты (`palette.categoryByName`, `palette.glyphs`) и списки безопасных
+дефолтов (`project.ignoreDirs`, `project.skipFiles`, `project.formSchemaMarkers`) **дополняют**
+встроенные; `palette.order`, `palette.collapsedByDefault`, `components.*`, `ui.*`, `branding.*` —
+**замещают** дефолт, если заданы. JSON Schema контракта конфига публикуется в пакете как
+`@reformer/builder/runtime-config.schema.json` (для автодополнения в редакторе через `$schema`).
 
 > **Требование к упаковке `@reformer/ui-kit`:** чтобы subpath `@reformer/ui-kit/catalog`
 > резолвился у внешних потребителей, `component-catalog.json` обязан входить в поле `files`

package/bin/reformer-builder.d.mts

@@ -0,0 +1,36 @@
+/**
+ * Типы для тестируемых экспортов launcher'а (`reformer-builder.mjs` — zero-dependency JS без
+ * деклараций). Позволяет `.ts`-тестам импортировать хелперы без implicit-any (TS7016).
+ */
+
+export interface LauncherOpts {
+  port: number;
+  host: string;
+  open: boolean;
+  help: boolean;
+  version: boolean;
+  /** Путь к каталогу компонентов (`--catalog`) или `null` (авто-детект в cwd). */
+  catalog: string | null;
+  /** Путь к конфигу билдера (`--config`) или `null` (авто-детект в cwd). */
+  config: string | null;
+}
+
+export interface RuntimeBundleResult {
+  payload: { catalog: unknown; config: unknown };
+  sources: { catalog: string | null; config: string | null };
+}
+
+/** URL раздачи клиентского bundle. */
+export const RUNTIME_BUNDLE_URL: string;
+
+export function parseArgs(argv: string[]): LauncherOpts;
+
+export function loadRuntimeBundle(
+  opts: { catalog: string | null; config: string | null },
+  cwd: string
+): Promise<RuntimeBundleResult>;
+
+export function createRequestHandler(
+  indexHtmlPath: string,
+  runtimeBundleBody: Buffer
+): (req: unknown, res: unknown) => Promise<void>;

package/bin/reformer-builder.mjs

@@ -7,15 +7,27 @@
  * поднимает `dist/` на localhost и открывает браузер. Серверной логики у билдера нет — вся работа с
  * файлами проекта идёт в браузере через File System Access API (нужен Chromium-браузер).
  *
+ * Клиент может передать 2 JSON-файла для локальной кастомизации: каталог компонентов (--catalog)
+ * и конфиг билдера (--config). Launcher читает их с диска и отдаёт SPA по /__reformer-builder/
+ * runtime.json; без флагов пытается авто-подхватить одноимённые файлы из cwd. Отсутствие файлов —
+ * билдер работает на вшитых дефолтах.
+ *
  * Использование:
- *   npx reformer-builder [--port <n>] [--host <h>] [--no-open]
+ *   npx reformer-builder [--port <n>] [--host <h>] [--no-open] [--catalog <path>] [--config <path>]
  */
 
 import { createServer } from 'node:http';
 import { readFile, stat } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { extname, join, normalize, sep } from 'node:path';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+
+/** URL, по которому SPA забирает клиентский bundle (совпадает с RUNTIME_BUNDLE_PATH в src/config/load). */
+export const RUNTIME_BUNDLE_URL = '/__reformer-builder/runtime.json';
+
+/** Имена файлов для авто-детекта в cwd, если флаги `--catalog`/`--config` не заданы. */
+const DEFAULT_CATALOG_FILE = 'component-catalog.json';
+const DEFAULT_CONFIG_FILE = 'reformer-builder.config.json';
 
 // Без хвостового разделителя: иначе `distDir + sep` даёт двойной слэш и проверка
 // границы каталога в resolveFsPath() никогда не совпадает (все запросы → 400).
@@ -51,8 +63,64 @@ async function readVersion() {
   }
 }
 
-function parseArgs(argv) {
-  const opts = { port: 4321, host: '127.0.0.1', open: true, help: false, version: false };
+/**
+ * Прочитать и распарсить клиентский JSON-файл. Явно переданный (`--catalog`/`--config`) файл
+ * обязателен — при ошибке чтения/парсинга завершаемся с сообщением. Авто-детект: отсутствие файла
+ * (ENOENT) — тихий пропуск (fallback на вшитые дефолты); присутствует, но битый JSON — ошибка
+ * (файл явно предназначен к использованию).
+ */
+async function readRuntimeFile(path, { explicit, label }) {
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch (err) {
+    if (explicit) {
+      console.error(`reformer-builder: не удалось прочитать ${label} "${path}": ${err.message}`);
+      process.exit(1);
+    }
+    return null; // авто-детект: файла нет — работаем на вшитых дефолтах
+  }
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    console.error(`reformer-builder: невалидный JSON в ${label} "${path}": ${err.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Собрать runtime-bundle для SPA из файлов клиента. Пути берутся из флагов, иначе — авто-детект
+ * одноимённых файлов в cwd. Структурную валидацию делает SPA (реюз validateCatalog + AJV конфига);
+ * здесь ловим только отсутствие/JSON-синтаксис.
+ */
+export async function loadRuntimeBundle(opts, cwd) {
+  const catalogPath = resolve(cwd, opts.catalog ?? DEFAULT_CATALOG_FILE);
+  const configPath = resolve(cwd, opts.config ?? DEFAULT_CONFIG_FILE);
+  const catalog = await readRuntimeFile(catalogPath, {
+    explicit: Boolean(opts.catalog),
+    label: 'каталог (--catalog)',
+  });
+  const config = await readRuntimeFile(configPath, {
+    explicit: Boolean(opts.config),
+    label: 'конфиг (--config)',
+  });
+  return {
+    payload: { catalog: catalog ?? null, config: config ?? null },
+    sources: { catalog: catalog ? catalogPath : null, config: config ? configPath : null },
+  };
+}
+
+export function parseArgs(argv) {
+  const opts = {
+    port: 4321,
+    host: '127.0.0.1',
+    open: true,
+    help: false,
+    version: false,
+    // Явно переданные клиентом пути (null — не задан, будет авто-детект в cwd).
+    catalog: null,
+    config: null,
+  };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--help' || a === '-h') opts.help = true;
@@ -63,6 +131,10 @@ function parseArgs(argv) {
     else if (a.startsWith('--port=')) opts.port = Number(a.slice('--port='.length));
     else if (a === '--host') opts.host = String(argv[++i]);
     else if (a.startsWith('--host=')) opts.host = a.slice('--host='.length);
+    else if (a === '--catalog') opts.catalog = String(argv[++i]);
+    else if (a.startsWith('--catalog=')) opts.catalog = a.slice('--catalog='.length);
+    else if (a === '--config') opts.config = String(argv[++i]);
+    else if (a.startsWith('--config=')) opts.config = a.slice('--config='.length);
     else {
       console.error(`reformer-builder: неизвестный аргумент "${a}" (см. --help)`);
       process.exit(1);
@@ -82,11 +154,16 @@ function printHelp() {
   npx reformer-builder [опции]
 
 Опции:
-  -p, --port <n>    Порт (по умолчанию 4321; занят — берётся следующий свободный)
-      --host <h>    Хост (по умолчанию 127.0.0.1)
-      --no-open     Не открывать браузер автоматически
-  -h, --help        Показать эту справку
-  -v, --version     Показать версию
+  -p, --port <n>       Порт (по умолчанию 4321; занят — берётся следующий свободный)
+      --host <h>       Хост (по умолчанию 127.0.0.1)
+      --no-open        Не открывать браузер автоматически
+      --catalog <path> Каталог компонентов (JSON) для палитры/инспектора
+      --config <path>  Конфиг билдера (JSON): палитра, доступные компоненты, дефолты UI, брендинг
+  -h, --help           Показать эту справку
+  -v, --version        Показать версию
+
+Без --catalog/--config билдер пытается подхватить component-catalog.json и
+reformer-builder.config.json из текущей папки; если их нет — работает на вшитых дефолтах.
 
 Примечание: режим «открыть папку проекта» (File System Access API) работает только в
 Chromium-браузерах (Chrome/Edge/Arc/Brave).`);
@@ -142,7 +219,7 @@ async function sendFile(res, filePath, statusCode = 200) {
   res.end(body);
 }
 
-function createRequestHandler(indexHtmlPath) {
+export function createRequestHandler(indexHtmlPath, runtimeBundleBody) {
   return async (req, res) => {
     if (req.method !== 'GET' && req.method !== 'HEAD') {
       res.writeHead(405, { Allow: 'GET, HEAD' });
@@ -150,6 +227,16 @@ function createRequestHandler(indexHtmlPath) {
       return;
     }
     const pathname = (req.url || '/').split('?')[0].split('#')[0];
+    // Клиентский runtime-bundle (каталог/конфиг из файлов) — отдаём ДО резолва static/dist.
+    if (pathname === RUNTIME_BUNDLE_URL) {
+      res.writeHead(200, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Content-Length': runtimeBundleBody.length,
+        'Cache-Control': 'no-cache',
+      });
+      res.end(req.method === 'HEAD' ? undefined : runtimeBundleBody);
+      return;
+    }
     const target = resolveFsPath(pathname === '/' ? '/index.html' : pathname);
     if (target === null) {
       res.writeHead(400);
@@ -233,7 +320,12 @@ async function main() {
     process.exit(1);
   }
 
-  const server = createServer(createRequestHandler(indexHtmlPath));
+  // Клиентский конфиг/каталог из файлов (флаги или авто-детект в cwd). Отдаётся SPA по
+  // RUNTIME_BUNDLE_URL; отсутствие файлов ⇒ пустой bundle ⇒ билдер на вшитых дефолтах.
+  const runtime = await loadRuntimeBundle(opts, process.cwd());
+  const runtimeBundleBody = Buffer.from(JSON.stringify(runtime.payload));
+
+  const server = createServer(createRequestHandler(indexHtmlPath, runtimeBundleBody));
   let port;
   try {
     port = await listenWithFallback(server, opts.host, opts.port);
@@ -246,6 +338,8 @@ async function main() {
   const url = `http://${displayHost}:${port}/`;
   console.log(`\n  reformer-builder v${await readVersion()}`);
   console.log(`  Локальный сервер:  ${url}`);
+  if (runtime.sources.catalog) console.log(`  Каталог из файла:  ${runtime.sources.catalog}`);
+  if (runtime.sources.config) console.log(`  Конфиг из файла:   ${runtime.sources.config}`);
   console.log(`  Режим «открыть папку проекта» требует Chromium-браузер (File System Access API).`);
   console.log(`  Остановить: Ctrl+C\n`);
 
@@ -260,7 +354,10 @@ async function main() {
   process.on('SIGTERM', shutdown);
 }
 
-main().catch((err) => {
-  console.error(`reformer-builder: ${err?.stack || err}`);
-  process.exit(1);
-});
+// Не запускаем сервер при импорте из тестов (юнит-тесты дёргают экспортированные хелперы).
+if (process.env.REFORMER_BUILDER_TEST !== '1') {
+  main().catch((err) => {
+    console.error(`reformer-builder: ${err?.stack || err}`);
+    process.exit(1);
+  });
+}