@atolis-hq/corum 0.1.0

package/dist/src/web/server.js

@@ -0,0 +1,557 @@
+import express from 'express';
+import path from 'node:path';
+import { existsSync, readFileSync, readdirSync, watch } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import { computeClusterOverlay, getClusterView, listNodes } from '../graph/index.js';
+import { loadGraph, loadMultiGraph } from '../loader/index.js';
+import { VALID_EDGE_TYPE_SET } from '../loader/constants.js';
+import { getOwnedSections } from '../loader/pack-loader.js';
+import { QueryError } from '../schema/index.js';
+import { createGraphRuntimeConfig } from '../source/config.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const WEB_DIR = path.join(__dirname, '..', '..', '..', 'web');
+function createMultiGraphCache(source) {
+    let cache = null;
+    return {
+        async get() {
+            if (!cache)
+                cache = await loadMultiGraph({ source });
+            return cache;
+        },
+        invalidate() {
+            cache = null;
+        },
+    };
+}
+async function getGraphForRef(ref, cache, fallback) {
+    const multi = await cache.get();
+    const branch = multi.branches.find(item => item.ref === ref);
+    return branch?.graph ?? fallback;
+}
+async function getPluginFiles() {
+    try {
+        const files = await readdir(path.join(WEB_DIR, 'plugins'));
+        return files.filter(file => file.endsWith('.jsx'));
+    }
+    catch {
+        return [];
+    }
+}
+function getNavigationOwnership(graph, node) {
+    let match;
+    for (const parent of graph.nodesById.values()) {
+        if (parent.id === node.id)
+            continue;
+        const parentTemplate = graph.templates.get(parent.template);
+        if (!parentTemplate)
+            continue;
+        for (const [section, childTemplate] of Object.entries(getOwnedSections(parentTemplate))) {
+            if (childTemplate !== node.template)
+                continue;
+            if (!node.id.startsWith(`${parent.id}.${section}.`))
+                continue;
+            if (!match || parent.id.length > match.parentId.length) {
+                match = { parentId: parent.id, ownedSection: section };
+            }
+        }
+    }
+    return match;
+}
+function summarizeNodeForNavigation(graph, node) {
+    const ownership = getNavigationOwnership(graph, node);
+    return {
+        ...node,
+        ...(ownership ?? {}),
+    };
+}
+function resolveNodeRef(graph, node, rawValue) {
+    if (rawValue.startsWith('#/schemas/')) {
+        const name = rawValue.slice(10);
+        const id = `${node.id}.schemas.${name}`;
+        return graph.nodesById.has(id) ? { display: name, nodeId: id } : { display: name };
+    }
+    if (rawValue.startsWith('#/enums/')) {
+        const name = rawValue.slice(8);
+        const id = `${node.id}.enums.${name}`;
+        return graph.nodesById.has(id) ? { display: name, nodeId: id } : { display: name };
+    }
+    if (graph.nodesById.has(rawValue))
+        return { display: rawValue, nodeId: rawValue };
+    return { display: rawValue };
+}
+function getPropertySchemas(templateProperties) {
+    if (Array.isArray(templateProperties.allOf)) {
+        const merged = {};
+        for (const schema of templateProperties.allOf) {
+            Object.assign(merged, getPropertySchemas(schema));
+        }
+        return merged;
+    }
+    if (typeof templateProperties.properties === 'object' && templateProperties.properties !== null) {
+        return templateProperties.properties;
+    }
+    return {};
+}
+function annotateNodeRefProperties(graph, node, template) {
+    if (!template.properties)
+        return node.properties;
+    const propSchemas = getPropertySchemas(template.properties);
+    const result = { ...node.properties };
+    for (const [key, schema] of Object.entries(propSchemas)) {
+        const value = result[key];
+        if (value === undefined)
+            continue;
+        if (schema.format === 'node-ref' && typeof value === 'string') {
+            result[key] = resolveNodeRef(graph, node, value);
+        }
+        else if (schema.type === 'object' &&
+            typeof schema.additionalProperties === 'object' &&
+            schema.additionalProperties !== null &&
+            schema.additionalProperties.format === 'node-ref' &&
+            typeof value === 'object' &&
+            value !== null &&
+            !Array.isArray(value)) {
+            result[key] = Object.fromEntries(Object.entries(value).map(([k, v]) => typeof v === 'string' ? [k, resolveNodeRef(graph, node, v)] : [k, v]));
+        }
+    }
+    return result;
+}
+function annotateNode(graph, node) {
+    const template = graph.templates.get(node.template);
+    return template ? { ...node, properties: annotateNodeRefProperties(graph, node, template) } : node;
+}
+function parseIncludeEdges(value) {
+    if (typeof value !== 'string' || value.trim() === '')
+        return [];
+    const types = value
+        .split(',')
+        .map(item => item.trim())
+        .filter((item) => VALID_EDGE_TYPE_SET.has(item));
+    return [...new Set(types)];
+}
+function createReloadEvents() {
+    const clients = new Set();
+    let version = 0;
+    return {
+        subscribe(res) {
+            clients.add(res);
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                Connection: 'keep-alive',
+            });
+            res.write(`event: connected\ndata: ${JSON.stringify({ version })}\n\n`);
+            res.on('close', () => clients.delete(res));
+        },
+        notify() {
+            version += 1;
+            const payload = `event: graph-reloaded\ndata: ${JSON.stringify({ version })}\n\n`;
+            for (const client of clients) {
+                client.write(payload);
+            }
+        },
+    };
+}
+function replaceGraph(target, source) {
+    target.nodesById = source.nodesById;
+    target.edgesByFrom = source.edgesByFrom;
+    target.edgesByTo = source.edgesByTo;
+    target.templates = source.templates;
+    target.diagnostics = source.diagnostics;
+}
+function isFileWatcherEnabled(options) {
+    if (options.fileWatcher !== undefined)
+        return options.fileWatcher;
+    const value = process.env.CORUM_FILE_WATCHER ?? process.env.CORUM_WATCH;
+    return value === '1' || value === 'true' || value === 'yes';
+}
+function resolvePackDirs(graphPath) {
+    const graphYamlPath = path.join(graphPath, 'graph.yaml');
+    if (!existsSync(graphYamlPath)) {
+        return [path.resolve(graphPath, '.corum/packs')];
+    }
+    try {
+        const doc = parseYaml(readFileSync(graphYamlPath, 'utf-8'));
+        const packs = Array.isArray(doc.templatePacks) ? doc.templatePacks : [];
+        return packs
+            .filter((pack) => typeof pack === 'object' && pack !== null && typeof pack.path === 'string')
+            .map(pack => path.resolve(graphPath, pack.path));
+    }
+    catch {
+        return [];
+    }
+}
+function listDirectories(root) {
+    if (!existsSync(root))
+        return [];
+    const dirs = [root];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            dirs.push(...listDirectories(path.join(root, entry.name)));
+        }
+    }
+    return dirs;
+}
+function watchRoot(root, onChange) {
+    if (!existsSync(root))
+        return [];
+    try {
+        return [watch(root, { recursive: true }, (_eventType, filename) => onChange(filename))];
+    }
+    catch {
+        return listDirectories(root).map(dir => watch(dir, (_eventType, filename) => onChange(filename)));
+    }
+}
+function isRelevantWatchEvent(filename) {
+    if (!filename)
+        return true;
+    const name = String(filename).replace(/\\/g, '/');
+    return name.endsWith('.yaml') || name.endsWith('.yml');
+}
+export function startGraphFileWatcher(graph, options) {
+    const { graphPath, onReload } = options;
+    const logger = options.logger ?? console.error;
+    const debounceMs = options.debounceMs ?? 150;
+    let watchers = [];
+    let timer;
+    let reloading = false;
+    function closeWatchers() {
+        for (const watcher of watchers)
+            watcher.close();
+        watchers = [];
+    }
+    function refreshWatchers() {
+        closeWatchers();
+        const roots = [...new Set([path.resolve(graphPath), ...resolvePackDirs(graphPath)])];
+        watchers = roots.flatMap(root => watchRoot(root, scheduleReload));
+    }
+    async function reload() {
+        if (reloading)
+            return;
+        reloading = true;
+        try {
+            const nextGraph = await loadGraph({ graphPath, strict: true });
+            replaceGraph(graph, nextGraph);
+            refreshWatchers();
+            onReload?.();
+            logger(`[corum] graph reloaded after file change`);
+        }
+        catch (err) {
+            logger(`[corum] graph reload failed: ${err}`);
+        }
+        finally {
+            reloading = false;
+        }
+    }
+    function scheduleReload(filename) {
+        if (!isRelevantWatchEvent(filename))
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            void reload();
+        }, debounceMs);
+    }
+    refreshWatchers();
+    logger(`[corum] file watcher enabled`);
+    return () => {
+        if (timer)
+            clearTimeout(timer);
+        closeWatchers();
+    };
+}
+export function createApp(graph, reloadEvents = createReloadEvents(), source, multiCache, onReloadRequest) {
+    const app = express();
+    app.get('/health', (_req, res) => {
+        res.json({ ok: true });
+    });
+    app.get('/api/events', (_req, res) => {
+        reloadEvents.subscribe(res);
+    });
+    app.get('/api/templates', async (req, res) => {
+        const includeCore = req.query.includeCore === 'true';
+        let targetGraph = graph;
+        if (typeof req.query.ref === 'string' && multiCache) {
+            targetGraph = await getGraphForRef(req.query.ref, multiCache, graph);
+        }
+        const templates = [...targetGraph.templates.values()]
+            .filter(template => includeCore || !template.info?.core)
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map(template => ({
+            name: template.name,
+            version: template.info?.version,
+            core: template.info?.core ?? false,
+            abstract: template.info?.abstract ?? false,
+            extends: template.extends,
+            description: template.info?.description,
+            ui: template.ui,
+        }));
+        res.json(templates);
+    });
+    app.get('/api/nodes', async (req, res) => {
+        const { template, component, state, stability } = req.query;
+        const includeCore = req.query.includeCore === 'true';
+        const filter = {
+            template: typeof template === 'string' ? template : undefined,
+            component: typeof component === 'string' ? component : undefined,
+            state: typeof state === 'string' ? state : undefined,
+            stability: typeof stability === 'string' ? stability : undefined,
+        };
+        let targetGraph = graph;
+        if (typeof req.query.ref === 'string' && multiCache) {
+            targetGraph = await getGraphForRef(req.query.ref, multiCache, graph);
+        }
+        const nodes = listNodes(targetGraph, filter)
+            .filter(node => includeCore || !targetGraph.templates.get(node.template)?.info?.core)
+            .map(node => {
+            const ownership = summarizeNodeForNavigation(targetGraph, node);
+            return {
+                id: ownership.id,
+                template: ownership.template,
+                component: ownership.component,
+                state: ownership.state,
+                stability: ownership.stability,
+                parentId: ownership.parentId,
+                ownedSection: ownership.ownedSection,
+            };
+        });
+        res.json(nodes);
+    });
+    app.get('/api/cluster', async (req, res) => {
+        const nodeId = typeof req.query.nodeId === 'string' ? req.query.nodeId : undefined;
+        if (!nodeId) {
+            res.status(400).json({ error: 'nodeId query param required' });
+            return;
+        }
+        try {
+            let targetGraph = graph;
+            if (typeof req.query.ref === 'string' && multiCache) {
+                targetGraph = await getGraphForRef(req.query.ref, multiCache, graph);
+            }
+            const cluster = getClusterView(targetGraph, nodeId, parseIncludeEdges(req.query.includeEdges));
+            const rawOverlayRefs = req.query.overlayRefs;
+            const overlayRefs = Array.isArray(rawOverlayRefs)
+                ? rawOverlayRefs.filter((r) => typeof r === 'string' && r.length > 0)
+                : typeof rawOverlayRefs === 'string' && rawOverlayRefs.length > 0
+                    ? [rawOverlayRefs]
+                    : [];
+            let overlay = null;
+            if (overlayRefs.length > 0 && multiCache && typeof req.query.ref === 'string') {
+                const multi = await multiCache.get();
+                overlay = computeClusterOverlay(multi, req.query.ref, overlayRefs, nodeId);
+            }
+            res.json({
+                root: summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, cluster.root)),
+                descendants: cluster.descendants.map(child => summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, child))),
+                includedNodes: cluster.includedNodes.map(node => summarizeNodeForNavigation(targetGraph, annotateNode(targetGraph, node))),
+                edges: cluster.edges,
+                overlay,
+            });
+        }
+        catch (err) {
+            if (err instanceof QueryError) {
+                res.status(404).json({ error: err.message });
+            }
+            else {
+                res.status(500).json({ error: 'Internal server error' });
+            }
+        }
+    });
+    app.get('/api/plugins', (_req, res) => {
+        getPluginFiles()
+            .then(files => res.json(files))
+            .catch(() => res.json([]));
+    });
+    app.get('/api/branches', async (_req, res) => {
+        if (!source) {
+            res.status(501).json({ error: 'multi-branch requires a configured source' });
+            return;
+        }
+        try {
+            const multi = multiCache ? await multiCache.get() : await loadMultiGraph({ source });
+            res.json({
+                default: multi.default.ref,
+                branches: multi.branches.map(branch => ({
+                    ref: branch.ref,
+                    isDefault: branch.isDefault,
+                })),
+                results: multi.branchResults,
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : 'Internal server error' });
+        }
+    });
+    app.post('/api/reload', async (_req, res) => {
+        try {
+            await onReloadRequest?.();
+            res.status(202).json({ ok: true });
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : 'Internal server error' });
+        }
+    });
+    app.get('/api/overlay/:ref(*)', async (req, res) => {
+        if (!source) {
+            res.status(501).json({ error: 'multi-branch requires a configured source' });
+            return;
+        }
+        try {
+            const multi = multiCache ? await multiCache.get() : await loadMultiGraph({ source });
+            const overlay = multi.overlay(req.params.ref);
+            res.json({
+                viewingRef: overlay.viewingRef,
+                nodes: [...overlay.nodes.values()].map(node => ({
+                    id: node.id,
+                    ghostState: node.ghostState,
+                    branches: [...node.presence.keys()],
+                    node: node.presence.get(overlay.viewingRef) ?? [...node.presence.values()][0],
+                })),
+            });
+        }
+        catch (err) {
+            if (err instanceof QueryError) {
+                res.status(400).json({ error: err.message });
+            }
+            else {
+                res.status(500).json({ error: err instanceof Error ? err.message : 'Internal server error' });
+            }
+        }
+    });
+    app.use(express.static(WEB_DIR, {
+        setHeaders(res, filePath) {
+            if (filePath.endsWith('.jsx')) {
+                res.setHeader('Content-Type', 'text/babel; charset=utf-8');
+            }
+        },
+    }));
+    return app;
+}
+export function startWebServer(graph, options = {}) {
+    const portSource = options.port !== undefined
+        ? 'options.port'
+        : process.env.CORUM_WEB_PORT !== undefined
+            ? 'CORUM_WEB_PORT'
+            : 'default';
+    const graphPathSource = options.graphPath !== undefined
+        ? 'options.graphPath'
+        : process.env.CORUM_GRAPH_PATH !== undefined
+            ? 'CORUM_GRAPH_PATH'
+            : 'default';
+    const port = options.port ?? parseInt(process.env.CORUM_WEB_PORT ?? '3000', 10);
+    const graphPath = options.graphPath ?? process.env.CORUM_GRAPH_PATH ?? path.join(process.cwd(), '.corum/graph');
+    const logger = options.logger ?? console.error;
+    const reloadEvents = createReloadEvents();
+    const multiCache = options.source ? createMultiGraphCache(options.source) : undefined;
+    let reloadInFlight = null;
+    async function reloadState(reason) {
+        if (reloadInFlight)
+            return reloadInFlight;
+        reloadInFlight = (async () => {
+            const nextGraph = options.source
+                ? await loadGraph({ source: options.source, strict: true })
+                : await loadGraph({ graphPath, strict: true });
+            replaceGraph(graph, nextGraph);
+            multiCache?.invalidate();
+            reloadEvents.notify();
+            logger(`[corum] graph reloaded after ${reason}`);
+        })();
+        try {
+            await reloadInFlight;
+        }
+        finally {
+            reloadInFlight = null;
+        }
+    }
+    const app = createApp(graph, reloadEvents, options.source, multiCache, () => reloadState('manual reload'));
+    const stopWatcher = isFileWatcherEnabled(options)
+        ? startGraphFileWatcher(graph, {
+            graphPath,
+            debounceMs: options.fileWatcherDebounceMs,
+            logger,
+            onReload: () => {
+                multiCache?.invalidate();
+                reloadEvents.notify();
+            },
+        })
+        : undefined;
+    const stopPoller = startGitSourcePoller(options.source, options.gitPollSeconds, logger, () => reloadState('git poll'));
+    return new Promise((resolve, reject) => {
+        const server = app.listen(port, () => {
+            const addr = server.address();
+            if (options.port !== 0) {
+                // graphPath is informational only — the graph object was already loaded by the caller
+                logger(`[corum web] config graphPath=${graphPath} (${graphPathSource})`);
+                logger(`[corum web] config port=${addr.port} (${portSource})`);
+                logger(`[corum web] config webDir=${WEB_DIR}`);
+                logger(`[corum web] http://localhost:${addr.port}`);
+            }
+            resolve({
+                port: addr.port,
+                close: () => new Promise((res, rej) => {
+                    stopWatcher?.();
+                    stopPoller?.();
+                    server.close(err => (err ? rej(err) : res()));
+                }),
+            });
+        });
+        server.on('error', reject);
+    });
+}
+function startGitSourcePoller(source, pollSeconds, logger, onChange) {
+    if (!source || !pollSeconds || !hasReloadSignature(source))
+        return undefined;
+    const pollableSource = source;
+    let timer;
+    let stopped = false;
+    let inFlight = false;
+    let lastSignature = null;
+    async function check() {
+        if (stopped || inFlight)
+            return;
+        inFlight = true;
+        try {
+            const signature = await pollableSource.reloadSignature();
+            if (lastSignature !== null && signature !== lastSignature) {
+                await onChange();
+            }
+            lastSignature = signature;
+        }
+        catch (err) {
+            logger(`[corum] git poll failed: ${err}`);
+        }
+        finally {
+            inFlight = false;
+        }
+    }
+    void check();
+    timer = setInterval(() => {
+        void check();
+    }, pollSeconds * 1000);
+    logger(`[corum] git poll enabled (${pollSeconds}s)`);
+    return () => {
+        stopped = true;
+        if (timer)
+            clearInterval(timer);
+    };
+}
+function hasReloadSignature(source) {
+    return typeof source.reloadSignature === 'function';
+}
+function isEntrypoint() {
+    return process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+}
+if (isEntrypoint()) {
+    const config = createGraphRuntimeConfig();
+    const graph = await loadGraph({ source: config.source, strict: true });
+    await startWebServer(graph, {
+        graphPath: config.graphPath,
+        source: config.source,
+        gitPollSeconds: config.gitPollSeconds,
+        fileWatcher: config.fileWatcherGraphPath && process.argv.includes('--watch') ? true : undefined,
+    });
+}