@ressjs/cli 0.6.0-experimental.0

package/dist/api/index.js

@@ -0,0 +1,16 @@
+/**
+ * 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';

package/dist/api/inspect.d.ts

@@ -0,0 +1,75 @@
+import { type OptionSource } from './options.js';
+import type { RessAppOptions } from './types.js';
+/**
+ * `inspectProject` siempre devuelve el diagnóstico completo: filtrar a
+ * `--routes` / `--variants` / `--config-only` es presentación, y por eso vive
+ * en el comando de la CLI (`src/cli/commands/info.ts`), no acá.
+ */
+export type InspectOptions = RessAppOptions;
+export interface ConfigValidationError {
+    message: string;
+}
+export interface ProjectInfo {
+    versions: {
+        node: string;
+        cli: string;
+        packages: Record<string, string>;
+        vite: string;
+        react: string;
+    };
+    platform: {
+        os: string;
+        arch: string;
+        cwd: string;
+    };
+    config: {
+        file: string | null;
+        valid: boolean;
+        errors?: ConfigValidationError[];
+        resolved: Record<string, unknown> | null;
+        sources: Record<string, {
+            value: unknown;
+            source: OptionSource;
+            origin: string;
+        }>;
+    };
+    routes: {
+        count: number;
+        entries: Array<{
+            pattern: string;
+            pageId: string;
+            kind: string;
+            file: string;
+        }>;
+        conflicts: Array<{
+            pattern: string;
+            files: string[];
+        }>;
+    };
+    variants: {
+        tags: string[];
+        byPage: Record<string, string[]>;
+        declared: string[];
+    };
+    build: {
+        present: boolean;
+        outDir: string;
+        manifestVersion: number | null;
+        compatible: boolean;
+        builtAt: string | null;
+        sizes: {
+            client: number;
+            server: number;
+        };
+    };
+}
+/**
+ * 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

@@ -0,0 +1,170 @@
+/**
+ * `inspectProject` — el diagnóstico de `ress info`.
+ *
+ * Nunca lanza por un proyecto roto: un comando de diagnóstico que aborta ante
+ * el problema que se está diagnosticando no sirve (UC-4, Flujo D). Reutiliza
+ * `resolveOptions` y `scanRoutes`/`getPages`: no tiene lectura propia del
+ * proyecto, así que su salida coincide con lo que `ress dev` va a hacer.
+ */
+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 { resolveOptions } from './options.js';
+import { RessError } from './errors.js';
+async function dirBytes(dir) {
+    const { readdir, stat } = await import('node:fs/promises');
+    let entries;
+    try {
+        entries = (await readdir(dir, { recursive: true }));
+    }
+    catch {
+        return 0;
+    }
+    let bytes = 0;
+    for (const entry of entries) {
+        const info = await stat(path.join(dir, entry)).catch(() => null);
+        if (info?.isFile())
+            bytes += info.size;
+    }
+    return bytes;
+}
+async function packageVersion(root, name) {
+    try {
+        const raw = await readFile(path.join(root, 'node_modules', ...name.split('/'), 'package.json'), 'utf-8');
+        return JSON.parse(raw).version;
+    }
+    catch {
+        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 });
+        for (const [key, entry] of Object.entries(options)) {
+            if (key === 'config')
+                continue;
+            const { value, source, origin } = entry;
+            sources[key] = { value, source, origin };
+        }
+        resolvedConfig = options.config;
+        configFile = options.configFile.value;
+    }
+    catch (cause) {
+        valid = false;
+        const message = cause instanceof RessError ? (cause.reason ?? cause.title) : String(cause);
+        errors = [{ message }];
+    }
+    // Rutas: nunca aborta. `scanRoutes` sin `strict` avisa por consola y sigue
+    // con la primera; para el diagnóstico interesa además la lista de conflictos,
+    // así que se detectan comparando duplicados de patrón a mano.
+    const pagesDir = path.join(root, 'app/pages');
+    let entries = [];
+    const conflicts = [];
+    try {
+        const data = await scanRoutes({ pagesDir });
+        entries = data.entries;
+        conflicts.push(...(data.conflicts ?? []));
+    }
+    catch {
+        // Un proyecto sin `app/pages` no tiene rutas: no es un error del diagnóstico.
+    }
+    // Variantes: mismo catálogo que `createRessApp` construiría.
+    let tags = [];
+    const byPage = {};
+    try {
+        const pages = getPages();
+        const catalog = await buildVariantCatalog({ pages });
+        const tagSet = new Set();
+        for (const [pageId, variants] of catalog.variantsByPage) {
+            const suffixes = variants.map((v) => v.suffix).filter(Boolean);
+            byPage[pageId] = suffixes;
+            for (const suffix of suffixes)
+                tagSet.add(suffix);
+        }
+        tags = [...tagSet].sort();
+    }
+    catch {
+        // Sin páginas, catálogo vacío.
+    }
+    const platformConfig = resolvedConfig?.platform;
+    const declared = platformConfig?.targets ??
+        (platformConfig?.values ?? []).map((value) => value.token);
+    // Build.
+    const outDirAbs = path.join(root, OUT_DIR.base);
+    let present = false;
+    let manifestVersion = null;
+    let compatible = false;
+    let builtAt = null;
+    const sizes = { client: 0, server: 0 };
+    try {
+        const raw = await readFile(path.join(outDirAbs, 'route-manifest.json'), 'utf-8');
+        present = true;
+        const data = JSON.parse(raw);
+        manifestVersion = data.version ?? null;
+        try {
+            loadRouteManifest(raw);
+            compatible = true;
+        }
+        catch {
+            compatible = false;
+        }
+        const stat = await import('node:fs/promises').then((fs) => fs.stat(path.join(outDirAbs, 'route-manifest.json')));
+        builtAt = stat.mtime.toISOString();
+        sizes.client = await dirBytes(path.join(root, OUT_DIR.client));
+        sizes.server = await dirBytes(path.join(root, OUT_DIR.ssr));
+    }
+    catch {
+        present = false;
+    }
+    return {
+        versions: {
+            node: process.version,
+            cli: await cliVersion(),
+            packages: Object.fromEntries((await Promise.all(['@ressjs/vite-router', '@ressjs/config', '@ressjs/cli', '@ressjs/platform'].map(async (name) => [name, await packageVersion(root, name)]))).filter((entry) => Boolean(entry[1]))),
+            vite: (await packageVersion(root, 'vite')) ?? 'desconocida',
+            react: (await packageVersion(root, 'react')) ?? 'desconocida',
+        },
+        platform: { os: `${os.platform()} ${os.arch()}`, arch: os.arch(), cwd: root },
+        config: { file: configFile, valid, errors, resolved: resolvedConfig, sources },
+        routes: {
+            count: entries.length,
+            entries: entries.map((e) => ({ pattern: e.pattern, pageId: e.pageId, kind: e.kind, file: e.sourceFile })),
+            conflicts,
+        },
+        variants: { tags, byPage, declared },
+        build: {
+            present,
+            outDir: OUT_DIR.base,
+            manifestVersion,
+            compatible,
+            builtAt,
+            sizes,
+        },
+    };
+}

package/dist/api/options.d.ts

@@ -0,0 +1,29 @@
+import { type ResolvedConfig } from '@ressjs/vite-router';
+import type { LogLevel, RessAppOptions, RessMode } from './types.js';
+export type OptionSource = 'flag' | 'env' | 'config' | 'default';
+export interface ResolvedOption<T> {
+    value: T;
+    source: OptionSource;
+    /** Nombre concreto del origen: '--port', 'PORT', 'config:basePath'. */
+    origin: string;
+}
+export interface ResolvedRessOptions {
+    root: ResolvedOption<string>;
+    configFile: ResolvedOption<string | null>;
+    mode: ResolvedOption<RessMode>;
+    port: ResolvedOption<number>;
+    host: ResolvedOption<string>;
+    strictPort: ResolvedOption<boolean>;
+    base: ResolvedOption<string>;
+    logLevel: ResolvedOption<LogLevel>;
+    serverFile: ResolvedOption<string | null>;
+    outDir: ResolvedOption<string>;
+    /** `ResolvedConfig` de F-008, ya fusionado por modo. */
+    config: ResolvedConfig;
+}
+export interface ResolveDefaults {
+    mode?: RessMode;
+    host?: string;
+    port?: number;
+}
+export declare function resolveOptions(opts: RessAppOptions, defaults?: ResolveDefaults): Promise<ResolvedRessOptions>;

package/dist/api/options.js

@@ -0,0 +1,152 @@
+/**
+ * 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 path from 'node:path';
+import { loadConfig } from '@ressjs/vite-router';
+import { RessError } from './errors.js';
+const VALID_MODES = ['development', 'production'];
+const VALID_LOG_LEVELS = ['silent', 'error', 'warn', 'info', 'debug'];
+function opt(value, source, origin) {
+    return { 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(process.cwd(), 'default', 'process.cwd()');
+    const configFile = opts.configFile
+        ? opt(opts.configFile, 'flag', '--config')
+        : env.RESS_CONFIG
+            ? opt(env.RESS_CONFIG, 'env', 'RESS_CONFIG')
+            : opt(null, 'default', 'autodetectado');
+    const mode = resolveMode(opts, defaults, env);
+    // Config del proyecto: F-008. Se carga con la raíz y el modo ya resueltos —es
+    // la misma resolución que usará `createRessApp`, así que lo que reporta
+    // `ress info` coincide con lo que el servidor va a hacer.
+    let config;
+    try {
+        config = await loadConfig(root.value, mode.value);
+    }
+    catch (cause) {
+        throw RessError.configInvalid(cause instanceof Error ? cause.message : String(cause), undefined, cause);
+    }
+    const port = resolvePort(opts, defaults, env);
+    const host = resolveHost(opts, defaults, env);
+    const strictPort = resolveStrictPort(opts);
+    const base = resolveBase(opts, config);
+    const logLevel = resolveLogLevel(opts, env);
+    const serverFile = resolveServerFile(opts);
+    const outDir = opts.outDir
+        ? opt(opts.outDir, 'flag', '--out-dir')
+        : opt('dist', 'default', 'dist');
+    return {
+        root,
+        configFile,
+        mode,
+        port,
+        host,
+        strictPort,
+        base,
+        logLevel,
+        serverFile,
+        outDir,
+        config,
+    };
+}
+function resolveMode(opts, defaults, env) {
+    if (opts.mode !== undefined) {
+        if (!VALID_MODES.includes(opts.mode)) {
+            throw RessError.badUsage(`--mode sólo acepta ${VALID_MODES.join(' o ')}; se recibió "${opts.mode}".`);
+        }
+        return opt(opts.mode, 'flag', '--mode');
+    }
+    if (env.NODE_ENV === 'production' || env.NODE_ENV === 'development') {
+        return opt(env.NODE_ENV, 'env', 'NODE_ENV');
+    }
+    return opt(defaults.mode ?? 'development', 'default', 'default del framework');
+}
+function resolvePort(opts, defaults, env) {
+    if (opts.port !== undefined) {
+        if (!Number.isInteger(opts.port) || opts.port < 0) {
+            throw RessError.badUsage(`--port tiene que ser un entero no negativo; se recibió "${opts.port}".`);
+        }
+        return opt(opts.port, 'flag', '--port');
+    }
+    if (env.PORT !== undefined) {
+        const parsed = Number(env.PORT);
+        if (!Number.isInteger(parsed) || parsed < 0) {
+            throw RessError.badUsage(`PORT tiene que ser un entero no negativo; se recibió "${env.PORT}".`);
+        }
+        return opt(parsed, 'env', 'PORT');
+    }
+    return opt(defaults.port ?? 3000, 'default', 'default del framework');
+}
+function resolveHost(opts, defaults, env) {
+    if (opts.host !== undefined) {
+        // `--host` sin valor llega como `true`: equivale a exponer en todas las interfaces.
+        const value = opts.host === true ? '0.0.0.0' : opts.host === false ? 'localhost' : opts.host;
+        return opt(value, 'flag', '--host');
+    }
+    if (env.HOST !== undefined) {
+        return opt(env.HOST, 'env', 'HOST');
+    }
+    return opt(defaults.host ?? 'localhost', 'default', 'default del framework');
+}
+function resolveStrictPort(opts) {
+    if (opts.strictPort !== undefined) {
+        return opt(opts.strictPort, 'flag', opts.strictPort ? '--strict-port' : '--no-strict-port');
+    }
+    return opt(true, 'default', 'default del framework');
+}
+function resolveBase(opts, config) {
+    if (opts.base !== undefined) {
+        return opt(opts.base, 'flag', '--base');
+    }
+    if (config.basePath) {
+        return opt(config.basePath, 'config', 'config:basePath');
+    }
+    return opt('/', 'default', 'default del framework');
+}
+function resolveLogLevel(opts, env) {
+    if (opts.logLevel !== undefined) {
+        if (!VALID_LOG_LEVELS.includes(opts.logLevel)) {
+            throw RessError.badUsage(`--log-level sólo acepta ${VALID_LOG_LEVELS.join(', ')}; se recibió "${opts.logLevel}".`);
+        }
+        return opt(opts.logLevel, 'flag', '--log-level');
+    }
+    if (env.RESS_LOG_LEVEL !== undefined) {
+        const value = env.RESS_LOG_LEVEL;
+        if (!VALID_LOG_LEVELS.includes(value)) {
+            throw RessError.badUsage(`RESS_LOG_LEVEL sólo acepta ${VALID_LOG_LEVELS.join(', ')}; se recibió "${env.RESS_LOG_LEVEL}".`);
+        }
+        return opt(value, 'env', 'RESS_LOG_LEVEL');
+    }
+    return opt('info', 'default', 'default del framework');
+}
+function resolveServerFile(opts) {
+    if (opts.serverFile === false) {
+        return opt(null, 'flag', '--server=false');
+    }
+    if (typeof opts.serverFile === 'string') {
+        return opt(opts.serverFile, 'flag', '--server');
+    }
+    // La autodetección real (¿existe server.{ts,tsx,js,mjs} en la raíz?) la hace
+    // `extend.ts`, que sí toca el sistema de archivos. Acá sólo se declara que no
+    // hubo elección explícita.
+    return opt(null, 'default', 'autodetectado');
+}

package/dist/api/reporter.d.ts

@@ -0,0 +1,74 @@
+/**
+ * El canal de eventos.
+ *
+ * "La API no imprime" necesita un mecanismo o se convierte en una convención
+ * que el primer log de conveniencia por `console` rompe. Cada punto de la API que
+ * quiera informar progreso emite un `RessEvent`; quién lo escucha y cómo lo
+ * muestra es responsabilidad exclusiva de la CLI (`src/cli/reporters/*`).
+ */
+import type { RouteEntry } from '@ressjs/vite-router';
+import type { RessError } from './errors.js';
+import type { RessMode } from './types.js';
+export type VariantTag = string;
+export type RessEvent = {
+    type: 'config:loaded';
+    file: string | null;
+    durationMs: number;
+} | {
+    type: 'routes:scanned';
+    entries: RouteEntry[];
+    durationMs: number;
+} | {
+    type: 'routes:conflict';
+    pattern: string;
+    files: string[];
+} | {
+    type: 'routes:changed';
+    added: string[];
+    removed: string[];
+} | {
+    type: 'catalog:built';
+    pages: number;
+    variants: VariantTag[];
+} | {
+    type: 'server:listening';
+    url: string;
+    mode: RessMode;
+    port: number;
+} | {
+    type: 'server:extended';
+    file: string;
+    hook: 'before' | 'after' | 'file';
+} | {
+    type: 'build:start';
+    target: 'client' | 'ssr';
+} | {
+    type: 'build:done';
+    target: 'client' | 'ssr';
+    durationMs: number;
+    bytes: number;
+} | {
+    type: 'build:artifact';
+    file: string;
+    bytes: number;
+} | {
+    type: 'config:reload';
+    keys: string[];
+    requiresRestart: string[];
+} | {
+    type: 'warn';
+    message: string;
+    file?: string;
+} | {
+    type: 'error';
+    error: RessError;
+};
+export interface RessReporter {
+    event(e: RessEvent): void;
+}
+/** Default de toda la API. No hace nada: la API es utilizable sin ensuciar stdout. */
+export declare const silentReporter: RessReporter;
+/** Reporter de conveniencia para tests: acumula todo lo que recibe. */
+export declare function collectingReporter(): RessReporter & {
+    events: RessEvent[];
+};

package/dist/api/reporter.js

@@ -0,0 +1,12 @@
+/** Default de toda la API. No hace nada: la API es utilizable sin ensuciar stdout. */
+export const silentReporter = { event() { } };
+/** Reporter de conveniencia para tests: acumula todo lo que recibe. */
+export function collectingReporter() {
+    const events = [];
+    return {
+        events,
+        event(e) {
+            events.push(e);
+        },
+    };
+}

package/dist/api/start.d.ts

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

package/dist/api/start.js

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

package/dist/api/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Tipos públicos de la API de `@ressjs/cli`.
+ *
+ * La CLI y la API programática comparten esta forma. Un comando de la CLI hace
+ * poco más que traducir argumentos a `RessAppOptions` e invocar una de estas
+ * funciones — ver `src/cli/commands/*`.
+ */
+import type { Express } from 'express';
+import type { RessReporter } from './reporter.js';
+import type { ResolvedRessOptions } from './options.js';
+import type { RouteManifest } from '@ressjs/vite-router';
+export type RessMode = 'development' | 'production';
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+/** Lo que un consumidor puede pedir. Todo opcional: hay default para cada cosa. */
+export interface RessAppOptions {
+    /** Raíz del proyecto. Default: `process.cwd()`. */
+    root?: string;
+    /** Ruta explícita a un archivo de configuración; si falta, se autodetecta `config/` bajo `root` (F-008). */
+    configFile?: string;
+    /** Default: `'development'` en dev, `'production'` en build y start. */
+    mode?: RessMode;
+    /** Default: `3000`. */
+    port?: number;
+    /** Default: `'localhost'`. `true` equivale a `'0.0.0.0'`. */
+    host?: string | boolean;
+    /** Si el puerto está ocupado: fallar (default) o probar el siguiente. */
+    strictPort?: boolean;
+    /** Prefijo de servido. Default: `config.basePath ?? '/'`. */
+    base?: string;
+    /** Default: `'info'`. */
+    logLevel?: LogLevel;
+    /** Canal de eventos. Default: `silentReporter`. La API nunca imprime. */
+    reporter?: RessReporter;
+    /**
+     * Archivo de servidor del proyecto (vía de escape nivel 2).
+     * Default: se autodetecta `server.{ts,tsx,js,mjs}` en la raíz; ausente = no hay.
+     */
+    serverFile?: string | false;
+    /** Raíz de salida del build. Default: `'dist'`. */
+    outDir?: string;
+}
+export interface RessServer {
+    readonly url: string;
+    readonly port: number;
+    readonly httpServer: import('node:http').Server;
+    close(): Promise<void>;
+}
+export interface RessApp {
+    /** La aplicación Express, ya con el enrutador del framework montado. */
+    readonly app: Express;
+    /** Opciones resueltas, con procedencia. */
+    readonly options: ResolvedRessOptions;
+    /** Manifest de rutas vigente (F-018). En dev cambia con el watcher. */
+    readonly manifest: RouteManifest;
+    /** Servidor de desarrollo del bundler. `undefined` en producción. */
+    readonly vite?: unknown;
+    /** Pone la app a escuchar. Resuelve cuando ya acepta conexiones. */
+    listen(): Promise<RessServer>;
+    /** Cierra bundler, watchers y `ModuleLoader`. Idempotente. */
+    close(): Promise<void>;
+}
+export interface RessServerFileContext {
+    app: Express;
+    mode: RessMode;
+    options: ResolvedRessOptions;
+    manifest: RouteManifest;
+    vite?: unknown;
+}
+export type RessServerFile = (ctx: RessServerFileContext) => Express | void | Promise<Express | void>;
+export interface BuildTargetResult {
+    target: 'client' | 'ssr';
+    durationMs: number;
+    bytes: number;
+    files: string[];
+}
+export interface BuildResult {
+    targets: BuildTargetResult[];
+    durationMs: number;
+    outDir: string;
+    routes: number;
+    variants: number;
+}

package/dist/api/types.js

@@ -0,0 +1 @@
+export {};