@ecopages/core 0.2.0-beta.8 → 0.2.0-rc.0

package/src/adapters/shared/runtime/port-manager.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Detects whether a thrown error indicates the requested port is already in
+ * use.
+ *
+ * @remarks
+ * Matches Node's `code: 'EADDRINUSE'` and Bun's surface, where the error
+ * carries the same `code` plus a human-readable message such as
+ * `"Failed to start server. Is port 3000 in use?"`. Older Bun builds that do
+ * not set `.code` are covered by a fallback match on `syscall === 'listen'`
+ * plus the message shape.
+ */
+export declare function isPortInUseError(error: unknown): boolean;
+/**
+ * Probes whether a TCP port is currently bindable from this process. Uses a
+ * short-lived Node `net.Server` so both Node and Bun can run it via their
+ * Node-compatible core.
+ *
+ * @remarks
+ * A successful probe only guarantees the port was free at probe time; callers
+ * must still handle EADDRINUSE when they actually bind, since release races
+ * can flip the answer between probe and bind.
+ */
+export declare function isPortAvailable(port: number, hostname?: string): Promise<boolean>;
+/**
+ * Default interactive prompt. Asks a yes/no question on stdin/stdout and
+ * auto-approves (returns `true`) after `timeoutMs` with no input.
+ *
+ * @returns `true` when the user accepted (or timed out), `false` when they declined.
+ */
+export type PromptFunction = (message: string, timeoutMs: number) => Promise<boolean>;
+export interface PortManagerOptions {
+    /**
+     * Bind factory. Should throw on EADDRINUSE (or return `null`/`undefined`
+     * when it declines without a port collision). Returning a non-null port
+     * marks the bind as successful.
+     */
+    startOnPort: (port: number) => Promise<number | null | undefined>;
+    /** Emits the "moved to port X" warning when the bound port differs from the preferred port. */
+    warn?: (message: string) => void;
+    /** Infers a free port to display in the prompt. Defaults to {@link isPortAvailable}. */
+    probePort?: (port: number) => Promise<boolean>;
+    /** Custom prompter. Defaults to a readline-based yes/no prompt on the process stdio. */
+    prompt?: PromptFunction;
+    /** Enables the prompt flow at all. Defaults to `process.stdin.isTTY && process.stdout.isTTY`. */
+    interactive?: boolean;
+    /** Auto-approve timeout (ms) for the prompt. Defaults to 10000. */
+    autoApproveMs?: number;
+    /** Maximum port offset to scan when falling back. Defaults to 20. */
+    maxPortOffset?: number;
+    /** Retry attempts for the same port before declaring it taken. Defaults to 2. */
+    releaseRaceRetries?: number;
+    /** Backoff between same-port retries. Defaults to 100 ms. */
+    releaseRaceDelayMs?: number;
+}
+export interface BindPortOptions {
+    /** Port the caller would prefer to bind. */
+    preferredPort: number;
+    /**
+     * Whether the caller permits moving to the next free port automatically when
+     * the preferred port is busy and no interactive prompt is available
+     * (non-TTY / CI). Explicit ports that fall back silently in CI would surprise
+     * operators, so this is honoured by the non-interactive path only.
+     */
+    allowPortFallback: boolean;
+}
+/**
+ * Owns preview-port assignment: probing, race-release retries, fallback, and
+ * an optional interactive auto-approve prompt.
+ *
+ * @remarks
+ * Single-process API. The manager does not cache ports across calls; each
+ * `bind()` runs fresh from the preferred port.
+ */
+export declare class PortManager {
+    private readonly startOnPort;
+    private readonly warn;
+    private readonly probePort;
+    private readonly prompt;
+    private readonly interactive;
+    private readonly autoApproveMs;
+    private readonly maxPortOffset;
+    private readonly releaseRaceRetries;
+    private readonly releaseRaceDelayMs;
+    constructor(options: PortManagerOptions);
+    /**
+     * Binds the preview server to the preferred port.
+     *
+     * @remarks
+     * When the preferred port is free, binds it directly — no prompt, no
+     * fallback. The interactive prompt only fires on a genuine EADDRINUSE
+     * collision (TTY runs), and auto-approves after
+     * {@link PortManagerOptions.autoApproveMs}. In non-interactive (CI) runs,
+     * the manager falls back silently only when
+     * {@link BindPortOptions.allowPortFallback} is true (the default-port
+     * path); pinned ports rethrow EADDRINUSE so Docker-style fixed-port
+     * deployments fail loudly instead of silently moving.
+     */
+    bind(options: BindPortOptions): Promise<number | null>;
+    private shouldFallback;
+    private fallForward;
+    /**
+     * Attempts to bind via {@link PortManagerOptions.startOnPort} on `port`,
+     * retrying EADDRINUSE collisions up to
+     * {@link PortManagerOptions.releaseRaceRetries} to ride through TIME_WAIT
+     * race release.
+     *
+     * @remarks
+     * Only EADDRINUSE is retryable. Any other error is rethrown synchronously
+     * rather than swallowed as a soft "port taken" result, so a misconfigured
+     * factory surfaces loudly instead of causing a silent fallback. A `null`
+     * return from the factory (no throw) is reported as `factory-refused`, not
+     * conflated with a real collision.
+     */
+    private tryPort;
+    private findNextFreePort;
+}

package/src/adapters/shared/runtime/port-manager.js

@@ -0,0 +1,226 @@
+import { createServer as createNetServer } from 'node:net';
+import { createInterface } from 'node:readline';
+/**
+ * Detects whether a thrown error indicates the requested port is already in
+ * use.
+ *
+ * @remarks
+ * Matches Node's `code: 'EADDRINUSE'` and Bun's surface, where the error
+ * carries the same `code` plus a human-readable message such as
+ * `"Failed to start server. Is port 3000 in use?"`. Older Bun builds that do
+ * not set `.code` are covered by a fallback match on `syscall === 'listen'`
+ * plus the message shape.
+ */
+export function isPortInUseError(error) {
+    if (!(error instanceof Error) && (typeof error !== 'object' || error === null)) {
+        return false;
+    }
+    const maybeErr = error;
+    const code = typeof maybeErr.code === 'string' || typeof maybeErr.code === 'number' ? String(maybeErr.code) : undefined;
+    const syscall = typeof maybeErr.syscall === 'string' ? maybeErr.syscall : undefined;
+    const message = error instanceof Error ? error.message : String(maybeErr.message ?? '');
+    if (code === 'EADDRINUSE') {
+        return true;
+    }
+    if (message.includes('EADDRINUSE')) {
+        return true;
+    }
+    if (syscall === 'listen' && /is port \d+ in use\??/i.test(message)) {
+        return true;
+    }
+    return false;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Probes whether a TCP port is currently bindable from this process. Uses a
+ * short-lived Node `net.Server` so both Node and Bun can run it via their
+ * Node-compatible core.
+ *
+ * @remarks
+ * A successful probe only guarantees the port was free at probe time; callers
+ * must still handle EADDRINUSE when they actually bind, since release races
+ * can flip the answer between probe and bind.
+ */
+export function isPortAvailable(port, hostname = '127.0.0.1') {
+    return new Promise((resolve) => {
+        const tester = createNetServer();
+        tester.once('error', () => resolve(false));
+        tester.once('listening', () => {
+            tester.close(() => resolve(true));
+        });
+        tester.listen(port, hostname);
+    });
+}
+function createDefaultPrompt(stdin, stdout) {
+    return async (message, timeoutMs) => {
+        stdout.write(`${message} `);
+        return await new Promise((resolve) => {
+            const rl = createInterface({ input: stdin, output: undefined, terminal: false });
+            let settled = false;
+            const finish = (value) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                rl.close();
+                stdout.write('\n');
+                resolve(value);
+            };
+            const timer = setTimeout(() => finish(true), timeoutMs);
+            rl.once('line', (line) => {
+                const answer = line.trim().toLowerCase();
+                if (answer === '' || answer === 'y' || answer === 'yes') {
+                    finish(true);
+                }
+                else {
+                    finish(false);
+                }
+            });
+            rl.once('close', () => finish(true));
+        });
+    };
+}
+const PREVIEW_PORT_RELEASE_RACE_RETRIES = 2;
+const PREVIEW_PORT_FALLBACK_ATTEMPTS = 20;
+const PREVIEW_PORT_RELEASE_RACE_DELAY_MS = 100;
+const PREVIEW_PORT_AUTO_APPROVE_MS = 10_000;
+/**
+ * Owns preview-port assignment: probing, race-release retries, fallback, and
+ * an optional interactive auto-approve prompt.
+ *
+ * @remarks
+ * Single-process API. The manager does not cache ports across calls; each
+ * `bind()` runs fresh from the preferred port.
+ */
+export class PortManager {
+    startOnPort;
+    warn;
+    probePort;
+    prompt;
+    interactive;
+    autoApproveMs;
+    maxPortOffset;
+    releaseRaceRetries;
+    releaseRaceDelayMs;
+    constructor(options) {
+        this.startOnPort = options.startOnPort;
+        this.warn = options.warn;
+        this.probePort = options.probePort ?? isPortAvailable;
+        this.maxPortOffset = options.maxPortOffset ?? PREVIEW_PORT_FALLBACK_ATTEMPTS - 1;
+        this.releaseRaceRetries = options.releaseRaceRetries ?? PREVIEW_PORT_RELEASE_RACE_RETRIES;
+        this.releaseRaceDelayMs = options.releaseRaceDelayMs ?? PREVIEW_PORT_RELEASE_RACE_DELAY_MS;
+        this.autoApproveMs = options.autoApproveMs ?? PREVIEW_PORT_AUTO_APPROVE_MS;
+        this.interactive =
+            typeof options.interactive === 'boolean'
+                ? options.interactive
+                : Boolean(typeof process !== 'undefined' && process.stdin?.isTTY && process.stdout?.isTTY);
+        if (options.prompt) {
+            this.prompt = options.prompt;
+        }
+        else if (this.interactive) {
+            this.prompt = createDefaultPrompt(process.stdin, process.stdout);
+        }
+        else {
+            this.prompt = undefined;
+        }
+    }
+    /**
+     * Binds the preview server to the preferred port.
+     *
+     * @remarks
+     * When the preferred port is free, binds it directly — no prompt, no
+     * fallback. The interactive prompt only fires on a genuine EADDRINUSE
+     * collision (TTY runs), and auto-approves after
+     * {@link PortManagerOptions.autoApproveMs}. In non-interactive (CI) runs,
+     * the manager falls back silently only when
+     * {@link BindPortOptions.allowPortFallback} is true (the default-port
+     * path); pinned ports rethrow EADDRINUSE so Docker-style fixed-port
+     * deployments fail loudly instead of silently moving.
+     */
+    async bind(options) {
+        const preferredPort = options.preferredPort;
+        const firstAttempt = await this.tryPort(preferredPort);
+        if (firstAttempt.status === 'bound') {
+            return firstAttempt.boundPort;
+        }
+        if (firstAttempt.status === 'factory-refused') {
+            return null;
+        }
+        // firstAttempt.status === 'port-in-use'
+        await this.shouldFallback(preferredPort, options.allowPortFallback, firstAttempt.error);
+        return await this.fallForward(preferredPort);
+    }
+    async shouldFallback(preferredPort, allowPortFallback, error) {
+        if (this.interactive && this.prompt) {
+            const nextFree = await this.findNextFreePort(preferredPort);
+            const nextFreeSuffix = typeof nextFree === 'number' ? ` (next free: ${nextFree})` : '';
+            const autoApproveHint = `auto-yes in ${Math.round(this.autoApproveMs / 1000)}s`;
+            const message = `[@ecopages/core] Port ${preferredPort} is already in use${nextFreeSuffix}. Bind there instead? [Y/n] (${autoApproveHint})`;
+            const accepted = await this.prompt(message, this.autoApproveMs);
+            if (!accepted) {
+                throw error;
+            }
+            return;
+        }
+        if (!allowPortFallback) {
+            throw error;
+        }
+    }
+    async fallForward(preferredPort) {
+        for (let offset = 1; offset <= this.maxPortOffset; offset += 1) {
+            const candidatePort = preferredPort + offset;
+            const attempt = await this.tryPort(candidatePort);
+            if (attempt.status === 'bound') {
+                this.warn?.(`Port ${preferredPort} is in use; preview serving on port ${attempt.boundPort} instead. Pin the preview port with --port or ECOPAGES_PORT when a fixed binding is required.`);
+                return attempt.boundPort;
+            }
+        }
+        return null;
+    }
+    /**
+     * Attempts to bind via {@link PortManagerOptions.startOnPort} on `port`,
+     * retrying EADDRINUSE collisions up to
+     * {@link PortManagerOptions.releaseRaceRetries} to ride through TIME_WAIT
+     * race release.
+     *
+     * @remarks
+     * Only EADDRINUSE is retryable. Any other error is rethrown synchronously
+     * rather than swallowed as a soft "port taken" result, so a misconfigured
+     * factory surfaces loudly instead of causing a silent fallback. A `null`
+     * return from the factory (no throw) is reported as `factory-refused`, not
+     * conflated with a real collision.
+     */
+    async tryPort(port) {
+        for (let attempt = 0; attempt < this.releaseRaceRetries; attempt += 1) {
+            try {
+                const bound = await this.startOnPort(port);
+                if (bound) {
+                    return { status: 'bound', boundPort: bound };
+                }
+                return { status: 'factory-refused' };
+            }
+            catch (error) {
+                if (!isPortInUseError(error)) {
+                    throw error;
+                }
+                if (attempt === this.releaseRaceRetries - 1) {
+                    return { status: 'port-in-use', error };
+                }
+                await sleep(this.releaseRaceDelayMs);
+            }
+        }
+        return { status: 'factory-refused' };
+    }
+    async findNextFreePort(startPort) {
+        for (let offset = 1; offset <= this.maxPortOffset; offset += 1) {
+            const candidate = startPort + offset;
+            if (await this.probePort(candidate)) {
+                return candidate;
+            }
+        }
+        return null;
+    }
+}

package/src/adapters/shared/{render-context.d.ts → runtime/render-context.d.ts}

@@ -1,5 +1,5 @@
-import type { RenderContext } from '../../types/public-types.js';
-import type { AnyIntegrationPlugin } from '../../plugins/integration-plugin.js';
+import type { RenderContext } from '../../../types/public-types.js';
+import type { AnyIntegrationPlugin } from '../../../plugins/integration-plugin.js';
 export interface CreateRenderContextOptions {
     integrations: AnyIntegrationPlugin[];
     rendererModules?: unknown;

package/src/adapters/shared/runtime/render-context.js

@@ -0,0 +1,99 @@
+import { fileURLToPath } from 'node:url';
+import { invariant } from '../../../utils/invariant.js';
+import { createBodyResponse } from '../http/create-body-response.js';
+function resolveServerModulePath(filePath) {
+    return filePath instanceof URL ? fileURLToPath(filePath) : filePath;
+}
+/**
+ * Merges request locals into component props as a dedicated 'locals' property.
+ * This prevents naming conflicts and maintains type safety by keeping locals
+ * separate from other props.
+ *
+ * @param props - The original component props
+ * @param locals - Optional request-scoped locals from middleware
+ * @returns Props with locals merged in, or original props if no locals provided
+ */
+function mergePropsWithLocals(props, locals) {
+    if (!locals || typeof props !== 'object' || props === null) {
+        return props;
+    }
+    return { ...props, locals };
+}
+/**
+ * Creates a render context for route handlers.
+ * Provides render(), renderPartial(), json(), and html() methods that can be used
+ * within route handlers to generate responses.
+ *
+ * @param options - Configuration options including available integrations
+ * @returns A RenderContext object with methods for rendering views and creating responses
+ */
+export function createRenderContext(options) {
+    const { integrations } = options;
+    /**
+     * Resolves the appropriate renderer for a given view component based on its integration.
+     * Throws an error if the integration cannot be determined or is not found.
+     */
+    const getRendererForView = (view) => {
+        const integrationName = view.config?.integration ?? view.config?.identity?.integration;
+        invariant(!!integrationName, 'Cannot determine integration for view. Set view.config.integration explicitly or ensure the view is defined with eco.page() in a file with a recognized extension.');
+        const integration = integrations.find((i) => i.name === integrationName);
+        invariant(!!integration, `No integration found for: ${integrationName}`);
+        return integration.initializeRenderer({
+            rendererModules: options.rendererModules,
+        });
+    };
+    const renderContext = {
+        importServerModule: async (filePath) => {
+            invariant(!!options.importServerModule, 'Server module importing is not available in this render context.');
+            return (await options.importServerModule(resolveServerModulePath(filePath)));
+        },
+        async renderServerModule(filePath, props, renderOptions) {
+            const module = await renderContext.importServerModule(filePath);
+            const view = module.default;
+            const locals = this?.locals;
+            const mergedProps = mergePropsWithLocals(props ?? {}, locals);
+            const renderer = getRendererForView(view);
+            const ctx = {
+                partial: false,
+                status: renderOptions?.status,
+                headers: renderOptions?.headers,
+            };
+            return await renderer.renderToResponse(view, mergedProps, ctx);
+        },
+        async render(view, props, renderOptions) {
+            const locals = this?.locals;
+            const mergedProps = mergePropsWithLocals(props ?? {}, locals);
+            const renderer = getRendererForView(view);
+            const ctx = {
+                partial: false,
+                status: renderOptions?.status,
+                headers: renderOptions?.headers,
+            };
+            return renderer.renderToResponse(view, mergedProps, ctx);
+        },
+        async renderPartial(view, props, renderOptions) {
+            const locals = this?.locals;
+            const mergedProps = mergePropsWithLocals(props, locals);
+            const renderer = getRendererForView(view);
+            const ctx = {
+                partial: true,
+                status: renderOptions?.status,
+                headers: renderOptions?.headers,
+            };
+            return renderer.renderToResponse(view, mergedProps, ctx);
+        },
+        json(data, responseOptions) {
+            return createBodyResponse('json', data, {
+                status: responseOptions?.status,
+                headers: responseOptions?.headers,
+            });
+        },
+        html(content, responseOptions) {
+            return createBodyResponse('html', content, {
+                status: responseOptions?.status,
+                headers: responseOptions?.headers,
+            });
+        },
+    };
+    return renderContext;
+}

package/src/adapters/shared/{runtime-app-bootstrap.d.ts → runtime/runtime-app-bootstrap.d.ts}

@@ -1,11 +1,13 @@
-import type { ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ReturnParseCliArgs } from '../../../utils/parse-cli-args.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
 export type RuntimeBinding = {
     preferredPort: number;
     preferredHostname: string;
     runtimeOrigin: string;
     serveOptions: Record<string, unknown>;
     watch: boolean;
+    /** Whether preview may bind to the next free port when the preferred port is busy. */
+    allowPortFallback: boolean;
 };
 export type StaticRuntimeMode = {
     canBuildWithoutRuntimeServer: boolean;

package/src/adapters/shared/runtime/runtime-app-bootstrap.js

@@ -0,0 +1,38 @@
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from '../../../config/constants.js';
+function normalizeOriginHostname(hostname) {
+    if (hostname.includes(':') && !hostname.startsWith('[') && !hostname.endsWith(']')) {
+        return `[${hostname}]`;
+    }
+    return hostname;
+}
+export function resolveServeRuntimeOrigin(serveOptions) {
+    const hostname = normalizeOriginHostname(String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME));
+    const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
+    return `http://${hostname}:${port}`;
+}
+export function resolveRuntimeBinding(options) {
+    const env = options.env ?? process.env;
+    const portExplicitlyConfigured = options.cliArgs.port !== undefined || Boolean(env.ECOPAGES_PORT) || options.serverOptions?.port !== undefined;
+    const preferredPort = options.cliArgs.port ?? (env.ECOPAGES_PORT ? Number(env.ECOPAGES_PORT) : undefined) ?? DEFAULT_ECOPAGES_PORT;
+    const preferredHostname = options.cliArgs.hostname ?? env.ECOPAGES_HOSTNAME ?? DEFAULT_ECOPAGES_HOSTNAME;
+    return {
+        preferredPort,
+        preferredHostname,
+        allowPortFallback: !portExplicitlyConfigured,
+        runtimeOrigin: resolveServeRuntimeOrigin({
+            hostname: preferredHostname,
+            port: preferredPort,
+        }),
+        serveOptions: {
+            port: preferredPort,
+            hostname: preferredHostname,
+            ...(options.serverOptions ?? {}),
+        },
+        watch: options.cliArgs.dev,
+    };
+}
+export function resolveStaticRuntimeMode(options) {
+    return {
+        canBuildWithoutRuntimeServer: options.cliArgs.build || options.cliArgs.preview,
+    };
+}

package/src/adapters/shared/runtime/runtime-server-lifecycle.d.ts

@@ -0,0 +1,45 @@
+import type { EcoPagesAppConfig, IHmrManager } from '../../../types/internal-types.js';
+import type { ProjectWatcher } from '../../../watchers/project-watcher.js';
+/**
+ * Copies source `public/` into dist and ensures the resolved assets directory exists.
+ */
+export declare function prepareRuntimePublicDir(appConfig: EcoPagesAppConfig): void;
+/**
+ * Attaches the shared HMR manager to every integration exactly once per app config.
+ *
+ * @remarks
+ * Runtime plugin setup must not call `integration.setHmrManager()` directly. Adapters invoke
+ * this after the manager is enabled so late plugin init cannot double-bind integrations.
+ */
+export declare function attachHmrToIntegrations(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): void;
+/**
+ * Starts background activation of every configured integration after watch-mode HMR is ready.
+ *
+ * @remarks
+ * Fire-and-forget: overlaps with watcher setup so first-page render can join the same
+ * coalesced {@link ensureIntegrationRuntimeReady} promise instead of paying a cold vendor build.
+ * Failures are logged and do not crash the server.
+ */
+export declare function startDevWarmup(options: {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+}): void;
+/**
+ * Releases shared dev resources in a consistent order across server adapters.
+ *
+ * @remarks
+ * Bun calls `buildRuntime()` during `initialize()` when watch is enabled; Node defers
+ * runtime creation to `completeInitialization()`. Transport-specific setup stays in
+ * each adapter — only shared teardown lives here.
+ */
+export declare function disposeDevResources(options: {
+    projectWatcher: ProjectWatcher | null | undefined;
+    appConfig: EcoPagesAppConfig;
+    hmrManager: IHmrManager | null | undefined;
+    bridge: {
+        destroy(): void;
+    } | null | undefined;
+    previewHost: {
+        stop(): Promise<void>;
+    };
+}): Promise<void>;

package/src/adapters/shared/runtime/runtime-server-lifecycle.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { RESOLVED_ASSETS_DIR } from '../../../config/constants.js';
+import { disposeAppBuildRuntime } from '../../../build/runtime/build-runtime.js';
+import { ensureIntegrationRuntimeReady } from '../../../build/app-build-manifest-runtime.js';
+import { appLogger } from '../../../global/app-logger.js';
+import { copyRuntimePublicDirIfChanged } from './copy-runtime-public-dir.js';
+import { clearAppDevClientBridge } from '../../../dev/client-bridge-registry.js';
+import { clearAppHmrManager } from '../../../dev/hmr-manager-registry.js';
+/**
+ * Copies source `public/` into dist and ensures the resolved assets directory exists.
+ */
+export function prepareRuntimePublicDir(appConfig) {
+    const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
+    if (fileSystem.exists(srcPublicDir)) {
+        copyRuntimePublicDirIfChanged(srcPublicDir, path.join(appConfig.rootDir, appConfig.distDir));
+    }
+    fileSystem.ensureDir(path.join(appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
+}
+const attachedHmrApps = new WeakSet();
+/**
+ * Attaches the shared HMR manager to every integration exactly once per app config.
+ *
+ * @remarks
+ * Runtime plugin setup must not call `integration.setHmrManager()` directly. Adapters invoke
+ * this after the manager is enabled so late plugin init cannot double-bind integrations.
+ */
+export function attachHmrToIntegrations(appConfig, hmrManager) {
+    if (attachedHmrApps.has(appConfig)) {
+        return;
+    }
+    attachedHmrApps.add(appConfig);
+    for (const integration of appConfig.integrations) {
+        integration.setHmrManager(hmrManager);
+    }
+}
+/**
+ * Starts background activation of every configured integration after watch-mode HMR is ready.
+ *
+ * @remarks
+ * Fire-and-forget: overlaps with watcher setup so first-page render can join the same
+ * coalesced {@link ensureIntegrationRuntimeReady} promise instead of paying a cold vendor build.
+ * Failures are logged and do not crash the server.
+ */
+export function startDevWarmup(options) {
+    const { appConfig, runtimeOrigin } = options;
+    void Promise.all(appConfig.integrations.map((integration) => ensureIntegrationRuntimeReady({
+        appConfig,
+        integrationName: integration.name,
+        runtimeOrigin,
+    }))).catch((error) => {
+        appLogger.error(`Failed to prewarm integration runtimes: ${error instanceof Error ? error.message : String(error)}`);
+    });
+}
+/**
+ * Releases shared dev resources in a consistent order across server adapters.
+ *
+ * @remarks
+ * Bun calls `buildRuntime()` during `initialize()` when watch is enabled; Node defers
+ * runtime creation to `completeInitialization()`. Transport-specific setup stays in
+ * each adapter — only shared teardown lives here.
+ */
+export async function disposeDevResources(options) {
+    await options.projectWatcher?.close();
+    await disposeAppBuildRuntime(options.appConfig);
+    options.hmrManager?.stop();
+    options.bridge?.destroy();
+    clearAppDevClientBridge(options.appConfig);
+    clearAppHmrManager(options.appConfig);
+    await options.previewHost.stop();
+}