@foxford/den 3.0.0 → 3.1.1

package/README.mdx

@@ -4,6 +4,270 @@ title: Den
 
 # @foxford/den
 
-Den — декларативный метафреймворк Foxford (core runtime).
+Декларативный метафреймворк Foxford: приложение объявляет, из чего оно состоит, а исполняет
+это движок. Ядро host-агностично — про Vike и Next знают отдельные пакеты
+(`@foxford/den-vike`, `@foxford/den-next`), про React — `@foxford/den-react`.
 
-Содержит core runtime: define* API, lifecycle, container orchestration, NavigationManager.
+Здесь примеры. Почему устроено именно так — в [SPECIFICATION.md](./SPECIFICATION.md).
+
+## Единицы приложения
+
+Слои объявляются `define*`-функциями и складываются в контейнер. Зависимости приходят через
+`requires` и резолвятся движком, поэтому единица не знает, кто её создаёт.
+
+```ts
+// content-page.repository.ts
+import { defineRepository } from '@foxford/den/define'
+
+export default defineRepository(ContentPageRepositoryToken, {
+  create: () => ({
+    getPage: async (path: string) => fetch(`/api/pages${path}`).then((res) => res.json()),
+  }),
+})
+```
+
+```ts
+// content-page.vm.ts
+import { defineViewModel } from '@foxford/den/define'
+import { ViewModel } from '@foxford/vm'
+
+import type { IslandRoute } from '@foxford/den/island'
+
+export class ContentPageVM extends ViewModel<ReturnType<typeof makeState>> {
+  constructor(private readonly service: ContentPageService) {
+    super(makeState())
+  }
+
+  /** Зовёт движок при рендере страницы — на сервере и в браузере одинаково. */
+  async activate(route: IslandRoute): Promise<void> {
+    this.state.set(await loadContentPage(this.service, route.pathname))
+  }
+}
+
+export default defineViewModel(ContentPageVmToken, {
+  create: ([service]) => new ContentPageVM(service),
+  requires: [ContentPageServiceToken] as const,
+})
+```
+
+## Заявка на адреса и её параметры
+
+Приложение объявляет, какие пути берётся обслуживать. Заявка — **регулярка**: она строго
+выразительнее шаблона (`'.*'` как ловец остатка, префиксы, альтернативы), и порядок в списке
+значим — хост отдаёт путь первому заявившему, поэтому частные записи ставятся выше общих.
+
+Параметры адреса — именованные группы. Писать их руками не нужно, для этого `pathPattern`:
+
+```ts
+import { pathPattern } from '@foxford/den/island'
+
+routes: [
+  pathPattern('/course/:id'), // → '^/course/(?<id>[^/]+)$'
+  '^/legal', // обычная регулярка рядом
+]
+```
+
+Выделяет их `matchRoute` — один матчер на всех: по нему хост решает, кому отдать адрес,
+а рантайм приложения — своё ли это. Разойдись эти два ответа, приложение получало бы запросы
+по путям, которых не заявляло. Значения раскодированы (`/legal/%D0%BE...` → `оферта`).
+
+## Шов рендера: разметка и состояние одним вызовом
+
+`renderApp` — то, чем хост спрашивает у приложения страницу. Внутри движок поднимает контейнер,
+активирует VM по адресу, рисует дерево и снимает состояние; дескриптор при этом остаётся
+декларацией без поведения.
+
+```ts
+import { renderApp } from '@foxford/den/island'
+
+const { status, html, state, head, headHtml, redirect, assets } = await renderApp(app, {
+  pathname: '/legal/general',
+  search: '?from=footer',
+  context: { cookies, headers }, // реквизиты браузерного запроса
+})
+```
+
+`status` — исход запроса: `200` значит «вот страница», всё остальное значит, что страницы по
+этому адресу нет, и тело такого ответа выбирает хост. `state` едет в документ и гидрирует
+остров в браузере, `headHtml` — стили, собранные во время рендера. `assets` — ссылки на
+initial-чанки клиентской сборки, их подключает хост; байты приложение не отдаёт ни в одном
+транспорте.
+
+### Вклад в документ
+
+Заголовок и исход сообщает VM — необязательным методом `describeDocument`. Полем дескриптора
+это быть не может: после активации только VM знает, нашлась ли страница по адресу.
+
+```ts
+export class ContentPageVM extends ViewModel<State> {
+  /** В ручку ходим ЗДЕСЬ. */
+  async activate(route: IslandRoute): Promise<void> {
+    this.state.set(await loadContentPage(this.service, route.pathname))
+  }
+
+  /** А здесь только решаем по тому, что уже приехало. */
+  describeDocument(): DocumentContribution {
+    const { page } = this.state.get()
+
+    if (page === null) {
+      return { status: 404 } // хост ответит честным 404
+    }
+
+    return { head: { description: page.description, title: page.title } }
+  }
+}
+```
+
+`describeDocument` синхронный намеренно. Приложению, которому «есть ли такая страница» известно
+только от бэкенда, второй поход не нужен: движок ждёт активацию ДО сбора вклада, поэтому к
+моменту вызова ответ уже лежит в состоянии. Разреши мы тут асинхронность — у рендера появилась
+бы вторая фаза походов в сеть, а логика загрузки разъехалась бы по двум местам.
+
+Редирект объявляется там же: `{ redirect: '/user/login' }` — без статуса это `302`.
+
+## Сетевой транспорт: то же самое по HTTP
+
+Приложение поднимается отдельным сервисом **без единой строки своего серверного кода** —
+дескриптор тот же, что и в процессе хоста. Точку входа процесса выпускает `den build`
+(см. «Сборка приложения»), поэтому прод это голая нода:
+
+```jsonc
+// package.json приложения
+"scripts": {
+  "dev": "den dev",
+  "build": "den build",
+  "start": "node build/server.mjs"
+}
+```
+
+Рантайм вокруг дескриптора отдаёт три ручки:
+
+| Ручка | Ответ |
+| --- | --- |
+| `GET /_render?url=<path+search>` | `200` + ответ `renderApp` телом |
+| `GET /_routes` | `200` + массив regex-строк заявки на адреса |
+| `GET /_health` | `200 ok` |
+
+**Статус HTTP описывает транспорт, а исход страницы едет полем `status` в теле.** `200` значит
+«приложение ответило» — хоть `404`, хоть редиректом. Всё остальное значит «до приложения не
+дошли»: `400` — сломанный запрос, `404` — неизвестная ручка или путь вне заявки, `500` — рендер
+упал. Так `404` от приложения не путается с `404` от неверно настроенного прокси.
+
+Браузерные заголовки рантайм читает только из `X-Forwarded-*` и кладёт в `RequestContextToken`;
+`Cookie` — обычным именем.
+
+### Расширение снаружи: пример с Sentry
+
+Основа — fastify, и отдаётся она плагином, поэтому Sentry, метрики, cors и трейсинг ставит
+ПОТРЕБИТЕЛЬ. Своих опций под каждую такую потребность пакет не заводит.
+
+Инициализация Sentry должна пройти раньше всего остального кода, поэтому она живёт отдельным
+модулем и грузится флагом `--import`, а не из точки входа:
+
+```ts
+// instrument.js — грузится раньше приложения
+import * as Sentry from '@sentry/node'
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  environment: process.env.NODE_ENV,
+  tracesSampleRate: 0.1,
+})
+```
+
+Обработчик ошибок вешается уже на готовый инстанс — это и есть `configure`:
+
+```ts
+// configure.js — дефолтный экспорт получает инстанс fastify до прослушивания
+import * as Sentry from '@sentry/node'
+
+export default (instance) => {
+  Sentry.setupFastifyErrorHandler(instance)
+
+  instance.get('/metrics', () => renderMetrics())
+}
+```
+
+Такое расширение объявляется в конфиге приложения полем `server.configure` — своего серверного
+кода по-прежнему ноль. Запуск с инструментацией:
+`NODE_OPTIONS='--import ./instrument.js' pnpm start`.
+
+Если сервер нужен свой — общий порт с чужими ручками, свой порядок плагинов, — берите плагин
+и монтируйте куда угодно, хоть под префиксом:
+
+```ts
+import Fastify from 'fastify'
+import * as Sentry from '@sentry/node'
+import { appPlugin } from '@foxford/den/serve'
+
+const instance = Fastify()
+Sentry.setupFastifyErrorHandler(instance)
+
+await instance.register(appPlugin, { app, prefix: '/den' })
+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` зовётся один раз на процесс до первого
+рендера, включая приложение в процессе хоста, где обвязки нет и дождаться было бы некому.
+Упавшая настройка не повторяется: процесс сломан, и прятать это за случайным успехом нельзя.
+
+## Подпути
+
+| Подпуть | Что там |
+| --- | --- |
+| `@foxford/den` | рантайм, `define*`, менеджеры контейнеров и состояния |
+| `@foxford/den/define` | те же `define*` без сайд-эффекта установки резолвера |
+| `@foxford/den/adapter` | шов резолва для адаптеров хостов |
+| `@foxford/den/island` | остров: жизненный цикл, шов `renderApp`, порт `ViewAdapter` |
+| `@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 _chunkOKRO4G4Lcjs = require('../chunk-OKRO4G4L.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 _chunkOKRO4G4Lcjs.buildApp.call(void 0, target);
+      return;
+    }
+    if (command === "dev") {
+      yield _chunkOKRO4G4Lcjs.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-REFU7UMG.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 _chunkOKRO4G4Lcjs = require('../chunk-OKRO4G4L.cjs');
+require('../chunk-A6ZPAM6Z.cjs');
+require('../chunk-T5QVCXVB.cjs');
+
+
+
+
+exports.buildApp = _chunkOKRO4G4Lcjs.buildApp; exports.defineAppConfig = _chunkOKRO4G4Lcjs.defineAppConfig; exports.devApp = _chunkOKRO4G4Lcjs.devApp;

package/builder/index.d.cts

@@ -0,0 +1,120 @@
+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;
+
+/** Что нужно собрать. */
+interface BuildAppOptions {
+    /** Корень приложения. */
+    root: string;
+    /** Префикс адресов артефактов: в проде CDN, в разработке развязка у хоста. */
+    base?: string;
+}
+/**
+ * Собирает приложение целиком.
+ *
+ * @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 };