@ressjs/cli 0.6.0-experimental.0

package/dist/cli/argv.d.ts

@@ -0,0 +1,63 @@
+import type { LogLevel, RessMode } from '../api/types.js';
+export interface DevFlags {
+    port?: number;
+    host?: string | boolean;
+    strictPort?: boolean;
+    base?: string;
+    root?: string;
+    config?: string;
+    mode?: RessMode;
+    server?: string | false;
+    logLevel?: LogLevel;
+    open?: boolean;
+    clearScreen?: boolean;
+}
+export interface BuildFlags {
+    root?: string;
+    config?: string;
+    mode?: RessMode;
+    outDir?: string;
+    target?: 'all' | 'client' | 'ssr';
+    clean?: boolean;
+    logLevel?: LogLevel;
+}
+export interface StartFlags {
+    port?: number;
+    host?: string | boolean;
+    strictPort?: boolean;
+    base?: string;
+    root?: string;
+    config?: string;
+    outDir?: string;
+    server?: string | false;
+    logLevel?: LogLevel;
+}
+export interface InfoFlags {
+    root?: string;
+    config?: string;
+    mode?: RessMode;
+    json?: boolean;
+    routes?: boolean;
+    variants?: boolean;
+    configOnly?: boolean;
+}
+export type ParsedCommand = {
+    command: 'dev';
+    flags: DevFlags;
+} | {
+    command: 'build';
+    flags: BuildFlags;
+} | {
+    command: 'start';
+    flags: StartFlags;
+} | {
+    command: 'info';
+    flags: InfoFlags;
+} | {
+    command: 'help';
+    text: string;
+} | {
+    command: 'version';
+    text: string;
+};
+export declare function parseArgv(argv: readonly string[], version: string): ParsedCommand;

package/dist/cli/argv.js

@@ -0,0 +1,148 @@
+/**
+ * Definición de los cuatro comandos y sus argumentos.
+ *
+ * Usa `commander`: la CLI tiene cuatro subcomandos con muchos alias, pares
+ * `--x`/`--no-x` y un flag de valor opcional (`--host`). A diferencia de
+ * `create-ress-app` —que F-017 dejó sin dependencias porque se descarga entero
+ * en cada `npx`—, `@ressjs/cli` se instala una vez como dependencia del
+ * proyecto y se reusa en cada `npm run dev`: el costo de una dependencia bien
+ * mantenida se paga una sola vez, no en cada invocación.
+ *
+ * Un argumento desconocido o un valor de enum inválido produce `RESS_BAD_USAGE`
+ * (código 2), nunca la salida cruda de `commander`.
+ */
+import { Command, Option } from 'commander';
+import { RessError } from '../api/errors.js';
+const LOG_LEVELS = ['silent', 'error', 'warn', 'info', 'debug'];
+function normalizeServer(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === 'false')
+        return false;
+    return raw;
+}
+function fail(message) {
+    throw RessError.badUsage(message);
+}
+/**
+ * `writeOut` se deja intacto: `--help` y `--version` se imprimen con el
+ * formateador de `commander`, directo a stdout, como cualquier CLI. Sólo se
+ * suprime `writeErr`: los errores de uso reales se reformatean como
+ * `RessError` para que tengan el mismo aspecto que cualquier otro error del
+ * framework, en vez del formato propio de `commander`.
+ */
+function quietErrors() {
+    return { writeErr: () => { } };
+}
+function baseCommand(name, description) {
+    return new Command(name)
+        .description(description)
+        .exitOverride((err) => {
+        if (err.code?.startsWith('commander.help') || err.code === 'commander.version') {
+            throw err;
+        }
+        fail(err.message.replace(/^error: /, ''));
+    })
+        .configureOutput(quietErrors());
+}
+export function parseArgv(argv, version) {
+    const program = new Command('ress')
+        .description('La CLI de ress.js: dev, build, start e info.')
+        .version(version, '-V, --version')
+        .exitOverride((err) => {
+        throw err;
+    })
+        .configureOutput(quietErrors());
+    let result;
+    const dev = baseCommand('dev', 'Levanta el servidor de desarrollo con recarga en caliente')
+        .option('-p, --port <n>', 'Puerto de escucha', (v) => parsePort(v))
+        .option('-H, --host [host]', 'Sin valor equivale a 0.0.0.0')
+        .option('--strict-port', 'Falla si el puerto está ocupado')
+        .option('--no-strict-port', 'Prueba el siguiente puerto libre')
+        .option('--base <path>', 'Prefijo de servido')
+        .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)')
+        .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')
+        .option('--no-clear-screen', 'Conserva el scrollback')
+        .action((opts) => {
+        result = { command: 'dev', flags: { ...opts, server: normalizeServer(opts.server) } };
+    });
+    const build = baseCommand('build', 'Produce el build de producción, cliente y servidor')
+        .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('--out-dir <dir>', 'Raíz de salida')
+        .addOption(new Option('--target <t>', 'Qué entorno construir').choices(['all', 'client', 'ssr']))
+        .option('--no-clean', 'Conserva la salida anterior')
+        .addOption(new Option('-l, --log-level <lvl>', 'Detalle de la salida').choices(LOG_LEVELS))
+        .action((opts) => {
+        result = { command: 'build', flags: opts };
+    });
+    const start = baseCommand('start', 'Sirve el build de producción')
+        .option('-p, --port <n>', 'Puerto de escucha', (v) => parsePort(v))
+        .option('-H, --host [host]', 'En producción el default es abierto')
+        .option('--strict-port', 'Falla si el puerto está ocupado')
+        .option('--no-strict-port', 'Prueba el siguiente puerto libre')
+        .option('--base <path>', 'Prefijo de servido')
+        .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)')
+        .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) } };
+    });
+    const info = baseCommand('info', 'Reporta qué detectó el framework en este proyecto')
+        .option('--root <dir>', 'Raíz del proyecto')
+        .addOption(new Option('-c, --config <file>', 'Archivo de configuración'))
+        .addOption(new Option('-m, --mode <mode>', 'Modo con el que resolver la config').choices(['development', 'production']))
+        .option('--json', 'Salida legible por máquina')
+        .option('--routes', 'Sólo la sección de rutas')
+        .option('--variants', 'Sólo la sección de variantes')
+        .option('--config-only', 'Sólo la configuración resuelta')
+        .action((opts) => {
+        result = { command: 'info', flags: opts };
+    });
+    program.addCommand(dev);
+    program.addCommand(build);
+    program.addCommand(start);
+    program.addCommand(info);
+    try {
+        program.parse(argv, { from: 'user' });
+    }
+    catch (err) {
+        if (err instanceof RessError)
+            throw err;
+        const commanderErr = err;
+        // El texto ya salió por stdout de la mano de `commander` (`writeOut` no se
+        // tocó): acá sólo se señala que no hay nada más que hacer.
+        if (commanderErr.code?.startsWith('commander.help')) {
+            return { command: 'help', text: '' };
+        }
+        if (commanderErr.code === 'commander.version') {
+            return { command: 'version', text: '' };
+        }
+        if (commanderErr.code === 'commander.unknownCommand' || commanderErr.code === 'commander.unknownOption') {
+            fail(commanderErr.message?.replace(/^error: /, '') ?? 'comando o argumento desconocido');
+        }
+        if (commanderErr.code === 'commander.missingArgument' || commanderErr.code === 'commander.invalidArgument') {
+            fail(commanderErr.message?.replace(/^error: /, '') ?? 'argumento inválido');
+        }
+        throw err;
+    }
+    if (!result) {
+        return { command: 'help', text: program.helpInformation() };
+    }
+    return result;
+}
+function parsePort(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        fail(`--port tiene que ser un entero no negativo; se recibió "${value}".`);
+    }
+    return parsed;
+}

package/dist/cli/commands/build.d.ts

@@ -0,0 +1,2 @@
+import type { BuildFlags } from '../argv.js';
+export declare function buildCommand(flags: BuildFlags): Promise<number>;

package/dist/cli/commands/build.js

@@ -0,0 +1,7 @@
+import { buildApp } from '../../api/index.js';
+import { createTerminalReporter } from '../reporters/terminal.js';
+export async function buildCommand(flags) {
+    const reporter = createTerminalReporter({ logLevel: flags.logLevel });
+    await buildApp({ ...flags, reporter });
+    return 0;
+}

package/dist/cli/commands/dev.d.ts

@@ -0,0 +1,2 @@
+import type { DevFlags } from '../argv.js';
+export declare function devCommand(flags: DevFlags): Promise<number>;

package/dist/cli/commands/dev.js

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

package/dist/cli/commands/info.d.ts

@@ -0,0 +1,2 @@
+import type { InfoFlags } from '../argv.js';
+export declare function infoCommand(flags: InfoFlags): Promise<number>;

package/dist/cli/commands/info.js

@@ -0,0 +1,17 @@
+import { inspectProject } from '../../api/index.js';
+import { detectFormatEnv } from '../reporters/format.js';
+import { formatProjectInfo } from '../reporters/info-format.js';
+import { printJson } from '../reporters/json.js';
+export async function infoCommand(flags) {
+    const info = await inspectProject(flags);
+    // El diagnóstico nunca aborta por un proyecto roto: sale 0 aun con
+    // `config.valid === false` o rutas en conflicto. Ese es el punto de `info`.
+    if (flags.json) {
+        printJson(info);
+        return 0;
+    }
+    const env = detectFormatEnv(Boolean(process.stdout.isTTY));
+    process.stdout.write(formatProjectInfo(info, { routes: flags.routes, variants: flags.variants, configOnly: flags.configOnly }, env) +
+        '\n');
+    return 0;
+}

package/dist/cli/commands/start.d.ts

@@ -0,0 +1,2 @@
+import type { StartFlags } from '../argv.js';
+export declare function startCommand(flags: StartFlags): Promise<number>;

package/dist/cli/commands/start.js

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

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: readonly string[]): Promise<void>;

package/dist/cli/main.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Punto de entrada. Único bloque de captura de errores del paquete: mapea
+ * `RessError` a su código de salida y al formato de error del reporter. Un
+ * `try/catch` por comando sería la primera duplicación — por eso vive acá y no
+ * 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) {
+    switch (parsed.command) {
+        case 'dev':
+            return devCommand(parsed.flags);
+        case 'build':
+            return buildCommand(parsed.flags);
+        case 'start':
+            return startCommand(parsed.flags);
+        case 'info':
+            return infoCommand(parsed.flags);
+    }
+}
+export async function main(argv = process.argv.slice(2)) {
+    // El parseo de argumentos también puede fallar (comando desconocido,
+    // argumento contradictorio) y su error tiene que pasar por el mismo formato
+    // y la misma tabla de códigos de salida que cualquier otro `RessError` — si
+    // quedara afuera del bloque, `ress dev --nope` saldría con una traza cruda y
+    // código 1 en vez del 2 que le corresponde a un error de uso.
+    try {
+        const version = await cliVersion();
+        const parsed = parseArgv(argv, version);
+        if (parsed.command === 'help' || parsed.command === 'version') {
+            if (parsed.text)
+                process.stdout.write(parsed.text + '\n');
+            process.exitCode = 0;
+            return;
+        }
+        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;
+            return;
+        }
+        // No identificado por el framework: se muestra la traza tal cual. Ocultarla
+        // sería peor que un error sin formatear (UC-12).
+        process.stderr.write(String(error instanceof Error ? (error.stack ?? error.message) : error) + '\n');
+        process.exitCode = 1;
+    }
+}
+main().catch((error) => {
+    process.stderr.write(String(error?.stack ?? error) + '\n');
+    process.exitCode = 1;
+});

package/dist/cli/reporters/format.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Detección de entorno de salida y utilidades de formato.
+ *
+ * Todo lo que decide si hay color, cursor o animaciones vive acá, en un solo
+ * lugar: `terminal.ts` sólo lo consulta.
+ */
+import { styleText } from 'node:util';
+export interface FormatEnv {
+    isTTY: boolean;
+    color: boolean;
+}
+export declare function detectFormatEnv(streamIsTTY: boolean, env?: NodeJS.ProcessEnv): FormatEnv;
+type Style = Parameters<typeof styleText>[0];
+export declare function paint(env: FormatEnv, style: Style, text: string): string;
+export declare function bold(env: FormatEnv, text: string): string;
+export declare function dim(env: FormatEnv, text: string): string;
+export declare function green(env: FormatEnv, text: string): string;
+export declare function red(env: FormatEnv, text: string): string;
+export declare function yellow(env: FormatEnv, text: string): string;
+export declare function cyan(env: FormatEnv, text: string): string;
+/** `1234567` → `'1.2 MB'`. Sin dependencias: es una tabla de cuatro casos. */
+export declare function formatBytes(bytes: number): string;
+export declare function formatDuration(ms: number): string;
+export {};

package/dist/cli/reporters/format.js

@@ -0,0 +1,50 @@
+/**
+ * Detección de entorno de salida y utilidades de formato.
+ *
+ * Todo lo que decide si hay color, cursor o animaciones vive acá, en un solo
+ * lugar: `terminal.ts` sólo lo consulta.
+ */
+import { styleText } from 'node:util';
+export function detectFormatEnv(streamIsTTY, env = process.env) {
+    const isTTY = streamIsTTY && !env.CI;
+    const color = isTTY && !env.NO_COLOR;
+    return { isTTY, color };
+}
+export function paint(env, style, text) {
+    if (!env.color)
+        return text;
+    return styleText(style, text);
+}
+export function bold(env, text) {
+    return paint(env, 'bold', text);
+}
+export function dim(env, text) {
+    return paint(env, 'dim', text);
+}
+export function green(env, text) {
+    return paint(env, 'green', text);
+}
+export function red(env, text) {
+    return paint(env, 'red', text);
+}
+export function yellow(env, text) {
+    return paint(env, 'yellow', text);
+}
+export function cyan(env, text) {
+    return paint(env, 'cyan', text);
+}
+/** `1234567` → `'1.2 MB'`. Sin dependencias: es una tabla de cuatro casos. */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)} ms`;
+    return `${(ms / 1000).toFixed(2)} s`;
+}

package/dist/cli/reporters/info-format.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Formato de `ress info` en modo humano.
+ *
+ * Aparte de `terminal.ts` porque no traduce eventos: recibe el `ProjectInfo`
+ * completo de una sola vez y decide qué secciones mostrar según las banderas
+ * `--routes` / `--variants` / `--config-only`.
+ */
+import type { ProjectInfo } from '../../api/inspect.js';
+import { type FormatEnv } from './format.js';
+export interface InfoSections {
+    routes?: boolean;
+    variants?: boolean;
+    configOnly?: boolean;
+}
+export declare function formatProjectInfo(info: ProjectInfo, sections: InfoSections, env: FormatEnv): string;

package/dist/cli/reporters/info-format.js

@@ -0,0 +1,49 @@
+import { bold, dim, formatBytes, green, red } from './format.js';
+export function formatProjectInfo(info, sections, env) {
+    const only = sections.routes || sections.variants || sections.configOnly;
+    const lines = [];
+    if (!only || sections.configOnly) {
+        lines.push('', bold(env, '  Sistema'));
+        lines.push(`    node            ${info.versions.node}`);
+        lines.push(`    os              ${info.platform.os}`);
+        lines.push(`    cwd             ${info.platform.cwd}`);
+        lines.push('', bold(env, '  Paquetes'));
+        for (const [name, version] of Object.entries(info.versions.packages)) {
+            lines.push(`    ${name.padEnd(24)} ${version}`);
+        }
+        lines.push('', bold(env, '  Configuración'));
+        lines.push(`    archivo         ${info.config.file ?? '(autodetectado)'}`);
+        lines.push(`    válida          ${info.config.valid ? green(env, '✓ sí') : red(env, '✖ no')}`);
+        if (!info.config.valid) {
+            for (const e of info.config.errors ?? [])
+                lines.push(`      · ${e.message}`);
+        }
+        for (const [key, entry] of Object.entries(info.config.sources)) {
+            lines.push(`    ${key.padEnd(15)} ${JSON.stringify(entry.value)}  ${dim(env, entry.origin)}`);
+        }
+    }
+    if (!only || sections.routes) {
+        lines.push('', bold(env, `  Rutas (${info.routes.count})`));
+        for (const r of info.routes.entries)
+            lines.push(`    ${r.pattern.padEnd(24)} ${r.kind.padEnd(8)} ${r.file}`);
+        for (const c of info.routes.conflicts) {
+            lines.push(red(env, `    ⚠ conflicto ${c.pattern}: ${c.files.join(', ')}`));
+        }
+    }
+    if (!only || sections.variants) {
+        lines.push('', bold(env, '  Variantes'));
+        lines.push(`    declaradas      ${info.variants.declared.join(', ') || '(ninguna)'}`);
+        lines.push(`    enumeradas      ${info.variants.tags.join(', ') || '(ninguna)'}`);
+    }
+    if (!only) {
+        lines.push('', bold(env, '  Build'));
+        lines.push(`    ${info.build.outDir}/           ${info.build.present ? 'presente' : 'ausente'}`);
+        if (info.build.present) {
+            lines.push(`    manifest        v${info.build.manifestVersion} · ${info.build.compatible ? 'compatible' : 'incompatible'}`);
+            lines.push(`    generado        ${info.build.builtAt}`);
+            lines.push(`    tamaños         client ${formatBytes(info.build.sizes.client)} · server ${formatBytes(info.build.sizes.server)}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/cli/reporters/json.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Reporter JSON — `--json` no es un segundo camino de datos, es otro
+ * `RessReporter` sobre los mismos eventos. Acumula y no imprime nada por sí
+ * mismo: quien lo usa (`info.ts`) decide cuándo volcar el JSON final, después
+ * de tener el resultado completo de `inspectProject`.
+ */
+import type { RessEvent, RessReporter } from '../../api/reporter.js';
+export declare function createJsonReporter(): RessReporter & {
+    events: RessEvent[];
+};
+/** Vuelca un único objeto JSON a stdout. Usado por `ress info --json`. */
+export declare function printJson(value: unknown, stdout?: NodeJS.WritableStream): void;

package/dist/cli/reporters/json.js

@@ -0,0 +1,13 @@
+export function createJsonReporter() {
+    const events = [];
+    return {
+        events,
+        event(e) {
+            events.push(e);
+        },
+    };
+}
+/** Vuelca un único objeto JSON a stdout. Usado por `ress info --json`. */
+export function printJson(value, stdout = process.stdout) {
+    stdout.write(JSON.stringify(value, null, 2) + '\n');
+}

package/dist/cli/reporters/terminal.d.ts

@@ -0,0 +1,35 @@
+/**
+ * El reporter de terminal.
+ *
+ * Único módulo del paquete que llama a `console`/`process.stdout` — la regla
+ * que el test de arquitectura verifica. Traduce cada `RessEvent` a una línea de
+ * texto; nada de lo que hay acá vive en la API.
+ *
+ * Todo lo informativo va a stdout; advertencias y errores, a stderr. Es lo que
+ * permite `ress info --json > info.json` sin que un warning corrompa el archivo.
+ */
+import type { RessEvent, RessReporter } from '../../api/reporter.js';
+import type { RessError } from '../../api/errors.js';
+import type { LogLevel } from '../../api/types.js';
+import { type FormatEnv } from './format.js';
+export interface TerminalReporterOptions {
+    logLevel?: LogLevel;
+    clearScreen?: boolean;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function createTerminalReporter(opts?: TerminalReporterOptions): RessReporter;
+interface Sinks {
+    out: (line: string) => void;
+    debugOut: (line: string) => void;
+    warnOut: (line: string) => void;
+    errOut: (line: string) => void;
+}
+/**
+ * Un caso por variante de `RessEvent`, a propósito: es lo que el test de
+ * reporter recorre para comprobar que ninguna se quedó sin formato.
+ */
+export declare function formatEvent(e: RessEvent, env: FormatEnv, sinks: Sinks): void;
+export declare function formatError(error: RessError, env: FormatEnv): string;
+export {};