@ressjs/cli 0.6.0-experimental.0 → 0.6.0-rc.1

package/LICENSE

@@ -0,0 +1,69 @@
+ress.js Proprietary License
+
+Copyright (c) 2025-2026 gabrielspisso. All rights reserved.
+
+This license applies to the ress.js packages (the "Software"), published on npm
+under the @ressjs and @gzzy scopes, in every version released from 0.6.0-rc.0
+onwards. Earlier versions were released under the MIT License and remain
+available under those terms.
+
+1. GRANT
+   Subject to this license, the Licensor grants you a worldwide, non-exclusive,
+   non-transferable, non-sublicensable, royalty-free license to install and use
+   the Software, as distributed by the Licensor, to build, run and deploy your
+   own applications and services, including commercial ones, and to charge your
+   own customers for them.
+
+2. RESTRICTIONS
+   You may not:
+   a) fork, copy, or redistribute the Software, in whole or in part, except for
+      the portions that are necessarily included in the build output of your own
+      application in order to run it;
+   b) publish, distribute or make available a modified version of the Software
+      or any work derived from it. Modifications for your own internal use are
+      allowed, but they remain subject to this license;
+   c) use the Software, or any part of it, to build, offer or support a
+      framework, library, tool or service that competes with the Software;
+   d) sell, sublicense, rent or host the Software itself as a product or service
+      for third parties, as opposed to hosting your own application built with
+      it;
+   e) remove or alter copyright, license or attribution notices;
+   f) use the name "ress.js" or the Licensor's names or marks to endorse or
+      promote your products without written permission.
+
+3. SCAFFOLDING OUTPUT
+   Files that @ressjs/create-ress-app copies into your project (templates and
+   generated configuration) are yours: you may use, modify and distribute them
+   without restriction. This does not extend to the Software packages that the
+   generated project installs as dependencies.
+
+4. SUPPORT
+   The Software is provided without any obligation of support, maintenance or
+   updates. The Licensor may offer support, maintenance, training or consulting
+   under a separate paid agreement; that agreement does not change this license
+   unless it says so explicitly and is signed by the Licensor.
+
+5. OWNERSHIP
+   The Software is licensed, not sold. The Licensor retains all rights not
+   expressly granted here. Feedback and suggestions you send may be used by the
+   Licensor without obligation to you.
+
+6. TERMINATION
+   This license ends automatically if you breach it. On termination you must
+   stop using the Software and delete your copies. Sections 4 to 8 survive
+   termination.
+
+7. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+   PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+8. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR WILL NOT BE LIABLE FOR
+   ANY INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES, OR FOR LOSS OF
+   PROFITS, DATA OR BUSINESS, ARISING FROM THE USE OF OR INABILITY TO USE THE
+   SOFTWARE. THE LICENSOR'S TOTAL LIABILITY IS LIMITED TO THE AMOUNT YOU PAID
+   FOR THE SOFTWARE, WHICH MAY BE ZERO.
+
+For other uses, including exceptions to section 2, contact the Licensor to
+agree a separate license.

package/dist/api/app.js

@@ -23,6 +23,8 @@ import { resolveOptions } from './options.js';
 import { silentReporter } from './reporter.js';
 import { RessError } from './errors.js';
 import { applyServerFile } from './extend.js';
+import { serverEntryOptions } from './server-context.js';
+import { toViteLogLevel } from './limits.js';
 /** Cierra un `http.Server`, tolerando que ya esté cerrado. Idempotente. */
 function closeHttpServer(server) {
     if (!server.listening)
@@ -49,6 +51,7 @@ async function assertBuildPresent(root, outDir) {
     }
 }
 export async function createRessApp(opts = {}) {
+    opts = { ...serverEntryOptions.getStore(), ...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
@@ -66,7 +69,8 @@ export async function createRessApp(opts = {}) {
     const isProduction = options.mode.value === 'production';
     const root = options.root.value;
     if (isProduction) {
-        await assertBuildPresent(root, options.outDir.value);
+        // La que el pipeline realmente escribe y sirve: `--out-dir` todavía no cambia eso.
+        await assertBuildPresent(root, OUT_DIR.base);
     }
     const app = express();
     // Vía de escape nivel 1: antes del enrutador del framework, gana ante sus rutas.
@@ -84,6 +88,7 @@ export async function createRessApp(opts = {}) {
     // diseño, ya no existe en el proyecto (UC-1, UC-6).
     const runtime = await createRuntime(isProduction, options.base.value, assetPrefix, {
         plugins: [react(), ressPlugin()],
+        logLevel: toViteLogLevel(options.logLevel.value),
     });
     const router = createViteRouter({
         isProduction,
@@ -150,6 +155,14 @@ export async function createRessApp(opts = {}) {
         server.once('listening', onListening);
         server.listen(port, host);
     });
+    const closeApp = async () => {
+        if (closed)
+            return;
+        closed = true;
+        if (httpServer)
+            await closeHttpServer(httpServer);
+        await runtime.close();
+    };
     return {
         app,
         options,
@@ -161,7 +174,12 @@ export async function createRessApp(opts = {}) {
             const server = http.createServer(app);
             httpServer = server;
             const host = options.host.value;
-            const boundPort = await bindPort(server, host, options.port.value);
+            // Si el bind falla, Vite (watchers y websocket de HMR) ya está creado: sin
+            // cerrarlo, el proceso imprime el error y queda vivo en vez de salir.
+            const boundPort = await bindPort(server, host, options.port.value).catch(async (error) => {
+                await closeApp().catch(() => { });
+                throw error;
+            });
             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 });
@@ -176,14 +194,7 @@ export async function createRessApp(opts = {}) {
                 close: () => closeHttpServer(server),
             };
         },
-        async close() {
-            if (closed)
-                return;
-            closed = true;
-            if (httpServer)
-                await closeHttpServer(httpServer);
-            await runtime.close();
-        },
+        close: closeApp,
     };
 }
 export { OUT_DIR };

package/dist/api/build.js

@@ -18,10 +18,11 @@
 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 { getPages, buildVariantCatalog, OUT_DIR, ressPlugin, scanRoutes, RouteConflictError } from '@ressjs/vite-router';
 import { resolveOptions } from './options.js';
 import { silentReporter } from './reporter.js';
 import { RessError } from './errors.js';
+import { outDirIgnored, toViteLogLevel } from './limits.js';
 const TARGET_DIRS = {
     client: OUT_DIR.client,
     ssr: OUT_DIR.ssr,
@@ -35,8 +36,7 @@ export async function buildApp(opts = {}) {
     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.`,
+            message: outDirIgnored(opts.outDir, OUT_DIR.base),
         });
     }
     // Igual que el resto de los comandos: abortar antes de tocar el disco si hay
@@ -45,9 +45,11 @@ export async function buildApp(opts = {}) {
         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);
+        // Sólo el conflicto de rutas se traduce; cualquier otro error del escaneo
+        // se propaga tal cual, en vez de presentarse como un conflicto.
+        if (cause instanceof RouteConflictError)
+            throw RessError.routeConflict(cause.pattern, [...cause.files]);
+        throw cause;
     }
     if (clean) {
         await rm(path.join(root, OUT_DIR.base), { recursive: true, force: true });
@@ -55,7 +57,11 @@ export async function buildApp(opts = {}) {
     const { createBuilder } = await import('vite');
     const builder = await createBuilder({
         root,
-        mode: 'production',
+        // El modo efectivo (`--mode`, por defecto `production`): es el que el plugin usa
+        // para elegir la capa de configuración. Fijo en `production`, `--mode development`
+        // calculaba las opciones con una capa y construía con otra.
+        mode: options.mode.value,
+        logLevel: toViteLogLevel(options.logLevel.value),
         plugins: [react(), ressPlugin({ extensions: options.config.extensions })],
         build: { emptyOutDir: false },
     });

package/dist/api/dev.js

@@ -1,6 +1,12 @@
 import { createRessApp } from './app.js';
+import { devModeIgnored } from './limits.js';
+import { silentReporter } from './reporter.js';
 /** `ress dev`: construye la app en modo desarrollo y la pone a escuchar. */
 export async function startDevServer(opts = {}) {
+    if (opts.mode !== undefined && opts.mode !== 'development') {
+        ;
+        (opts.reporter ?? silentReporter).event({ type: 'warn', message: devModeIgnored(opts.mode) });
+    }
     const app = await createRessApp({ ...opts, mode: 'development' });
     return app.listen();
 }

package/dist/api/errors.d.ts

@@ -6,7 +6,25 @@
  * 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 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' | 'RESS_PLATFORM_TOKEN_INVALID';
+/**
+ * Lo que la CLI necesita de un `PlatformTokenError` (de `@ressjs/platform`).
+ *
+ * Es estructural a propósito: la CLI no puede importar el paquete en el
+ * arranque —cargaría React antes de fijar `NODE_ENV`—, así que lo reconoce por
+ * su `code` estable.
+ */
+export interface PlatformTokenFailure extends Error {
+    code: 'RESS_PLATFORM_TOKEN';
+    kind: 'retired' | 'unknown';
+    token: string;
+    origin?: string;
+    replacement?: string;
+    reason?: string;
+    suggestion?: string;
+    valid: readonly string[];
+}
+export declare function isPlatformTokenFailure(error: unknown): error is PlatformTokenFailure;
 export interface RessErrorInit {
     title: string;
     files?: string[];
@@ -27,6 +45,7 @@ export declare class RessError extends Error {
     static configInvalid(reason: string, files?: string[], cause?: unknown): RessError;
     static configNotFound(file: string): RessError;
     static routeConflict(pattern: string, files: string[]): RessError;
+    static platformToken(cause: PlatformTokenFailure): RessError;
     static routePatternInvalid(pattern: string, file: string, reason: string): RessError;
     static buildMissing(outDir: string): RessError;
     static buildIncompatible(found: number, expected: number): RessError;

package/dist/api/errors.js

@@ -6,6 +6,9 @@
  * 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 function isPlatformTokenFailure(error) {
+    return error instanceof Error && error.code === 'RESS_PLATFORM_TOKEN';
+}
 export class RessError extends Error {
     code;
     title;
@@ -53,6 +56,22 @@ export class RessError extends Error {
             exitCode: 1,
         });
     }
+    static platformToken(cause) {
+        const retired = cause.kind === 'retired';
+        return new RessError('RESS_PLATFORM_TOKEN_INVALID', {
+            title: retired ? 'Token de plataforma retirado' : 'Token de plataforma desconocido',
+            files: cause.origin ? [cause.origin] : undefined,
+            reason: retired
+                ? `El token "${cause.token}" ya no existe. Se retiró porque ${cause.reason}.`
+                : `El token "${cause.token}" no es de ningún eje de plataforma.` +
+                    (cause.suggestion ? ` ¿Quisiste decir "${cause.suggestion}"?` : ''),
+            action: retired
+                ? `Usá ${cause.replacement}.`
+                : `Usá uno de los tokens válidos: ${cause.valid.join(', ')}.`,
+            exitCode: 1,
+            cause,
+        });
+    }
     static routePatternInvalid(pattern, file, reason) {
         return new RessError('RESS_ROUTE_PATTERN_INVALID', {
             title: 'Patrón de ruta inválido',

package/dist/api/extend.js

@@ -17,7 +17,7 @@ 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'];
+const CANDIDATE_EXTENSIONS = ['.ts', '.js', '.mjs', '.tsx'];
 /** Autodetección: el primero que exista, en este orden. */
 export async function findServerFile(root) {
     for (const ext of CANDIDATE_EXTENSIONS) {

package/dist/api/index.d.ts

@@ -9,7 +9,8 @@ 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 { inspectProject } from './inspect.js';
+export { cliVersion } from './version.js';
 export { resolveOptions } from './options.js';
 export { silentReporter, collectingReporter } from './reporter.js';
 export { RessError } from './errors.js';

package/dist/api/index.js

@@ -9,7 +9,8 @@ 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 { inspectProject } from './inspect.js';
+export { cliVersion } from './version.js';
 export { resolveOptions } from './options.js';
 export { silentReporter, collectingReporter } from './reporter.js';
 export { RessError } from './errors.js';

package/dist/api/inspect.d.ts

@@ -63,13 +63,4 @@ export interface ProjectInfo {
         };
     };
 }
-/**
- * La versión de `@ressjs/cli`, leída de su propio `package.json`.
- *
- * Exportada porque `src/cli/main.ts` también la necesita para `--version` y no
- * puede tocar `node:fs` directamente sin romper la regla de separación —
- * "la CLI no reimplementa" incluye no leer archivos por su cuenta cuando la
- * API ya sabe cómo.
- */
-export declare function cliVersion(): Promise<string>;
 export declare function inspectProject(opts?: InspectOptions): Promise<ProjectInfo>;

package/dist/api/inspect.js

@@ -8,10 +8,10 @@
  */
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath, URL } from 'node:url';
 import { readFile } from 'node:fs/promises';
-import { buildVariantCatalog, getPages, loadRouteManifest, OUT_DIR, scanRoutes, } from '@ressjs/vite-router';
+import { buildVariantCatalog, DEFAULT_EXTENSION_POLICY, getPages, loadRouteManifest, OUT_DIR, scanRoutes, setExtensionPolicy, writeProjectTypes, } from '@ressjs/vite-router';
 import { resolveOptions } from './options.js';
+import { cliVersion } from './version.js';
 import { RessError } from './errors.js';
 async function dirBytes(dir) {
     const { readdir, stat } = await import('node:fs/promises');
@@ -39,33 +39,15 @@ async function packageVersion(root, name) {
         return undefined;
     }
 }
-/**
- * La versión de `@ressjs/cli`, leída de su propio `package.json`.
- *
- * Exportada porque `src/cli/main.ts` también la necesita para `--version` y no
- * puede tocar `node:fs` directamente sin romper la regla de separación —
- * "la CLI no reimplementa" incluye no leer archivos por su cuenta cuando la
- * API ya sabe cómo.
- */
-export async function cliVersion() {
-    try {
-        const raw = await readFile(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf-8');
-        return JSON.parse(raw).version ?? '0.0.0';
-    }
-    catch {
-        return '0.0.0';
-    }
-}
 export async function inspectProject(opts = {}) {
     const root = opts.root ? path.resolve(opts.root) : process.cwd();
-    const mode = opts.mode ?? 'development';
     let sources = {};
     let resolvedConfig = null;
     let configFile = null;
     let valid = true;
     let errors;
     try {
-        const options = await resolveOptions({ ...opts, root, mode }, { mode });
+        const options = await resolveOptions({ ...opts, root }, { mode: 'development' });
         for (const [key, entry] of Object.entries(options)) {
             if (key === 'config')
                 continue;
@@ -74,6 +56,13 @@ export async function inspectProject(opts = {}) {
         }
         resolvedConfig = options.config;
         configFile = options.configFile.value;
+        // Qué archivos son páginas lo decide `extensions`. El plugin de Vite fija esa
+        // política al arrancar; `ress info` no levanta Vite, así que la fija acá, o
+        // listaría páginas que el servidor no sirve.
+        setExtensionPolicy({ ...DEFAULT_EXTENSION_POLICY, ...options.config.extensions });
+        // Los tipos de `config.X` salen de la configuración resuelta. Generarlos acá
+        // permite tipar un clon limpio sin levantar el servidor (`ress info && tsc`).
+        await writeProjectTypes(root, options.config.platform);
     }
     catch (cause) {
         valid = false;

package/dist/api/limits.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Flags que la CLI acepta pero todavía no tienen efecto.
+ *
+ * Aceptarlos sin decir nada es peor que no tenerlos: parece que funcionan. Cada
+ * comando que los recibe avisa con estos mensajes, y la documentación de la CLI
+ * los lista como «aceptados, sin efecto».
+ */
+/** `--out-dir`: el pipeline escribe y lee siempre `dist/`. */
+export declare function outDirIgnored(flag: string, actual: string): string;
+/** `ress dev --mode`: el servidor de desarrollo siempre usa la capa de configuración `development`. */
+export declare function devModeIgnored(flag: string): string;
+/** Los niveles de log de Vite son cuatro; `debug` de ress se queda en `info`. */
+export declare function toViteLogLevel(level: 'silent' | 'error' | 'warn' | 'info' | 'debug'): 'silent' | 'error' | 'warn' | 'info';

package/dist/api/limits.js

@@ -0,0 +1,20 @@
+/**
+ * Flags que la CLI acepta pero todavía no tienen efecto.
+ *
+ * Aceptarlos sin decir nada es peor que no tenerlos: parece que funcionan. Cada
+ * comando que los recibe avisa con estos mensajes, y la documentación de la CLI
+ * los lista como «aceptados, sin efecto».
+ */
+/** `--out-dir`: el pipeline escribe y lee siempre `dist/`. */
+export function outDirIgnored(flag, actual) {
+    return `--out-dir "${flag}" se registró, pero por ahora ress siempre escribe y sirve el build desde "${actual}".`;
+}
+/** `ress dev --mode`: el servidor de desarrollo siempre usa la capa de configuración `development`. */
+export function devModeIgnored(flag) {
+    return (`--mode ${flag} se registró, pero \`ress dev\` siempre usa la capa de configuración "development". ` +
+        'Para probar la de producción, corré `ress build` y `ress start`.');
+}
+/** Los niveles de log de Vite son cuatro; `debug` de ress se queda en `info`. */
+export function toViteLogLevel(level) {
+    return level === 'debug' ? 'info' : level;
+}

package/dist/api/options.d.ts

@@ -1,3 +1,21 @@
+/**
+ * Resolución de opciones con procedencia.
+ *
+ * Precedencia fija: **argumento > variable de entorno > `config/` (F-008) >
+ * default del framework.** No se devuelven valores pelados: cada campo lleva su
+ * `source` y su `origin`, porque UC-10 pide que sea observable cuál ganó y
+ * `ress info` lo muestra.
+ *
+ * Variables de entorno leídas, y solo estas: `PORT`, `HOST`, `NODE_ENV`,
+ * `RESS_LOG_LEVEL`, `RESS_CONFIG`. `NODE_ENV` sólo se lee para derivar `mode`;
+ * nunca se escribe acá.
+ *
+ * Límite conocido: `loadConfig()` de F-008 resuelve `config/` a partir de
+ * `root` + `mode` y no acepta todavía una ruta de archivo explícita. Por eso
+ * `--config` / `RESS_CONFIG` quedan registrados con su procedencia pero no
+ * cambian qué archivo lee `loadConfig` — es una limitación de F-008, no de esta
+ * spec, y se deja documentada en vez de reimplementarse acá.
+ */
 import { type ResolvedConfig } from '@ressjs/vite-router';
 import type { LogLevel, RessAppOptions, RessMode } from './types.js';
 export type OptionSource = 'flag' | 'env' | 'config' | 'default';

package/dist/api/options.js

@@ -16,8 +16,7 @@
  * cambian qué archivo lee `loadConfig` — es una limitación de F-008, no de esta
  * spec, y se deja documentada en vez de reimplementarse acá.
  */
-import path from 'node:path';
-import { loadConfig } from '@ressjs/vite-router';
+import { canonicalPath, loadConfig, normalizeBasePath, validateConfig } from '@ressjs/vite-router';
 import { RessError } from './errors.js';
 const VALID_MODES = ['development', 'production'];
 const VALID_LOG_LEVELS = ['silent', 'error', 'warn', 'info', 'debug'];
@@ -27,7 +26,7 @@ function opt(value, source, origin) {
 export async function resolveOptions(opts, defaults = {}) {
     const env = process.env;
     const root = opts.root
-        ? opt(path.resolve(opts.root), 'flag', '--root')
+        ? opt(canonicalPath(opts.root), 'flag', '--root')
         : opt(process.cwd(), 'default', 'process.cwd()');
     const configFile = opts.configFile
         ? opt(opts.configFile, 'flag', '--config')
@@ -49,6 +48,11 @@ export async function resolveOptions(opts, defaults = {}) {
     const host = resolveHost(opts, defaults, env);
     const strictPort = resolveStrictPort(opts);
     const base = resolveBase(opts, config);
+    // El prefijo efectivo es uno solo. Quien lo quita de cada petición, el que
+    // prefija los artefactos y el de Vite leen `config.basePath`: si la flag lo
+    // cambiara sólo en `base`, la app respondería en `/` y no bajo el prefijo.
+    if (base.source === 'flag')
+        config = { ...config, basePath: base.value === '/' ? '' : base.value };
     const logLevel = resolveLogLevel(opts, env);
     const serverFile = resolveServerFile(opts);
     const outDir = opts.outDir
@@ -115,7 +119,15 @@ function resolveStrictPort(opts) {
 }
 function resolveBase(opts, config) {
     if (opts.base !== undefined) {
-        return opt(opts.base, 'flag', '--base');
+        // Misma validación y misma forma canónica que `basePath` en la config:
+        // `--base /app/` y `basePath: '/app/'` son la misma cosa.
+        try {
+            validateConfig({ basePath: opts.base });
+        }
+        catch (cause) {
+            throw RessError.badUsage(`--base ${JSON.stringify(opts.base)} no es un prefijo válido: ${cause instanceof Error ? cause.message : cause}`);
+        }
+        return opt(normalizeBasePath(opts.base) || '/', 'flag', '--base');
     }
     if (config.basePath) {
         return opt(config.basePath, 'config', 'config:basePath');

package/dist/api/server-context.d.ts

@@ -0,0 +1,3 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { RessAppOptions } from './types.js';
+export declare const serverEntryOptions: AsyncLocalStorage<RessAppOptions>;

package/dist/api/server-context.js

@@ -0,0 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+// CLI options follow calls made by the project's entry point, including awaits.
+// Nothing is stored globally or inherited by an unrelated application.
+export const serverEntryOptions = new AsyncLocalStorage();

package/dist/api/start.js

@@ -1,6 +1,12 @@
-import { createRessApp } from './app.js';
+import { OUT_DIR, createRessApp } from './app.js';
+import { outDirIgnored } from './limits.js';
+import { silentReporter } from './reporter.js';
 /** `ress start`: construye la app en modo producción y la pone a escuchar. */
 export async function startProdServer(opts = {}) {
+    if (opts.outDir && opts.outDir !== OUT_DIR.base) {
+        ;
+        (opts.reporter ?? silentReporter).event({ type: 'warn', message: outDirIgnored(opts.outDir, OUT_DIR.base) });
+    }
     const app = await createRessApp({ ...opts, mode: 'production' });
     return app.listen();
 }

package/dist/api/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * La versión de `@ressjs/cli`, leída de su propio `package.json`.
+ *
+ * Vive en un módulo propio, sin dependencias del runtime, porque
+ * `src/cli/main.ts` la necesita antes de fijar `NODE_ENV`. Importarla desde
+ * `inspect.ts` arrastraba `@ressjs/vite-router` y, con él, React: React elige
+ * su build de desarrollo o de producción al cargarse, así que quedaba en
+ * desarrollo aunque después se fijara `NODE_ENV=production`.
+ */
+export declare function cliVersion(): Promise<string>;

package/dist/api/version.js

@@ -0,0 +1,20 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath, URL } from 'node:url';
+/**
+ * La versión de `@ressjs/cli`, leída de su propio `package.json`.
+ *
+ * Vive en un módulo propio, sin dependencias del runtime, porque
+ * `src/cli/main.ts` la necesita antes de fijar `NODE_ENV`. Importarla desde
+ * `inspect.ts` arrastraba `@ressjs/vite-router` y, con él, React: React elige
+ * su build de desarrollo o de producción al cargarse, así que quedaba en
+ * desarrollo aunque después se fijara `NODE_ENV=production`.
+ */
+export async function cliVersion() {
+    try {
+        const raw = await readFile(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf-8');
+        return JSON.parse(raw).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/dist/cli/argv.js

@@ -63,7 +63,7 @@ export function parseArgv(argv, version) {
         .option('--root <dir>', 'Raíz del proyecto')
         .addOption(new Option('-c, --config <file>', 'Archivo de configuración'))
         .addOption(new Option('-m, --mode <mode>', 'Modo de configuración').choices(['development', 'production']))
-        .option('--server <file>', 'Archivo de servidor del proyecto ("false" para desactivar)')
+        .option('--server <file>', 'Entrada del servidor del proyecto ("false" para desactivar)')
         .addOption(new Option('-l, --log-level <lvl>', 'Detalle de la salida').choices(LOG_LEVELS))
         .option('-o, --open', 'Abre el navegador al arrancar')
         .option('--clear-screen', 'Limpia la pantalla en cada recarga')
@@ -91,7 +91,7 @@ export function parseArgv(argv, version) {
         .option('--root <dir>', 'Raíz del proyecto')
         .addOption(new Option('-c, --config <file>', 'Archivo de configuración'))
         .option('--out-dir <dir>', 'Build a servir')
-        .option('--server <file>', 'Archivo de servidor del proyecto ("false" para desactivar)')
+        .option('--server <file>', 'Entrada del servidor del proyecto ("false" para desactivar)')
         .addOption(new Option('-l, --log-level <lvl>', 'Detalle de la salida').choices(LOG_LEVELS))
         .action((opts) => {
         result = { command: 'start', flags: { ...opts, server: normalizeServer(opts.server) } };

package/dist/cli/commands/build.js

@@ -1,7 +1,12 @@
+import path from 'node:path';
 import { buildApp } from '../../api/index.js';
 import { createTerminalReporter } from '../reporters/terminal.js';
 export async function buildCommand(flags) {
+    // Page/style discovery uses cwd as well as Vite's root. Normalize before
+    // changing cwd so a relative --root is not resolved a second time.
+    const root = path.resolve(flags.root ?? process.cwd());
+    process.chdir(root);
     const reporter = createTerminalReporter({ logLevel: flags.logLevel });
-    await buildApp({ ...flags, reporter });
+    await buildApp({ ...flags, root, reporter });
     return 0;
 }

package/dist/cli/commands/dev.js

@@ -1,10 +1,14 @@
-import { startDevServer } from '../../api/index.js';
+import { runServerEntry } from '../server-entry.js';
 import { createTerminalReporter } from '../reporters/terminal.js';
 import { registerShutdown } from '../shutdown.js';
 export async function devCommand(flags) {
+    const entry = await runServerEntry(flags, flags.mode ?? 'development');
+    if (entry.handled)
+        return 0;
+    const { startDevServer } = await import('../../api/index.js');
     const { server: serverFile, ...rest } = flags;
     const reporter = createTerminalReporter({ logLevel: flags.logLevel });
-    const server = await startDevServer({ ...rest, serverFile, reporter });
+    const server = await startDevServer({ ...rest, root: entry.root, serverFile: entry.extension ?? serverFile, reporter });
     registerShutdown(() => server.close());
     return new Promise(() => { }); // dev no retorna hasta la señal
 }

package/dist/cli/commands/start.js

@@ -1,10 +1,14 @@
-import { startProdServer } from '../../api/index.js';
+import { runServerEntry } from '../server-entry.js';
 import { createTerminalReporter } from '../reporters/terminal.js';
 import { registerShutdown } from '../shutdown.js';
 export async function startCommand(flags) {
+    const entry = await runServerEntry(flags, 'production');
+    if (entry.handled)
+        return 0;
+    const { startProdServer } = await import('../../api/index.js');
     const { server: serverFile, ...rest } = flags;
     const reporter = createTerminalReporter({ logLevel: flags.logLevel });
-    const server = await startProdServer({ ...rest, serverFile, reporter });
+    const server = await startProdServer({ ...rest, root: entry.root, serverFile: entry.extension ?? serverFile, reporter });
     registerShutdown(() => server.close());
     return new Promise(() => { }); // start no retorna hasta la señal
 }

package/dist/cli/env.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `NODE_ENV` por comando.
+ *
+ * `ress start` y `ress build` no fijaban `NODE_ENV`, así que en producción
+ * React (y cualquier caché que lea `process.env.NODE_ENV`) seguía corriendo
+ * en modo desarrollo salvo que quien desplegara lo supiera y lo pusiera a
+ * mano. Se fija acá, antes de importar el runtime (`../../api/index.js`,
+ * detrás de un `import()` dinámico en `main.ts`), y no lo pisa si ya venía
+ * declarado desde afuera.
+ */
+export type EnvCommand = 'dev' | 'build' | 'start' | 'info' | 'help' | 'version';
+export declare function applyNodeEnvDefault(command: EnvCommand): void;

package/dist/cli/env.js

@@ -0,0 +1,9 @@
+export function applyNodeEnvDefault(command) {
+    if (command === 'dev') {
+        process.env.NODE_ENV ??= 'development';
+        return;
+    }
+    if (command === 'build' || command === 'start') {
+        process.env.NODE_ENV ??= 'production';
+    }
+}

package/dist/cli/main.js

@@ -6,24 +6,27 @@
  * en `commands/*`.
  */
 import { parseArgv } from './argv.js';
-import { devCommand } from './commands/dev.js';
-import { buildCommand } from './commands/build.js';
-import { startCommand } from './commands/start.js';
-import { infoCommand } from './commands/info.js';
 import { formatError } from './reporters/terminal.js';
 import { detectFormatEnv } from './reporters/format.js';
-import { RessError } from '../api/errors.js';
-import { cliVersion } from '../api/inspect.js';
-function dispatch(parsed) {
+import { applyNodeEnvDefault } from './env.js';
+import { RessError, isPlatformTokenFailure } from '../api/errors.js';
+// Sólo módulos sin el runtime: `cliVersion` vive aparte de `inspect.ts`, que
+// importa `@ressjs/vite-router` y con él React, y React tiene que cargarse
+// después de `applyNodeEnvDefault`.
+import { cliVersion } from '../api/version.js';
+// Import dinámico y no estático: así `NODE_ENV` queda fijado (`applyNodeEnvDefault`,
+// llamado antes de esto) antes de que se cargue `../../api/index.js`, que es
+// donde vive el runtime que lee `process.env.NODE_ENV`.
+async function dispatch(parsed) {
     switch (parsed.command) {
         case 'dev':
-            return devCommand(parsed.flags);
+            return (await import('./commands/dev.js')).devCommand(parsed.flags);
         case 'build':
-            return buildCommand(parsed.flags);
+            return (await import('./commands/build.js')).buildCommand(parsed.flags);
         case 'start':
-            return startCommand(parsed.flags);
+            return (await import('./commands/start.js')).startCommand(parsed.flags);
         case 'info':
-            return infoCommand(parsed.flags);
+            return (await import('./commands/info.js')).infoCommand(parsed.flags);
     }
 }
 export async function main(argv = process.argv.slice(2)) {
@@ -41,13 +44,17 @@ export async function main(argv = process.argv.slice(2)) {
             process.exitCode = 0;
             return;
         }
+        applyNodeEnvDefault(parsed.command);
         process.exitCode = await dispatch(parsed);
     }
     catch (error) {
         const env = detectFormatEnv(Boolean(process.stderr.isTTY));
-        if (error instanceof RessError) {
-            process.stderr.write(formatError(error, env) + '\n');
-            process.exitCode = error.exitCode;
+        // Un token de plataforma inválido lo lanza `@ressjs/platform` desde un hook
+        // de Vite: se presenta con el formato de los demás errores del proyecto.
+        const known = isPlatformTokenFailure(error) ? RessError.platformToken(error) : error;
+        if (known instanceof RessError) {
+            process.stderr.write(formatError(known, env) + '\n');
+            process.exitCode = known.exitCode;
             return;
         }
         // No identificado por el framework: se muestra la traza tal cual. Ocultarla

package/dist/cli/server-entry.d.ts

@@ -0,0 +1,7 @@
+import type { DevFlags, StartFlags } from './argv.js';
+/** Run the project's server before constructing the framework's default app. */
+export declare function runServerEntry(flags: DevFlags | StartFlags, mode: 'development' | 'production'): Promise<{
+    handled: boolean;
+    root: string;
+    extension?: string;
+}>;

package/dist/cli/server-entry.js

@@ -0,0 +1,43 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { findServerFile } from '../api/extend.js';
+import { serverEntryOptions } from '../api/server-context.js';
+import { RessError } from '../api/errors.js';
+/** Run the project's server before constructing the framework's default app. */
+export async function runServerEntry(flags, mode) {
+    const root = path.resolve(flags.root ?? process.cwd());
+    // Vite and route discovery also use cwd. Apply --root for the default path,
+    // including --server false, rather than only for a project-owned entry.
+    process.chdir(root);
+    if (flags.server === false)
+        return { handled: false, root };
+    const file = flags.server ? path.resolve(root, flags.server) : await findServerFile(root);
+    if (!file)
+        return { handled: false, root };
+    // JSX server extensions still use the framework's existing module loader.
+    if (path.extname(file) === '.tsx')
+        return { handled: false, root, extension: file };
+    if (path.extname(file) === '.ts' && !process.features.typescript) {
+        throw RessError.badUsage('Para ejecutar server.ts se necesita Node 22.18+ con soporte TypeScript habilitado.');
+    }
+    const { server: _server, config, ...rest } = flags;
+    const options = {
+        ...rest, root, configFile: config, mode, serverFile: false,
+    };
+    process.env.NODE_ENV = mode;
+    let mod;
+    try {
+        mod = await serverEntryOptions.run(options, () => import(pathToFileURL(file).href));
+    }
+    catch (cause) {
+        if (cause instanceof RessError)
+            throw cause;
+        throw RessError.serverFileThrew(file, cause);
+    }
+    // Preserve the existing default-export setup callback contract.
+    const exported = mod.default;
+    if (typeof mod.default === 'function' && typeof exported?.listen !== 'function') {
+        return { handled: false, root, extension: file };
+    }
+    return { handled: true, root };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ressjs/cli",
-  "version": "0.6.0-experimental.0",
+  "version": "0.6.0-rc.1",
   "description": "La CLI de ress.js: dev, build, start e info sobre la misma construcción de la aplicación que expone como API.",
   "type": "module",
   "bin": {
@@ -37,9 +37,9 @@
     "vite"
   ],
   "author": "ress.js team",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "@ressjs/vite-router": "0.6.0-experimental.0",
+    "@ressjs/vite-router": "0.6.0-rc.1",
     "@vitejs/plugin-react": "^6.1.0",
     "commander": "^12.1.0",
     "express": "^5.1.0"