@forzalabs/remora-preview 1.0.0

package/README.md

@@ -0,0 +1,43 @@
+# @forzalabs/remora-preview
+
+The read-only viewer for a [Remora](https://www.npmjs.com/package/@forzalabs/remora) project: the
+lineage graph of what feeds what, and a click-through table inspector for every source, producer,
+consumer and schema.
+
+It is normally used through the CLI, which hosts it and reloads it as you edit:
+
+```bash
+remora ui-preview            # http://127.0.0.1:5070, opens your browser
+remora ui-preview -p 8080 --no-open
+```
+
+You can also serve a snapshot on its own — no CLI, no licence, no project on disk:
+
+```bash
+remora graph -f json > project.json      # on a machine that has the project
+npx @forzalabs/remora-preview project.json
+```
+
+## It cannot read your data
+
+This package has no drivers, no credentials and no configuration reader; its only runtime dependency
+is `express`, and it binds to loopback. It receives one versioned JSON document — the snapshot — and
+renders it. Sampling live data is a capability of the CLI that hosts it, never of this viewer.
+
+## API
+
+```ts
+import { serve, fromSnapshot } from '@forzalabs/remora-preview'
+
+const server = await serve({ provider: fromSnapshot(snapshot), port: 5070, open: true })
+server.notifyChange()   // tell every open page to refetch
+await server.close()
+```
+
+A host that reads a live project implements `IPreviewProvider` directly, so views are built on demand
+rather than serialised up front.
+
+## Versioning
+
+The snapshot carries a `formatVersion`. This viewer renders the versions it knows and refuses a newer
+one with a message saying so, rather than drawing it wrong.

package/dist/Affirm.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The repo's precondition helper, re-stated locally.
+ *
+ * `@remora/app-core` would be the import everywhere else, but this package publishes to npm on its
+ * own and must keep `express` as its only runtime dependency (docs/PREVIEW_PLAN.md §2). Six lines of
+ * copy is the cheaper side of that trade.
+ */
+export declare const affirm: (value: unknown, message: string) => void;

package/dist/Affirm.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.affirm = void 0;
+/**
+ * The repo's precondition helper, re-stated locally.
+ *
+ * `@remora/app-core` would be the import everywhere else, but this package publishes to npm on its
+ * own and must keep `express` as its only runtime dependency (docs/PREVIEW_PLAN.md §2). Six lines of
+ * copy is the cheaper side of that trade.
+ */
+const affirm = (value, message) => {
+    if (!value)
+        throw new Error('Affirm failed: ' + message);
+};
+exports.affirm = affirm;

package/dist/Browser.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Opens the page in the default browser. Never throws and never blocks: a headless box, a locked-down
+ * desktop or a missing `xdg-open` is a reason to print the URL, not to fail the command.
+ */
+export declare const openBrowser: (url: string) => boolean;

package/dist/Browser.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openBrowser = void 0;
+const node_child_process_1 = require("node:child_process");
+/** One opener per platform. An unknown platform simply does not open anything. */
+const OPENERS = {
+    darwin: 'open',
+    win32: 'start ""',
+    linux: 'xdg-open'
+};
+/**
+ * Opens the page in the default browser. Never throws and never blocks: a headless box, a locked-down
+ * desktop or a missing `xdg-open` is a reason to print the URL, not to fail the command.
+ */
+const openBrowser = (url) => {
+    const opener = OPENERS[process.platform];
+    if (!opener)
+        return false;
+    try {
+        (0, node_child_process_1.exec)(`${opener} "${url}"`, () => { });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.openBrowser = openBrowser;

package/dist/Contract.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The CLI ↔ viewer contract, version 1.
+ *
+ * A HAND COPY of `packages/definitions/src/Preview.ts` and `Lineage.ts`, on purpose. This package is
+ * published to npm on its own and the workspace packages are not, so it cannot import them; and the
+ * contract between the two sides is meant to be one versioned JSON document rather than the whole
+ * resource surface (docs/PREVIEW_PLAN.md §2). `ContractParity.ts` type-checks this copy against the
+ * originals at build time, so the two cannot drift silently.
+ *
+ * Nothing here describes a remora resource — only tables, cells and nodes. That is what lets the page
+ * render a project it knows nothing about.
+ */
+/** The highest `formatVersion` this viewer can render. A newer snapshot is refused, not mis-drawn. */
+export declare const SUPPORTED_FORMAT_VERSION = 1;
+export interface IPreviewSnapshot {
+    formatVersion: number;
+    project: string;
+    generatedBy: string;
+    graph: ILineageGraph;
+    diagnostics: IPreviewDiagnostic[];
+    /** Inlined when the whole document is emitted at once; otherwise fetched per node from `/api/resource/:id`. */
+    resources?: IResourceView[];
+    /** What the host can do beyond rendering this document. Absent in a snapshot read from a file. */
+    capabilities?: IPreviewCapabilities;
+}
+/**
+ * Additive: a capability the viewer does not know about is one it never asks for, so no version bump.
+ * Each is something the HOST can do and this package cannot; a snapshot read from a file has none.
+ */
+export interface IPreviewCapabilities {
+    /** The host can read rows from a real data source: `/api/sample/:id` answers. */
+    sample?: boolean;
+    /** The host can execute a consumer: `POST /api/run/:id` answers. */
+    run?: boolean;
+    /** The host can read and write the authored configuration file: `/api/file/:id` answers. */
+    edit?: boolean;
+    /** The host can tail its own log file: `/api/logs` answers. */
+    logs?: boolean;
+}
+/** The authored configuration file behind a node — the file on disk, never the loaded object. */
+export interface IPreviewFile {
+    /** Project-relative path, shown so what is being edited is never in doubt. */
+    path: string;
+    /** The file's text, exactly as it is on disk. */
+    content: string;
+}
+/** What a save did, or refused to do. */
+export interface IPreviewSaveResult {
+    saved: boolean;
+    message?: string;
+}
+/** A run the host accepted. Progress is not streamed: the run overlay is the progress. */
+export interface IPreviewRunResult {
+    started: boolean;
+    /** What was started, or why it was refused. */
+    message?: string;
+}
+/** A tail of the host's log file. */
+export interface IPreviewLogs {
+    /** Project-relative path, or a note when nothing is being written to a file. */
+    path: string;
+    /** Oldest first, so the page renders it the way a terminal does. */
+    lines: string[];
+    truncated?: IViewTruncation;
+}
+export interface ILineageGraph {
+    nodes: ILineageNode[];
+    edges: ILineageEdge[];
+}
+export interface ILineageNode {
+    id: string;
+    kind: LineageNodeKind;
+    name: string;
+    description?: string;
+    badges?: string[];
+    status?: LineageStatus;
+    /** Referenced by another resource but never declared. Drawn anyway — that is the point. */
+    missing?: boolean;
+    /** The most recent execution of this resource, when the host knows of one. */
+    run?: ILineageRun;
+}
+/** One execution of a resource, as the graph shows it: the outcome, when, how long, how much. */
+export interface ILineageRun {
+    status: LineageRunStatus;
+    /** ISO start time. */
+    startedAt: string;
+    /** Wall-clock duration in ms. Absent while the run is still going. */
+    elapsedMS?: number;
+    /** Rows written. Absent, or -1, when the run never got far enough to know. */
+    itemsCount?: number;
+    /** Why it failed. Absent on anything but a failure. */
+    error?: string;
+    /** Remora release that ran it. */
+    engineVersion?: string;
+}
+export interface ILineageEdge {
+    id: string;
+    from: string;
+    to: string;
+    kind: LineageEdgeKind;
+    label?: string;
+}
+export type LineageNodeKind = 'source' | 'producer' | 'consumer' | 'schema' | 'destination';
+export type LineageEdgeKind = 'reads' | 'feeds' | 'writes' | 'validates' | 'triggers';
+export type LineageStatus = 'ok' | 'warn' | 'error';
+/** `started` is a run that has not reported a result: still going, or wedged. */
+export type LineageRunStatus = 'success' | 'failed' | 'started';
+export interface IPreviewDiagnostic {
+    severity: 'error' | 'warning';
+    origin: 'load' | 'lineage';
+    node?: string;
+    file?: string;
+    message: string;
+}
+export interface IResourceView {
+    id: string;
+    kind: LineageNodeKind;
+    name: string;
+    description?: string;
+    summary: IViewField[];
+    tables: IViewTable[];
+    raw?: unknown;
+}
+export interface IViewField {
+    label: string;
+    value: string | number | boolean | null;
+    link?: string;
+}
+export interface IViewTable {
+    title: string;
+    columns: IViewColumn[];
+    rows: IViewCell[][];
+    truncated?: IViewTruncation;
+}
+export interface IViewColumn {
+    key: string;
+    label: string;
+    align?: 'left' | 'right';
+}
+export interface IViewCell {
+    value: string | number | boolean | null;
+    /** A node id. Resolved server-side, per cell — the page never interprets remora semantics. */
+    link?: string;
+    muted?: boolean;
+    status?: LineageStatus;
+}
+export interface IViewTruncation {
+    shown: number;
+    total: number;
+}

package/dist/Contract.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * The CLI ↔ viewer contract, version 1.
+ *
+ * A HAND COPY of `packages/definitions/src/Preview.ts` and `Lineage.ts`, on purpose. This package is
+ * published to npm on its own and the workspace packages are not, so it cannot import them; and the
+ * contract between the two sides is meant to be one versioned JSON document rather than the whole
+ * resource surface (docs/PREVIEW_PLAN.md §2). `ContractParity.ts` type-checks this copy against the
+ * originals at build time, so the two cannot drift silently.
+ *
+ * Nothing here describes a remora resource — only tables, cells and nodes. That is what lets the page
+ * render a project it knows nothing about.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_FORMAT_VERSION = void 0;
+/** The highest `formatVersion` this viewer can render. A newer snapshot is refused, not mis-drawn. */
+exports.SUPPORTED_FORMAT_VERSION = 1;

package/dist/Server.d.ts

@@ -0,0 +1,31 @@
+import { IPreviewProvider } from './Snapshot';
+export interface IServeOptions {
+    /** Where the graph, the diagnostics and the resource views come from. */
+    provider: IPreviewProvider;
+    /** Preferred port; the next `PORT_ATTEMPTS` are tried when it is in use. */
+    port?: number;
+    /** Bind address. Overriding the loopback default exposes an unauthenticated page. */
+    bind?: string;
+    /** Open the default browser once the server is listening. */
+    open?: boolean;
+}
+export interface IPreviewServer {
+    url: string;
+    port: number;
+    /**
+     * The session token this server injected into the page. Every state-changing request must carry
+     * it in `x-remora-preview-token`; it is generated per session and never leaves the machine.
+     */
+    token: string;
+    /** Tell every open page the project changed; each one refetches what it is showing. */
+    notifyChange: () => void;
+    close: () => Promise<void>;
+}
+/**
+ * Serves the prebuilt page and a small read-only API over one preview provider.
+ *
+ * The server holds no remora concepts at all: it hands out whatever documents the provider builds.
+ * That is what keeps the viewer publishable on its own, and what makes it structurally incapable of
+ * reaching a data source (docs/PREVIEW_PLAN.md §2).
+ */
+export declare const serve: (options: IServeOptions) => Promise<IPreviewServer>;

package/dist/Server.js

@@ -0,0 +1,314 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serve = void 0;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const express_1 = __importDefault(require("express"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_http_1 = __importDefault(require("node:http"));
+const node_path_1 = __importDefault(require("node:path"));
+const Affirm_1 = require("./Affirm");
+const Browser_1 = require("./Browser");
+/** Clear of the backend (5069) and of the frontend dev server (3000). */
+const DEFAULT_PORT = 5070;
+/** Ports past the requested one to try when it is taken, before giving up with the reason. */
+const PORT_ATTEMPTS = 20;
+/** An SSE client that never disconnects is a leak with a view of the project. Bound it. */
+const MAX_CLIENTS = 32;
+/** Under every browser and proxy idle timeout there is, so a quiet session stays connected. */
+const HEARTBEAT_MS = 20000;
+/** Loopback only. The viewer has no authentication because it is never reachable off this machine. */
+const DEFAULT_BIND = '127.0.0.1';
+/** Rows a sample request may ask for. A sample is a look at the data, never an export of it. */
+const DEFAULT_SAMPLE_ROWS = 10;
+const MAX_SAMPLE_ROWS = 100;
+/** Log lines a tail may ask for. A log is a stream, not a document. */
+const DEFAULT_LOG_LINES = 200;
+const MAX_LOG_LINES = 2000;
+/**
+ * The header a state-changing request must carry, holding the session token injected into the page.
+ *
+ * A custom header is load-bearing beyond the token: a cross-origin request that sets one triggers a
+ * CORS preflight, and this server answers no preflight, so a page on another origin cannot make the
+ * request at all — before the token is even looked at.
+ */
+const TOKEN_HEADER = 'x-remora-preview-token';
+/** Methods that change something and therefore need the token. */
+const MUTATING_METHODS = ['POST', 'PUT', 'PATCH', 'DELETE'];
+/**
+ * Host names the server will answer on, whatever DNS says.
+ *
+ * Binding to loopback does not stop a BROWSER: every site the developer visits can address
+ * 127.0.0.1, and a hostname that resolves there (DNS rebinding) walks past a naive check. The `Host`
+ * header is therefore the boundary, not the bind address alone.
+ */
+const LOOPBACK_HOSTNAMES = ['127.0.0.1', 'localhost', '::1', '[::1]'];
+/** A configuration file larger than this is not a configuration file. */
+const MAX_EDIT_BYTES = '2mb';
+/**
+ * Serves the prebuilt page and a small read-only API over one preview provider.
+ *
+ * The server holds no remora concepts at all: it hands out whatever documents the provider builds.
+ * That is what keeps the viewer publishable on its own, and what makes it structurally incapable of
+ * reaching a data source (docs/PREVIEW_PLAN.md §2).
+ */
+const serve = async (options) => {
+    (0, Affirm_1.affirm)(options, 'Missing preview server options');
+    (0, Affirm_1.affirm)(options.provider, 'Missing preview provider');
+    const pagePath = node_path_1.default.join(__dirname, 'page');
+    (0, Affirm_1.affirm)(node_fs_1.default.existsSync(node_path_1.default.join(pagePath, 'index.html')), `The preview page is not built (${pagePath}). Run: npm run build --workspace=@forzalabs/remora-preview`);
+    const clients = new Set();
+    const app = (0, express_1.default)();
+    const bind = options.bind ?? DEFAULT_BIND;
+    // Per session, so a token that leaks is worthless the moment the preview is closed.
+    const token = node_crypto_1.default.randomBytes(24).toString('hex');
+    app.disable('x-powered-by');
+    app.use(guard(bind, token));
+    // Before the static middleware, because this is the same document with the token injected.
+    app.get(['/', '/index.html'], servePage(pagePath, token));
+    registerApi(app, options.provider, clients);
+    app.use(express_1.default.static(pagePath, { index: false }));
+    const server = await listen(app, options.port ?? DEFAULT_PORT, bind, PORT_ATTEMPTS);
+    const heartbeat = setInterval(() => clients.forEach(client => client.write(': ping\n\n')), HEARTBEAT_MS);
+    const port = server.address().port;
+    const url = `http://${bind}:${port}`;
+    if (options.open)
+        (0, Browser_1.openBrowser)(url);
+    return {
+        url,
+        port,
+        token,
+        notifyChange: () => clients.forEach(client => client.write('event: change\ndata: {}\n\n')),
+        close: () => close(server, clients, heartbeat)
+    };
+};
+exports.serve = serve;
+/**
+ * Refuses anything that is not this page asking.
+ *
+ * Loopback is why the page needs no login, but loopback alone does not make it private: every site
+ * the developer visits can address 127.0.0.1 from their browser, and once this server can RUN a
+ * consumer or REWRITE a config file, that stops being a curiosity. Three layers, cheapest first:
+ *
+ * - the `Host` header must be one this server answers on, which is what closes DNS rebinding;
+ * - a request carrying a cross-origin `Origin` is refused outright;
+ * - anything that changes state must also carry the session token from the page.
+ *
+ * Applied to READS as well, deliberately: a website quietly reading someone's project graph was
+ * always possible and was never wanted either.
+ */
+const guard = (bind, token) => (req, res, next) => {
+    if (!isAllowedHost(req.headers.host, bind))
+        return res.status(403).json({ message: `Refused: unexpected Host header "${req.headers.host ?? ''}"` });
+    const origin = req.headers.origin;
+    if (origin && !isAllowedHost(authorityOf(origin), bind))
+        return res.status(403).json({ message: `Refused: cross-origin request from ${origin}` });
+    if (MUTATING_METHODS.includes(req.method) && req.headers[TOKEN_HEADER] !== token)
+        return res.status(403).json({ message: 'Refused: this request needs the preview session token' });
+    next();
+};
+/** @param host a `Host` header or an origin's authority — with or without a port. */
+const isAllowedHost = (host, bind) => {
+    if (!host)
+        return false;
+    const hostname = stripPort(host);
+    return LOOPBACK_HOSTNAMES.includes(hostname) || hostname === bind;
+};
+/** Splits the port off an authority, leaving an IPv6 literal's own colons alone. */
+const stripPort = (host) => {
+    if (host.startsWith('['))
+        return host.slice(0, host.indexOf(']') + 1);
+    const separator = host.lastIndexOf(':');
+    return separator > 0 ? host.slice(0, separator) : host;
+};
+/** An origin's `host:port`, or null when it is not a URL at all. */
+const authorityOf = (origin) => {
+    try {
+        return new URL(origin).host;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * The prebuilt page, with the session token injected.
+ *
+ * Injected into the document rather than handed out by a route: a page on another origin cannot read
+ * this response body, which is the whole reason the token is worth anything. Read once — the page is
+ * prebuilt and does not change while a session is open.
+ */
+const servePage = (pagePath, token) => {
+    const html = node_fs_1.default.readFileSync(node_path_1.default.join(pagePath, 'index.html'), 'utf8');
+    const script = `<script>window.__REMORA_PREVIEW_TOKEN__ = ${JSON.stringify(token)}</script>`;
+    const injected = html.includes('</head>') ? html.replace('</head>', `${script}</head>`) : script + html;
+    return (req, res) => res.type('html').send(injected);
+};
+/**
+ * The routes.
+ *
+ * The reads are always there. Everything a host can DO — sample, run, edit, tail its logs — is
+ * registered only when that host can actually do it, so a standalone viewer has no such route rather
+ * than a route that refuses. That absence is the capability check. docs/PREVIEW_PLAN.md §2.
+ */
+const registerApi = (app, provider, clients) => {
+    // A cached snapshot would show a project as it was two saves ago, which is the one thing live
+    // reload exists to prevent.
+    app.use('/api', (req, res, next) => {
+        res.setHeader('Cache-Control', 'no-store');
+        next();
+    });
+    app.get('/api/snapshot', (req, res) => send(res, () => provider.snapshot()));
+    app.get('/api/resource/:id', (req, res) => send(res, () => {
+        const view = provider.resource(req.params.id);
+        if (!view) {
+            res.status(404);
+            return { message: `No resource view for "${req.params.id}"` };
+        }
+        return view;
+    }));
+    app.get('/api/events', (req, res) => subscribe(req, res, clients));
+    if (provider.sample)
+        registerSample(app, provider);
+    if (provider.run)
+        registerRun(app, provider);
+    if (provider.file)
+        registerFile(app, provider);
+    if (provider.logs)
+        registerLogs(app, provider);
+};
+const registerSample = (app, provider) => {
+    app.get('/api/sample/:id', (req, res) => sendAsync(res, async () => {
+        const rows = readRows(req.query.rows);
+        const table = await provider.sample(req.params.id, rows);
+        if (!table) {
+            res.status(404);
+            return { message: `No data to sample for "${req.params.id}"` };
+        }
+        return table;
+    }));
+};
+/**
+ * Executing a resource. `POST`, because it changes the world, which also means it needs the token.
+ *
+ * It answers as soon as the run has STARTED. A run takes minutes and holding a request open for one
+ * would make the page's progress display a second mechanism — where the run overlay already is one.
+ */
+const registerRun = (app, provider) => {
+    app.post('/api/run/:id', (req, res) => sendAsync(res, async () => {
+        const result = await provider.run(req.params.id);
+        if (!result?.started)
+            res.status(409);
+        return result ?? { started: false, message: `Nothing to run for "${req.params.id}"` };
+    }));
+};
+/**
+ * Reading and writing the file behind a node. The write is registered only when the host offers one,
+ * so a host can expose the authored file without accepting changes to it.
+ */
+const registerFile = (app, provider) => {
+    app.get('/api/file/:id', (req, res) => send(res, () => {
+        const file = provider.file(req.params.id);
+        if (!file) {
+            res.status(404);
+            return { message: `No configuration file for "${req.params.id}"` };
+        }
+        return file;
+    }));
+    if (!provider.save)
+        return;
+    app.put('/api/file/:id', express_1.default.json({ limit: MAX_EDIT_BYTES }), (req, res) => sendAsync(res, async () => {
+        const content = req.body?.content;
+        if (typeof content !== 'string') {
+            res.status(400);
+            return { saved: false, message: 'A save must carry the file as { "content": "..." }' };
+        }
+        // A refusal is the expected outcome here — invalid JSON, a schema violation — so it comes
+        // back as the reason with a 422, never as a 500 the page can only call an error.
+        const result = await provider.save(req.params.id, content);
+        if (!result?.saved)
+            res.status(422);
+        return result ?? { saved: false, message: `Nothing to save for "${req.params.id}"` };
+    }));
+};
+const registerLogs = (app, provider) => {
+    app.get('/api/logs', (req, res) => send(res, () => provider.logs(readLines(req.query.lines))));
+};
+/** Whatever a URL carries, a sample stays a sample: a bad value reads as the default, never as more. */
+const readRows = (value) => {
+    const rows = parseInt(String(value ?? ''), 10);
+    if (isNaN(rows) || rows < 1)
+        return DEFAULT_SAMPLE_ROWS;
+    return Math.min(rows, MAX_SAMPLE_ROWS);
+};
+/** The same rule for a log tail: bounded above, whatever was asked for. */
+const readLines = (value) => {
+    const lines = parseInt(String(value ?? ''), 10);
+    if (isNaN(lines) || lines < 1)
+        return DEFAULT_LOG_LINES;
+    return Math.min(lines, MAX_LOG_LINES);
+};
+/**
+ * A provider reads a configuration that is being edited, so it is allowed to fail. Returning the
+ * reason as JSON lets the page say what happened instead of blanking out.
+ */
+const send = (res, build) => {
+    try {
+        res.json(build());
+    }
+    catch (error) {
+        res.status(500).json({ message: error.message });
+    }
+};
+/**
+ * The same contract as `send`, for the one route that reaches a data source and so cannot answer
+ * synchronously. A source that is unreachable or unauthorised is the expected outcome here, not an
+ * exceptional one, so its reason is what the page gets to show.
+ */
+const sendAsync = async (res, build) => {
+    try {
+        res.json(await build());
+    }
+    catch (error) {
+        if (res.headersSent)
+            return;
+        res.status(500).json({ message: error.message });
+    }
+};
+/** Server-sent events: the page is told a change happened and refetches; nothing is pushed to it. */
+const subscribe = (req, res, clients) => {
+    if (clients.size >= MAX_CLIENTS) {
+        res.status(503).json({ message: `Too many open preview sessions (${MAX_CLIENTS})` });
+        return;
+    }
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-store',
+        Connection: 'keep-alive'
+    });
+    res.write('retry: 2000\n\n');
+    clients.add(res);
+    req.on('close', () => clients.delete(res));
+};
+/**
+ * Listens on the first free port at or after `port`. A developer running two previews should get the
+ * second one on 5071, not an EADDRINUSE stack trace — and the bound port is reported back, so the
+ * URL printed is always the URL that works.
+ */
+const listen = (app, port, bind, attempts) => new Promise((resolve, reject) => {
+    const server = node_http_1.default.createServer(app);
+    server.once('error', (error) => {
+        if (error.code !== 'EADDRINUSE' || attempts <= 1)
+            return reject(error);
+        listen(app, port + 1, bind, attempts - 1).then(resolve, reject);
+    });
+    server.listen(port, bind, () => resolve(server));
+});
+const close = (server, clients, heartbeat) => {
+    clearInterval(heartbeat);
+    // An open event stream keeps the socket alive, so close() would otherwise never call back.
+    clients.forEach(client => client.end());
+    clients.clear();
+    return new Promise(resolve => server.close(() => resolve()));
+};

package/dist/Snapshot.d.ts

@@ -0,0 +1,43 @@
+import { IPreviewFile, IPreviewLogs, IPreviewRunResult, IPreviewSaveResult, IPreviewSnapshot, IResourceView, IViewTable } from './Contract';
+/**
+ * What the server reads the project through. A host that can reload — the CLI watching a directory —
+ * implements it over a live environment; a fixed document is adapted by `fromSnapshot`.
+ *
+ * One input instead of a `snapshot`-or-`provider` pair, so the server has a single code path.
+ */
+export interface IPreviewProvider {
+    /** Graph and diagnostics. Called per request, so a reloading host needs no invalidation. */
+    snapshot: () => IPreviewSnapshot;
+    /** The inspector view of one node id, or null when the node is unknown. */
+    resource: (nodeId: string) => IResourceView | null;
+    /**
+     * OPTIONAL, and the reason this viewer can be published on its own: reading real rows needs
+     * drivers and credentials, which live in the host. A host that has them offers this and the
+     * server routes to it; one that does not — `fromSnapshot`, and so `remora-preview <file>` — has
+     * no route to offer, rather than a route that is refused. docs/PREVIEW_PLAN.md §2.
+     *
+     * @returns the rows as a table, or null when the node holds no data to read.
+     */
+    sample?: (nodeId: string, rows: number) => Promise<IViewTable | null>;
+    /**
+     * OPTIONAL. Executes a resource. Returns as soon as the run has STARTED, never when it finishes:
+     * a run takes minutes, and the run overlay is already the progress display — the execution writes
+     * a `started` record that the host's next poll turns into a repaint.
+     */
+    run?: (nodeId: string) => Promise<IPreviewRunResult>;
+    /**
+     * OPTIONAL, and paired with `save`. The resource's file AS AUTHORED. Never the loaded object: a
+     * loaded producer has had its groups expanded, so writing that back would persist the expansion.
+     */
+    file?: (nodeId: string) => IPreviewFile | null;
+    /** OPTIONAL. Writes the file back, or refuses with the reason. Registered only alongside `file`. */
+    save?: (nodeId: string, content: string) => Promise<IPreviewSaveResult>;
+    /** OPTIONAL. The tail of the host's own log file. */
+    logs?: (lines: number) => IPreviewLogs;
+}
+/**
+ * Serves one already-built document — the standalone `remora-preview <file>` entrypoint, and any
+ * static export. Resource views come from the snapshot's own `resources`, so a document generated
+ * without them shows the graph and reports that the detail was not included.
+ */
+export declare const fromSnapshot: (snapshot: IPreviewSnapshot) => IPreviewProvider;