@ressjs/cli 0.6.0-experimental.0

package/bin/ress.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/cli/main.js')

package/dist/api/app.d.ts

@@ -0,0 +1,4 @@
+import { OUT_DIR } from '@ressjs/vite-router';
+import type { RessApp, RessAppOptions } from './types.js';
+export declare function createRessApp(opts?: RessAppOptions): Promise<RessApp>;
+export { OUT_DIR };

package/dist/api/app.js

@@ -0,0 +1,189 @@
+/**
+ * `createRessApp` — la única construcción de la aplicación de servidor.
+ *
+ * `startDevServer`, `startProdServer`, el archivo de servidor del proyecto (vía
+ * de escape nivel 2) y el uso programático (nivel 3) comparten esta función. No
+ * hay una cuarta forma de construir la app.
+ *
+ * Reutiliza lo que F-015/F-018 ya construyen — `createRuntime` arma el servidor
+ * de Vite o los artefactos de producción, `createViteRouter` monta el
+ * enrutador— en vez de reimplementarlos. El plan de esta spec nombra un
+ * `createRessRouter` que no existe como tal en `@ressjs/vite-router`: lo que
+ * el paquete expone es `createViteRouter`, que hace exactamente lo mismo
+ * (enumera rutas, construye el pipeline de petición, se mantiene al día con un
+ * watcher). Se usa ese nombre real en vez de inventar un alias.
+ */
+import http from 'node:http';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import express from 'express';
+import react from '@vitejs/plugin-react';
+import { assetPrefixFor, createRouteManifest, createRuntime, createViteRouter, loadRouteManifest, OUT_DIR, ressPlugin, ROUTE_MANIFEST_VERSION, scanRoutes, waitForViteRouter, } from '@ressjs/vite-router';
+import { resolveOptions } from './options.js';
+import { silentReporter } from './reporter.js';
+import { RessError } from './errors.js';
+import { applyServerFile } from './extend.js';
+/** Cierra un `http.Server`, tolerando que ya esté cerrado. Idempotente. */
+function closeHttpServer(server) {
+    if (!server.listening)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        server.close((err) => (err && err.code !== 'ERR_SERVER_NOT_RUNNING' ? reject(err) : resolve()));
+    });
+}
+async function assertBuildPresent(root, outDir) {
+    const manifestPath = path.join(root, outDir, 'route-manifest.json');
+    let raw;
+    try {
+        raw = await fs.readFile(manifestPath, 'utf-8');
+    }
+    catch {
+        throw RessError.buildMissing(path.join(outDir));
+    }
+    try {
+        loadRouteManifest(raw);
+    }
+    catch {
+        const data = JSON.parse(raw);
+        throw RessError.buildIncompatible(data.version ?? -1, ROUTE_MANIFEST_VERSION);
+    }
+}
+export async function createRessApp(opts = {}) {
+    const configStart = Date.now();
+    const reporter = opts.reporter ?? silentReporter;
+    // El host por defecto difiere por modo: en desarrollo, sólo esta máquina; en
+    // producción, abierto — es la tabla de `ress dev` / `ress start` del plan.
+    const mode = opts.mode ?? 'development';
+    const options = await resolveOptions(opts, {
+        mode,
+        host: mode === 'production' ? '0.0.0.0' : 'localhost',
+    });
+    reporter.event({
+        type: 'config:loaded',
+        file: options.configFile.value,
+        durationMs: Date.now() - configStart,
+    });
+    const isProduction = options.mode.value === 'production';
+    const root = options.root.value;
+    if (isProduction) {
+        await assertBuildPresent(root, options.outDir.value);
+    }
+    const app = express();
+    // Vía de escape nivel 1: antes del enrutador del framework, gana ante sus rutas.
+    if (options.config.server.beforeRouter) {
+        await options.config.server.beforeRouter(app);
+        reporter.event({ type: 'server:extended', file: 'config', hook: 'before' });
+    }
+    const assetPrefix = assetPrefixFor({
+        basePath: options.base.value,
+        cdnPrefix: options.config.assets?.cdnPrefix,
+    });
+    // Un proyecto de ress.js no tiene `vite.config.ts`: la CLI es quien le pasa a
+    // Vite el plugin del framework y el de React. Sin esto, `createDevRuntime`
+    // dependería de que Vite encontrara un archivo de configuración que, por
+    // diseño, ya no existe en el proyecto (UC-1, UC-6).
+    const runtime = await createRuntime(isProduction, options.base.value, assetPrefix, {
+        plugins: [react(), ressPlugin()],
+    });
+    const router = createViteRouter({
+        isProduction,
+        basePath: options.base.value,
+        config: options.config,
+        runtime,
+    });
+    // `listen()` sólo queda disponible después de que el runtime, el manifest y
+    // las cadenas de rutas terminaron de construirse. Así no existe una ventana
+    // en la que el socket acepta conexiones pero las páginas todavía no están.
+    await waitForViteRouter(router);
+    app.use('/', router);
+    // Vía de escape nivel 1, segunda mitad: después del enrutador, no puede pisarlo.
+    if (options.config.server.afterRouter) {
+        await options.config.server.afterRouter(app);
+        reporter.event({ type: 'server:extended', file: 'config', hook: 'after' });
+    }
+    const routesStart = Date.now();
+    const manifest = isProduction
+        ? runtime.routes
+        : createRouteManifest(await scanRoutes({ pagesDir: path.join(root, 'app/pages') }));
+    reporter.event({
+        type: 'routes:scanned',
+        entries: [...manifest.entries],
+        durationMs: Date.now() - routesStart,
+    });
+    reporter.event({
+        type: 'catalog:built',
+        pages: runtime.catalog.pagesById.size,
+        variants: [...new Set(runtime.catalog.buildEntries.map((e) => e.variant.suffix).filter(Boolean))],
+    });
+    // Vía de escape nivel 2: el archivo de servidor del proyecto.
+    await applyServerFile({
+        app,
+        options,
+        mode: options.mode.value,
+        manifest,
+        vite: runtime.vite ?? undefined,
+        reporter,
+        moduleLoader: isProduction ? undefined : runtime.moduleLoader,
+        onSourceChange: isProduction ? undefined : runtime.onSourceChange,
+    });
+    let httpServer;
+    let closed = false;
+    const bindPort = (server, host, port, attempt = 0) => new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.off('listening', onListening);
+            if (err.code === 'EADDRINUSE') {
+                if (options.strictPort.value || attempt >= 20) {
+                    return reject(RessError.portInUse(port));
+                }
+                return resolve(bindPort(server, host, port + 1, attempt + 1));
+            }
+            reject(err);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            // `port: 0` le pide al SO un puerto libre; el que realmente se usó
+            // sólo se sabe después de escuchar, leyendo la dirección real.
+            const address = server.address();
+            resolve(typeof address === 'object' && address ? address.port : port);
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, host);
+    });
+    return {
+        app,
+        options,
+        manifest,
+        vite: runtime.vite ?? undefined,
+        async listen() {
+            if (httpServer)
+                throw new Error('[ress] Este RessApp ya está escuchando.');
+            const server = http.createServer(app);
+            httpServer = server;
+            const host = options.host.value;
+            const boundPort = await bindPort(server, host, options.port.value);
+            const displayHost = host === '0.0.0.0' ? 'localhost' : host;
+            const url = `http://${displayHost}:${boundPort}${options.base.value}`;
+            reporter.event({ type: 'server:listening', url, mode: options.mode.value, port: boundPort });
+            return {
+                url,
+                port: boundPort,
+                httpServer: server,
+                // No es sólo `RessServer.close()`: si alguien la llama y después llama
+                // también a `RessApp.close()` (o al revés — el shutdown de la CLI hace
+                // exactamente eso indirectamente), el segundo cierre no puede fallar
+                // con `ERR_SERVER_NOT_RUNNING` por encontrar el socket ya cerrado.
+                close: () => closeHttpServer(server),
+            };
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            if (httpServer)
+                await closeHttpServer(httpServer);
+            await runtime.close();
+        },
+    };
+}
+export { OUT_DIR };

package/dist/api/build.d.ts

@@ -0,0 +1,8 @@
+import type { BuildResult, RessAppOptions } from './types.js';
+export interface BuildAppOptions extends RessAppOptions {
+    /** Qué entorno construir. Default `'all'`: cliente y servidor, en ese orden. */
+    target?: 'all' | 'client' | 'ssr';
+    /** `false` conserva la salida anterior. Default `true`. */
+    clean?: boolean;
+}
+export declare function buildApp(opts?: BuildAppOptions): Promise<BuildResult>;

package/dist/api/build.js

@@ -0,0 +1,113 @@
+/**
+ * `ress build` — cliente y servidor en una sola invocación, en el orden que
+ * fija el framework.
+ *
+ * El orden lo decide `builder.buildApp` de F-015 (`defineEnvironments()` en
+ * `@ressjs/vite-router`, aplicado por `ressPlugin()`): primero cliente, después
+ * servidor, porque el servidor necesita el manifest de assets que produce el
+ * cliente. Esta función no reimplementa ese orden: crea el `builder` de Vite y
+ * lo invoca.
+ *
+ * **Límite conocido, documentado y no resuelto por esta spec**: `--out-dir` se
+ * acepta y queda registrado en `ResolvedRessOptions`, pero F-015/F-016/F-018
+ * escriben y leen siempre bajo la constante `OUT_DIR` (`dist/client`,
+ * `dist/server`, `dist/route-manifest.json`), sin parametrizarla. Cambiar eso
+ * cruza tres specs ajenas para una bandera de conveniencia; se avisa con un
+ * evento `warn` en vez de fingir que el build respeta la ruta pedida.
+ */
+import path from 'node:path';
+import { readdir, rm, stat } from 'node:fs/promises';
+import react from '@vitejs/plugin-react';
+import { getPages, buildVariantCatalog, OUT_DIR, ressPlugin, scanRoutes } from '@ressjs/vite-router';
+import { resolveOptions } from './options.js';
+import { silentReporter } from './reporter.js';
+import { RessError } from './errors.js';
+const TARGET_DIRS = {
+    client: OUT_DIR.client,
+    ssr: OUT_DIR.ssr,
+};
+export async function buildApp(opts = {}) {
+    const reporter = opts.reporter ?? silentReporter;
+    const options = await resolveOptions(opts, { mode: 'production' });
+    const root = options.root.value;
+    const target = opts.target ?? 'all';
+    const clean = opts.clean ?? true;
+    if (opts.outDir && opts.outDir !== OUT_DIR.base) {
+        reporter.event({
+            type: 'warn',
+            message: `--out-dir "${opts.outDir}" se registró, pero el pipeline de build (F-015/F-016/F-018) ` +
+                `siempre escribe en "${OUT_DIR.base}". Es una limitación conocida, no un bug silencioso.`,
+        });
+    }
+    // Igual que el resto de los comandos: abortar antes de tocar el disco si hay
+    // un conflicto de rutas, en vez de dejar un build parcial publicable.
+    try {
+        await scanRoutes({ strict: true, pagesDir: path.join(root, 'app/pages') });
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        const files = [...message.matchAll(/"([^"]+)"/g)].map((m) => m[1]).slice(0, 2);
+        throw RessError.routeConflict(message, files);
+    }
+    if (clean) {
+        await rm(path.join(root, OUT_DIR.base), { recursive: true, force: true });
+    }
+    const { createBuilder } = await import('vite');
+    const builder = await createBuilder({
+        root,
+        mode: 'production',
+        plugins: [react(), ressPlugin({ extensions: options.config.extensions })],
+        build: { emptyOutDir: false },
+    });
+    const targets = [];
+    const t0 = Date.now();
+    const buildOne = async (name) => {
+        const env = builder.environments[name];
+        if (!env) {
+            throw new Error(`[ress] El entorno "${name}" no está declarado en la configuración de Vite.`);
+        }
+        reporter.event({ type: 'build:start', target: name });
+        const tStart = Date.now();
+        await builder.build(env);
+        const durationMs = Date.now() - tStart;
+        const dir = path.join(root, TARGET_DIRS[name]);
+        const { files, bytes } = await dirStats(dir);
+        for (const file of files)
+            reporter.event({ type: 'build:artifact', file, bytes: 0 });
+        reporter.event({ type: 'build:done', target: name, durationMs, bytes });
+        targets.push({ target: name, durationMs, bytes, files });
+    };
+    if (target === 'all' || target === 'client')
+        await buildOne('client');
+    if (target === 'all' || target === 'ssr')
+        await buildOne('ssr');
+    const pages = getPages();
+    const catalog = await buildVariantCatalog({ pages });
+    return {
+        targets,
+        durationMs: Date.now() - t0,
+        outDir: OUT_DIR.base,
+        routes: pages.length,
+        variants: catalog.buildEntries.length,
+    };
+}
+async function dirStats(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { recursive: true });
+    }
+    catch {
+        return { files: [], bytes: 0 };
+    }
+    const files = [];
+    let bytes = 0;
+    for (const entry of entries) {
+        const full = path.join(dir, entry);
+        const info = await stat(full).catch(() => null);
+        if (!info || !info.isFile())
+            continue;
+        files.push(entry.split(path.sep).join('/'));
+        bytes += info.size;
+    }
+    return { files, bytes };
+}

package/dist/api/dev.d.ts

@@ -0,0 +1,3 @@
+import type { RessAppOptions, RessServer } from './types.js';
+/** `ress dev`: construye la app en modo desarrollo y la pone a escuchar. */
+export declare function startDevServer(opts?: RessAppOptions): Promise<RessServer>;

package/dist/api/dev.js

@@ -0,0 +1,6 @@
+import { createRessApp } from './app.js';
+/** `ress dev`: construye la app en modo desarrollo y la pone a escuchar. */
+export async function startDevServer(opts = {}) {
+    const app = await createRessApp({ ...opts, mode: 'development' });
+    return app.listen();
+}

package/dist/api/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Errores identificados del framework.
+ *
+ * "Identificado" es la palabra clave: un `RessError` siempre tiene causa,
+ * ubicación (cuando aplica) y una acción sugerida. Lo que no pasa por acá —una
+ * excepción del código del usuario, un fallo de compilación— se presenta con su
+ * traza tal cual, porque ocultarla sería peor.
+ */
+export type RessErrorCode = 'RESS_CONFIG_INVALID' | 'RESS_CONFIG_NOT_FOUND' | 'RESS_ROUTE_CONFLICT' | 'RESS_ROUTE_PATTERN_INVALID' | 'RESS_BUILD_MISSING' | 'RESS_BUILD_INCOMPATIBLE' | 'RESS_PORT_IN_USE' | 'RESS_SERVER_FILE_INVALID' | 'RESS_SERVER_FILE_THREW' | 'RESS_BAD_USAGE';
+export interface RessErrorInit {
+    title: string;
+    files?: string[];
+    reason?: string;
+    action?: string;
+    exitCode: 1 | 2 | 3;
+    cause?: unknown;
+}
+export declare class RessError extends Error {
+    readonly code: RessErrorCode;
+    readonly title: string;
+    readonly files?: string[];
+    readonly reason?: string;
+    readonly action?: string;
+    readonly exitCode: 1 | 2 | 3;
+    readonly cause?: unknown;
+    constructor(code: RessErrorCode, init: RessErrorInit);
+    static configInvalid(reason: string, files?: string[], cause?: unknown): RessError;
+    static configNotFound(file: string): RessError;
+    static routeConflict(pattern: string, files: string[]): RessError;
+    static routePatternInvalid(pattern: string, file: string, reason: string): RessError;
+    static buildMissing(outDir: string): RessError;
+    static buildIncompatible(found: number, expected: number): RessError;
+    static portInUse(port: number, process_?: string): RessError;
+    static serverFileInvalid(file: string): RessError;
+    static serverFileThrew(file: string, cause: unknown): RessError;
+    static badUsage(reason: string): RessError;
+}

package/dist/api/errors.js

@@ -0,0 +1,119 @@
+/**
+ * Errores identificados del framework.
+ *
+ * "Identificado" es la palabra clave: un `RessError` siempre tiene causa,
+ * ubicación (cuando aplica) y una acción sugerida. Lo que no pasa por acá —una
+ * excepción del código del usuario, un fallo de compilación— se presenta con su
+ * traza tal cual, porque ocultarla sería peor.
+ */
+export class RessError extends Error {
+    code;
+    title;
+    files;
+    reason;
+    action;
+    exitCode;
+    cause;
+    constructor(code, init) {
+        super(init.title);
+        this.name = 'RessError';
+        this.code = code;
+        this.title = init.title;
+        this.files = init.files;
+        this.reason = init.reason;
+        this.action = init.action;
+        this.exitCode = init.exitCode;
+        this.cause = init.cause;
+    }
+    static configInvalid(reason, files, cause) {
+        return new RessError('RESS_CONFIG_INVALID', {
+            title: 'Configuración inválida',
+            reason,
+            files,
+            action: 'Corregí la configuración en config/ y volvé a intentar.',
+            exitCode: 1,
+            cause,
+        });
+    }
+    static configNotFound(file) {
+        return new RessError('RESS_CONFIG_NOT_FOUND', {
+            title: 'No se encontró el archivo de configuración',
+            files: [file],
+            reason: 'Se pasó --config con una ruta que no existe.',
+            action: 'Verificá la ruta o quitá --config para autodetectarlo.',
+            exitCode: 1,
+        });
+    }
+    static routeConflict(pattern, files) {
+        return new RessError('RESS_ROUTE_CONFLICT', {
+            title: 'Conflicto de ruta',
+            files,
+            reason: `Dos archivos declaran el patrón ${pattern}.`,
+            action: 'Renombrá uno de los dos archivos para que declaren patrones diferentes.',
+            exitCode: 1,
+        });
+    }
+    static routePatternInvalid(pattern, file, reason) {
+        return new RessError('RESS_ROUTE_PATTERN_INVALID', {
+            title: 'Patrón de ruta inválido',
+            files: [file],
+            reason,
+            action: `Corregí el nombre de archivo que produce "${pattern}".`,
+            exitCode: 1,
+        });
+    }
+    static buildMissing(outDir) {
+        return new RessError('RESS_BUILD_MISSING', {
+            title: 'No hay build de producción',
+            files: [outDir],
+            reason: `No se encontró ${outDir}.`,
+            action: 'Ejecutá `ress build` antes de `ress start`.',
+            exitCode: 3,
+        });
+    }
+    static buildIncompatible(found, expected) {
+        return new RessError('RESS_BUILD_INCOMPATIBLE', {
+            title: 'El build es de una versión incompatible',
+            reason: `El manifest es de la versión ${found} y este ress.js espera la ${expected}.`,
+            action: 'Volvé a ejecutar `ress build`.',
+            exitCode: 3,
+        });
+    }
+    static portInUse(port, process_) {
+        return new RessError('RESS_PORT_IN_USE', {
+            title: 'Puerto ocupado',
+            reason: process_
+                ? `El puerto ${port} ya lo usa ${process_}.`
+                : `El puerto ${port} ya está en uso.`,
+            action: 'Elegí otro puerto con --port o pasá --no-strict-port para probar el siguiente libre.',
+            exitCode: 3,
+        });
+    }
+    static serverFileInvalid(file) {
+        return new RessError('RESS_SERVER_FILE_INVALID', {
+            title: 'El archivo de servidor no tiene la forma esperada',
+            files: [file],
+            reason: 'Se esperaba una función por defecto que reciba { app, mode, options, manifest }.',
+            action: `Revisá ${file}: debe hacer \`export default function setup(ctx) { ... }\`.`,
+            exitCode: 1,
+        });
+    }
+    static serverFileThrew(file, cause) {
+        return new RessError('RESS_SERVER_FILE_THREW', {
+            title: 'El archivo de servidor falló al cargarse',
+            files: [file],
+            reason: cause instanceof Error ? cause.message : String(cause),
+            action: 'Corregí el error en el archivo de servidor.',
+            exitCode: 1,
+            cause,
+        });
+    }
+    static badUsage(reason) {
+        return new RessError('RESS_BAD_USAGE', {
+            title: 'Uso incorrecto',
+            reason,
+            action: 'Ejecutá `ress --help` para ver los comandos y argumentos disponibles.',
+            exitCode: 2,
+        });
+    }
+}

package/dist/api/extend.d.ts

@@ -0,0 +1,29 @@
+import type { Express } from 'express';
+import type { ModuleLoader, RouteManifest } from '@ressjs/vite-router';
+import type { RessReporter } from './reporter.js';
+import type { RessMode } from './types.js';
+import type { ResolvedRessOptions } from './options.js';
+/** Autodetección: el primero que exista, en este orden. */
+export declare function findServerFile(root: string): Promise<string | null>;
+/**
+ * Resuelve qué archivo usar, si alguno.
+ *
+ * `serverFile.origin === '--server=false'` es la única forma de distinguir
+ * "no se pidió nada, autodetectá" de "se pidió explícitamente que no haya
+ * ninguno" cuando los dos resuelven `value: null` en `resolveOptions`.
+ */
+export declare function resolveServerFilePath(options: ResolvedRessOptions): Promise<string | null>;
+export interface ApplyServerFileParams {
+    app: Express;
+    options: ResolvedRessOptions;
+    mode: RessMode;
+    manifest: RouteManifest;
+    vite?: unknown;
+    reporter: RessReporter;
+    /** Sólo en desarrollo: el cargador que ya construyó el runtime del framework. */
+    moduleLoader?: ModuleLoader;
+    /** Sólo en desarrollo: para reintentar cuando el archivo lanzó al cargarse. */
+    onSourceChange?: (cb: (file: string) => void) => () => void;
+}
+/** Aplica el archivo de servidor del proyecto, si existe. No hace nada si no hay ninguno. */
+export declare function applyServerFile(params: ApplyServerFileParams): Promise<void>;

package/dist/api/extend.js

@@ -0,0 +1,117 @@
+/**
+ * Vía de escape nivel 2 — archivo de servidor del proyecto.
+ *
+ * Si existe `server.{ts,tsx,js,mjs}` en la raíz, se carga y se le pasa la app
+ * ya construida por `createRessApp`. El archivo no construye nada: sólo recibe
+ * y opcionalmente devuelve.
+ *
+ * **Límite conocido, documentado y no resuelto por esta spec**: en producción
+ * sólo se soportan archivos `.js`/`.mjs`, cargados con `import()` nativo. Un
+ * `server.ts`/`.tsx` en producción requeriría que el pipeline de build de
+ * F-015 lo compilara como una entrada más — F-015 sólo compila páginas y
+ * middlewares bajo `app/pages`, no un archivo arbitrario en la raíz. Extender
+ * ese pipeline es trabajo de F-015, no de F-033: se falla con un mensaje que
+ * dice exactamente esto en vez de fingir que funciona.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { RessError } from './errors.js';
+const CANDIDATE_EXTENSIONS = ['.ts', '.tsx', '.js', '.mjs'];
+/** Autodetección: el primero que exista, en este orden. */
+export async function findServerFile(root) {
+    for (const ext of CANDIDATE_EXTENSIONS) {
+        const candidate = path.join(root, `server${ext}`);
+        try {
+            await fs.access(candidate);
+            return candidate;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Resuelve qué archivo usar, si alguno.
+ *
+ * `serverFile.origin === '--server=false'` es la única forma de distinguir
+ * "no se pidió nada, autodetectá" de "se pidió explícitamente que no haya
+ * ninguno" cuando los dos resuelven `value: null` en `resolveOptions`.
+ */
+export async function resolveServerFilePath(options) {
+    const { serverFile, root } = options;
+    if (serverFile.value)
+        return path.resolve(root.value, serverFile.value);
+    if (serverFile.origin === '--server=false')
+        return null;
+    return findServerFile(root.value);
+}
+async function loadServerModule(file, root, mode, moduleLoader) {
+    if (mode === 'development' && moduleLoader) {
+        const id = '/' + path.relative(root, file).replace(/\\/g, '/');
+        return moduleLoader.load(id);
+    }
+    const ext = path.extname(file);
+    if (ext === '.ts' || ext === '.tsx') {
+        throw RessError.serverFileThrew(file, new Error('En producción sólo se soportan archivos .js/.mjs para el servidor del proyecto. ' +
+            'F-015 no compila todavía un archivo de servidor arbitrario fuera de app/pages: ' +
+            'escribí server.js o server.mjs, o esperá a que F-015 lo cubra.'));
+    }
+    return import(/* @vite-ignore */ pathToFileURL(file).href + `?t=${Date.now()}`);
+}
+function validateShape(mod, file) {
+    const fn = mod.default;
+    if (typeof fn !== 'function')
+        throw RessError.serverFileInvalid(file);
+    return fn;
+}
+/** Aplica el archivo de servidor del proyecto, si existe. No hace nada si no hay ninguno. */
+export async function applyServerFile(params) {
+    const { app, options, mode, manifest, vite, reporter, moduleLoader, onSourceChange } = params;
+    const file = await resolveServerFilePath(options);
+    if (!file)
+        return;
+    const ctx = { app, mode, options, manifest, vite };
+    const attempt = async () => {
+        let mod;
+        try {
+            mod = await loadServerModule(file, options.root.value, mode, moduleLoader);
+        }
+        catch (cause) {
+            if (cause instanceof RessError)
+                throw cause;
+            throw RessError.serverFileThrew(file, cause);
+        }
+        const setup = validateShape(mod, file);
+        const result = await setup(ctx);
+        if (result)
+            Object.assign(app, result);
+        reporter.event({ type: 'server:extended', file, hook: 'file' });
+        return true;
+    };
+    try {
+        await attempt();
+    }
+    catch (error) {
+        if (mode === 'production')
+            throw error;
+        // En desarrollo el proceso sigue vivo: se avisa y se reintenta cuando el
+        // archivo vuelva a cambiar. No hay nada montado todavía, así que el
+        // reintento es un primer montaje, no un remontaje.
+        const message = error instanceof RessError ? error.reason ?? error.title : String(error);
+        reporter.event({ type: 'warn', message: `server.* falló al cargarse: ${message}`, file });
+        if (!onSourceChange)
+            return;
+        const stop = onSourceChange((changed) => {
+            if (path.resolve(changed) !== path.resolve(file))
+                return;
+            attempt()
+                .then(() => stop())
+                .catch((retryError) => {
+                const retryMessage = retryError instanceof RessError ? retryError.reason ?? retryError.title : String(retryError);
+                reporter.event({ type: 'warn', message: `server.* volvió a fallar: ${retryMessage}`, file });
+            });
+        });
+    }
+}

package/dist/api/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Superficie pública de `@ressjs/cli`.
+ *
+ * Todo lo que hace un comando de la CLI está disponible acá como función. La
+ * CLI (`src/cli/**`) es un consumidor de esta superficie, no una segunda
+ * implementación.
+ */
+export { createRessApp } from './app.js';
+export { startDevServer } from './dev.js';
+export { startProdServer } from './start.js';
+export { buildApp } from './build.js';
+export { inspectProject, cliVersion } from './inspect.js';
+export { resolveOptions } from './options.js';
+export { silentReporter, collectingReporter } from './reporter.js';
+export { RessError } from './errors.js';
+export { findServerFile, resolveServerFilePath } from './extend.js';
+export type { BuildAppOptions } from './build.js';
+export type { ProjectInfo, InspectOptions } from './inspect.js';
+export type { OptionSource, ResolvedOption, ResolvedRessOptions, ResolveDefaults, } from './options.js';
+export type { RessEvent, RessReporter, VariantTag } from './reporter.js';
+export type { RessErrorCode, RessErrorInit } from './errors.js';
+export type { BuildResult, BuildTargetResult, LogLevel, RessApp, RessAppOptions, RessMode, RessServer, RessServerFile, RessServerFileContext, } from './types.js';