@yarkivaev/scada 2.3.62 → 2.3.64

package/README.md

@@ -71,6 +71,8 @@ PostgreSQL ← STOMP alerts (via plantServer)
 plantApi → REST + SSE → frontend / @yarkivaev/scada/client
 ```
 
+`GET /api/v1/topology` returns `{ plant, nodes, links }` from `plant.topology()` or a shop/machine/sensor walk, then paints `status` from live `sensor.current()` freshness (`ok` / `degraded` / `down`). Nodes without a matching sensor stay `unknown`. `GET /infra` serves a generic SVG of that graph. Optional node `inspect: { host, port }` is reached same-origin at `/infra/inspect/:id` (CDP `Host` is loopback).
+
 **Supervisor-sink** (write path):
 
 ```
@@ -89,7 +91,8 @@ Main entry (`import { … } from '@yarkivaev/scada'`):
 |--------|---------|
 | `plant`, `shop`, `machine` | Domain hierarchy |
 | `timeline`, `alerts`, `alert`, `acknowledgedAlert` | Timeline and alerting |
-| `plantApi`, `plantServer`, `siteServer` | HTTP composition |
+| `plantApi`, `plantServer`, `siteServer`, `topologyFromPlant`, `topologyHealth` | HTTP composition and topology graph |
+
 | `exportQuery`, `exportStream`, `exportSink`, `exportJob` | Generic export ports over plantApi / `@yarkivaev/scada/client` |
 | `siteSync`, `siteSyncSites`, `siteSyncBind` | Pull kinds from an allowlisted remote plantApi into local persistence |
 | `metricsPlant`, `shopWithTimeline`, `machineInPlant` | Plant wiring helpers |

package/index.js

@@ -14,6 +14,8 @@ export { default as initialized } from './src/domain/shared/initialized.js';
 export { default as pubsub } from './src/domain/shared/pubsub.js';
 
 export { default as plantApi } from './src/application/plantApi.js';
+export { default as topologyFromPlant } from './src/application/topologyFromPlant.js';
+export { default as topologyHealth } from './src/application/topologyHealth.js';
 export { default as tagCatalog } from './src/infrastructure/catalog/tagCatalog.js';
 export { default as machineInPlant } from './src/application/machineInPlant.js';
 export { default as shopWithTimeline } from './src/application/shopWithTimeline.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarkivaev/scada",
-  "version": "2.3.62",
+  "version": "2.3.64",
   "description": "SCADA domain objects, state persistence, and plant monitoring",
   "repository": {
     "type": "git",

package/src/application/plantApi.js

@@ -11,6 +11,9 @@ import operationStream from '../infrastructure/http/plant/streams/operationStrea
 import heartbeatStream from '../infrastructure/http/plant/streams/heartbeatStream.js';
 import simulationRoute from '../infrastructure/http/plant/routes/simulationRoute.js';
 import catalogRoute from '../infrastructure/http/plant/routes/catalogRoute.js';
+import topologyRoute from '../infrastructure/http/plant/routes/topologyRoute.js';
+import infraRoute from '../infrastructure/http/plant/routes/infraRoute.js';
+import inspectRoute from '../infrastructure/http/plant/routes/inspectRoute.js';
 import { routes } from '@yarkivaev/simple-server';
 
 function pass(_id, rows) {
@@ -38,6 +41,7 @@ export default function plantApi(basePath, plant, config) {
     const decorate = opts.decorateTimeline || pass;
     const routeList = [
         ...catalogRoute(basePath, opts.tagCatalog),
+        ...topologyRoute(basePath, plant, time),
         ...machineRoute(basePath, plant),
         ...stateRoute(basePath, plant),
         ...measurementStream(basePath, plant, time),
@@ -50,6 +54,8 @@ export default function plantApi(basePath, plant, config) {
         ...operationStream(basePath, plant, time),
         ...heartbeatStream(basePath, time, opts.heartbeat),
         ...(time.jump ? simulationRoute(basePath, time) : []),
+        ...infraRoute(),
+        ...inspectRoute(plant),
         ...extra
     ];
     return routes(routeList, { requestTimeoutMs: opts.requestTimeoutMs });

package/src/application/plantServer.js

@@ -8,6 +8,7 @@ import stompTimelineSegments from '../infrastructure/messaging/stomp/stompTimeli
 import userDecisions from '../infrastructure/messaging/stomp/userDecisions.js';
 import segmentRetags from '../infrastructure/messaging/stomp/segmentRetags.js';
 import { parseRequestTimeoutMs, virtualClock } from '@yarkivaev/simple-server';
+import inspectUpgrade from '../infrastructure/http/plant/inspect/inspectUpgrade.js';
 
 function stompCollectorFactory(stompUrl, destination, credentials) {
     return (collector) => {
@@ -108,6 +109,9 @@ export default async function plantServer(config) {
     const server = http.createServer((req, res) => {
         return api.handle(req, res);
     });
+    server.on('upgrade', (req, socket, head) => {
+        inspectUpgrade(p, req, socket, head);
+    });
     await new Promise((resolve) => {
         server.listen(config.port, resolve);
     });

package/src/application/topologyFromPlant.js

@@ -0,0 +1,85 @@
+/**
+ * Builds the plant topology JSON contract.
+ * An explicit plant.topology() function wins; otherwise the shop/machine/sensor tree is walked.
+ *
+ * @param {object} plant - plant with shops and optional topology()
+ * @returns {object} { plant, nodes, links }
+ *
+ * @example
+ *   topologyFromPlant(plant);
+ */
+function assertGraph(graph) {
+    if (!graph || typeof graph !== 'object') {
+        throw new Error(`topology graph is missing: ${graph}`);
+    }
+    if (!graph.plant || typeof graph.plant.id !== 'string' || typeof graph.plant.title !== 'string') {
+        throw new Error(`topology plant id and title are required: ${JSON.stringify(graph.plant)}`);
+    }
+    if (!Array.isArray(graph.nodes) || !Array.isArray(graph.links)) {
+        throw new Error('topology nodes and links arrays are required');
+    }
+    graph.nodes.forEach((node) => {
+        if (typeof node.id !== 'string' || typeof node.kind !== 'string' || typeof node.title !== 'string') {
+            throw new Error(`topology node requires id, kind, title: ${JSON.stringify(node)}`);
+        }
+    });
+    graph.links.forEach((link) => {
+        if (typeof link.from !== 'string' || typeof link.to !== 'string' || typeof link.kind !== 'string') {
+            throw new Error(`topology link requires from, to, kind: ${JSON.stringify(link)}`);
+        }
+    });
+    return graph;
+}
+
+function collectors(machineId, item) {
+    const nodes = [];
+    const links = [];
+    Object.keys(item.sensors || {}).forEach((key) => {
+        nodes.push({
+            id: `${machineId}-${key}`,
+            kind: 'collector',
+            title: key,
+            parent: machineId,
+            status: 'unknown'
+        });
+        links.push({ from: machineId, to: `${machineId}-${key}`, kind: 'contains' });
+    });
+    return { nodes, links };
+}
+
+function shopGraph(shopId, area) {
+    const nodes = [{ id: shopId, kind: 'shop', title: area.name(), status: 'unknown' }];
+    const links = [];
+    Object.entries(area.machines.get()).forEach(([machineId, item]) => {
+        nodes.push({
+            id: machineId,
+            kind: 'machine',
+            title: item.name(),
+            parent: shopId,
+            status: 'unknown'
+        });
+        links.push({ from: shopId, to: machineId, kind: 'contains' });
+        const nested = collectors(machineId, item);
+        nodes.push(...nested.nodes);
+        links.push(...nested.links);
+    });
+    return { nodes, links };
+}
+
+function walkGraph(plant) {
+    const nodes = [];
+    const links = [];
+    Object.entries(plant.shops.get()).forEach(([shopId, area]) => {
+        const piece = shopGraph(shopId, area);
+        nodes.push(...piece.nodes);
+        links.push(...piece.links);
+    });
+    return { plant: { id: 'plant', title: 'plant' }, nodes, links };
+}
+
+export default function topologyFromPlant(plant) {
+    if (typeof plant.topology === 'function') {
+        return assertGraph(plant.topology());
+    }
+    return walkGraph(plant);
+}

package/src/application/topologyHealth.js

@@ -0,0 +1,128 @@
+/**
+ * Paints topology node status from live sensor current() readings.
+ * Does not read kube or Prometheus. Unmatched nodes keep their existing status.
+ *
+ * @param {object} graph - topology contract { plant, nodes, links }
+ * @param {object} plant - plant with shops().get() machines and sensors
+ * @param {function} [clock] - () => Date
+ * @returns {Promise<object>} graph with status overlays
+ *
+ * @example
+ *   await topologyHealth(graph, plant, () => new Date());
+ */
+function age(reading, now) {
+    if (!reading || reading.found !== true || !reading.timestamp) {
+        return Number.POSITIVE_INFINITY;
+    }
+    return now.getTime() - new Date(reading.timestamp).getTime();
+}
+
+function grade(ms) {
+    if (!Number.isFinite(ms)) {
+        return 'down';
+    }
+    if (ms <= 300000) {
+        return 'ok';
+    }
+    if (ms <= 1800000) {
+        return 'degraded';
+    }
+    return 'down';
+}
+
+function rollup(states) {
+    if (states.length === 0) {
+        return undefined;
+    }
+    if (states.every((item) => {
+        return item === 'ok';
+    })) {
+        return 'ok';
+    }
+    if (states.every((item) => {
+        return item === 'down';
+    })) {
+        return 'down';
+    }
+    return 'degraded';
+}
+
+async function sample(id, item, now) {
+    try {
+        return [id, grade(age(await item.current(), now))];
+    } catch {
+        return [id, 'down'];
+    }
+}
+
+async function probeMachine(machineId, item, now) {
+    const keys = Object.keys(item.sensors || {});
+    const pairs = await Promise.all(keys.map((key) => {
+        return sample(`${machineId}-${key}`, item.sensors[key], now);
+    }));
+    const status = rollup(pairs.map((pair) => {
+        return pair[1];
+    }));
+    if (status) {
+        pairs.push([machineId, status]);
+    }
+    return pairs;
+}
+
+function machineMarks(pairs, machineIds) {
+    return machineIds.map((machineId) => {
+        const hit = pairs.find((pair) => {
+            return pair[0] === machineId;
+        });
+        return hit ? hit[1] : undefined;
+    }).filter(Boolean);
+}
+
+async function probeShop(shopId, area, now) {
+    const machines = area.machines.get();
+    const chunks = await Promise.all(Object.entries(machines).map(([machineId, item]) => {
+        return probeMachine(machineId, item, now);
+    }));
+    const pairs = chunks.flat();
+    const status = rollup(machineMarks(pairs, Object.keys(machines)));
+    if (status) {
+        pairs.push([shopId, status]);
+    }
+    return pairs;
+}
+
+function statusOf(node, marks) {
+    if (marks.has(node.id)) {
+        return marks.get(node.id);
+    }
+    if (node.kind === 'collector' && node.parent && marks.has(node.parent)) {
+        return marks.get(node.parent);
+    }
+    return undefined;
+}
+
+function paint(graph, marks) {
+    return {
+        plant: graph.plant,
+        links: graph.links,
+        nodes: graph.nodes.map((node) => {
+            const status = statusOf(node, marks);
+            if (!status) {
+                return node;
+            }
+            return { ...node, status };
+        })
+    };
+}
+
+export default async function topologyHealth(graph, plant, clock) {
+    if (!plant.shops || typeof plant.shops.get !== 'function') {
+        return graph;
+    }
+    const now = clock ? clock() : new Date();
+    const shops = plant.shops.get();
+    const chunks = await Promise.all(Object.entries(shops).map(([shopId, area]) => {
+        return probeShop(shopId, area, now);
+    }));
+    return paint(graph, new Map(chunks.flat()));
+}

package/src/domain/plant/plant.js

@@ -3,16 +3,18 @@
  * Provides initialization for all contained shops.
  *
  * @param {object} shops - initialized list of shops
+ * @param {object} [options] - operations, topology
  * @returns {object} plant with shops property and init method
  *
  * @example
- *   const p = plant(initialized({ area: shop }, Object.values));
+ *   const p = plant(initialized({ area: shop }, Object.values), { topology: () => graph });
  *   p.init();
  */
 export default function plant(shops, options = {}) {
     return {
         shops,
         operations: options.operations,
+        topology: options.topology,
         init() {
             shops.init();
         }

package/src/infrastructure/client/scadaClient.js

@@ -9,7 +9,7 @@ import sseConnection from './sseConnection.js';
  * @param {function} fetcher - fetch function
  * @param {function} eventSource - EventSource constructor
  * @param {object} [logger] - optional logger with error(tag, detail)
- * @returns {object} client with machines, machine, jump, reset, simulation methods
+ * @returns {object} client with machines, topology, machine, jump, reset, simulation methods
  *
  * @example
  *   const client = scadaClient('http://localhost:3000/api/v1', fetch, EventSource, logger);
@@ -45,6 +45,9 @@ export default function scadaClient(baseUrl, fetcher, eventSource, logger) {
         machines() {
             return requestJson('/machines');
         },
+        topology() {
+            return requestJson('/topology');
+        },
         tagCatalog() {
             return requestJson('/tag-catalog');
         },

package/src/infrastructure/http/plant/inspect/cdpGateway.js

@@ -0,0 +1,143 @@
+import http from 'node:http';
+
+/**
+ * Loopback Host Chromium accepts for HTTP CDP.
+ *
+ * @param {number} port - debug port
+ * @returns {string} Host header value
+ *
+ * @example
+ *   cdpRequest({ host: '192.0.2.10', port: 9222 }, '/json/list');
+ */
+export function cdpRequest(target, path) {
+    return {
+        hostname: target.host,
+        port: target.port,
+        path,
+        method: 'GET',
+        headers: { Host: `127.0.0.1:${target.port}` }
+    };
+}
+
+/**
+ * Rewrites CDP debugger URLs onto the same-origin inspect prefix.
+ *
+ * @param {string} text - upstream JSON or HTML
+ * @param {string} hostHeader - incoming Host
+ * @param {string} nodeId - topology node id
+ * @returns {string} rewritten body
+ *
+ * @example
+ *   rewriteDebugger(body, 'example.test:443', 'm1');
+ */
+export function rewriteDebugger(text, hostHeader, nodeId) {
+    const secure = hostHeader.endsWith(':443');
+    const scheme = secure ? 'wss' : 'ws';
+    const host = hostHeader.replace(/:443$/u, '').replace(/:80$/u, '');
+    const prefix = `/infra/inspect/${nodeId}`;
+    const origin = `${scheme}://${host}${prefix}`;
+    const query = `$<scheme>=${host}${prefix}`;
+    return text
+        .replace(/"\/devtools\//gu, `"${prefix}/devtools/`)
+        .replace(/wss?:\/\/127\.0\.0\.1:\d+/gu, origin)
+        .replace(/(?<scheme>wss?)=127\.0\.0\.1:\d+/gu, query);
+}
+
+function readBody(res) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        res.on('data', (chunk) => {
+            chunks.push(chunk);
+        });
+        res.on('end', () => {
+            resolve(Buffer.concat(chunks));
+        });
+        res.on('error', reject);
+    });
+}
+
+function requestCdp(target, path) {
+    return new Promise((resolve, reject) => {
+        const req = http.request(cdpRequest(target, path), (res) => {
+            readBody(res).then((body) => {
+                resolve({ status: res.statusCode, headers: res.headers, body });
+            }, reject);
+        });
+        req.on('error', reject);
+        req.end();
+    });
+}
+
+function capturePng(wsUrl) {
+    return new Promise((resolve, reject) => {
+        const socket = new globalThis.WebSocket(wsUrl);
+        const timer = setTimeout(() => {
+            socket.close();
+            reject(new Error(`cdp screenshot timed out for ${wsUrl}`));
+        }, 10000);
+        socket.addEventListener('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        socket.addEventListener('open', () => {
+            socket.send(JSON.stringify({ id: 1, method: 'Page.captureScreenshot', params: { format: 'png' } }));
+        });
+        socket.addEventListener('message', (event) => {
+            const message = JSON.parse(String(event.data));
+            if (message.id !== 1) {
+                return;
+            }
+            clearTimeout(timer);
+            socket.close();
+            resolve(Buffer.from(message.result.data, 'base64'));
+        });
+    });
+}
+
+async function defaultShot(target, requestImpl) {
+    const listed = await requestImpl(target, '/json/list');
+    const pages = JSON.parse(listed.body.toString('utf8'));
+    const page = Array.isArray(pages) ? pages[0] : pages;
+    if (!page || !page.webSocketDebuggerUrl) {
+        throw new Error(`cdp page websocket is missing on ${target.host}:${target.port}`);
+    }
+    const wsUrl = page.webSocketDebuggerUrl.replace(/wss?:\/\/127\.0\.0\.1:\d+/u, `ws://${target.host}:${target.port}`);
+    return capturePng(wsUrl);
+}
+
+/**
+ * HTTP CDP client that forces a loopback Host and rewrites debugger URLs.
+ *
+ * @param {function} [requestImpl] - optional (target, path) => { status, headers, body }
+ * @param {function} [shotImpl] - optional (target) => Buffer png
+ * @returns {object} json, shot, proxy
+ *
+ * @example
+ *   const body = await cdpGateway().json(target, '/json/list', 'example.test:443', 'm1');
+ */
+export default function cdpGateway(requestImpl, shotImpl) {
+    const request = requestImpl || requestCdp;
+    const shot = shotImpl || ((target) => {
+        return defaultShot(target, request);
+    });
+    return {
+        async json(target, path, hostHeader, nodeId) {
+            const result = await request(target, path);
+            return rewriteDebugger(result.body.toString('utf8'), hostHeader, nodeId);
+        },
+        shot(target) {
+            return shot(target);
+        },
+        proxy(target, path, res) {
+            const req = http.request(cdpRequest(target, path), (up) => {
+                res.writeHead(up.statusCode, up.headers);
+                up.pipe(res);
+            });
+            req.on('error', (err) => {
+                res.writeHead(502, { 'Content-Type': 'text/plain' });
+                res.end(String(err));
+            });
+            req.end();
+        }
+    };
+}

package/src/infrastructure/http/plant/inspect/inspectUpgrade.js

@@ -0,0 +1,76 @@
+import net from 'node:net';
+
+/**
+ * Parses /infra/inspect/:id/... into node id and upstream path.
+ *
+ * @param {string} url - request URL
+ * @returns {{id: string, path: string}|undefined} match
+ */
+export function inspectUrl(url) {
+    const path = url.split('?')[0];
+    const match = path.match(/^\/infra\/inspect\/(?<id>[^/]+)\/(?<rest>.*)$/u);
+    if (!match) {
+        return undefined;
+    }
+    return { id: match.groups.id, path: `/${match.groups.rest}` };
+}
+
+function inspectOf(plant, id) {
+    if (typeof plant.topology !== 'function') {
+        return undefined;
+    }
+    const node = plant.topology().nodes.find((item) => {
+        return item.id === id;
+    });
+    return node && node.inspect;
+}
+
+function writeUpgrade(upstream, req, target, path, head) {
+    const lines = [
+        `GET ${path} HTTP/1.1`,
+        `Host: 127.0.0.1:${target.port}`,
+        'Connection: Upgrade',
+        'Upgrade: websocket',
+        `Sec-WebSocket-Version: ${req.headers['sec-websocket-version'] || '13'}`,
+        `Sec-WebSocket-Key: ${req.headers['sec-websocket-key']}`
+    ];
+    if (req.headers['sec-websocket-protocol']) {
+        lines.push(`Sec-WebSocket-Protocol: ${req.headers['sec-websocket-protocol']}`);
+    }
+    upstream.write(`${lines.join('\r\n')}\r\n\r\n`);
+    if (head && head.length) {
+        upstream.write(head);
+    }
+}
+
+/**
+ * Upgrades a same-origin inspect websocket onto the node debug port.
+ *
+ * @param {object} plant - plant with topology()
+ * @param {object} req - HTTP upgrade request
+ * @param {object} socket - client socket
+ * @param {Buffer} head - leftover bytes
+ * @returns {void}
+ *
+ * @example
+ *   server.on('upgrade', (req, socket, head) => inspectUpgrade(plant, req, socket, head));
+ */
+export default function inspectUpgrade(plant, req, socket, head) {
+    const match = inspectUrl(req.url);
+    const target = match ? inspectOf(plant, match.id) : undefined;
+    if (!match || !target) {
+        socket.destroy();
+        return;
+    }
+    const upstream = net.connect(target.port, target.host, () => {
+        writeUpgrade(upstream, req, target, match.path, head);
+        upstream.pipe(socket);
+        socket.pipe(upstream);
+    });
+    upstream.on('error', () => {
+        socket.destroy();
+    });
+    socket.on('error', () => {
+        upstream.destroy();
+    });
+}

package/src/infrastructure/http/plant/routes/infraRoute.js

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { route } from '@yarkivaev/simple-server';
+
+const dir = join(dirname(fileURLToPath(import.meta.url)), '../ui');
+
+/**
+ * Sends a static file next to the infra UI module.
+ *
+ * @param {object} res - HTTP response
+ * @param {string} name - file path relative to ui/
+ * @param {string} type - Content-Type
+ * @returns {void}
+ */
+function sendFile(res, name, type) {
+    res.writeHead(200, { 'Content-Type': type });
+    res.end(readFileSync(join(dir, name)));
+}
+
+/**
+ * Site-server topology page and its static assets.
+ *
+ * @returns {array} route objects
+ *
+ * @example
+ *   infraRoute();
+ */
+export default function infraRoute() {
+    return [
+        route('GET', '/infra', (req, res) => {
+            sendFile(res, 'infra.html', 'text/html; charset=utf-8');
+        }),
+        route('GET', '/infra/', (req, res) => {
+            sendFile(res, 'infra.html', 'text/html; charset=utf-8');
+        }),
+        route('GET', '/infra/app.js', (req, res) => {
+            sendFile(res, 'infra/app.js', 'text/javascript; charset=utf-8');
+        }),
+        route('GET', '/infra/app.css', (req, res) => {
+            sendFile(res, 'infra/app.css', 'text/css; charset=utf-8');
+        }),
+        route('GET', '/infra/graph.js', (req, res) => {
+            sendFile(res, 'infra/graph.js', 'text/javascript; charset=utf-8');
+        }),
+        route('GET', '/infra/panel.js', (req, res) => {
+            sendFile(res, 'infra/panel.js', 'text/javascript; charset=utf-8');
+        })
+    ];
+}

package/src/infrastructure/http/plant/routes/inspectRoute.js

@@ -0,0 +1,110 @@
+import { errorResponse } from '@yarkivaev/simple-server';
+import cdpGateway from '../inspect/cdpGateway.js';
+import { inspectUrl } from '../inspect/inspectUpgrade.js';
+
+function inspectOf(plant, id) {
+    if (typeof plant.topology !== 'function') {
+        return undefined;
+    }
+    const node = plant.topology().nodes.find((item) => {
+        return item.id === id;
+    });
+    return node && node.inspect;
+}
+
+function hostOf(req) {
+    return req.headers.host || req.headers.Host || 'localhost';
+}
+
+function cdpPath(rest) {
+    if (rest === '/json' || rest === '/json/list') {
+        return '/json/list';
+    }
+    if (rest === '/json/version') {
+        return '/json/version';
+    }
+    if (rest.startsWith('/devtools/')) {
+        return rest;
+    }
+    return undefined;
+}
+
+function missing(res, url) {
+    errorResponse('NOT_FOUND', `Inspect path '${url}' was not found`, 404).send(res);
+}
+
+function queryOf(url) {
+    return url.includes('?') ? `?${url.split('?')[1]}` : '';
+}
+
+async function sendJson(cdp, target, req, res, nodeId) {
+    const path = cdpPath(inspectUrl(req.url).path);
+    const body = await cdp.json(target, path, hostOf(req), nodeId);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(body);
+}
+
+async function sendShot(cdp, target, res) {
+    const png = await cdp.shot(target);
+    res.writeHead(200, { 'Content-Type': 'image/png' });
+    res.end(png);
+}
+
+async function sendCdp(cdp, target, req, res, match) {
+    const path = cdpPath(match.path);
+    if (!path) {
+        missing(res, req.url);
+        return;
+    }
+    if (path.startsWith('/devtools/')) {
+        cdp.proxy(target, `${path}${queryOf(req.url)}`, res);
+        return;
+    }
+    await sendJson(cdp, target, req, res, match.id);
+}
+
+async function dispatchInspect(plant, cdp, req, res, match) {
+    const target = inspectOf(plant, match.id);
+    if (!target) {
+        missing(res, req.url);
+        return;
+    }
+    if (match.path === '/shot') {
+        await sendShot(cdp, target, res);
+        return;
+    }
+    await sendCdp(cdp, target, req, res, match);
+}
+
+async function dispatch(plant, cdp, req, res) {
+    const match = inspectUrl(req.url);
+    if (!match) {
+        missing(res, req.url);
+        return;
+    }
+    await dispatchInspect(plant, cdp, req, res, match);
+}
+
+/**
+ * Same-origin CDP inspect routes for nodes that declare inspect { host, port }.
+ *
+ * @param {object} plant - plant with topology()
+ * @param {object} [gateway] - optional cdpGateway
+ * @returns {array} route objects
+ *
+ * @example
+ *   inspectRoute(plant);
+ */
+export default function inspectRoute(plant, gateway) {
+    const cdp = gateway || cdpGateway();
+    return [
+        {
+            matches(request) {
+                return request.method === 'GET' && Boolean(inspectUrl(request.url));
+            },
+            handle(request, response) {
+                return dispatch(plant, cdp, request, response);
+            }
+        }
+    ];
+}

package/src/infrastructure/http/plant/routes/topologyRoute.js

@@ -0,0 +1,23 @@
+import { jsonResponse, route } from '@yarkivaev/simple-server';
+import topologyFromPlant from '../../../../application/topologyFromPlant.js';
+import topologyHealth from '../../../../application/topologyHealth.js';
+
+/**
+ * Plant topology graph route.
+ *
+ * @param {string} basePath - API base path
+ * @param {object} plant - plant domain object
+ * @param {function} [clock] - () => Date for sensor freshness
+ * @returns {array} route objects
+ *
+ * @example
+ *   topologyRoute('/api/v1', plant);
+ */
+export default function topologyRoute(basePath, plant, clock) {
+    return [
+        route('GET', `${basePath}/topology`, async (req, res) => {
+            const graph = await topologyHealth(topologyFromPlant(plant), plant, clock);
+            jsonResponse(graph).send(res);
+        })
+    ];
+}

package/src/infrastructure/http/plant/ui/infra/app.css

@@ -0,0 +1,154 @@
+:root {
+    --ink: #d7e0ea;
+    --muted: #8ea0b3;
+    --bg: #0b1118;
+    --panel: #121a24;
+    --line: #243140;
+    --ok: #3f9d6a;
+    --degraded: #c9a227;
+    --down: #c24b3a;
+    --unknown: #5d6d7e;
+    --accent: #7eb1c9;
+}
+
+* {
+    box-sizing: border-box;
+}
+
+html,
+body {
+    margin: 0;
+    min-height: 100%;
+    background: radial-gradient(circle at 12% 0, #152033 0, var(--bg) 42%);
+    color: var(--ink);
+    font: 14px/1.4 "IBM Plex Sans", "Segoe UI", sans-serif;
+}
+
+.mast {
+    padding: 20px 28px 8px;
+    border-bottom: 1px solid var(--line);
+}
+
+.mast__kicker {
+    margin: 0;
+    letter-spacing: 0.18em;
+    text-transform: uppercase;
+    color: var(--accent);
+    font-size: 11px;
+}
+
+.mast h1 {
+    margin: 4px 0 0;
+    font-size: 28px;
+    font-weight: 560;
+}
+
+.mast__meta {
+    margin: 4px 0 0;
+    color: var(--muted);
+}
+
+.stage {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) 320px;
+    min-height: calc(100vh - 92px);
+}
+
+.stage__graph {
+    width: 100%;
+    height: calc(100vh - 92px);
+}
+
+.stage__panel {
+    border-left: 1px solid var(--line);
+    background: var(--panel);
+    padding: 20px;
+    overflow: auto;
+}
+
+.stage__panel[hidden] {
+    display: none;
+}
+
+.node {
+    cursor: pointer;
+}
+
+.node__shape {
+    stroke: #0b1118;
+    stroke-width: 2;
+}
+
+.node--ok .node__shape { fill: var(--ok); }
+.node--degraded .node__shape { fill: var(--degraded); }
+.node--down .node__shape { fill: var(--down); }
+.node--unknown .node__shape { fill: var(--unknown); }
+
+.node__label,
+.node__version {
+    fill: var(--ink);
+    font-size: 12px;
+}
+
+.link {
+    fill: none;
+    stroke: #3a5166;
+    stroke-width: 1.4;
+}
+
+.link--feeds {
+    stroke-dasharray: 5 4;
+    stroke: #7eb1c9;
+}
+
+.panel__kind {
+    color: var(--muted);
+    text-transform: uppercase;
+    letter-spacing: 0.12em;
+    font-size: 11px;
+}
+
+.panel__title {
+    margin: 6px 0 16px;
+    font-size: 22px;
+}
+
+.panel__row {
+    display: flex;
+    justify-content: space-between;
+    gap: 12px;
+    padding: 8px 0;
+    border-bottom: 1px solid var(--line);
+}
+
+.panel__actions {
+    display: flex;
+    gap: 8px;
+    margin-top: 18px;
+}
+
+.panel__actions button {
+    background: #1b2836;
+    color: var(--ink);
+    border: 1px solid #314559;
+    border-radius: 4px;
+    padding: 8px 12px;
+    cursor: pointer;
+}
+
+.panel__preview,
+.panel__tools {
+    width: 100%;
+    margin-top: 16px;
+    background: #0b1118;
+    border: 1px solid var(--line);
+}
+
+.panel__preview {
+    min-height: 140px;
+}
+
+.panel__tools {
+    min-height: 280px;
+    border: 0;
+}

package/src/infrastructure/http/plant/ui/infra/app.js

@@ -0,0 +1,14 @@
+import draw from './graph.js';
+import show from './panel.js';
+
+const title = document.getElementById('plant-title');
+const meta = document.getElementById('plant-meta');
+const svg = document.getElementById('graph');
+const aside = document.getElementById('panel');
+const graph = await (await fetch('/api/v1/topology')).json();
+
+title.textContent = graph.plant.title;
+meta.textContent = [graph.plant.id, graph.plant.version].filter(Boolean).join(' · ');
+draw(svg, graph, (node) => {
+    show(aside, node);
+});

package/src/infrastructure/http/plant/ui/infra/graph.js

@@ -0,0 +1,106 @@
+const SVG = 'http://www.w3.org/2000/svg';
+
+function shops(nodes) {
+    return nodes.filter((node) => {
+        return node.kind === 'shop';
+    });
+}
+
+function children(nodes, parentId, kind) {
+    return nodes.filter((node) => {
+        return node.parent === parentId && node.kind === kind;
+    });
+}
+
+function placed(graph) {
+    const positions = {};
+    shops(graph.nodes).forEach((area, i) => {
+        const x = 170 + i * 280;
+        positions[area.id] = { x, y: 56 };
+        children(graph.nodes, area.id, 'machine').forEach((item, j) => {
+            const y = 150 + j * 96;
+            positions[item.id] = { x, y };
+            children(graph.nodes, item.id, 'collector').forEach((col, k) => {
+                positions[col.id] = { x: x + 96, y: y + k * 26 };
+            });
+        });
+    });
+    graph.nodes.filter((node) => {
+        return node.kind === 'collector' && !positions[node.id];
+    }).forEach((node, i) => {
+        positions[node.id] = { x: 72, y: 88 + i * 54 };
+    });
+    return positions;
+}
+
+function el(name, attrs) {
+    const node = document.createElementNS(SVG, name);
+    Object.entries(attrs).forEach(([key, value]) => {
+        node.setAttribute(key, String(value));
+    });
+    return node;
+}
+
+function paintLink(svg, graph, positions) {
+    graph.links.forEach((link) => {
+        const from = positions[link.from];
+        const to = positions[link.to];
+        if (!from || !to) {
+            return;
+        }
+        const line = el('path', { class: `link link--${link.kind}` });
+        line.setAttribute('d', `M ${from.x} ${from.y} C ${from.x} ${(from.y + to.y) / 2}, ${to.x} ${(from.y + to.y) / 2}, ${to.x} ${to.y}`);
+        svg.appendChild(line);
+    });
+}
+
+function paintShape(node, pos) {
+    if (node.kind === 'machine') {
+        return el('rect', { class: 'node__shape', x: pos.x - 42, y: pos.y - 18, width: 84, height: 36, rx: 4 });
+    }
+    const radius = node.kind === 'shop' ? 22 : 10;
+    return el('circle', { class: 'node__shape', cx: pos.x, cy: pos.y, r: radius });
+}
+
+function paintNode(svg, node, pos, onClick) {
+    const group = el('g', { class: `node node--${node.status || 'unknown'}`, 'data-id': node.id });
+    const label = el('text', { class: 'node__label', x: pos.x, y: pos.y + 36, 'text-anchor': 'middle' });
+    label.textContent = node.title;
+    group.appendChild(paintShape(node, pos));
+    group.appendChild(label);
+    if (node.version) {
+        const version = el('text', { class: 'node__version', x: pos.x, y: pos.y + 50, 'text-anchor': 'middle' });
+        version.textContent = node.version;
+        group.appendChild(version);
+    }
+    group.addEventListener('click', () => {
+        onClick(node);
+    });
+    svg.appendChild(group);
+}
+
+/**
+ * Draws a parent/kind column graph into an SVG element.
+ *
+ * @param {SVGElement} svg - target
+ * @param {object} graph - topology contract
+ * @param {function} onClick - selected node callback
+ * @returns {void}
+ *
+ * @example
+ *   draw(svg, graph, (node) => show(panel, node));
+ */
+export default function draw(svg, graph, onClick) {
+    while (svg.firstChild) {
+        svg.removeChild(svg.firstChild);
+    }
+    const columns = Math.max(shops(graph.nodes).length, 1);
+    svg.setAttribute('viewBox', `0 0 ${Math.max(960, columns * 280 + 120)} 520`);
+    const positions = placed(graph);
+    paintLink(svg, graph, positions);
+    graph.nodes.forEach((node) => {
+        if (positions[node.id]) {
+            paintNode(svg, node, positions[node.id], onClick);
+        }
+    });
+}

package/src/infrastructure/http/plant/ui/infra/panel.js

@@ -0,0 +1,89 @@
+function row(label, value) {
+    const line = document.createElement('div');
+    line.className = 'panel__row';
+    const name = document.createElement('span');
+    name.textContent = label;
+    const body = document.createElement('span');
+    body.textContent = value;
+    line.appendChild(name);
+    line.appendChild(body);
+    return line;
+}
+
+function button(label, action) {
+    const el = document.createElement('button');
+    el.type = 'button';
+    el.textContent = label;
+    el.addEventListener('click', action);
+    return el;
+}
+
+function preview(id) {
+    const img = document.createElement('img');
+    img.className = 'panel__preview';
+    img.alt = 'Screen preview';
+    img.src = `/infra/inspect/${id}/shot`;
+    return img;
+}
+
+async function tools(id, host) {
+    const frame = document.createElement('iframe');
+    frame.className = 'panel__tools';
+    frame.title = 'DevTools';
+    const response = await fetch(`/infra/inspect/${id}/json/list`);
+    const payload = await response.json();
+    const page = Array.isArray(payload) ? payload[0] : payload;
+    if (page && page.devtoolsFrontendUrl) {
+        frame.src = page.devtoolsFrontendUrl;
+        return frame;
+    }
+    frame.srcdoc = `<p>${host}</p>`;
+    return frame;
+}
+
+function facts(aside, node) {
+    aside.appendChild(row('id', node.id));
+    aside.appendChild(row('status', node.status || 'unknown'));
+    if (node.version) {
+        aside.appendChild(row('version', node.version));
+    }
+}
+
+function actions(aside, node) {
+    const bar = document.createElement('div');
+    bar.className = 'panel__actions';
+    bar.appendChild(button('Preview', () => {
+        aside.appendChild(preview(node.id));
+    }));
+    bar.appendChild(button('DevTools', async () => {
+        aside.appendChild(await tools(node.id, node.inspect.host));
+    }));
+    aside.appendChild(bar);
+}
+
+/**
+ * Fills the topology side panel for one node.
+ *
+ * @param {HTMLElement} aside - panel root
+ * @param {object} node - topology node
+ * @returns {void}
+ *
+ * @example
+ *   show(panel, node);
+ */
+export default function show(aside, node) {
+    aside.hidden = false;
+    aside.replaceChildren();
+    const kind = document.createElement('p');
+    kind.className = 'panel__kind';
+    kind.textContent = node.kind;
+    const title = document.createElement('h2');
+    title.className = 'panel__title';
+    title.textContent = node.title;
+    aside.appendChild(kind);
+    aside.appendChild(title);
+    facts(aside, node);
+    if (node.inspect) {
+        actions(aside, node);
+    }
+}

package/src/infrastructure/http/plant/ui/infra.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Plant topology</title>
+    <link rel="stylesheet" href="/infra/app.css">
+</head>
+<body>
+    <header class="mast">
+        <p class="mast__kicker">Admin</p>
+        <h1 id="plant-title">Topology</h1>
+        <p id="plant-meta" class="mast__meta"></p>
+    </header>
+    <main class="stage">
+        <svg id="graph" class="stage__graph" role="img" aria-label="Plant topology"></svg>
+        <aside id="panel" class="stage__panel" hidden></aside>
+    </main>
+    <script type="module" src="/infra/app.js"></script>
+</body>
+</html>