@matteeh/osq 0.1.0 → 0.2.0

package/dist/core/web/web-events.js

@@ -0,0 +1,162 @@
+import path from 'node:path';
+import { watch } from 'chokidar';
+import { getArchiveDir, getChangesDir, getRejectedDir } from '../status/layout.js';
+import { numericIdOf } from './web-data-folders.js';
+/** SSE response headers shared by GET and HEAD. */
+export const SSE_HEADERS = {
+    'Content-Type': 'text/event-stream; charset=utf-8',
+    'Cache-Control': 'no-store',
+    Connection: 'keep-alive',
+};
+const WATCHED_EVENTS = ['add', 'change', 'unlink', 'addDir', 'unlinkDir'];
+function defaultWatch(paths, options) {
+    const watcher = watch([...paths], { ignoreInitial: options.ignoreInitial });
+    const emitter = watcher;
+    return {
+        on: (event, listener) => emitter.on(event, listener),
+        close: () => watcher.close(),
+    };
+}
+function defaultSchedule(callback, delayMs) {
+    const timer = setTimeout(callback, delayMs);
+    return { cancel: () => clearTimeout(timer) };
+}
+function folderKeyWithin(base, target) {
+    const relative = path.relative(base, target);
+    if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative))
+        return null;
+    const key = relative.split(path.sep)[0];
+    return key === undefined || key === '' || key === '.' ? null : key;
+}
+/**
+ * Leading numeric id for a path inside exactly one change folder, or `null`
+ * when the path belongs to shared state: capability specs, root layout, or an
+ * unrecognized folder.
+ */
+export function classifyChangePath(target, changesDir, archiveDir, rejectedDir) {
+    for (const base of [archiveDir, rejectedDir]) {
+        const key = folderKeyWithin(base, target);
+        if (key !== null)
+            return numericIdOf(key);
+    }
+    const key = folderKeyWithin(changesDir, target);
+    if (key === null || key === 'archive' || key === 'rejected')
+        return null;
+    return numericIdOf(key);
+}
+/** Create the one watcher and debounce accumulator owned by a server. */
+export function createInvalidationHub(options) {
+    const changesDir = path.resolve(getChangesDir(options.openspecRoot, options.projectRoot));
+    const archiveDir = path.resolve(getArchiveDir(options.openspecRoot, options.projectRoot));
+    const rejectedDir = path.resolve(getRejectedDir(options.openspecRoot, options.projectRoot));
+    const root = path.resolve(options.projectRoot, options.openspecRoot);
+    const factory = options.watch ?? defaultWatch;
+    const schedule = options.schedule ?? defaultSchedule;
+    const listeners = new Set();
+    const ids = new Set();
+    let global = false;
+    let pending = null;
+    let sequence = 0;
+    let closed = false;
+    let closing = null;
+    function emitBatch() {
+        const batch = { ids: global ? [] : [...ids].sort((a, b) => a - b) };
+        ids.clear();
+        global = false;
+        for (const listener of [...listeners])
+            listener(batch);
+    }
+    function cancelPending() {
+        sequence += 1;
+        if (pending !== null) {
+            pending.cancel();
+            pending = null;
+        }
+        ids.clear();
+        global = false;
+    }
+    const watcher = factory([root], { ignoreInitial: true });
+    for (const event of WATCHED_EVENTS) {
+        watcher.on(event, (target) => {
+            if (closed || typeof target !== 'string')
+                return;
+            const id = classifyChangePath(path.resolve(target), changesDir, archiveDir, rejectedDir);
+            if (id === null)
+                global = true;
+            else
+                ids.add(id);
+            if (pending === null) {
+                sequence += 1;
+                const token = sequence;
+                pending = schedule(() => {
+                    if (closed || token !== sequence)
+                        return;
+                    pending = null;
+                    emitBatch();
+                }, options.debounceMs);
+            }
+        });
+    }
+    watcher.on('error', () => undefined);
+    return {
+        subscribe(listener) {
+            if (closed)
+                return () => undefined;
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        cancelPending,
+        close() {
+            if (closing !== null)
+                return closing;
+            closed = true;
+            cancelPending();
+            listeners.clear();
+            closing = Promise.resolve().then(() => watcher.close());
+            return closing;
+        },
+    };
+}
+/** The exact wire frame for one debounced invalidation. */
+export function formatChangedEvent(ids) {
+    return `event: changed\ndata: ${JSON.stringify({ ids })}\n\n`;
+}
+/** Track connected SSE responses and fan out one frame per derived batch. */
+export function createEventStream(hub) {
+    const clients = new Set();
+    const unsubscribe = hub.subscribe((batch) => {
+        const frame = formatChangedEvent(batch.ids);
+        for (const res of clients) {
+            if (!res.writableEnded)
+                res.write(frame);
+        }
+    });
+    return {
+        handle(res, head) {
+            if (head) {
+                res.writeHead(200, SSE_HEADERS);
+                res.end();
+                return;
+            }
+            res.writeHead(200, SSE_HEADERS);
+            res.flushHeaders();
+            clients.add(res);
+            const remove = () => {
+                clients.delete(res);
+            };
+            res.on('close', remove);
+            res.on('error', remove);
+        },
+        close() {
+            unsubscribe();
+            for (const res of clients) {
+                if (!res.writableEnded)
+                    res.end();
+            }
+            clients.clear();
+        },
+    };
+}
+//# sourceMappingURL=web-events.js.map

package/dist/core/web/web-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-events.js","sourceRoot":"","sources":["../../../src/core/web/web-events.ts"],"names":[],"mappings":"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"}

package/dist/core/web/web-export.d.ts

@@ -0,0 +1,18 @@
+import type { OsqConfig } from '../foundation/config.js';
+export interface ExportDashboardOptions {
+    readonly projectRoot: string;
+    readonly config: OsqConfig;
+    readonly targetDir: string;
+    /** Built UI directory; defaults to the package-root staged `ui/dist`. */
+    readonly uiDir?: string;
+    /** Home directory scrubbed to `~`; defaults to `os.homedir()`. */
+    readonly home?: string;
+    /** Derivation clock; defaults to the current time. */
+    readonly now?: Date;
+}
+/**
+ * Write a self-contained snapshot of every dashboard view into `targetDir`.
+ * A non-empty target is refused before any write. Returns the written files.
+ */
+export declare function exportDashboard(options: ExportDashboardOptions): Promise<string[]>;
+//# sourceMappingURL=web-export.d.ts.map

package/dist/core/web/web-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-export.d.ts","sourceRoot":"","sources":["../../../src/core/web/web-export.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAwBzD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;CACrB;AAsFD;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBxF"}

package/dist/core/web/web-export.js

@@ -0,0 +1,112 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { getMetricsReport } from '../report/report.js';
+import { readInbox } from '../status/inbox-projection.js';
+import { getWebChange } from './web-data-change.js';
+import { getWebGraph } from './web-data.js';
+import { serializeWebJson } from './web-server.js';
+import { resolveUiDir } from './web-static.js';
+const DATA_SCRIPT = '<script src="./data.js"></script>';
+const DATA_FILE = 'data.js';
+const INDEX_FILE = 'index.html';
+/** Replace every occurrence of each source string in every nested string value. */
+function scrubStrings(value, replacements) {
+    if (typeof value === 'string') {
+        let result = value;
+        for (const [from, to] of replacements)
+            result = result.split(from).join(to);
+        return result;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => scrubStrings(item, replacements));
+    if (value !== null && typeof value === 'object') {
+        const result = {};
+        for (const [key, item] of Object.entries(value)) {
+            result[key] = scrubStrings(item, replacements);
+        }
+        return result;
+    }
+    return value;
+}
+/** The folder key plus the padded numeric id prefix for one change node. */
+function changeKeys(folderKey) {
+    const prefix = /^(\d+)/.exec(folderKey)?.[1];
+    return prefix === undefined ? [folderKey] : [folderKey, prefix.padStart(3, '0')];
+}
+/** Compose every route document from the current project tree. */
+async function buildInlineData(projectRoot, config, now, home) {
+    const graph = await getWebGraph(projectRoot, config);
+    const report = await getMetricsReport(projectRoot, config);
+    const inbox = await readInbox(projectRoot, { config, now, home });
+    const changes = {};
+    for (const node of graph.changes) {
+        const change = await getWebChange(projectRoot, node.folderKey, config, now);
+        for (const key of changeKeys(node.folderKey))
+            changes[key] = change;
+    }
+    return { report, graph, inbox, changes };
+}
+/** `true` when `target` is missing, or an existing empty directory. */
+async function targetIsWritable(target) {
+    const stat = await fs.lstat(target).catch(() => null);
+    if (stat === null)
+        return true;
+    if (!stat.isDirectory())
+        return false;
+    return (await fs.readdir(target)).length === 0;
+}
+/** Copy each top-level entry of `uiDir` into the existing empty `target`. */
+async function copyUi(uiDir, target) {
+    const entries = await fs.readdir(uiDir, { withFileTypes: true });
+    for (const entry of entries) {
+        await fs.cp(path.join(uiDir, entry.name), path.join(target, entry.name), { recursive: true });
+    }
+}
+/** Insert the data script immediately before the copied index's first script. */
+async function injectDataScript(indexPath) {
+    const html = await fs.readFile(indexPath, 'utf8');
+    const at = html.indexOf('<script');
+    if (at < 0)
+        throw new Error(`exported dashboard index has no script tag: ${indexPath}`);
+    await fs.writeFile(indexPath, `${html.slice(0, at)}${DATA_SCRIPT}${html.slice(at)}`, 'utf8');
+}
+/** Every regular file below `root`, absolute and sorted. */
+async function listFiles(root) {
+    const files = [];
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    for (const entry of entries) {
+        const full = path.join(root, entry.name);
+        if (entry.isDirectory())
+            files.push(...(await listFiles(full)));
+        else if (entry.isFile())
+            files.push(full);
+    }
+    return files.sort((a, b) => a.localeCompare(b));
+}
+/**
+ * Write a self-contained snapshot of every dashboard view into `targetDir`.
+ * A non-empty target is refused before any write. Returns the written files.
+ */
+export async function exportDashboard(options) {
+    const target = path.resolve(options.targetDir);
+    const uiDir = options.uiDir ?? resolveUiDir();
+    const home = options.home ?? os.homedir();
+    const now = options.now ?? new Date();
+    if (!(await targetIsWritable(target))) {
+        throw new Error(`dashboard export target must be an empty directory: ${target}`);
+    }
+    const data = await buildInlineData(options.projectRoot, options.config, now, home);
+    const replacements = [];
+    if (options.projectRoot)
+        replacements.push([options.projectRoot, '.']);
+    if (home)
+        replacements.push([home, '~']);
+    await fs.mkdir(target, { recursive: true });
+    await copyUi(uiDir, target);
+    await injectDataScript(path.join(target, INDEX_FILE));
+    const serialized = serializeWebJson(scrubStrings(data, replacements));
+    await fs.writeFile(path.join(target, DATA_FILE), `window.__OSQ_DATA__ = ${serialized};`, 'utf8');
+    return listFiles(target);
+}
+//# sourceMappingURL=web-export.js.map

package/dist/core/web/web-export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-export.js","sourceRoot":"","sources":["../../../src/core/web/web-export.ts"],"names":[],"mappings":"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"}

package/dist/core/web/web-server.d.ts

@@ -0,0 +1,34 @@
+import type { OsqConfig } from '../foundation/config.js';
+import { type MetricsReport } from '../report/report.js';
+import { type ReadInboxOptions } from '../status/inbox-projection.js';
+import type { Inbox } from '../status/inbox.js';
+import type { WebChange, WebGraph } from './web-data-types.js';
+import { type ScheduleFn, type WatcherFactory } from './web-events.js';
+type ChangeDocumentFn = (projectRoot: string, selector: string, config: OsqConfig, now: Date) => Promise<WebChange>;
+/** Dependency-injected composition root for the read-only loopback server. */
+export interface WebServerOptions {
+    readonly projectRoot: string;
+    readonly config: OsqConfig;
+    readonly port?: number;
+    readonly uiDir?: string;
+    readonly now?: () => Date;
+    readonly home?: string;
+    readonly getReport?: (projectRoot: string, config: OsqConfig) => Promise<MetricsReport>;
+    readonly getGraph?: (projectRoot: string, config: OsqConfig) => Promise<WebGraph>;
+    readonly getChange?: ChangeDocumentFn;
+    readonly getInbox?: (projectRoot: string, options: ReadInboxOptions) => Promise<Inbox>;
+    readonly watch?: WatcherFactory;
+    readonly schedule?: ScheduleFn;
+}
+/** An idempotently closable listener with its actual bound loopback URL. */
+export interface WebServerHandle {
+    readonly url: string;
+    readonly port: number;
+    close(): Promise<void>;
+}
+/** Deterministic UTF-8 JSON shared by every API document. */
+export declare function serializeWebJson(data: unknown): string;
+/** Start one loopback-only HTTP server over the current project tree. */
+export declare function startWebServer(options: WebServerOptions): Promise<WebServerHandle>;
+export {};
+//# sourceMappingURL=web-server.d.ts.map

package/dist/core/web/web-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-server.d.ts","sourceRoot":"","sources":["../../../src/core/web/web-server.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,KAAK,aAAa,EAAoB,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,KAAK,gBAAgB,EAAa,MAAM,+BAA+B,CAAC;AACjF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAGhD,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EACL,KAAK,UAAU,EACf,KAAK,cAAc,EAGpB,MAAM,iBAAiB,CAAC;AAOzB,KAAK,gBAAgB,GAAG,CACtB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,IAAI,KACN,OAAO,CAAC,SAAS,CAAC,CAAC;AAExB,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IACxF,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;CAChC;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAWD,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAEtD;AAsDD,yEAAyE;AACzE,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkHxF"}

package/dist/core/web/web-server.js

@@ -0,0 +1,182 @@
+import http from 'node:http';
+import { DEFAULT_SERVE_CONFIG } from '../foundation/config-serve.js';
+import { getMetricsReport } from '../report/report.js';
+import { readInbox } from '../status/inbox-projection.js';
+import { getWebChange } from './web-data-change.js';
+import { getWebGraph } from './web-data-graph.js';
+import { WebDataError } from './web-data-types.js';
+import { createEventStream, createInvalidationHub, } from './web-events.js';
+import { UI_CONTENT_SECURITY_POLICY, resolveStaticFile, resolveUiDir } from './web-static.js';
+const SERVE_HOST = '127.0.0.1';
+const CHANGE_PREFIX = '/api/changes/';
+const EVENTS_PATH = '/api/events';
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const source = value;
+    const sorted = {};
+    for (const key of Object.keys(source).sort())
+        sorted[key] = sortKeysDeep(source[key]);
+    return sorted;
+}
+/** Deterministic UTF-8 JSON shared by every API document. */
+export function serializeWebJson(data) {
+    return JSON.stringify(sortKeysDeep(data));
+}
+function send(res, status, body, contentType, cache, head, headers = {}) {
+    res.writeHead(status, {
+        'Content-Type': contentType,
+        'Content-Length': body.byteLength,
+        'Cache-Control': cache,
+        ...headers,
+    });
+    if (head)
+        res.end();
+    else
+        res.end(body);
+}
+function sendJson(res, status, data, head, headers = {}) {
+    const body = Buffer.from(serializeWebJson(data), 'utf8');
+    send(res, status, body, 'application/json; charset=utf-8', 'no-store', head, headers);
+}
+function sendFailure(res, error, head = false) {
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) }, head);
+}
+/** Decode a change selector once, rejecting separators, traversal, and bad escapes. */
+function decodeChangeSelector(raw) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(raw);
+    }
+    catch {
+        return null;
+    }
+    if (decoded.length === 0 || decoded.includes('\0'))
+        return null;
+    if (decoded.includes('/') || decoded.includes('\\'))
+        return null;
+    if (decoded === '.' || decoded === '..')
+        return null;
+    return decoded;
+}
+/** Start one loopback-only HTTP server over the current project tree. */
+export async function startWebServer(options) {
+    const projectRoot = options.projectRoot;
+    const config = options.config;
+    const uiDir = options.uiDir ?? resolveUiDir();
+    const home = options.home;
+    const clock = options.now ?? (() => new Date());
+    const getReport = options.getReport ?? getMetricsReport;
+    const getGraph = options.getGraph ?? getWebGraph;
+    const getChange = options.getChange ?? getWebChange;
+    const getInbox = options.getInbox ?? ((root, inbox) => readInbox(root, inbox));
+    const hub = createInvalidationHub({
+        projectRoot,
+        openspecRoot: config.paths.openspecRoot,
+        debounceMs: config.serve?.eventDebounceMs ?? DEFAULT_SERVE_CONFIG.eventDebounceMs,
+        watch: options.watch,
+        schedule: options.schedule,
+    });
+    const events = createEventStream(hub);
+    async function handleChange(res, pathname, head) {
+        const raw = pathname.slice(CHANGE_PREFIX.length);
+        if (raw.length === 0)
+            return sendJson(res, 404, { error: 'change not found' }, head);
+        const selector = decodeChangeSelector(raw);
+        if (selector === null)
+            return sendJson(res, 400, { error: 'unsafe change selector' }, head);
+        try {
+            sendJson(res, 200, await getChange(projectRoot, selector, config, clock()), head);
+        }
+        catch (error) {
+            if (error instanceof WebDataError) {
+                return sendJson(res, error.kind === 'ambiguous' ? 409 : 404, { error: error.message }, head);
+            }
+            sendFailure(res, error, head);
+        }
+    }
+    async function handleApi(res, pathname, head) {
+        try {
+            if (pathname === EVENTS_PATH)
+                return events.handle(res, head);
+            const documents = {
+                '/api/report': () => getReport(projectRoot, config),
+                '/api/graph': () => getGraph(projectRoot, config),
+                '/api/inbox': () => getInbox(projectRoot, { config, now: clock(), home }),
+            };
+            const document = documents[pathname];
+            if (document)
+                return sendJson(res, 200, await document(), head);
+            if (pathname.startsWith(CHANGE_PREFIX))
+                return await handleChange(res, pathname, head);
+            sendJson(res, 404, { error: 'not found' }, head);
+        }
+        catch (error) {
+            sendFailure(res, error, head);
+        }
+    }
+    async function handleStatic(res, pathname, head) {
+        const asset = await resolveStaticFile(pathname, uiDir);
+        if (asset === null) {
+            const body = Buffer.from('Not Found\n', 'utf8');
+            return send(res, 404, body, 'text/plain; charset=utf-8', 'no-store', head);
+        }
+        const headers = asset.isHtml
+            ? { 'Content-Security-Policy': UI_CONTENT_SECURITY_POLICY }
+            : {};
+        send(res, 200, asset.body, asset.contentType, asset.cacheControl, head, headers);
+    }
+    async function handleRequest(req, res) {
+        const method = req.method ?? 'GET';
+        if (method !== 'GET' && method !== 'HEAD') {
+            return sendJson(res, 405, { error: 'method not allowed' }, false, { Allow: 'GET, HEAD' });
+        }
+        const head = method === 'HEAD';
+        const rawUrl = req.url ?? '/';
+        const pathname = rawUrl.startsWith('/') ? rawUrl.replace(/[?#].*$/, '') : null;
+        if (pathname === null)
+            return sendJson(res, 400, { error: 'malformed request url' }, head);
+        if (pathname.startsWith('/api/'))
+            await handleApi(res, pathname, head);
+        else
+            await handleStatic(res, pathname, head);
+    }
+    const server = http.createServer((req, res) => {
+        handleRequest(req, res).catch((error) => sendFailure(res, error));
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.once('listening', resolve);
+            server.listen(options.port ?? config.serve?.port ?? DEFAULT_SERVE_CONFIG.port, SERVE_HOST);
+        });
+    }
+    catch (error) {
+        hub.cancelPending();
+        events.close();
+        await hub.close();
+        throw error;
+    }
+    const address = server.address();
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        hub.cancelPending();
+        events.close();
+        await hub.close();
+        await new Promise((resolve) => {
+            server.close(() => resolve());
+            server.closeIdleConnections();
+        });
+    };
+    return { url: `http://${SERVE_HOST}:${address.port}/`, port: address.port, close };
+}
+//# sourceMappingURL=web-server.js.map

package/dist/core/web/web-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-server.js","sourceRoot":"","sources":["../../../src/core/web/web-server.ts"],"names":[],"mappings":"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"}

package/dist/core/web/web-static.d.ts

@@ -0,0 +1,20 @@
+/** Package-root `ui/dist` for both `src/core` under tsx and `dist/core` shipped. */
+export declare function resolveUiDir(): string;
+/** Self-only policy for the generated application plus same-origin SSE. */
+export declare const UI_CONTENT_SECURITY_POLICY: string;
+/** Fingerprinted build assets may be cached immutably; everything else revalidates. */
+export declare function isFingerprintedAsset(fileName: string): boolean;
+/** One resolved static file with its delivery metadata. */
+export interface StaticAsset {
+    readonly body: Buffer;
+    readonly contentType: string;
+    readonly cacheControl: string;
+    readonly isHtml: boolean;
+}
+/**
+ * Resolve `pathname` to one regular file inside `uiDir`. Returns null for
+ * malformed escapes, traversal, dot segments, directories, and absent files.
+ * `/` and `/index.html` both resolve to the application shell.
+ */
+export declare function resolveStaticFile(pathname: string, uiDir?: string): Promise<StaticAsset | null>;
+//# sourceMappingURL=web-static.d.ts.map

package/dist/core/web/web-static.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-static.d.ts","sourceRoot":"","sources":["../../../src/core/web/web-static.ts"],"names":[],"mappings":"AAaA,oFAAoF;AACpF,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,2EAA2E;AAC3E,eAAO,MAAM,0BAA0B,QAW3B,CAAC;AA0Bb,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAiBD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAuB,GAC7B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CA8B7B"}