@ozdao/scriptorium 0.1.3 → 0.1.4

package/README.md

@@ -1,19 +1,21 @@
 # @ozdao/scriptorium
 
-Сайт документации из папок markdown на @ozdao/martyrs (Vue 3, rspack, SSR). Все `.md` репозитория — страницы; `AGENTS.md` — индекс своей папки; адреса без `.md`.
+Сайт документации из папок markdown на @ozdao/martyrs (Vue 3, rspack). Все `.md` репозитория — страницы; `AGENTS.md` — индекс своей папки; адреса без `.md`. Работает как VitePress: `dev` — сервер разработки, `build` — статический сайт в папке `dist/`, деплой — раздать папку.
 
 ## Раскладка у пользователя
 
-Как у VitePress: сайт живёт в одной папке `documentation/` в корне репозитория документации, команды запускаются из неё. Страницы — все `.md` репозитория (папка над `documentation/`); сама `documentation/` в сайт не входит.
+Сайт живёт в одной папке `documentation/` в корне репозитория документации, команды запускаются из неё. Страницы — все `.md` репозитория (папка над `documentation/`); сама `documentation/` в сайт не входит.
 
 ```
 documentation/
-├── package.json     зависимости и скрипты сайта
-├── node_modules/    единственный node_modules репозитория документации
-├── config.js        конфиг сайта (обязателен)
-├── theme/           логотип, блок над страницей, стили (необязательно)
-├── public/          статика сайта: своё (favicon) + генерируемое сборкой
-└── builds/          сборка
+├── package.json         зависимости и скрипты сайта
+├── pnpm-workspace.yaml  разрешения на install-скрипты зависимостей (pnpm 11)
+├── node_modules/        единственный node_modules репозитория документации
+├── config.js            конфиг сайта (обязателен)
+├── theme/               логотип, блок над страницей, стили (необязательно)
+├── public/              своя статика сайта (favicon)
+├── builds/              сборка клиента и render-бандла (генерируется)
+└── dist/                статический сайт после build (генерируется)
 ```
 
 Код сайта целиком в пакете (`node_modules/@ozdao/scriptorium`), туда при работе ничего не пишется. В корне репозитория документации `package.json` и `node_modules` нет.
@@ -27,15 +29,13 @@ documentation/
   "name": "docs",
   "private": true,
   "type": "module",
-  "packageManager": "pnpm@10.8.0",
   "scripts": {
     "preinstall": "npx only-allow pnpm",
     "dev": "scriptorium dev",
-    "build": "scriptorium build",
-    "start": "scriptorium start"
+    "build": "scriptorium build"
   },
   "devDependencies": {
-    "@ozdao/scriptorium": "0.1.0",
+    "@ozdao/scriptorium": "0.1.4",
     "@ozdao/martyrs": "0.2.609",
     "vue": "3.5.42",
     "vue-i18n": "11.4.10",
@@ -44,9 +44,15 @@ documentation/
 }
 ```
 
-`@ozdao/martyrs`, `vue`, `vue-router`, `vue-i18n` — peer-зависимости пакета, и указывать их обязательно. Сборка martyrs берёт `vue` из `documentation/node_modules/vue`, а шаблон service worker — из `documentation/node_modules/@ozdao/martyrs`. pnpm кладёт наверх `node_modules` только прямые зависимости проекта. Без явного указания этих пакетов там нет, и сборка падает.
+`@ozdao/martyrs`, `vue`, `vue-router`, `vue-i18n` — peer-зависимости пакета, указывать обязательно: сборка martyrs берёт `vue` из `documentation/node_modules/vue`, а pnpm кладёт наверх только прямые зависимости проекта.
 
-`packageManager: pnpm@10.8.0` нужен, как в шаблоне create-martyrs: pnpm 11 отказывается ставить git-зависимость martyrs (`uWebSockets.js`, `blockExoticSubdeps`) и передаёт установку pnpm 10.
+`documentation/pnpm-workspace.yaml` — pnpm 11 запускает install-скрипты зависимостей только с разрешения:
+
+```yaml
+allowBuilds:
+  "@ozdao/martyrs": true
+  better-sqlite3: true
+```
 
 ```bash
 cd documentation && pnpm install
@@ -56,11 +62,12 @@ cd documentation && pnpm install
 
 ```bash
 cd documentation
-pnpm dev     # разработка, http://localhost:8200 (порт — PORT)
-pnpm build   # сборка в builds/
-pnpm start   # сервер по сборке
+pnpm dev     # разработка с HMR, http://localhost:8200 (порт — PORT)
+pnpm build   # статический сайт в dist/
 ```
 
+`build` собирает клиент и render-бандл в `builds/`, пререндерит каждую страницу в `dist/<адрес>/index.html`, кладёт рядом ассеты, `public/` и `404.html`. Деплой — любой статический сервер с корнем `dist/`; для адресов без расширения — `try_files $uri $uri/index.html =404` (nginx), `404.html` — на неизвестный адрес.
+
 Команда запускается только из `documentation/`: там должны лежать `config.js` и `package.json`.
 
 ## Конфиг
@@ -74,7 +81,7 @@ export default {
   skipped_names: ['node_modules', 'builds'], // папки, пропускаемые на любой глубине
   skipped_paths: [],                         // пути от корня репозитория; documentation/ пропускается всегда
   nav: [{ text: 'Обзор', link: '/' }],
-  sidebar: { priority: ['AGENTS.md'], folders_to_bottom: true, collapse_depth: 2, hidden: ['templates'] },
+  sidebar: { priority: ['AGENTS.md'], folders_to_bottom: true, collapse_depth: 2, hidden: [] },
   outline: { level: [2, 3], label: 'На странице' },
   labels: { menu: 'Меню', theme: 'Тема', top: 'Наверх', prev: 'Назад', next: 'Дальше', not_found: 'Страница не найдена', home: 'На главную' },
 }
@@ -87,27 +94,21 @@ import { Badge, useDocs } from '@ozdao/scriptorium'
 const { page, frontmatter, config, pages } = useDocs()
 ```
 
-`documentation/public/` отдаётся статикой раньше статики пакета: свой `favicon/` перекрывает умолчание.
+Картинки в `.md` — относительными путями от файла; сборка кладёт их в ассеты (png, jpg, webp, avif, svg, gif).
 
 ## Что генерируется
 
-Сборка martyrs пишет в `documentation/`. В `.gitignore` репозитория документации:
+В `.gitignore` репозитория документации:
 
 ```
 documentation/node_modules
 documentation/builds
-documentation/public/sw.js
-documentation/public/icon-sprite.svg
-documentation/public/fonts/
+documentation/dist
 documentation/.cache
 documentation/logs
 ```
 
-- `builds/` — клиентская и серверная сборка;
-- `public/sw.js` — service worker в dev (в prod он лежит в `builds/web/client/`);
-- `public/icon-sprite.svg`, `public/fonts/` — спрайт иконок и шрифты martyrs; у документации своих исходников нет, файлы не появляются;
-- `.cache/martyrs-jit.css` — JIT-утилиты martyrs;
-- `logs/testid-duplicates.txt` — отчёт дублей `data-testid` dev-сборки.
+`.cache/martyrs-jit.css` — JIT-утилиты martyrs; `logs/testid-duplicates.txt` — отчёт dev-сборки.
 
 ## Разработка пакета
 
@@ -115,6 +116,6 @@ documentation/logs
 pnpm install   # в корне пакета: pnpm-workspace.yaml разрешает install-скрипты
 ```
 
-Подключение к репозиторию документации без публикации — `"@ozdao/scriptorium": "link:<путь к пакету>"` в `documentation/package.json`. При `link:` pnpm не ставит зависимости пакета в проект, поэтому peer-зависимости выше там тоже обязательны.
+Подключение к репозиторию документации без публикации — `"@ozdao/scriptorium": "link:<путь к пакету>"` в `documentation/package.json`; peer-зависимости выше там тоже обязательны.
 
-Устройство: `bin/scriptorium.js` — CLI и сборка конфигов rspack поверх builder'а martyrs (корень приложения = `documentation/`, вход и сервер — файлы пакета); `src/` — приложение сайта (клиент, `server.js`, loader'ы markdown, списка страниц и индекса поиска).
+Устройство: `bin/scriptorium.js` — CLI, конфиги rspack поверх builder'а martyrs (корень приложения = `documentation/`, вход и сервер — файлы пакета), `build`; `src/static-site.js` — пререндер в `dist/`; `src/server.js` — сервер dev; `src/content/` — loader'ы markdown, списка страниц и индекса поиска; `src/components/` — раскладка сайта.

package/bin/scriptorium.js

@@ -16,10 +16,11 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isMainThread } from 'node:worker_threads';
 
+// dev — dev-сервер martyrs с HMR; build — статический сайт в documentation/dist
+// (пререндер всех страниц + ассеты), деплой = раздать папку. Node в проде не нужен.
 const environment_of_command = {
   dev: 'development',
   build: 'production',
-  start: 'production',
 };
 
 const command = process.argv[2];
@@ -164,11 +165,12 @@ for (const config of Object.values(configs.ssr)) {
       plugin.options.exclude = plugin.options.exclude.filter((part) => part !== 'node_modules');
     }
 
-    // Service worker сайту документации не нужен: его регистрирует только модуль
-    // notifications martyrs, которого здесь нет. Плагин в dev писал бы sw.js в
-    // <корень приложения>/../public — корень репозитория документации.
+    // Service worker: клиент martyrs регистрирует /sw.js на каждой странице. В
+    // сборке плагин эмитит sw.js ассетом — он попадает в dist. В dev он писал бы
+    // файл в <корень приложения>/../public — корень репозитория документации,
+    // поэтому в dev плагин убирается (ошибка регистрации в консоли dev — не беда).
     const is_service_worker = plugin?.constructor === Object && String(plugin.apply).includes('service-worker');
-    return !is_service_worker;
+    return !(is_service_worker && process.env.NODE_ENV !== 'production');
   });
 }
 
@@ -178,9 +180,24 @@ for (const config of Object.values(configs.ssr)) {
 // клиент при гидратации ставил другой адрес.
 configs.ssr.server.output.publicPath = '/';
 
-await run(command, configs);
-
-// Воркер бэкенда в dev (тот же файл, не главный поток) и сборка адрес не печатают.
-if (isMainThread && command !== 'build') {
-  console.log(`Docs: http://localhost:${process.env.PORT}`);
+if (command === 'build') {
+  // Клиент и render-бандл — компиляторами rspack по тем же конфигам, что у dev;
+  // затем пререндер страниц в dist. Сборка martyrs (builder/build.js) после
+  // компиляции завершает процесс, поэтому компиляторы запускаются здесь.
+  const { rspack } = await import('@rspack/core');
+  for (const config of [configs.ssr.client, configs.ssr.server]) {
+    const compiler = rspack(config);
+    const failed = await new Promise((resolve, reject) => compiler.run((error, stats) => {
+      if (error) { reject(error); return; }
+      if (stats.hasErrors()) console.error(stats.toString({ errors: true, warnings: false, colors: true }));
+      compiler.close(() => resolve(stats.hasErrors()));
+    }));
+    if (failed) process.exit(1);
+  }
+  const { writeStaticSite } = await import('../src/static-site.js');
+  await writeStaticSite(configs.ssr, path.join(docs_dir, 'dist'));
+} else {
+  await run(command, configs);
+  // Воркер бэкенда в dev (тот же файл, не главный поток) адрес не печатает.
+  if (isMainThread) console.log(`Docs: http://localhost:${process.env.PORT}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ozdao/scriptorium",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Documentation site generator on @ozdao/martyrs: markdown folders to an SSR site",
   "author": "OZ DAO <hello@ozdao.com>",
   "license": "GPL-3.0-or-later",

package/src/server.js

@@ -1,5 +1,6 @@
-// Сервер сайта документации: express + статика. Порт слушает раннер martyrs
-// (builder/start.js), SSR-рендер страниц он же вешает поверх этого приложения.
+// Сервер сайта документации для dev: express + статика. Порт слушает раннер
+// martyrs (builder/start.js внутри dev), SSR-рендер страниц он же вешает поверх
+// этого приложения. В проде сервера нет: build пишет статический сайт в dist.
 // Env и резолв-хуки уже стоят: register выполняет bin/scriptorium.js до этого файла.
 // Грузится в node без сборки, поэтому импорты только относительные: хуки martyrs
 // ведут '@/' в src/ корня приложения (documentation/src), которого нет.
@@ -9,7 +10,7 @@ import { fileURLToPath } from 'node:url';
 import express from 'express';
 import cookies from 'cookie-parser';
 
-import { docs_dir, docs_root, loadSiteConfig } from './content/scan.js';
+import { docs_dir, loadSiteConfig } from './content/scan.js';
 
 // Статика пакета: favicon по умолчанию.
 const package_public = fileURLToPath(new URL('../public', import.meta.url));
@@ -39,27 +40,8 @@ const createServer = async () => {
   app.use(express.static(path.join(docs_dir, 'public')));
   app.use(express.static(package_public));
 
-  // Файлы репозитория по ссылкам из документов (референсы, логотипы, манифест):
-  // как VitePress отдаёт всё из папки исходников. Только медиа и данные, без
-  // скрытых папок и node_modules: исходники и конфиги наружу не отдаются.
-  app.use((req, res, next) => {
-    if (!/\.(?:png|jpe?g|gif|webp|avif|svg|mp4|webm|pdf|json)$/i.test(req.path)) return next();
-    if (/\/\.|\/node_modules\//.test(req.path)) return next();
-    // Папка самого сайта (конфиг, package.json, lockfile) — не документация.
-    if (req.path.startsWith(`/${path.relative(docs_root, docs_dir)}/`)) return next();
-    express.static(docs_root, { index: false, dotfiles: 'ignore' })(req, res, next);
-  });
-
   const server = http.createServer(app);
 
-  // scriptorium start: SIGTERM (systemd, деплой) — штатный выход с кодом 0,
-  // а не 143. В dev этот файл живёт в воркере бэкенда, сигналы туда не
-  // приходят: остановку ведёт главный поток (builder/dev.js, сообщение close).
-  process.once('SIGTERM', () => {
-    server.close(() => process.exit(0));
-    server.closeAllConnections();
-  });
-
   return { app, server };
 };
 

package/src/static-site.js

@@ -0,0 +1,70 @@
+// Статическая сборка сайта — как `vitepress build`: каждая страница
+// пререндерится тем же render-бандлом, что обслуживает dev, и пишется в
+// dist/<адрес>/index.html; рядом — ассеты клиента и public/. Деплой — раздать
+// папку dist любым статическим сервером, node в проде не нужен.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createAssetResolver } from '@ozdao/martyrs/src/builder/ssr/asset-resolver.js';
+import { renderHtml } from '@ozdao/martyrs/src/builder/ssr/ssr-render-html.js';
+import { createBeastiesProcessor } from '@ozdao/martyrs/src/builder/ssr/beasties-processor.js';
+import { docs_dir, docs_root, loadSiteConfig, scanPages } from './content/scan.js';
+
+export async function writeStaticSite({ client, server }, dist_dir) {
+  const site_config = await loadSiteConfig();
+  const client_dir = client.output.path;
+  const server_dir = server.output.path;
+
+  // Статы клиента → теги <script>/<link> под чанки страницы; render-бандл — по manifest.json.
+  const resolver = createAssetResolver(JSON.parse(fs.readFileSync(path.join(client_dir, 'stats.json'), 'utf-8')));
+  const manifest = JSON.parse(fs.readFileSync(path.join(server_dir, 'manifest.json'), 'utf-8'));
+  const { _renderApp: renderApp } = await import(/* webpackIgnore: true */ pathToFileURL(path.join(server_dir, manifest['main.js'])).href);
+  // Критический CSS в <head> страницы, как в проде martyrs.
+  const beasties = createBeastiesProcessor(client_dir, { publicPath: client.output.publicPath });
+
+  fs.rmSync(dist_dir, { recursive: true, force: true });
+  fs.mkdirSync(dist_dir, { recursive: true });
+
+  // Ассеты клиента (без статов сборки) и public/ пользователя — в корень dist.
+  for (const entry of fs.readdirSync(client_dir)) {
+    if (entry === 'stats.json') continue;
+    fs.cpSync(path.join(client_dir, entry), path.join(dist_dir, entry), { recursive: true });
+  }
+  if (fs.existsSync(path.join(docs_dir, 'public'))) {
+    fs.cpSync(path.join(docs_dir, 'public'), dist_dir, { recursive: true });
+  }
+
+  // Страницы сайта плюс одна несуществующая — для 404.html.
+  const urls = [...scanPages(docs_root, site_config).map((page) => page.url), '/404'];
+
+  for (const url of urls) {
+    const { html, meta, state, usedModules, loadedModules } = await renderApp({
+      url,
+      // Тема по умолчанию — та же cookie, по которой рендерер martyrs ставит data-theme.
+      cookies: site_config.appearance === 'auto' ? {} : { theme: site_config.appearance },
+      headers: { host: 'localhost' },
+      languages: [site_config.lang],
+      ssrContext: {},
+    });
+    const modules = loadedModules || usedModules || [];
+    const { head, body } = resolver.collect(modules, { criticalCss: true });
+    const page_html = await beasties.processHtml(await renderHtml({
+      appHtml: html,
+      meta,
+      head,
+      body,
+      initialState: JSON.stringify(state),
+      loadedModulesJson: JSON.stringify(loadedModules || []),
+    }), { url, modules });
+
+    // '/' → index.html, '/code/core/' и '/code/GLOSSARY' → <путь>/index.html,
+    // '/404' → 404.html (его отдаёт статический сервер на любой неизвестный адрес).
+    const file = url === '/404'
+      ? path.join(dist_dir, '404.html')
+      : path.join(dist_dir, decodeURI(url).replace(/^\/|\/$/g, ''), 'index.html');
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, page_html);
+  }
+
+  console.log(`✓ ${path.relative(process.cwd(), dist_dir)}: ${urls.length - 1} страниц, 404.html`);
+}