@oxeo/visual 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @oxeo/visual
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Интерактивная карта схемы данных oxeo. Модели, поля, embedded-блоки, варианты дискриминатора и связи берутся из
+`DataScheme` и исходников схемы. Подсказки показывают JSDoc, декораторы и типы TS, у json-полей — интерфейс значения.
+Проект задаёт только каркас карты: зоны, пояса, порядок файлов и цвета.
+
+## Подключение
+
+```json
+{
+  "devDependencies": {
+    "@oxeo/visual": "*",
+    "ts-node": "^10.9.0"
+  },
+  "scripts": {
+    "scheme:map": "oxeo-visual dev",
+    "scheme:map:build": "oxeo-visual build"
+  }
+}
+```
+
+`ts-node` нужен, если конфиг написан на TypeScript: пакет берёт его из проекта, вместе с `tsconfig.json` проекта.
+
+## Конфиг
+
+`oxeo-visual.config.ts` рядом с `package.json`. Пути считаются от папки конфига.
+
+```ts
+import { defineConfig } from '@oxeo/visual'
+import { dataScheme } from './scheme'
+
+export default defineConfig({
+  scheme: dataScheme,
+  sourceDir: './scheme',
+  output: { dir: './scheme', name: 'scheme-map' },
+  // Пояса сверху вниз, в каждом — зоны слева направо
+  bands: [
+    ['sales', 'execution'],
+    ['people', 'dictionaries']
+  ],
+  zones: [
+    { id: 'sales', title: 'Продажи', color: '#e2580b', colorDark: '#fb923c', files: [['sales.ts']] },
+    // Ряды файлов зоны сверху вниз
+    {
+      id: 'execution',
+      title: 'Исполнение',
+      color: '#0f8f86',
+      files: [['projects.ts', 'shifts.ts'], ['timesheet.ts']]
+    },
+    { id: 'people', title: 'Люди', color: '#7c3aed', files: [['workers.ts']] },
+    {
+      id: 'dictionaries',
+      title: 'Справочники',
+      color: '#a87700',
+      files: [['dictionary.ts', 'settings.ts']]
+    }
+  ]
+})
+```
+
+| Поле             | Назначение                                                                  |
+| ---------------- | --------------------------------------------------------------------------- |
+| `scheme`         | схема данных проекта                                                        |
+| `sourceDir`      | папка с классами схемы: файлы, JSDoc, декораторы, типы полей                |
+| `bands`, `zones` | каркас карты; файлы вне зон попадают в зону «Без зоны»                      |
+| `hubMinSources`  | с какого числа ссылающихся коллекций модель считается хабом, по умолчанию 7 |
+| `tsconfig`       | tsconfig для разрешения типов; по умолчанию ближайший к конфигу             |
+| `watch`          | дополнительные пути для `dev`; папка конфига отслеживается всегда           |
+| `output`         | куда `build` пишет `<name>.html` и `<name>.svg`                             |
+| `spacing`        | отступы раскладки, см. `DEFAULT_SPACING`                                    |
+
+Описание модели — JSDoc `/** … */` над её классом, описание поля — JSDoc над свойством.
+
+## Команды
+
+```
+oxeo-visual dev    [--config <файл>] [--port <номер>] [--no-open]
+oxeo-visual build  [--config <файл>] [--out <папка>]
+```
+
+`dev` поднимает сервер на `127.0.0.1:4870` (если порт занят — следующий свободный) и открывает карту в браузере.
+Пока скрипт работает, изменения в папке конфига и в `watch` пересобирают карту. Страница перезагружается и
+сохраняет масштаб, выделение и поиск, а при ошибке сборки показывает её первую строку. `Ctrl+C` останавливает
+сервер, открытая страница сообщает, что карта больше не обновляется.
+
+`build` один раз собирает карту и пишет самодостаточный HTML (без сети работает всё, кроме веб-шрифтов) и
+статический SVG для документации.
+
+Каждая сборка идёт в отдельном процессе: декораторы oxeo регистрируют метаданные в глобальном хранилище, и
+повторная загрузка схемы в том же процессе их задвоила бы.
+
+## API
+
+```ts
+import { buildSchemeMap, extractScheme } from '@oxeo/visual'
+
+const { html, svg, metrics } = await buildSchemeMap(dataScheme, { sourceDir, tsconfig, config })
+```
+
+Маршрутизация связей — [libavoid-js](https://github.com/Aksem/libavoid-js) (LGPL-2.1).

package/bin/oxeo-visual.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli/index.js')

package/dist/build.d.ts

@@ -0,0 +1,23 @@
+import { type VisualConfig } from './config';
+import { type RoutingMetrics } from './layout/route';
+import type { SchemeModel } from './model';
+import type { SchemeSource } from './scheme-meta';
+export interface SchemeMapOptions {
+    sourceDir: string;
+    tsconfig?: string;
+    config: VisualConfig;
+}
+export interface SchemeMapResult {
+    html: string;
+    svg: string;
+    model: SchemeModel;
+    metrics: {
+        width: number;
+        height: number;
+        cards: number;
+        hubs: string[];
+        all: RoutingMetrics;
+        nohub: RoutingMetrics;
+    };
+}
+export declare const buildSchemeMap: (dataScheme: SchemeSource, { sourceDir, tsconfig, config }: SchemeMapOptions) => Promise<SchemeMapResult>;

package/dist/build.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSchemeMap = void 0;
+const config_1 = require("./config");
+const extract_1 = require("./extract");
+const cards_1 = require("./layout/cards");
+const place_1 = require("./layout/place");
+const route_1 = require("./layout/route");
+const html_1 = require("./render/html");
+const palette_1 = require("./render/palette");
+const svg_1 = require("./render/svg");
+const text_1 = require("./text");
+const buildSchemeMap = async (dataScheme, { sourceDir, tsconfig, config }) => {
+    const model = (0, extract_1.extractScheme)(dataScheme, { sourceDir, tsconfig });
+    const spacing = (0, config_1.resolveSpacing)(config);
+    const cards = new Map(model.entities.map((e) => [e.key, (0, cards_1.buildCard)(e, spacing)]));
+    const placement = (0, place_1.place)(model, cards, config, spacing);
+    const sources = new Map();
+    for (const r of model.relations) {
+        if (r.kind === 'own')
+            continue;
+        sources.set(r.target, (sources.get(r.target) ?? new Set()).add(r.source));
+    }
+    const sourcesCount = new Map([...sources].map(([key, set]) => [key, set.size]));
+    const hubs = new Set([...sourcesCount].filter(([, n]) => n >= (config.hubMinSources ?? 7)).map(([key]) => key));
+    const all = await (0, route_1.routeRelations)(model.relations, placement, cards, spacing);
+    const nohub = await (0, route_1.routeRelations)(model.relations.filter((r) => r.kind === 'own' || !hubs.has(r.target)), placement, cards, spacing);
+    const layers = { all: all.routes, nohub: nohub.routes };
+    const renderOptions = { config, spacing, placement, layers, hubs, sourcesCount };
+    const zones = placement.zones.map((z) => z.zone);
+    const zoneOf = Object.fromEntries([...placement.cards].map(([key, c]) => [key, c.zone]));
+    const data = {
+        generatedAt: new Date().toISOString(),
+        zones: zones.map((z) => ({ id: z.id, title: z.title, colorVar: (0, palette_1.zoneVar)(z.id) })),
+        entities: model.entities,
+        types: model.types,
+        relations: model.relations,
+        zoneOf,
+        hubs: [...hubs],
+        sources: Object.fromEntries(sourcesCount),
+        size: { width: placement.width, height: placement.height }
+    };
+    const meta = `${(0, text_1.plural)(model.entities.length, ['коллекция', 'коллекции', 'коллекций'])} · ${(0, text_1.plural)(model.relations.length, ['связь', 'связи', 'связей'])} · ${(0, text_1.plural)(model.files.length, ['файл', 'файла', 'файлов'])}`;
+    return {
+        html: (0, html_1.renderPage)({ zones, mapSvg: (0, svg_1.renderMapSvg)(renderOptions), data, meta }),
+        svg: (0, svg_1.renderMapSvg)({ ...renderOptions, standalone: true }),
+        model,
+        metrics: {
+            width: Math.round(placement.width),
+            height: Math.round(placement.height),
+            cards: cards.size,
+            hubs: [...hubs],
+            all: all.metrics,
+            nohub: nohub.metrics
+        }
+    };
+};
+exports.buildSchemeMap = buildSchemeMap;

package/dist/cli/build-command.d.ts

@@ -0,0 +1,5 @@
+export interface BuildOptions {
+    configPath: string;
+    out?: string;
+}
+export declare const buildOnce: ({ configPath, out }: BuildOptions) => Promise<void>;

package/dist/cli/build-command.js

@@ -0,0 +1,57 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOnce = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const output_1 = require("./output");
+const run_1 = require("./run");
+const buildOnce = async ({ configPath, out }) => {
+    const started = Date.now();
+    const message = await (0, run_1.startBuild)(configPath).done;
+    if (message.type === 'error') {
+        (0, output_1.log)(`сборка не удалась:\n${message.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    const dir = out ? path.resolve(out) : message.settings.output.dir;
+    const base = path.join(dir, message.settings.output.name);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(`${base}.html`, message.html);
+    fs.writeFileSync(`${base}.svg`, message.svg);
+    (0, output_1.log)((0, output_1.describeBuild)(message.metrics, Date.now() - started));
+    (0, output_1.log)(`${path.relative(process.cwd(), `${base}.html`)}, ${path.relative(process.cwd(), `${base}.svg`)}`);
+};
+exports.buildOnce = buildOnce;

package/dist/cli/dev.d.ts

@@ -0,0 +1,6 @@
+export interface DevOptions {
+    configPath: string;
+    port: number;
+    open: boolean;
+}
+export declare const dev: ({ configPath, port, open }: DevOptions) => Promise<void>;

package/dist/cli/dev.js

@@ -0,0 +1,274 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dev = void 0;
+const fs = __importStar(require("fs"));
+const http = __importStar(require("http"));
+const path = __importStar(require("path"));
+const open_1 = require("./open");
+const output_1 = require("./output");
+const run_1 = require("./run");
+const EVENTS_PATH = '/__xeo-visual/events';
+const IGNORED_DIRS = new Set(['node_modules', 'dist', 'build', 'coverage']);
+const WATCHED_FILE = /\.(c|m)?[jt]sx?$|\.json$/;
+const devClient = (build) => `
+<style>
+#xv-dev { position: fixed; left: 50%; bottom: 16px; transform: translateX(-50%); z-index: 100; max-width: min(720px, calc(100vw - 32px)); padding: 8px 14px; border-radius: 6px; font: 500 13px/1.45 system-ui, sans-serif; box-shadow: 0 8px 24px rgb(0 0 0 / 0.18); }
+#xv-dev[data-tone='info'] { background: var(--xv-surface, #fff); color: var(--xv-text, #18181b); border: 1px solid var(--xv-line-strong, #d4d4d8); }
+#xv-dev[data-tone='error'] { background: #b42318; color: #fff; }
+#xv-dev[data-tone='stop'] { background: #3f3f46; color: #fff; }
+</style>
+<script>
+;(() => {
+  const BUILD = ${JSON.stringify(build)}
+  const bar = document.createElement('div')
+  bar.id = 'xv-dev'
+  bar.setAttribute('role', 'status')
+  bar.hidden = true
+  document.body.appendChild(bar)
+  const show = (text, tone) => {
+    bar.textContent = text
+    bar.dataset.tone = tone
+    bar.hidden = false
+  }
+  const reload = () => {
+    try {
+      if (window.__xv) sessionStorage.setItem('xv-restore', JSON.stringify(window.__xv.state()))
+    } catch (e) {}
+    location.reload()
+  }
+  const events = new EventSource(${JSON.stringify(EVENTS_PATH)})
+  events.addEventListener('hello', (e) => {
+    const { build, error } = JSON.parse(e.data)
+    if (build && build !== BUILD) return reload()
+    if (error) show('Сборка не удалась: ' + error + ' — подробности в терминале', 'error')
+    else bar.hidden = true
+  })
+  events.addEventListener('building', () => show('Пересобираю карту…', 'info'))
+  events.addEventListener('built', (e) => {
+    if (JSON.parse(e.data).build !== BUILD) reload()
+  })
+  events.addEventListener('failed', (e) => {
+    show('Сборка не удалась: ' + JSON.parse(e.data).message + ' — подробности в терминале', 'error')
+  })
+  events.addEventListener('shutdown', () => {
+    events.close()
+    show('oxeo-visual остановлен: карта больше не обновляется', 'stop')
+  })
+  events.onerror = () => {
+    if (bar.dataset.tone !== 'stop') show('Нет связи с oxeo-visual: сервер остановлен или перезапускается', 'stop')
+  }
+})()
+</script>
+`;
+const waitingPage = () => `<!doctype html>
+<meta charset="utf-8" />
+<title>oxeo-visual</title>
+<style>
+body { margin: 0; height: 100vh; display: grid; place-items: center; background: #f6f6f7; color: #63636e; font: 14px/1.5 system-ui, sans-serif; }
+@media (prefers-color-scheme: dark) { body { background: #0c0c0e; color: #a3a3ad; } }
+</style>
+<p>Собираю карту схемы…</p>
+${devClient(null)}`;
+const watchTree = (root, listener) => {
+    const handles = [];
+    const add = (target) => {
+        try {
+            handles.push(fs.watch(target, (_event, file) => listener(file ? path.join(target, String(file)) : target)));
+        }
+        catch { }
+    };
+    const visit = (dir) => {
+        add(dir);
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isDirectory() && !IGNORED_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+                visit(path.join(dir, entry.name));
+            }
+        }
+    };
+    if (fs.statSync(root).isDirectory())
+        visit(root);
+    else
+        add(root);
+    return () => handles.forEach((handle) => handle.close());
+};
+const listen = async (server, port) => {
+    for (let candidate = port; candidate < port + 20; candidate++) {
+        try {
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(candidate, '127.0.0.1', () => {
+                    server.off('error', reject);
+                    resolve();
+                });
+            });
+            return candidate;
+        }
+        catch (error) {
+            if (error.code !== 'EADDRINUSE')
+                throw error;
+        }
+    }
+    throw new Error(`порты ${port}–${port + 19} заняты, укажите другой: --port <номер>`);
+};
+const dev = async ({ configPath, port, open }) => {
+    let html = null;
+    let svg = null;
+    let build = null;
+    let error = null;
+    let current = null;
+    let queued = false;
+    let stopping = false;
+    const clients = new Set();
+    const broadcast = (event, data = {}) => {
+        for (const res of clients)
+            res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    };
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        if (url.pathname === EVENTS_PATH) {
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream; charset=utf-8',
+                'Cache-Control': 'no-cache',
+                Connection: 'keep-alive'
+            });
+            res.write(`event: hello\ndata: ${JSON.stringify({ build, error: error && (0, output_1.firstLine)(error) })}\n\n`);
+            clients.add(res);
+            req.on('close', () => clients.delete(res));
+            return;
+        }
+        if (url.pathname === '/' || url.pathname === '/index.html') {
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+            res.end(html ? html + devClient(build) : waitingPage());
+            return;
+        }
+        if (url.pathname.endsWith('.svg') && svg) {
+            res.writeHead(200, {
+                'Content-Type': 'image/svg+xml; charset=utf-8',
+                'Cache-Control': 'no-store'
+            });
+            res.end(svg);
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+        res.end('Не найдено');
+    });
+    const ping = setInterval(() => clients.forEach((res) => res.write(': ping\n\n')), 25_000);
+    const stoppers = new Map();
+    let timer = null;
+    let changed = '';
+    const onChange = (file) => {
+        if (stopping || !WATCHED_FILE.test(file))
+            return;
+        changed = file;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            (0, output_1.log)(`изменение: ${path.relative(process.cwd(), changed) || changed}`);
+            void rebuild();
+        }, 200);
+    };
+    const watch = (roots) => {
+        const unique = roots.filter((root) => !roots.some((other) => root !== other && root.startsWith(other + path.sep)));
+        for (const [root, stop] of stoppers) {
+            if (!unique.includes(root)) {
+                stop();
+                stoppers.delete(root);
+            }
+        }
+        for (const root of unique) {
+            if (!stoppers.has(root) && fs.existsSync(root))
+                stoppers.set(root, watchTree(root, onChange));
+        }
+    };
+    const rebuild = async () => {
+        if (current) {
+            queued = true;
+            return;
+        }
+        const started = Date.now();
+        broadcast('building');
+        current = (0, run_1.startBuild)(configPath);
+        const message = await current.done;
+        current = null;
+        if (stopping)
+            return;
+        if (message.type === 'result') {
+            html = message.html;
+            svg = message.svg;
+            error = null;
+            build = String(started);
+            (0, output_1.log)((0, output_1.describeBuild)(message.metrics, Date.now() - started));
+            broadcast('built', { build });
+            watch(message.settings.watch);
+        }
+        else {
+            error = message.message;
+            (0, output_1.log)(`сборка не удалась:\n${message.message}`);
+            broadcast('failed', { message: (0, output_1.firstLine)(message.message) });
+        }
+        if (queued) {
+            queued = false;
+            void rebuild();
+        }
+    };
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        broadcast('shutdown');
+        clients.forEach((res) => res.end());
+        clearInterval(ping);
+        if (timer)
+            clearTimeout(timer);
+        stoppers.forEach((stopWatching) => stopWatching());
+        current?.child.kill();
+        server.close(() => process.exit(0));
+        setTimeout(() => process.exit(0), 500).unref();
+        (0, output_1.log)('остановлен');
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    process.on('SIGHUP', stop);
+    const actualPort = await listen(server, port);
+    const url = `http://127.0.0.1:${actualPort}`;
+    (0, output_1.log)(`карта схемы: ${url} — Ctrl+C, чтобы остановить`);
+    watch([path.dirname(configPath)]);
+    if (open)
+        (0, open_1.openBrowser)(url);
+    await rebuild();
+};
+exports.dev = dev;

package/dist/cli/index.d.ts

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

package/dist/cli/index.js

@@ -0,0 +1,104 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const project_1 = require("../project");
+const build_command_1 = require("./build-command");
+const dev_1 = require("./dev");
+const output_1 = require("./output");
+const HELP = `oxeo-visual — карта схемы данных oxeo
+
+  oxeo-visual dev    [--config <файл>] [--port <номер>] [--no-open]
+  oxeo-visual build  [--config <файл>] [--out <папка>]
+
+  dev    сервер с картой в браузере: пересобирает карту при изменении схемы,
+         останавливается вместе со скриптом (Ctrl+C)
+  build  пишет <name>.html и <name>.svg в output.dir из конфига или в --out
+
+  Конфиг по умолчанию — ${project_1.CONFIG_FILES.join(', ')} в текущей папке.
+`;
+const DEFAULT_PORT = 4870;
+const parse = (argv) => {
+    const [command, ...rest] = argv;
+    const flags = new Map();
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (!arg.startsWith('--'))
+            continue;
+        const [name, inline] = arg.slice(2).split('=', 2);
+        if (inline !== undefined)
+            flags.set(name, inline);
+        else if (rest[i + 1] && !rest[i + 1].startsWith('--'))
+            flags.set(name, rest[++i]);
+        else
+            flags.set(name, true);
+    }
+    return { command, flags };
+};
+const findConfig = (explicit) => {
+    if (explicit) {
+        const file = path.resolve(explicit);
+        if (!fs.existsSync(file))
+            throw new Error(`конфиг не найден: ${file}`);
+        return file;
+    }
+    const found = project_1.CONFIG_FILES.map((name) => path.resolve(name)).find((file) => fs.existsSync(file));
+    if (!found)
+        throw new Error(`нет ${project_1.CONFIG_FILES[0]} в ${process.cwd()} — создайте его или укажите --config`);
+    return found;
+};
+const main = async () => {
+    const { command, flags } = parse(process.argv.slice(2));
+    const value = (name) => typeof flags.get(name) === 'string' ? flags.get(name) : undefined;
+    if (command === 'dev') {
+        const port = Number(value('port') ?? process.env.OXEO_VISUAL_PORT ?? DEFAULT_PORT);
+        if (!Number.isInteger(port) || port <= 0)
+            throw new Error(`неверный порт: ${value('port')}`);
+        await (0, dev_1.dev)({ configPath: findConfig(value('config')), port, open: !flags.has('no-open') });
+    }
+    else if (command === 'build') {
+        await (0, build_command_1.buildOnce)({ configPath: findConfig(value('config')), out: value('out') });
+    }
+    else {
+        process.stdout.write(HELP);
+        if (command && command !== 'help' && command !== '--help')
+            process.exitCode = 1;
+    }
+};
+main().catch((error) => {
+    (0, output_1.log)(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/cli/open.d.ts

@@ -0,0 +1 @@
+export declare const openBrowser: (url: string) => void;

package/dist/cli/open.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openBrowser = void 0;
+const child_process_1 = require("child_process");
+const output_1 = require("./output");
+const openBrowser = (url) => {
+    const [command, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '""', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = (0, child_process_1.spawn)(command, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => (0, output_1.log)(`откройте в браузере: ${url}`));
+        child.unref();
+    }
+    catch {
+        (0, output_1.log)(`откройте в браузере: ${url}`);
+    }
+};
+exports.openBrowser = openBrowser;

package/dist/cli/output.d.ts

@@ -0,0 +1,4 @@
+import type { SchemeMapResult } from '../build';
+export declare const log: (message: string) => void;
+export declare const firstLine: (text: string) => string;
+export declare const describeBuild: (metrics: SchemeMapResult["metrics"], ms: number) => string;