@foxford/den 3.1.0 → 3.1.2

package/README.mdx

@@ -80,7 +80,7 @@ routes: [
 ```ts
 import { renderApp } from '@foxford/den/island'
 
-const { status, html, state, head, headHtml, redirect } = await renderApp(app, {
+const { status, html, state, head, headHtml, redirect, assets } = await renderApp(app, {
   pathname: '/legal/general',
   search: '?from=footer',
   context: { cookies, headers }, // реквизиты браузерного запроса
@@ -89,7 +89,9 @@ const { status, html, state, head, headHtml, redirect } = await renderApp(app, {
 
 `status` — исход запроса: `200` значит «вот страница», всё остальное значит, что страницы по
 этому адресу нет, и тело такого ответа выбирает хост. `state` едет в документ и гидрирует
-остров в браузере, `headHtml` — стили, собранные во время рендера.
+остров в браузере, `headHtml` — стили, собранные во время рендера. `assets` — ссылки на
+initial-чанки клиентской сборки, их подключает хост; байты приложение не отдаёт ни в одном
+транспорте.
 
 ### Вклад в документ
 
@@ -126,17 +128,19 @@ export class ContentPageVM extends ViewModel<State> {
 ## Сетевой транспорт: то же самое по HTTP
 
 Приложение поднимается отдельным сервисом **без единой строки своего серверного кода** —
-дескриптор тот же, что и в процессе хоста.
+дескриптор тот же, что и в процессе хоста. Точку входа процесса выпускает `den build`
+(см. «Сборка приложения»), поэтому прод это голая нода:
 
 ```jsonc
 // package.json приложения
 "scripts": {
-  "dev": "tsup --watch src --onSuccess \"den-serve build/index.js\"",
-  "start": "den-serve build/index.js --port 3342"
+  "dev": "den dev",
+  "build": "den build",
+  "start": "node build/server.mjs"
 }
 ```
 
-`den-serve <модуль>` берёт дефолтный экспорт указанного модуля и поднимает вокруг него рантайм:
+Рантайм вокруг дескриптора отдаёт три ручки:
 
 | Ручка | Ответ |
 | --- | --- |
@@ -184,14 +188,9 @@ export default (instance) => {
 }
 ```
 
-```jsonc
-// package.json приложения — своего серверного кода по-прежнему ноль
-"scripts": {
-  "start": "den-serve build/index.js --configure ./configure.js --port 3342"
-},
-```
-
-Запуск с инструментацией: `NODE_OPTIONS='--import ./instrument.js' pnpm start`.
+Такое расширение объявляется в конфиге приложения полем `server.configure` — своего серверного
+кода по-прежнему ноль. Запуск с инструментацией:
+`NODE_OPTIONS='--import ./instrument.js' pnpm start`.
 
 Если сервер нужен свой — общий порт с чужими ручками, свой порядок плагинов, — берите плагин
 и монтируйте куда угодно, хоть под префиксом:
@@ -211,6 +210,56 @@ await instance.listen({ port: 3342 })
 `serveApp` поверх плагина добавляет логирование запросов (в терминах `@foxford/logger`, корень —
 имя приложения, рендер дольше порога уходит в `warn`) и закрытие по `SIGTERM`/`SIGINT`.
 
+## Сборка приложения: `den build`
+
+Приложение объявляет дескриптор и `den.config.ts`. Конфиг сборщика, вход гидрации и точку входа
+процесса писать не нужно — их собирает команда.
+
+```ts
+// den.config.ts
+import { defineAppConfig } from '@foxford/den/build'
+import { react } from '@foxford/den-react/preset'
+
+export default defineAppConfig({
+  preset: react({ babel: { plugins: [['babel-plugin-styled-components', { ssr: true }]] } }),
+  server: {
+    setup: () => installServerDom(),
+    render: (tree, render) => ({ head: sheet.getStyleTags(), html: render(sheet.collectStyles(tree)) }),
+    container: (c) => c.bind(HttpConfigToken).toValue({ baseUrl: process.env.API_ORIGIN }),
+    configure: (instance) => Sentry.setupFastifyErrorHandler(instance),
+    noExternal: ['@foxford/ui', 'styled-components'],
+  },
+})
+```
+
+`den build [--root <каталог>] [--base <префикс>]` выпускает три выхода, `den dev` — то же плюс
+подъём процесса и пересборка на изменение исходников:
+
+| Выход | Что внутри | Кто потребляет |
+| --- | --- | --- |
+| `build/client` | браузерный бандл и манифест | браузер, по ссылкам из ответа рендера |
+| `build/server` | дескриптор с вплавленными серверными кусками конфига | хост, импортом в своём процессе |
+| `build/server.mjs` | тот же дескриптор под сетевым рантаймом | `node build/server.mjs` |
+
+**Про фреймворк команда не знает.** Чем собирать и чем оживлять, приносит пресет из пакета
+адаптера, поэтому приложение на другом фреймворке подключается своим пресетом и в командах не
+меняется ничего.
+
+**Конфиг — вход СБОРКИ, а не рантайм-сосед дескриптора.** Серверные куски вплавляются в
+серверный выход, и дескриптор остаётся декларацией — иначе он не годился бы входом клиентской
+сборки: сборщик не выкинет сбор стилей, пока объект дескриптора на него ссылается. Соседом
+конфиг быть не может: приложение в процессе хоста импортируется хостом целиком, конфига у хоста
+нет, и до движка серверные куски не доехали бы.
+
+**Движок в серверный выход не вбандливается.** У него модульное состояние, app-контейнер —
+синглтон, и своя копия внутри приложения даёт второй контейнер: приложение биндит в один,
+а резолвит из другого. Симптом — «view-слой не объявлен» на приложении, которое его объявило.
+Клиентский выход наоборот собирается целиком: браузер голых имён модулей не резолвит.
+
+**Настройку процесса дожидается движок.** `server.setup` зовётся один раз на процесс до первого
+рендера, включая приложение в процессе хоста, где обвязки нет и дождаться было бы некому.
+Упавшая настройка не повторяется: процесс сломан, и прятать это за случайным успехом нельзя.
+
 ## Подпути
 
 | Подпуть | Что там |
@@ -219,4 +268,6 @@ await instance.listen({ port: 3342 })
 | `@foxford/den/define` | те же `define*` без сайд-эффекта установки резолвера |
 | `@foxford/den/adapter` | шов резолва для адаптеров хостов |
 | `@foxford/den/island` | остров: жизненный цикл, шов `renderApp`, порт `ViewAdapter` |
-| `@foxford/den/serve` | сетевой транспорт: `serveApp`, `appPlugin`, команда `den-serve` |
+| `@foxford/den/serve` | сетевой транспорт: `serveApp`, `appPlugin` |
+| `@foxford/den/build` | конфиг приложения и сборка: `defineAppConfig`, `buildApp` |
+| `@foxford/den/bin` | точка входа команды `den` |

package/adapter.cjs

@@ -2,7 +2,7 @@
 
 
 var _chunkC7BM4DGXcjs = require('./chunk-C7BM4DGX.cjs');
-require('./chunk-XHYR3SGG.cjs');
+require('./chunk-T5QVCXVB.cjs');
 
 
 

package/adapter.d.cts

@@ -1,4 +1,4 @@
-export { R as RequestContext } from './types-COwVwgzE.cjs';
+export { R as RequestContext } from './types-Dx5qGiwk.cjs';
 import { Token } from '@foxford/ioc';
 
 /**

package/adapter.d.ts

@@ -1,4 +1,4 @@
-export { R as RequestContext } from './types-COwVwgzE.js';
+export { R as RequestContext } from './types-Dx5qGiwk.js';
 import { Token } from '@foxford/ioc';
 
 /**

package/adapter.js

@@ -2,7 +2,7 @@ import {
   installResolver,
   resolveDefinition
 } from "./chunk-WBHHHICS.js";
-import "./chunk-HJO26HIQ.js";
+import "./chunk-6FNC3XMI.js";
 export {
   installResolver,
   resolveDefinition

package/bin/den.cjs

@@ -0,0 +1,88 @@
+"use strict";
+
+
+var _chunkLW7IN57Fcjs = require('../chunk-LW7IN57F.cjs');
+require('../chunk-A6ZPAM6Z.cjs');
+
+
+var _chunkT5QVCXVBcjs = require('../chunk-T5QVCXVB.cjs');
+
+// src/bin/cli.ts
+var USAGE = `den <\u043A\u043E\u043C\u0430\u043D\u0434\u0430> [\u043E\u043F\u0446\u0438\u0438]
+
+\u041A\u043E\u043C\u0430\u043D\u0434\u044B:
+  build                 \u0441\u043E\u0431\u0440\u0430\u0442\u044C \u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u0435: \u043A\u043B\u0438\u0435\u043D\u0442\u0441\u043A\u0438\u0439 \u0432\u044B\u0445\u043E\u0434, \u0441\u0435\u0440\u0432\u0435\u0440\u043D\u044B\u0439 \u0434\u0435\u0441\u043A\u0440\u0438\u043F\u0442\u043E\u0440 \u0438 \u0442\u043E\u0447\u043A\u0443
+                        \u0432\u0445\u043E\u0434\u0430 \u043F\u0440\u043E\u0446\u0435\u0441\u0441\u0430 (build/client, build/server, build/server.mjs)
+  dev                   \u0442\u043E \u0436\u0435 \u043F\u043B\u044E\u0441 \u043F\u043E\u0434\u044A\u0451\u043C \u043F\u0440\u043E\u0446\u0435\u0441\u0441\u0430 \u0438 \u043F\u0435\u0440\u0435\u0441\u0431\u043E\u0440\u043A\u0430 \u043D\u0430 \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u0435 \u0438\u0441\u0445\u043E\u0434\u043D\u0438\u043A\u043E\u0432
+
+\u041E\u043F\u0446\u0438\u0438:
+  --root <\u043A\u0430\u0442\u0430\u043B\u043E\u0433>      \u043A\u043E\u0440\u0435\u043D\u044C \u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u044F (\u043F\u043E \u0443\u043C\u043E\u043B\u0447\u0430\u043D\u0438\u044E \u0442\u0435\u043A\u0443\u0449\u0438\u0439 \u043A\u0430\u0442\u0430\u043B\u043E\u0433)
+  --base <\u043F\u0440\u0435\u0444\u0438\u043A\u0441>      \u043F\u0440\u0435\u0444\u0438\u043A\u0441 \u0430\u0434\u0440\u0435\u0441\u043E\u0432 \u0430\u0440\u0442\u0435\u0444\u0430\u043A\u0442\u043E\u0432: \u0432 \u043F\u0440\u043E\u0434\u0435 CDN, \u0432 \u0440\u0430\u0437\u0440\u0430\u0431\u043E\u0442\u043A\u0435 \u0440\u0430\u0437\u0432\u044F\u0437\u043A\u0430
+                        \u0443 \u0445\u043E\u0441\u0442\u0430 (\u043F\u043E \u0443\u043C\u043E\u043B\u0447\u0430\u043D\u0438\u044E /)
+  -h, --help            \u044D\u0442\u0430 \u0441\u043F\u0440\u0430\u0432\u043A\u0430
+`;
+function parseArgs(argv) {
+  const options = {};
+  let command;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      return { help: true, options: {} };
+    }
+    if (arg === "--root" || arg === "--base") {
+      i += 1;
+      options[arg.slice(2)] = argv[i];
+      continue;
+    }
+    if ((arg == null ? void 0 : arg.startsWith("-")) === true) {
+      throw new Error(`\u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u0430\u044F \u043E\u043F\u0446\u0438\u044F ${arg}`);
+    }
+    if (command !== void 0) {
+      throw new Error("\u043A\u043E\u043C\u0430\u043D\u0434\u0430 \u0443\u043A\u0430\u0437\u044B\u0432\u0430\u0435\u0442\u0441\u044F \u043E\u0434\u043D\u0430");
+    }
+    command = arg;
+  }
+  return { command, options };
+}
+function fail(message) {
+  process.stderr.write(`den: ${message}
+
+${USAGE}`);
+  process.exit(1);
+}
+function run(argv) {
+  return _chunkT5QVCXVBcjs.__async.call(void 0, this, null, function* () {
+    var _a;
+    let parsed;
+    try {
+      parsed = parseArgs(argv);
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    }
+    if (parsed.help === true) {
+      process.stdout.write(USAGE);
+      return;
+    }
+    const { command, options } = parsed;
+    if (command === void 0) {
+      fail("\u043D\u0435 \u0443\u043A\u0430\u0437\u0430\u043D\u0430 \u043A\u043E\u043C\u0430\u043D\u0434\u0430");
+    }
+    const target = { base: options["base"], root: (_a = options["root"]) != null ? _a : process.cwd() };
+    if (command === "build") {
+      yield _chunkLW7IN57Fcjs.buildApp.call(void 0, target);
+      return;
+    }
+    if (command === "dev") {
+      yield _chunkLW7IN57Fcjs.devApp.call(void 0, target);
+      return;
+    }
+    fail(`\u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u0430\u044F \u043A\u043E\u043C\u0430\u043D\u0434\u0430 \xAB${command}\xBB`);
+  });
+}
+
+// src/bin/den.ts
+run(process.argv.slice(2)).catch((error) => {
+  process.stderr.write(`den: ${error instanceof Error ? error.message : String(error)}
+`);
+  process.exit(1);
+});

package/bin/den.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/bin/den.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/bin/den.js

@@ -0,0 +1,88 @@
+import {
+  buildApp,
+  devApp
+} from "../chunk-MCMYOVGT.js";
+import "../chunk-TPBI6TOU.js";
+import {
+  __async
+} from "../chunk-6FNC3XMI.js";
+
+// src/bin/cli.ts
+var USAGE = `den <\u043A\u043E\u043C\u0430\u043D\u0434\u0430> [\u043E\u043F\u0446\u0438\u0438]
+
+\u041A\u043E\u043C\u0430\u043D\u0434\u044B:
+  build                 \u0441\u043E\u0431\u0440\u0430\u0442\u044C \u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u0435: \u043A\u043B\u0438\u0435\u043D\u0442\u0441\u043A\u0438\u0439 \u0432\u044B\u0445\u043E\u0434, \u0441\u0435\u0440\u0432\u0435\u0440\u043D\u044B\u0439 \u0434\u0435\u0441\u043A\u0440\u0438\u043F\u0442\u043E\u0440 \u0438 \u0442\u043E\u0447\u043A\u0443
+                        \u0432\u0445\u043E\u0434\u0430 \u043F\u0440\u043E\u0446\u0435\u0441\u0441\u0430 (build/client, build/server, build/server.mjs)
+  dev                   \u0442\u043E \u0436\u0435 \u043F\u043B\u044E\u0441 \u043F\u043E\u0434\u044A\u0451\u043C \u043F\u0440\u043E\u0446\u0435\u0441\u0441\u0430 \u0438 \u043F\u0435\u0440\u0435\u0441\u0431\u043E\u0440\u043A\u0430 \u043D\u0430 \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u0435 \u0438\u0441\u0445\u043E\u0434\u043D\u0438\u043A\u043E\u0432
+
+\u041E\u043F\u0446\u0438\u0438:
+  --root <\u043A\u0430\u0442\u0430\u043B\u043E\u0433>      \u043A\u043E\u0440\u0435\u043D\u044C \u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u044F (\u043F\u043E \u0443\u043C\u043E\u043B\u0447\u0430\u043D\u0438\u044E \u0442\u0435\u043A\u0443\u0449\u0438\u0439 \u043A\u0430\u0442\u0430\u043B\u043E\u0433)
+  --base <\u043F\u0440\u0435\u0444\u0438\u043A\u0441>      \u043F\u0440\u0435\u0444\u0438\u043A\u0441 \u0430\u0434\u0440\u0435\u0441\u043E\u0432 \u0430\u0440\u0442\u0435\u0444\u0430\u043A\u0442\u043E\u0432: \u0432 \u043F\u0440\u043E\u0434\u0435 CDN, \u0432 \u0440\u0430\u0437\u0440\u0430\u0431\u043E\u0442\u043A\u0435 \u0440\u0430\u0437\u0432\u044F\u0437\u043A\u0430
+                        \u0443 \u0445\u043E\u0441\u0442\u0430 (\u043F\u043E \u0443\u043C\u043E\u043B\u0447\u0430\u043D\u0438\u044E /)
+  -h, --help            \u044D\u0442\u0430 \u0441\u043F\u0440\u0430\u0432\u043A\u0430
+`;
+function parseArgs(argv) {
+  const options = {};
+  let command;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      return { help: true, options: {} };
+    }
+    if (arg === "--root" || arg === "--base") {
+      i += 1;
+      options[arg.slice(2)] = argv[i];
+      continue;
+    }
+    if ((arg == null ? void 0 : arg.startsWith("-")) === true) {
+      throw new Error(`\u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u0430\u044F \u043E\u043F\u0446\u0438\u044F ${arg}`);
+    }
+    if (command !== void 0) {
+      throw new Error("\u043A\u043E\u043C\u0430\u043D\u0434\u0430 \u0443\u043A\u0430\u0437\u044B\u0432\u0430\u0435\u0442\u0441\u044F \u043E\u0434\u043D\u0430");
+    }
+    command = arg;
+  }
+  return { command, options };
+}
+function fail(message) {
+  process.stderr.write(`den: ${message}
+
+${USAGE}`);
+  process.exit(1);
+}
+function run(argv) {
+  return __async(this, null, function* () {
+    var _a;
+    let parsed;
+    try {
+      parsed = parseArgs(argv);
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    }
+    if (parsed.help === true) {
+      process.stdout.write(USAGE);
+      return;
+    }
+    const { command, options } = parsed;
+    if (command === void 0) {
+      fail("\u043D\u0435 \u0443\u043A\u0430\u0437\u0430\u043D\u0430 \u043A\u043E\u043C\u0430\u043D\u0434\u0430");
+    }
+    const target = { base: options["base"], root: (_a = options["root"]) != null ? _a : process.cwd() };
+    if (command === "build") {
+      yield buildApp(target);
+      return;
+    }
+    if (command === "dev") {
+      yield devApp(target);
+      return;
+    }
+    fail(`\u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u0430\u044F \u043A\u043E\u043C\u0430\u043D\u0434\u0430 \xAB${command}\xBB`);
+  });
+}
+
+// src/bin/den.ts
+run(process.argv.slice(2)).catch((error) => {
+  process.stderr.write(`den: ${error instanceof Error ? error.message : String(error)}
+`);
+  process.exit(1);
+});

package/builder/index.cjs

@@ -0,0 +1,12 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+var _chunkLW7IN57Fcjs = require('../chunk-LW7IN57F.cjs');
+require('../chunk-A6ZPAM6Z.cjs');
+require('../chunk-T5QVCXVB.cjs');
+
+
+
+
+exports.buildApp = _chunkLW7IN57Fcjs.buildApp; exports.defineAppConfig = _chunkLW7IN57Fcjs.defineAppConfig; exports.devApp = _chunkLW7IN57Fcjs.devApp;

package/builder/index.d.cts

@@ -0,0 +1,124 @@
+import { a as ServerRender } from '../server-render-CocWXQKC.cjs';
+import { Container } from '@foxford/ioc';
+import { FastifyInstance } from 'fastify';
+import { PluginOption } from 'vite';
+
+/**
+ * Пресет фреймворка: чем собирать его исходники и чем оживлять фрагмент в браузере.
+ *
+ * Отдаёт его пакет адаптера — он единственный, кто знает и то, и другое. Команды сборки
+ * пресет не разбирают, а укладывают: `plugins` — в конфиг сборщика, `clientEntry` — в
+ * сгенерированный клиентский вход.
+ */
+interface AppBuildPreset {
+    /** Имя фреймворка — им пресет представляется в логах и сообщениях об ошибках. */
+    view: string;
+    /** Плагины сборщика, которыми рисуется этот фреймворк. */
+    plugins: PluginOption[];
+    /**
+     * Модуль с `hydrateApp(descriptor)` — по нему сборка генерирует клиентский вход.
+     *
+     * Специфицируется именем, а не функцией: вход собирается в браузерный бандл, и функция из
+     * процесса сборки в него не переедет.
+     */
+    clientEntry: string;
+    /**
+     * Проверка, что пресету хватает объявленного: получает зависимости приложения, возвращает
+     * причину отказа либо `null`.
+     *
+     * Здесь, а не в командах: какая зависимость требует сборочной поддержки, знает пресет —
+     * командам об этом знать нечем, и захардкоженный список сделал бы их привязанными к стеку.
+     * Нужна проверка потому, что цена ошибки — молчание: имена классов разъезжаются между
+     * выходами, и это видно только сломанной гидрацией в браузере.
+     */
+    validate?: (dependencies: string[]) => string | null;
+}
+/** Серверная часть конфига — всё, что вплавляется в серверный выход. */
+interface AppServerConfig {
+    /**
+     * Настройка процесса перед первым рендером: разбор разметки, полифиллы, прогрев.
+     *
+     * Дожидается её движок, один раз на процесс, — приложению ждать не нужно.
+     */
+    setup?: () => void | Promise<void>;
+    /**
+     * Обёртка серверного рендера: через неё собираются стили, которые фреймворк заводит по
+     * ходу рендера, и уезжают в `<head>` разметкой.
+     */
+    render?: ServerRender;
+    /**
+     * Биндинги app-контейнера: адрес ручек, ключи, всё, что приложение читает через `requires`.
+     *
+     * Контейнер приложения — родитель контейнеров островов, поэтому положенное здесь резолвится
+     * по parent-chain на любом рендере.
+     */
+    container?: (container: Container) => void;
+    /**
+     * Расширение сетевого инстанса до начала прослушивания: Sentry, метрики, cors.
+     *
+     * Зовётся только сетевым транспортом — в процессе хоста инстанса нет.
+     */
+    configure?: (instance: FastifyInstance) => void | Promise<void>;
+    /**
+     * Зависимости, которые серверный выход обязан собрать ИСХОДНИКАМИ, а не оставить внешним
+     * модулем.
+     *
+     * Нужно тем пакетам, чей выход не переживает загрузку через node-ESM: интероп
+     * default-экспорта разъезжается, и вместо фабрики приходит пространство имён модуля.
+     */
+    noExternal?: Array<string | RegExp>;
+}
+/** Конфиг приложения. */
+interface AppConfig {
+    /** Модуль дескриптора; по умолчанию `src/index.ts`. */
+    entry?: string;
+    /** Пресет фреймворка — из пакета адаптера. */
+    preset: AppBuildPreset;
+    server?: AppServerConfig;
+    /**
+     * Последнее слово за приложением: правит собранный конфиг сборщика перед запуском.
+     *
+     * Щель на случай, когда коробки не хватило. Зовётся отдельно для каждого выхода, поэтому
+     * правка адресуется тому, кому предназначена.
+     */
+    vite?: (config: Record<string, unknown>, target: 'server' | 'client') => Record<string, unknown>;
+}
+/**
+ * Объявляет конфиг приложения.
+ *
+ * Функция, а не голый объект, ради типизации на месте: интерфейс проверяется там, где конфиг
+ * написан, а не там, где его прочитали команды.
+ *
+ * @param config - Конфиг приложения
+ */
+declare function defineAppConfig(config: AppConfig): AppConfig;
+
+/** Режим сборки: им плагины выбирают рантайм фреймворка. */
+type BuildMode = 'production' | 'development';
+/** Что нужно собрать. */
+interface BuildAppOptions {
+    /** Корень приложения. */
+    root: string;
+    /** Префикс адресов артефактов: в проде CDN, в разработке развязка у хоста. */
+    base?: string;
+    /** Режим сборки; по умолчанию `production`. */
+    mode?: BuildMode;
+}
+/**
+ * Собирает приложение целиком.
+ *
+ * @param options - Корень приложения и префикс адресов артефактов
+ * @throws Если конфига нет либо пресет сообщил, что ему не хватает объявленного
+ */
+declare function buildApp(options: BuildAppOptions): Promise<void>;
+
+/** Наблюдение берёт те же опции, что сборка: путь у них один. */
+type DevAppOptions = BuildAppOptions;
+/**
+ * Собирает приложение и держит его поднятым, пересобирая на изменение исходников.
+ *
+ * @param options - Корень приложения и префикс адресов артефактов
+ */
+declare function devApp(options: DevAppOptions): Promise<void>;
+
+export { type AppBuildPreset, type AppConfig, type AppServerConfig, type BuildAppOptions, type DevAppOptions, buildApp, defineAppConfig, devApp };

package/builder/index.d.ts

@@ -0,0 +1,124 @@
+import { a as ServerRender } from '../server-render-CocWXQKC.js';
+import { Container } from '@foxford/ioc';
+import { FastifyInstance } from 'fastify';
+import { PluginOption } from 'vite';
+
+/**
+ * Пресет фреймворка: чем собирать его исходники и чем оживлять фрагмент в браузере.
+ *
+ * Отдаёт его пакет адаптера — он единственный, кто знает и то, и другое. Команды сборки
+ * пресет не разбирают, а укладывают: `plugins` — в конфиг сборщика, `clientEntry` — в
+ * сгенерированный клиентский вход.
+ */
+interface AppBuildPreset {
+    /** Имя фреймворка — им пресет представляется в логах и сообщениях об ошибках. */
+    view: string;
+    /** Плагины сборщика, которыми рисуется этот фреймворк. */
+    plugins: PluginOption[];
+    /**
+     * Модуль с `hydrateApp(descriptor)` — по нему сборка генерирует клиентский вход.
+     *
+     * Специфицируется именем, а не функцией: вход собирается в браузерный бандл, и функция из
+     * процесса сборки в него не переедет.
+     */
+    clientEntry: string;
+    /**
+     * Проверка, что пресету хватает объявленного: получает зависимости приложения, возвращает
+     * причину отказа либо `null`.
+     *
+     * Здесь, а не в командах: какая зависимость требует сборочной поддержки, знает пресет —
+     * командам об этом знать нечем, и захардкоженный список сделал бы их привязанными к стеку.
+     * Нужна проверка потому, что цена ошибки — молчание: имена классов разъезжаются между
+     * выходами, и это видно только сломанной гидрацией в браузере.
+     */
+    validate?: (dependencies: string[]) => string | null;
+}
+/** Серверная часть конфига — всё, что вплавляется в серверный выход. */
+interface AppServerConfig {
+    /**
+     * Настройка процесса перед первым рендером: разбор разметки, полифиллы, прогрев.
+     *
+     * Дожидается её движок, один раз на процесс, — приложению ждать не нужно.
+     */
+    setup?: () => void | Promise<void>;
+    /**
+     * Обёртка серверного рендера: через неё собираются стили, которые фреймворк заводит по
+     * ходу рендера, и уезжают в `<head>` разметкой.
+     */
+    render?: ServerRender;
+    /**
+     * Биндинги app-контейнера: адрес ручек, ключи, всё, что приложение читает через `requires`.
+     *
+     * Контейнер приложения — родитель контейнеров островов, поэтому положенное здесь резолвится
+     * по parent-chain на любом рендере.
+     */
+    container?: (container: Container) => void;
+    /**
+     * Расширение сетевого инстанса до начала прослушивания: Sentry, метрики, cors.
+     *
+     * Зовётся только сетевым транспортом — в процессе хоста инстанса нет.
+     */
+    configure?: (instance: FastifyInstance) => void | Promise<void>;
+    /**
+     * Зависимости, которые серверный выход обязан собрать ИСХОДНИКАМИ, а не оставить внешним
+     * модулем.
+     *
+     * Нужно тем пакетам, чей выход не переживает загрузку через node-ESM: интероп
+     * default-экспорта разъезжается, и вместо фабрики приходит пространство имён модуля.
+     */
+    noExternal?: Array<string | RegExp>;
+}
+/** Конфиг приложения. */
+interface AppConfig {
+    /** Модуль дескриптора; по умолчанию `src/index.ts`. */
+    entry?: string;
+    /** Пресет фреймворка — из пакета адаптера. */
+    preset: AppBuildPreset;
+    server?: AppServerConfig;
+    /**
+     * Последнее слово за приложением: правит собранный конфиг сборщика перед запуском.
+     *
+     * Щель на случай, когда коробки не хватило. Зовётся отдельно для каждого выхода, поэтому
+     * правка адресуется тому, кому предназначена.
+     */
+    vite?: (config: Record<string, unknown>, target: 'server' | 'client') => Record<string, unknown>;
+}
+/**
+ * Объявляет конфиг приложения.
+ *
+ * Функция, а не голый объект, ради типизации на месте: интерфейс проверяется там, где конфиг
+ * написан, а не там, где его прочитали команды.
+ *
+ * @param config - Конфиг приложения
+ */
+declare function defineAppConfig(config: AppConfig): AppConfig;
+
+/** Режим сборки: им плагины выбирают рантайм фреймворка. */
+type BuildMode = 'production' | 'development';
+/** Что нужно собрать. */
+interface BuildAppOptions {
+    /** Корень приложения. */
+    root: string;
+    /** Префикс адресов артефактов: в проде CDN, в разработке развязка у хоста. */
+    base?: string;
+    /** Режим сборки; по умолчанию `production`. */
+    mode?: BuildMode;
+}
+/**
+ * Собирает приложение целиком.
+ *
+ * @param options - Корень приложения и префикс адресов артефактов
+ * @throws Если конфига нет либо пресет сообщил, что ему не хватает объявленного
+ */
+declare function buildApp(options: BuildAppOptions): Promise<void>;
+
+/** Наблюдение берёт те же опции, что сборка: путь у них один. */
+type DevAppOptions = BuildAppOptions;
+/**
+ * Собирает приложение и держит его поднятым, пересобирая на изменение исходников.
+ *
+ * @param options - Корень приложения и префикс адресов артефактов
+ */
+declare function devApp(options: DevAppOptions): Promise<void>;
+
+export { type AppBuildPreset, type AppConfig, type AppServerConfig, type BuildAppOptions, type DevAppOptions, buildApp, defineAppConfig, devApp };

package/builder/index.js

@@ -0,0 +1,12 @@
+import {
+  buildApp,
+  defineAppConfig,
+  devApp
+} from "../chunk-MCMYOVGT.js";
+import "../chunk-TPBI6TOU.js";
+import "../chunk-6FNC3XMI.js";
+export {
+  buildApp,
+  defineAppConfig,
+  devApp
+};