@c9up/ream 0.1.26 → 0.1.28

package/README.md

@@ -35,6 +35,71 @@ const app = new Ignitor({ port: 3000 })
 await app.start()
 ```
 
+## Testing
+
+Declare your suites in `reamrc.ts`, the way AdonisJS declares them in
+`adonisrc.ts`, and `ream test` runs them:
+
+```ts
+// reamrc.ts
+export default defineConfig({
+  tests: {
+    timeout: 2_000,
+    forceExit: false,
+    suites: [
+      { name: 'unit', files: ['tests/unit/**/*.spec.(js|ts)'] },
+      {
+        name: 'functional',
+        files: ['tests/functional/**/*.spec.ts'],
+        timeout: 30_000,
+        // Japa's per-suite `configure`. Costs an import of this file in every
+        // worker — `configureSuite` in tests/bootstrap.ts does the same for free.
+        configure: (suite) => suite.setup(() => startHttpServer()),
+      },
+    ],
+  },
+})
+```
+
+```sh
+ream test                    # every suite, in order
+ream test functional         # one suite
+ream test --bail --threads=4
+```
+
+`ream test` sets `NODE_ENV=test` and loads the `.env` files itself, before
+spawning anything: `.env.test` wins over `.env`, `.env.local` is skipped so
+a developer's local overrides never decide what CI runs, and the shell keeps
+the last word. The app writes no hook for this — the workers inherit the
+environment of the process that spawned them.
+
+`japaPlugins: true` lets official Japa plugins (`@japa/assert`, …) run: it
+points `@japa/runner/core` at helix's shim in every worker, so a plugin
+instruments the runner that is actually running. Off by default —
+redirecting a package specifier is not something to do behind your back.
+
+`forceExit: true` makes the run call `process.exit()` once it ends instead
+of waiting for the event loop to drain — the same thing Japa does with it,
+and the answer to a pool or a server the app left open. Without it the
+process exits on its own, so a leaked handle surfaces as a diagnosable
+hang rather than being swallowed.
+
+The stratification is AdonisJS's: ream reads its rc file and hands the
+suites to the runner ([`@c9up/helix`](../helix)), exactly as
+`@adonisjs/core` reads `adonisrc.ts` and hands them to Japa. helix knows
+nothing about ream, and ream owns no test execution. `tests/bootstrap.ts`
+— plugins, `runnerHooks`, `configureSuite` — is helix's, unchanged.
+
+Driving it yourself (a `bin/test.ts`, a console command) is the same call:
+
+```ts
+import { runTestsFromRcFile } from '@c9up/ream/test-runner'
+
+process.exitCode = await runTestsFromRcFile('./reamrc.ts', {
+  suites: process.argv.slice(2),
+})
+```
+
 ## Ecosystem
 
 Every package is standalone and publishable on its own; they consume the Ream

package/dist/Ignitor.d.ts

@@ -13,7 +13,10 @@
  * @implements FR17, FR20, FR23
  */
 import { Application } from './Application.js';
+import type { Console } from './console/Console.js';
+import type { Kernel as ConsoleKernelInstance } from './console/Kernel.js';
 import type { ErrorEvent } from './ErrorBoundary.js';
+import { prettyPrintError } from './errors/prettyPrintError.js';
 import type { HttpKernelRequest, HttpKernelResponse } from './HttpKernel.js';
 import type { MiddlewareFunction } from './middleware/Pipeline.js';
 import type { AppContext, ProviderContract } from './Provider.js';
@@ -38,12 +41,81 @@ export interface ReamrcConfig {
         environment?: string[];
     }>;
     commands?: Array<() => Promise<unknown>>;
+    /**
+     * Command shorthands — Console's `commandsAliases`. The value is the command the
+     * alias stands for, flags included:
+     *   `{ resource: 'make:controller --resource' }`
+     */
+    commandsAliases?: Record<string, string>;
     modules?: {
         /** Path to the modules directory (relative to app root). Default: './app/modules' */
         path?: string;
         /** Auto-loaded files in each module directory. Default: ['routes'] */
         autoload?: string[];
     };
+    /** Test suites and runner settings — the `tests` block of adonisrc.ts. */
+    tests?: TestsConfig;
+}
+/** One test suite, as declared in the rc file (AdonisJS `tests.suites[]`). */
+export interface TestSuiteConfig {
+    /** Suite name — what `ream test <name>` selects. */
+    name: string;
+    /**
+     * The suite's files: a glob, several, or a callback returning their URLs
+     * (Japa `TestFiles`).
+     */
+    files: string | string[] | (() => URL[] | Promise<URL[]>);
+    /** Per-test timeout for this suite, in ms. */
+    timeout?: number;
+    /** Extra attempts on failure for this suite. */
+    retries?: number;
+    /**
+     * Configure the suite before it runs (Japa `TestSuite.configure`). Receives
+     * the same handle as the bootstrap's `configureSuite`, and runs after it.
+     *
+     * Costs an import of the rc file in every worker, since a function cannot
+     * cross a process boundary — `configureSuite` in `tests/bootstrap.ts` does
+     * the same job for free, and is what AdonisJS itself uses.
+     */
+    configure?: (suite: TestSuiteHandle) => void;
+}
+/**
+ * What a suite's `configure` receives — helix's `SuiteHandle`, re-declared here
+ * so the rc file types without ream depending on the runner at type level.
+ */
+export interface TestSuiteHandle {
+    readonly name: string;
+    setup(fn: () => void | Promise<void>): TestSuiteHandle;
+    teardown(fn: () => void | Promise<void>): TestSuiteHandle;
+    onTest(callback: (test: unknown) => void): TestSuiteHandle;
+    onGroup(callback: (group: unknown) => void): TestSuiteHandle;
+    bail(toggle?: boolean): TestSuiteHandle;
+}
+/**
+ * The `tests` block of the rc file — AdonisJS `adonisrc.ts` `tests`, field for
+ * field. The runner that consumes it is helix; ream reads the file, exactly as
+ * `@adonisjs/core` reads adonisrc and hands the suites to Japa.
+ */
+export interface TestsConfig {
+    /** Named suites. `ream test` with no argument runs them all, in order. */
+    suites?: TestSuiteConfig[];
+    /** Default per-test timeout, in ms. */
+    timeout?: number;
+    /** `process.exit()` once the run ends instead of draining the event loop. */
+    forceExit?: boolean;
+    /**
+     * Ream particularity: the bootstrap module's path. AdonisJS hardcodes
+     * `tests/bootstrap.ts`; that stays the default here, and this overrides it.
+     */
+    bootstrap?: string;
+    /**
+     * Point `@japa/runner/core` at helix's shim in every worker, so official Japa
+     * plugins (`@japa/assert`, …) instrument the runner that is actually running.
+     *
+     * Off by default: redirecting a package specifier is not something to do
+     * behind a user's back, and a project with no Japa plugin gains nothing.
+     */
+    japaPlugins?: boolean;
 }
 /** defineConfig helper — like AdonisJS defineConfig(). */
 export declare function defineConfig(config: ReamrcConfig): ReamrcConfig;
@@ -179,6 +251,24 @@ export declare class Ignitor {
     stop(): Promise<void>;
     port(): Promise<number>;
     getApp(): Application;
+    /**
+     * The application root passed to `new Ignitor(new URL('../', import.meta.url))`.
+     * Undefined for inline/test ignitors created without one.
+     */
+    getAppRoot(): URL | undefined;
+    /** Has the application already been started? */
+    isStarted(): boolean;
+    /**
+     * The `consoleApp` façade — the programmatic console.
+     *
+     * Built on demand: the console modules are only imported when something
+     * actually reaches for them, so an HTTP-only boot does not pay for the CLI.
+     */
+    consoleApp(): Promise<Console>;
+    /** The loaded rc file, if `useRcFile()` was called. */
+    getRcFile(): ReamrcConfig | undefined;
+    /** The custom module importer, when the app provided one. */
+    getImporter(): ((filePath: string) => Promise<unknown>) | undefined;
     getRouter(): Router;
     getServer(): Server;
     /**
@@ -190,17 +280,35 @@ export declare class Ignitor {
     getPhase(): string;
     private handleError;
 }
+export { prettyPrintError };
 /**
- * Pretty-print an error (like AdonisJS prettyPrintError).
- */
-export declare function prettyPrintError(error: unknown): void;
-/**
- * ConsoleKernel — handles CLI command dispatching.
- * Like AdonisJS: new Ignitor(...).console().handle(process.argv.splice(2))
+ * ConsoleKernel — boots the app in console mode and dispatches a command.
+ *
+ * Console parity: `new Ignitor(...).console().handle(process.argv.slice(2))`.
+ *
+ * Commands come from two places, as in Console:
+ *   1. the app's own `commands/` directory, discovered automatically;
+ *   2. `reamrc.commands[]`, which registers commands shipped by packages.
+ *
+ * The application is booted lazily — only for a command declaring
+ * `options.startApp`. A generator has no reason to open a database
+ * connection, and paying the boot cost on every `--help` is worse than
+ * pointless: it fails on a machine where the DB is simply not running.
  */
 export declare class ConsoleKernel {
-    private ignitor;
+    #private;
     constructor(ignitor: Ignitor);
+    /**
+     * Build the console kernel and the function that fills it.
+     *
+     * Shared by `handle()` (the CLI) and the `consoleApp` façade (programmatic use), so
+     * both see exactly the same commands — discovery plus `reamrc.commands` —
+     * instead of two loaders drifting apart.
+     */
+    build(): Promise<{
+        kernel: ConsoleKernelInstance;
+        load: () => Promise<void>;
+    }>;
     handle(argv: string[]): Promise<void>;
 }
 //# sourceMappingURL=Ignitor.d.ts.map

package/dist/Ignitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Ignitor.d.ts","sourceRoot":"","sources":["../src/Ignitor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Ignitor.d.ts","sourceRoot":"","sources":["../src/Ignitor.ts"],"names":[],"mappings":"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"}

package/dist/Ignitor.js

@@ -13,8 +13,10 @@
  * @implements FR17, FR20, FR23
  */
 import { Application } from './Application.js';
+import { isCommandClass } from './console/types.js';
 import { ErrorBoundary } from './ErrorBoundary.js';
 import { loadEnvFiles } from './env/loadEnvFiles.js';
+import { prettyPrintError } from './errors/prettyPrintError.js';
 import { ReamError } from './errors/ReamError.js';
 import { installGracefulShutdown } from './GracefulShutdown.js';
 import { startHotReload } from './HotReload.js';
@@ -54,6 +56,7 @@ export class Ignitor {
     phase = 'created';
     hotReloadCleanup;
     #shutdownHandle;
+    #console;
     // Inline configuration (for simple use or testing)
     inlineRoutes;
     inlineMiddleware = [];
@@ -202,6 +205,12 @@ export class Ignitor {
             await this.phaseRegister();
             await this.phaseBoot();
             await this.phaseStart();
+            // Console documents its `consoleApp` service as available once the application has
+            // booted, so the locator is installed here rather than on first use —
+            // `import consoleApp from '@c9up/ream/services/console'` must not throw in a running
+            // app. Only the façade is built (three small modules); loading the
+            // commands themselves stays lazy, inside `consoleApp.boot()`.
+            await this.consoleApp();
             await this.phaseReady();
         }
         catch (err) {
@@ -221,7 +230,7 @@ export class Ignitor {
     }
     /**
      * Load `.env` files into `process.env` before config and providers boot —
-     * mirroring AdonisJS, which loads env in BOTH the HTTP and the ace (console)
+     * mirroring AdonisJS, which loads env in BOTH the HTTP and the consoleApp (console)
      * flows. Without this, `ream migrate` and other console commands booted in a
      * clean subprocess never saw the `.env` the web server got from the shell.
      *
@@ -487,6 +496,19 @@ export class Ignitor {
      */
     async stop() {
         const errors = [];
+        // Release the consoleApp locator first — ownership-guarded, so a second Ignitor
+        // having rebound it is left alone.
+        if (this.#console !== undefined) {
+            const consoleApp = this.#console;
+            this.#console = undefined;
+            try {
+                const { clearConsole } = await import('./services/console.js');
+                clearConsole(consoleApp);
+            }
+            catch {
+                /* the module never loaded — nothing to clear */
+            }
+        }
         const attempt = async (step) => {
             try {
                 await step();
@@ -532,6 +554,45 @@ export class Ignitor {
     getApp() {
         return this.app;
     }
+    /**
+     * The application root passed to `new Ignitor(new URL('../', import.meta.url))`.
+     * Undefined for inline/test ignitors created without one.
+     */
+    getAppRoot() {
+        return this.appRoot;
+    }
+    /** Has the application already been started? */
+    isStarted() {
+        return this.phase === 'started' || this.phase === 'ready';
+    }
+    /**
+     * The `consoleApp` façade — the programmatic console.
+     *
+     * Built on demand: the console modules are only imported when something
+     * actually reaches for them, so an HTTP-only boot does not pay for the CLI.
+     */
+    async consoleApp() {
+        if (this.#console !== undefined)
+            return this.#console;
+        const [{ Console }, { setConsole }] = await Promise.all([
+            import('./console/Console.js'),
+            import('./services/console.js'),
+        ]);
+        const { kernel, load } = await new ConsoleKernel(this).build();
+        const consoleApp = new Console({ kernel, load });
+        this.#console = consoleApp;
+        setConsole(consoleApp);
+        this.app.container.singleton('console', () => consoleApp);
+        return consoleApp;
+    }
+    /** The loaded rc file, if `useRcFile()` was called. */
+    getRcFile() {
+        return this.reamrc;
+    }
+    /** The custom module importer, when the app provided one. */
+    getImporter() {
+        return this.config.importer;
+    }
     getRouter() {
         return this.router;
     }
@@ -585,56 +646,191 @@ export class Ignitor {
         });
     }
 }
+export { prettyPrintError };
 /**
- * Pretty-print an error (like AdonisJS prettyPrintError).
- */
-export function prettyPrintError(error) {
-    if (error instanceof ReamError) {
-        console.error(error.toDevString());
-    }
-    else if (error instanceof Error) {
-        console.error(`\n  ${error.message}\n`);
-        if (error.stack)
-            console.error(error.stack);
-    }
-    else {
-        console.error(error);
-    }
-}
-/**
- * ConsoleKernel — handles CLI command dispatching.
- * Like AdonisJS: new Ignitor(...).console().handle(process.argv.splice(2))
+ * ConsoleKernel — boots the app in console mode and dispatches a command.
+ *
+ * Console parity: `new Ignitor(...).console().handle(process.argv.slice(2))`.
+ *
+ * Commands come from two places, as in Console:
+ *   1. the app's own `commands/` directory, discovered automatically;
+ *   2. `reamrc.commands[]`, which registers commands shipped by packages.
+ *
+ * The application is booted lazily — only for a command declaring
+ * `options.startApp`. A generator has no reason to open a database
+ * connection, and paying the boot cost on every `--help` is worse than
+ * pointless: it fails on a machine where the DB is simply not running.
  */
 export class ConsoleKernel {
-    ignitor;
+    #ignitor;
+    #started = false;
     constructor(ignitor) {
-        this.ignitor = ignitor;
+        this.#ignitor = ignitor;
     }
-    async handle(argv) {
-        await this.ignitor.start();
-        const { CommandRunner } = await import('./console/CommandRunner.js');
-        const runner = new CommandRunner();
-        // Auto-register commands from reamrc
-        const reamrc = this.ignitor.reamrc;
-        if (reamrc?.commands) {
-            for (const commandImport of reamrc.commands) {
-                const mod = await commandImport();
-                const cmd = mod.default;
-                if (cmd?.name && typeof cmd?.run === 'function') {
-                    runner.register(cmd);
+    /**
+     * Build the console kernel and the function that fills it.
+     *
+     * Shared by `handle()` (the CLI) and the `consoleApp` façade (programmatic use), so
+     * both see exactly the same commands — discovery plus `reamrc.commands` —
+     * instead of two loaders drifting apart.
+     */
+    async build() {
+        const { Kernel } = await import('./console/Kernel.js');
+        const kernel = new Kernel({
+            binaryName: 'ream',
+            // A `staysAlive` command ends itself through `this.terminate()`; the
+            // kernel deliberately does not tear the app down for those.
+            onTerminate: async () => {
+                if (this.#started)
+                    await this.#ignitor.stop();
+            },
+            startApp: async () => {
+                // The façade can be used from an already-running application; starting
+                // it a second time would re-register providers.
+                if (!this.#ignitor.isStarted()) {
+                    await this.#ignitor.start();
+                    this.#started = true;
+                }
+                const app = this.#ignitor.getApp();
+                app.container.singleton('consoleKernel', () => kernel);
+                return app;
+            },
+        });
+        // Discovery is registered as a LOADER, not run beside the kernel: `boot()`
+        // is then the single moment commands come in, whether they were found on
+        // disk, declared in the rc file, or added by an application's own loader.
+        kernel.addLoader(this.#commandLoader(kernel));
+        const load = async () => {
+            const aliases = this.#ignitor.getRcFile()?.commandsAliases;
+            if (aliases !== undefined) {
+                for (const [alias, expansion] of Object.entries(aliases)) {
+                    kernel.addAlias(alias, expansion);
                 }
             }
-        }
-        this.ignitor.getApp().container.singleton('console', () => runner);
+            await kernel.boot();
+        };
+        return { kernel, load };
+    }
+    async handle(argv) {
+        const { kernel, load } = await this.build();
+        await load();
+        let staysAlive = false;
         try {
-            await runner.handle(argv);
+            // `process.execArgv` IS what node was started with — Console's `nodeArgs`,
+            // which a command reads to know how the process was launched.
+            const result = await kernel.handle(argv, process.execArgv);
+            staysAlive = result.staysAlive;
         }
         finally {
             // A throwing command must still release the Ignitor's resources
             // (scheduler tickers, watchers) — otherwise the CLI process hangs.
-            await this.ignitor.stop();
+            // A `staysAlive` command keeps them on purpose.
+            if (this.#started && !staysAlive)
+                await this.#ignitor.stop();
+        }
+    }
+    /**
+     * The application's commands, as a loader the kernel consumes at boot.
+     *
+     * Two sources, one collection: the `commands/` directory and the rc file's
+     * `commands[]`. Collecting them together is what lets a command listed in
+     * both be reported as the duplicate it is.
+     */
+    #commandLoader(kernel) {
+        const found = new Map();
+        return {
+            getMetaData: async () => {
+                await this.#discoverAppCommands(kernel, found);
+                await this.#loadPackageCommands(found);
+                // Imported here, not at the top of the file: the console stack is only
+                // loaded for a console dispatch, and a static import would pull it into
+                // every HTTP boot.
+                const { serializeCommand } = await import('./console/Kernel.js');
+                return [...found.values()].map(serializeCommand);
+            },
+            getCommand: async (metadata) => found.get(metadata.commandName) ?? null,
+        };
+    }
+    /**
+     * Load every command in the app's `commands/` directory.
+     *
+     * Tolerant by design: a module that does not default-export a command is
+     * reported and skipped rather than aborting the whole CLI. Discovery scans a
+     * conventional directory, so a stray helper file there must not make
+     * `ream list` unusable. Explicitly declared entries (`reamrc.commands`) are
+     * held to a stricter standard — see {@link #loadPackageCommands}.
+     */
+    async #discoverAppCommands(kernel, found) {
+        const root = this.#ignitor.getAppRoot();
+        if (root === undefined)
+            return;
+        // The framework's own `FsLoader`, with the application's importer plugged
+        // in: scanning a directory for commands is written once, and an app that
+        // compiles its sources differently only replaces the import.
+        const { FsLoader } = await import('./console/loaders.js');
+        const importModule = (file) => this.#importModule(file);
+        const loader = new (class extends FsLoader {
+            import(file) {
+                return importModule(file);
+            }
+        })(new URL('commands/', root)).onSkipped((fileName) => {
+            // Tolerant by design: discovery scans a conventional directory, so a
+            // stray helper there must not make `ream list` unusable.
+            kernel.logger.warning(`Skipped ${fileName} in commands/ — no default-exported command class.`);
+        });
+        for (const metadata of await loader.getMetaData()) {
+            const command = await loader.getCommand(metadata);
+            if (command !== null)
+                found.set(command.commandName, command);
+        }
+    }
+    /**
+     * Register commands declared in `reamrc.commands[]` — the channel for
+     * commands shipped by packages, which discovery cannot see.
+     *
+     * Strict: an entry listed by hand that does not resolve to a command is a
+     * configuration error, and silently ignoring it is how a command "disappears"
+     * with no explanation.
+     */
+    async #loadPackageCommands(found) {
+        const declared = this.#ignitor.getRcFile()?.commands;
+        if (!declared)
+            return;
+        for (const entry of declared) {
+            const command = commandOf(await entry());
+            if (command === undefined) {
+                throw new ReamError('E_CONSOLE_INVALID_COMMAND', 'An entry of reamrc.ts `commands` does not default-export a command class.', {
+                    hint: 'Expected `export default class X { static commandName = "..."; static description = "..."; run() {} }`.',
+                });
+            }
+            // The most likely duplicate after the move to auto-discovery: a command
+            // living in `commands/` AND still listed by hand. Say so, rather than
+            // leaving the user to guess which two registrations collided.
+            const existing = found.get(command.commandName);
+            if (existing !== undefined && existing !== command) {
+                throw new ReamError('E_CONSOLE_DUPLICATE_COMMAND', `Two commands claim the name "${command.commandName}".`, {
+                    hint: 'Commands in commands/ are discovered automatically — remove this entry from reamrc.ts `commands`, which is only for commands shipped by packages.',
+                });
+            }
+            found.set(command.commandName, command);
         }
     }
+    /** Honour the app's custom importer when it provided one. */
+    async #importModule(file) {
+        const importer = this.#ignitor.getImporter();
+        if (importer === undefined)
+            return import(file.href);
+        const root = this.#ignitor.getAppRoot();
+        const relative = root === undefined ? file.href : `./${file.href.slice(root.href.length)}`;
+        return importer(relative);
+    }
+}
+/** The command a module default-exports, or undefined when it exports none. */
+function commandOf(mod) {
+    if (typeof mod !== 'object' || mod === null)
+        return undefined;
+    const value = Reflect.get(mod, 'default');
+    return isCommandClass(value) ? value : undefined;
 }
 async function findAvailablePort(desired) {
     const net = await import('node:net');