@damurka/jovian 0.1.0

package/lib/session/supervisor-client.d.ts

@@ -0,0 +1,36 @@
+import type { EngineOptions } from '../types/index.js';
+import { Logger } from '../utils/logger.js';
+export interface SessionConnectionInfo {
+    sessionId: string;
+    httpBase: string;
+    wsBase: string;
+}
+export declare function buildSessionOptionsBody(options: Partial<EngineOptions>): Record<string, unknown>;
+export declare class SupervisorClient {
+    private child;
+    private readyPromise;
+    private readonly logger;
+    constructor(logger: Logger);
+    private ensureStarted;
+    private spawnSupervisor;
+    createSession(options: EngineOptions): Promise<SessionConnectionInfo>;
+    stopSession(info: SessionConnectionInfo): Promise<void>;
+    /**
+     * Replaces a session's kernel process in place (SessionRegistry::
+     * restartSession() on the native side stops the old kernel, spawns a
+     * fresh one, and re-registers it under the *same* session id) -- so
+     * unlike stopSession(), nothing about `info` changes here. Works both
+     * to recover a crashed session and, same as Jupyter's "Restart Kernel",
+     * to reset a healthy one.
+     *
+     * `options`, if given, replaces the R installation this session's next
+     * kernel process launches with (rHome/rPath/etc) instead of reusing
+     * whatever it was created with -- e.g. switching from R 4.4 to R 4.6
+     * for an existing notebook connection on the fly, without needing to
+     * close this session and create a new one just to pick a different R.
+     */
+    restartSession(info: SessionConnectionInfo, options?: Partial<EngineOptions>): Promise<void>;
+    /** Skips graceful per-session shutdown -- only for cleanup on the way out. */
+    kill(): void;
+}
+//# sourceMappingURL=supervisor-client.d.ts.map

package/lib/session/supervisor-client.js

@@ -0,0 +1,147 @@
+import { spawn } from 'child_process';
+import { createInterface } from 'readline';
+import { join } from 'path';
+import { bundledHeraSource, ensureExecutable, locateNativeDirectory } from './native-paths.js';
+// Pulled out as its own pure function (rather than inlined in createSession/
+// restartSession) so the exact shape sent to the supervisor's POST /sessions
+// and .../restart bodies is unit-testable without mocking fetch() or
+// spawning a real supervisor process. Undefined fields are dropped by
+// JSON.stringify() (e.g. rHome for a 'python' session), so passing every
+// field unconditionally is harmless -- session_registry.cpp's
+// parseSessionOptions() only reads the ones matching kernelType anyway.
+export function buildSessionOptionsBody(options) {
+    return {
+        kernelType: options.kernelType,
+        rHome: options.rHome,
+        rPath: options.rPath,
+        rLibs: options.rLibs,
+        pandocPath: options.pandocPath,
+        heraSrcPath: options.heraSrcPath ?? bundledHeraSource(),
+        pythonHome: options.pythonHome,
+        pythonPath: options.pythonPath,
+        venvPath: options.venvPath,
+        workingDirectory: options.workingDirectory
+    };
+}
+// themisto is the kernel supervisor: it's the only process in this system
+// that ever links a native ZMQ
+// binding. It spawns/owns `elara` kernel processes, speaks ZMQ to
+// each of them, and re-exposes sessions over plain HTTP (lifecycle) +
+// WebSocket (execute/interrupt/message streaming) -- so Electron/VS Code's
+// process, where this class runs, never needs a native dependency at all.
+export class SupervisorClient {
+    child;
+    readyPromise;
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    ensureStarted() {
+        if (!this.readyPromise) {
+            this.readyPromise = this.spawnSupervisor();
+        }
+        return this.readyPromise;
+    }
+    spawnSupervisor() {
+        return new Promise((resolve, reject) => {
+            const exePath = resolveSupervisorExecutable();
+            this.logger.debug(`Spawning supervisor process from: ${exePath}`);
+            const child = spawn(exePath, [], { stdio: ['ignore', 'pipe', 'pipe'] });
+            this.child = child;
+            child.stderr?.on('data', (chunk) => process.stderr.write(chunk));
+            const rl = createInterface({ input: child.stdout });
+            const onLine = (line) => {
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                if (message.type === 'supervisorReady' && typeof message.httpPort === 'number' && typeof message.wsPort === 'number') {
+                    cleanup();
+                    this.logger.info(`Supervisor ready (pid ${child.pid})`, { httpPort: message.httpPort, wsPort: message.wsPort });
+                    resolve({ httpPort: message.httpPort, wsPort: message.wsPort });
+                }
+            };
+            const onExit = (code) => {
+                cleanup();
+                reject(new Error(`Supervisor process exited before it was ready (code ${code})`));
+            };
+            const cleanup = () => {
+                rl.off('line', onLine);
+                child.off('exit', onExit);
+            };
+            rl.on('line', onLine);
+            child.once('error', (error) => { cleanup(); reject(error); });
+            child.once('exit', onExit);
+        });
+    }
+    async createSession(options) {
+        const { httpPort, wsPort } = await this.ensureStarted();
+        const httpBase = `http://127.0.0.1:${httpPort}`;
+        const res = await fetch(`${httpBase}/sessions`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(buildSessionOptionsBody(options))
+        });
+        const body = await res.json();
+        if (!res.ok || !body.sessionId) {
+            throw new Error(body.error ?? `Supervisor failed to create session (HTTP ${res.status})`);
+        }
+        return { sessionId: body.sessionId, httpBase, wsBase: `ws://127.0.0.1:${wsPort}` };
+    }
+    async stopSession(info) {
+        try {
+            await fetch(`${info.httpBase}/sessions/${info.sessionId}`, { method: 'DELETE' });
+        }
+        catch (error) {
+            this.logger.warn(`Failed to gracefully stop session ${info.sessionId} via supervisor`, error);
+        }
+    }
+    /**
+     * Replaces a session's kernel process in place (SessionRegistry::
+     * restartSession() on the native side stops the old kernel, spawns a
+     * fresh one, and re-registers it under the *same* session id) -- so
+     * unlike stopSession(), nothing about `info` changes here. Works both
+     * to recover a crashed session and, same as Jupyter's "Restart Kernel",
+     * to reset a healthy one.
+     *
+     * `options`, if given, replaces the R installation this session's next
+     * kernel process launches with (rHome/rPath/etc) instead of reusing
+     * whatever it was created with -- e.g. switching from R 4.4 to R 4.6
+     * for an existing notebook connection on the fly, without needing to
+     * close this session and create a new one just to pick a different R.
+     */
+    async restartSession(info, options) {
+        const res = await fetch(`${info.httpBase}/sessions/${info.sessionId}/restart`, {
+            method: 'POST',
+            ...(options ? {
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(buildSessionOptionsBody(options))
+            } : {})
+        });
+        const body = await res.json();
+        if (!res.ok || !body.sessionId) {
+            throw new Error(body.error ?? `Supervisor failed to restart session ${info.sessionId} (HTTP ${res.status})`);
+        }
+    }
+    /** Skips graceful per-session shutdown -- only for cleanup on the way out. */
+    kill() {
+        if (this.child && !this.child.killed) {
+            this.logger.warn(`Force-killing supervisor process (pid ${this.child.pid})`);
+            this.child.kill();
+        }
+    }
+}
+// Finds the supervisor binary: JOVIAN_NATIVE_DIR, else the installed
+// @scope/jovian-<os>-<cpu> package, else a source checkout's
+// dist/native/Release (see native-paths.ts).
+function resolveSupervisorExecutable() {
+    const { dir } = locateNativeDirectory();
+    // Electron keeps native files outside the asar archive.
+    const nativeDir = dir.replace(/\bnode_modules\.asar\b/, 'node_modules.asar.unpacked');
+    ensureExecutable(nativeDir);
+    return join(nativeDir, process.platform === 'win32' ? 'themisto.exe' : 'themisto');
+}
+//# sourceMappingURL=supervisor-client.js.map

package/lib/types/engine.d.ts

@@ -0,0 +1,269 @@
+import type { JupyterMessage } from './messages.js';
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+export type LoggerFunction = (level: LogLevel, message: string, data?: any) => void;
+export interface EngineOptions {
+    /**
+     * Which kernel a session runs: 'r' (Elara, the default -- every caller
+     * that predates this field keeps behaving exactly as before) or
+     * 'python' (Carpo). Selects which set of the fields below the
+     * supervisor actually uses (native/src/themisto/session_registry.cpp's
+     * SessionOptions::kernelType) and which kernel executable it spawns.
+     */
+    kernelType?: 'r' | 'python';
+    rHome?: string;
+    rPath?: string;
+    rLibs?: string;
+    /** Directory containing the pandoc binary, for bundled R installs that don't ship it on PATH. */
+    pandocPath?: string;
+    /**
+     * Source directory of the 'hera' R package (packages/hera in this repo).
+     * When set, Elara installs it via remotes::install_local() if it is
+     * missing or older than these sources (needs the 'remotes' package).
+     * There is no default: without it, R sessions use whichever 'hera' is
+     * already installed in the library -- install or update it with
+     * `npm run hera:install`.
+     */
+    heraSrcPath?: string;
+    /** Only used when kernelType is 'python' -- Carpo's equivalent of rHome. */
+    pythonHome?: string;
+    /** Only used when kernelType is 'python' -- Carpo's equivalent of rPath. */
+    pythonPath?: string;
+    /** Only used when kernelType is 'python' -- not yet consulted by Carpo itself (see carpo::EnvironmentConfig). */
+    venvPath?: string;
+    /**
+     * Directory the kernel process starts in -- what `getwd()` (R) /
+     * `os.getcwd()` (Python) report and what relative paths resolve against.
+     * Must already exist. Defaults to the supervisor's own working directory
+     * (i.e. the calling process's), which is rarely what you want for a
+     * notebook/project: set it to the project or document folder.
+     */
+    workingDirectory?: string;
+    queueSize?: number;
+    enableLogging?: boolean;
+    enableMetrics?: boolean;
+    logger?: LoggerFunction;
+}
+export type EngineState = 'idle' | 'starting' | 'running' | 'stopping' | 'stopped' | 'error';
+export interface ExecutionOptions {
+    silent?: boolean;
+    storeHistory?: boolean;
+    allowStdin?: boolean;
+    /**
+     * When this execution fails, abort every execute() still waiting behind
+     * it in the queue instead of running them (Jupyter's stop_on_error) --
+     * their results come back with `aborted: true` and nothing having run.
+     * Also forwarded to the kernel in the execute_request itself.
+     */
+    stopOnError?: boolean;
+    /**
+     * Expressions to evaluate in the kernel right after the code runs, as
+     * {name: expression} (Jupyter's user_expressions). Only evaluated when
+     * the code succeeded; each result -- or its own error -- comes back in
+     * `ExecutionResult.userExpressions` under the same name.
+     */
+    userExpressions?: Record<string, string>;
+    /**
+     * Milliseconds to wait for the execution to finish before giving up
+     * (default 30000; 0 = no timeout, for calls meant to run indefinitely
+     * such as a Shiny app).
+     */
+    timeout?: number;
+    /**
+     * When the timeout fires, also send the kernel an interrupt (default
+     * true) so it stops the code instead of carrying on with work no one is
+     * waiting for -- which would otherwise block everything queued behind it.
+     * Set false to leave the kernel running after a timeout.
+     */
+    interruptOnTimeout?: boolean;
+}
+/** One evaluated user expression: its rich value, or the error evaluating it raised. */
+export type UserExpressionResult = {
+    status: 'ok';
+    data: Record<string, any>;
+    metadata: Record<string, any>;
+} | {
+    status: 'error';
+    ename: string;
+    evalue: string;
+    traceback: string[];
+};
+export interface ExecutionResult {
+    success: boolean;
+    output: JupyterMessage[];
+    error?: Error;
+    executionCount?: number;
+    /** The execute_reply's own status; 'aborted' means it never ran (see ExecutionOptions.stopOnError). */
+    status?: 'ok' | 'error' | 'aborted';
+    /** True when this execution was skipped because an earlier one failed with stopOnError. */
+    aborted?: boolean;
+    /** Results of ExecutionOptions.userExpressions, by name. */
+    userExpressions?: Record<string, UserExpressionResult>;
+}
+/**
+ * One past execute() call's full record: the code that ran, its kernel-
+ * reported execution count (if the reply included one -- a silent execution
+ * never gets one), and every iopub message it produced (stream/
+ * execute_result/display_data/error/status/...), in arrival order. Kept by
+ * Session.getHistory() for the life of that Session object -- purely
+ * in-memory, gone once the Session (or its owning process) does, same as
+ * everything else client-side. See Session.getHistory()'s own doc comment
+ * for why this exists and how it differs from queryKernelHistory().
+ */
+export interface ExecutionHistoryEntry {
+    code: string;
+    executionCount?: number;
+    time: number;
+    messages: JupyterMessage[];
+    /**
+     * True when this execution printed so much that the oldest stream
+     * (stdout/stderr) messages were dropped to bound memory: the entry keeps
+     * the most recent ~500 KB of stream text and everything else (results,
+     * display data, errors) in full.
+     */
+    truncated?: boolean;
+}
+/**
+ * Options for Session.queryKernelHistory(), mirroring Jupyter's real
+ * history_request wire message (KernelCore::historyRequest() ->
+ * HistoryManager::processRequest(), native/src/adrastea/core/history/) --
+ * see that function's own field reads for exactly which of these apply to
+ * which histAccessType.
+ */
+export interface KernelHistoryOptions {
+    /** Defaults to 'tail' -- the n most recent executions. */
+    histAccessType?: 'tail' | 'range' | 'search';
+    /** Include each entry's output alongside its input. Defaults to false -- the kernel doesn't actually record output today either way, so this currently only ever comes back empty. */
+    output?: boolean;
+    raw?: boolean;
+    /** Max entries to return ('tail'/'search'). Defaults to 100. */
+    n?: number;
+    /** 'range' only. */
+    session?: number;
+    start?: number;
+    stop?: number;
+    /** 'search' only -- a glob pattern (*, ?). */
+    pattern?: string;
+    unique?: boolean;
+}
+/**
+ * One entry from a real history_reply: [session, line_number, input], or
+ * [session, line_number, [input, output]] when `output: true` was requested
+ * (see KernelHistoryOptions.output's own caveat -- output is currently
+ * always "").
+ */
+export type KernelHistoryEntry = [number, number, string | [string, string]];
+/** The supervisor's latest view of a kernel's heartbeat -- see Session.status(). */
+export interface HeartbeatInfo {
+    /** False until the first ping has been answered. */
+    hasPong: boolean;
+    /** Round trip of the most recent answered ping, in ms. */
+    rttMs: number;
+    /** How long ago that answer arrived, in ms. */
+    sinceLastPongMs: number;
+    /** Pings in a row that went unanswered (0 = healthy). */
+    misses: number;
+}
+/** What the supervisor knows about one session's kernel process. */
+export interface SessionStatusInfo {
+    sessionId: string;
+    status: 'starting' | 'ready' | 'stopped' | 'crashed';
+    kernelType: 'r' | 'python';
+    workingDirectory: string;
+    /** OS process id of the kernel; 0 when it is not running. */
+    pid: number;
+    /** Resident memory in bytes, or null where it can't be read. */
+    memoryBytes: number | null;
+    heartbeat: HeartbeatInfo | null;
+}
+export interface ShinyAppOptions {
+    /** Directory containing the Shiny app (server.R/ui.R or app.R). */
+    appDir: string;
+    /** Defaults to an OS-assigned free port. */
+    port?: number;
+    /** Defaults to '127.0.0.1'. */
+    host?: string;
+    /** Defaults to false -- the caller decides how/where to display the app. */
+    launchBrowser?: boolean;
+    /** Max time to wait for the app to start accepting connections, in ms. Defaults to 10000. */
+    readyTimeout?: number;
+    /**
+     * Environment variables to set (via Sys.setenv()) in the R session
+     * before launching the app -- e.g. rmncah's app.R reads
+     * CDSUITE_SHINY_NAME/CDSUITE_SHINY_VERSION/CDSUITE_SHINY_SELECTED_FILE/
+     * CDSUITE_SHINY_LOCALE via Sys.getenv(). Applied only for the duration
+     * of this R session (not the OS process), and only take effect for code
+     * that reads them after runApp() starts, since Sys.setenv() itself runs
+     * synchronously right before it in the same execute() call.
+     */
+    env?: Record<string, string>;
+}
+export interface ShinyAppHandle {
+    host: string;
+    port: number;
+    url: string;
+    /**
+     * Resolves with the R-side execute_reply once the app stops (e.g. via
+     * interrupt/restart) or crashes -- shiny::runApp() blocks the R session
+     * for as long as the app is running, so this does NOT resolve just
+     * because the app started successfully. Await `createShiny()` itself
+     * for that.
+     */
+    done: Promise<ExecutionResult>;
+}
+/**
+ * Reply contents for the Jupyter request/reply pairs Session exposes as
+ * methods -- see Session.complete()/inspect()/isComplete()/kernelInfo()/
+ * commInfo()/interrupt(). All of them carry the standard `status`.
+ */
+export interface CompleteReplyContent {
+    status: 'ok' | 'error';
+    matches: string[];
+    cursor_start: number;
+    cursor_end: number;
+    metadata: Record<string, any>;
+}
+export interface InspectReplyContent {
+    status: 'ok' | 'error';
+    found: boolean;
+    data: Record<string, any>;
+    metadata: Record<string, any>;
+}
+export interface IsCompleteReplyContent {
+    status: 'complete' | 'incomplete' | 'invalid' | 'unknown';
+    indent?: string;
+}
+export interface KernelInfoReplyContent {
+    status: 'ok' | 'error';
+    protocol_version: string;
+    implementation: string;
+    implementation_version: string;
+    language_info: {
+        name: string;
+        version: string;
+        mimetype: string;
+        file_extension: string;
+        pygments_lexer?: string;
+        codemirror_mode?: string | Record<string, any>;
+        nbconvert_exporter?: string;
+    };
+    banner: string;
+    help_links?: Array<{
+        text: string;
+        url: string;
+    }>;
+}
+export interface CommInfoReplyContent {
+    status: 'ok' | 'error';
+    /** comm_id -> {target_name} for every comm currently open in the kernel. */
+    comms: Record<string, {
+        target_name: string;
+    }>;
+}
+export interface InterruptReplyContent {
+    status: 'ok' | 'error';
+}
+export interface ShutdownReplyContent {
+    status: 'ok' | 'error';
+    restart: boolean;
+}
+//# sourceMappingURL=engine.d.ts.map

package/lib/types/engine.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=engine.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './messages.js';
+export * from './engine.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,3 @@
+export * from './messages.js';
+export * from './engine.js';
+//# sourceMappingURL=index.js.map

package/lib/types/messages.d.ts

@@ -0,0 +1,68 @@
+export type MessageTopic = 'stream' | 'execute_result' | 'display_data' | 'error' | 'execute_reply' | 'comm_open' | 'comm_msg' | 'comm_close' | 'status' | string;
+export type MessageChannel = 'iopub' | 'shell' | 'stdin' | 'control';
+export interface JupyterMessage<T = any> {
+    topic: MessageTopic;
+    msgType: string;
+    channel: MessageChannel;
+    parentMsgId: string;
+    content: T;
+    timestamp: number;
+    raw: string;
+}
+export interface StreamContent {
+    name: 'stdout' | 'stderr';
+    text: string;
+}
+export interface ExecuteResultContent {
+    execution_count: number;
+    data: {
+        'text/plain'?: string | string[];
+        'text/html'?: string;
+        'image/png'?: string;
+        [key: string]: any;
+    };
+    metadata: Record<string, any>;
+}
+export interface ErrorContent {
+    ename: string;
+    evalue: string;
+    traceback: string[];
+}
+export interface DisplayDataContent {
+    data: Record<string, any>;
+    metadata: Record<string, any>;
+}
+export interface InputRequestContent {
+    prompt: string;
+    password: boolean;
+}
+export type ExecutionState = 'busy' | 'idle' | 'starting';
+export interface StatusContent {
+    execution_state: ExecutionState;
+}
+export interface ExecuteInputContent {
+    code: string;
+    execution_count: number;
+}
+export interface ClearOutputContent {
+    wait: boolean;
+}
+export interface UpdateDisplayDataContent extends DisplayDataContent {
+    transient?: {
+        display_id?: string;
+    };
+}
+export interface CommOpenContent {
+    comm_id: string;
+    target_name: string;
+    data: Record<string, any>;
+}
+export interface CommMsgContent {
+    comm_id: string;
+    data: Record<string, any>;
+}
+export interface CommCloseContent {
+    comm_id: string;
+    data: Record<string, any>;
+}
+//# sourceMappingURL=messages.d.ts.map

package/lib/types/messages.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=messages.js.map

package/lib/utils/logger.d.ts

@@ -0,0 +1,12 @@
+import type { LoggerFunction } from '../types/index.js';
+export declare function timestamp(): string;
+export declare class Logger {
+    private customLogger?;
+    constructor(customLogger?: LoggerFunction);
+    trace(message: string, data?: any): void;
+    debug(message: string, data?: any): void;
+    info(message: string, data?: any): void;
+    warn(message: string, data?: any): void;
+    error(message: string, error?: any): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/lib/utils/logger.js

@@ -0,0 +1,58 @@
+// Matches the timestamp format used throughout VS Code's own logs
+// (exthost.log, output channels, etc.): "YYYY-MM-DD HH:mm:ss.mmm". Kept
+// local rather than pulled from a date library so this has no runtime
+// dependency beyond what's already here. Exported for the handful of call
+// sites (e.g. session-worker.ts) that log before a Logger instance exists.
+export function timestamp() {
+    const now = new Date();
+    const pad = (n, width = 2) => String(n).padStart(width, '0');
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ` +
+        `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}.${pad(now.getMilliseconds(), 3)}`;
+}
+export class Logger {
+    customLogger;
+    constructor(customLogger) {
+        this.customLogger = customLogger;
+    }
+    trace(message, data) {
+        if (this.customLogger) {
+            this.customLogger('trace', message, data);
+        }
+        else {
+            console.log(`${timestamp()} [trace] ${message}`, data ? data : '');
+        }
+    }
+    debug(message, data) {
+        if (this.customLogger) {
+            this.customLogger('debug', message, data);
+        }
+        else {
+            console.log(`${timestamp()} [debug] ${message}`, data ? data : '');
+        }
+    }
+    info(message, data) {
+        if (this.customLogger) {
+            this.customLogger('info', message, data);
+        }
+        else {
+            console.log(`${timestamp()} [info] ${message}`, data ? data : '');
+        }
+    }
+    warn(message, data) {
+        if (this.customLogger) {
+            this.customLogger('warn', message, data);
+        }
+        else {
+            console.warn(`${timestamp()} [warn] ${message}`, data ? data : '');
+        }
+    }
+    error(message, error) {
+        if (this.customLogger) {
+            this.customLogger('error', message, error);
+        }
+        else {
+            console.error(`${timestamp()} [error] ${message}`, error ? error : '');
+        }
+    }
+}
+//# sourceMappingURL=logger.js.map

package/lib/utils/network.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Asks the OS for an available TCP port by binding to port 0 and reading
+ * back what got assigned.
+ */
+export declare function findFreePort(host?: string): Promise<number>;
+/**
+ * Polls `host:port` until something accepts a TCP connection, or rejects
+ * once `timeoutMs` elapses without one.
+ */
+export declare function waitForPort(host: string, port: number, timeoutMs: number): Promise<void>;
+//# sourceMappingURL=network.d.ts.map

package/lib/utils/network.js

@@ -0,0 +1,50 @@
+import * as net from 'net';
+/**
+ * Asks the OS for an available TCP port by binding to port 0 and reading
+ * back what got assigned.
+ */
+export function findFreePort(host = '127.0.0.1') {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.once('error', reject);
+        server.listen(0, host, () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : undefined;
+            server.close(() => {
+                if (port) {
+                    resolve(port);
+                }
+                else {
+                    reject(new Error('Failed to allocate a free port'));
+                }
+            });
+        });
+    });
+}
+/**
+ * Polls `host:port` until something accepts a TCP connection, or rejects
+ * once `timeoutMs` elapses without one.
+ */
+export function waitForPort(host, port, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    return new Promise((resolve, reject) => {
+        const attempt = () => {
+            const socket = net.connect({ host, port }, () => {
+                socket.destroy();
+                resolve();
+            });
+            socket.once('error', () => {
+                socket.destroy();
+                if (Date.now() >= deadline) {
+                    reject(new Error(`Timed out waiting for ${host}:${port} to accept connections`));
+                }
+                else {
+                    setTimeout(attempt, 150);
+                }
+            });
+        };
+        attempt();
+    });
+}
+//# sourceMappingURL=network.js.map