@adonisjs/core 7.0.0-next.0 → 7.0.0-next.10

package/build/commands/make/view.d.ts

@@ -1,14 +1,37 @@
 import { BaseCommand } from '../../modules/ace/main.ts';
 /**
- * Make a new EdgeJS template file
+ * Command to create a new Edge.js template file.
+ * Edge templates are used for rendering HTML views in your web application,
+ * supporting layouts, partials, components, and template inheritance.
+ *
+ * @example
+ * ```
+ * ace make:view home
+ * ace make:view users/profile
+ * ace make:view components/navbar
+ * ace make:view layouts/app
+ * ```
  */
 export default class MakeView extends BaseCommand {
+    /**
+     * The command name
+     */
     static commandName: string;
+    /**
+     * The command description
+     */
     static description: string;
+    /**
+     * Name of the template file to create
+     */
     name: string;
     /**
-     * The stub to use for generating the template
+     * The stub template file to use for generating the Edge template
      */
     protected stubPath: string;
+    /**
+     * Execute the command to create a new Edge.js template file.
+     * Generates the template file in the views directory.
+     */
     run(): Promise<void>;
 }

package/build/commands/make/view.js

@@ -15,15 +15,35 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { stubsRoot } from "../../stubs/main.js";
 import { args, BaseCommand } from "../../modules/ace/main.js";
 /**
- * Make a new EdgeJS template file
+ * Command to create a new Edge.js template file.
+ * Edge templates are used for rendering HTML views in your web application,
+ * supporting layouts, partials, components, and template inheritance.
+ *
+ * @example
+ * ```
+ * ace make:view home
+ * ace make:view users/profile
+ * ace make:view components/navbar
+ * ace make:view layouts/app
+ * ```
  */
 export default class MakeView extends BaseCommand {
+    /**
+     * The command name
+     */
     static commandName = 'make:view';
+    /**
+     * The command description
+     */
     static description = 'Create a new Edge.js template file';
     /**
-     * The stub to use for generating the template
+     * The stub template file to use for generating the Edge template
      */
     stubPath = 'make/view/main.stub';
+    /**
+     * Execute the command to create a new Edge.js template file.
+     * Generates the template file in the views directory.
+     */
     async run() {
         const codemods = await this.createCodemods();
         await codemods.makeUsingStub(stubsRoot, this.stubPath, {

package/build/commands/repl.d.ts

@@ -1,14 +1,34 @@
 import { BaseCommand } from '../modules/ace/main.ts';
 import { type CommandOptions } from '../types/ace.ts';
 /**
- * The ReplCommand class is used to start the Repl server
+ * Command to start an interactive REPL (Read-Eval-Print Loop) session for AdonisJS.
+ * The REPL provides a command-line interface where you can execute JavaScript code
+ * in the context of your AdonisJS application, allowing you to interact with models,
+ * services, and other application components in real-time.
+ *
+ * @example
+ * ```
+ * ace repl
+ * ```
  */
 export default class ReplCommand extends BaseCommand {
+    /**
+     * The command name
+     */
     static commandName: string;
+    /**
+     * The command description
+     */
     static description: string;
+    /**
+     * Command options configuration.
+     * Requires the application to be started and keeps the process alive.
+     */
     static options: CommandOptions;
     /**
-     * Starts the REPL server process
+     * Execute the command to start the REPL server.
+     * Creates a REPL instance from the container and sets up an exit handler
+     * that properly terminates the application when the REPL session ends.
      */
     run(): Promise<void>;
 }

package/build/commands/repl.js

@@ -8,17 +8,37 @@
  */
 import { BaseCommand } from "../modules/ace/main.js";
 /**
- * The ReplCommand class is used to start the Repl server
+ * Command to start an interactive REPL (Read-Eval-Print Loop) session for AdonisJS.
+ * The REPL provides a command-line interface where you can execute JavaScript code
+ * in the context of your AdonisJS application, allowing you to interact with models,
+ * services, and other application components in real-time.
+ *
+ * @example
+ * ```
+ * ace repl
+ * ```
  */
 export default class ReplCommand extends BaseCommand {
+    /**
+     * The command name
+     */
     static commandName = 'repl';
+    /**
+     * The command description
+     */
     static description = 'Start a new REPL session';
+    /**
+     * Command options configuration.
+     * Requires the application to be started and keeps the process alive.
+     */
     static options = {
         startApp: true,
         staysAlive: true,
     };
     /**
-     * Starts the REPL server process
+     * Execute the command to start the REPL server.
+     * Creates a REPL instance from the container and sets up an exit handler
+     * that properly terminates the application when the REPL session ends.
      */
     async run() {
         const repl = await this.app.container.make('repl');

package/build/commands/serve.d.ts

@@ -5,17 +5,53 @@ import { BaseCommand } from '../modules/ace/main.ts';
  * Serve command is used to run the AdonisJS HTTP server during development. The
  * command under the hood runs the "bin/server.ts" file and watches for file
  * system changes
+ *
+ * @example
+ * ```
+ * ace serve
+ * ace serve --watch
+ * ace serve --hmr
+ * ace serve --poll
+ * ace serve --no-clear
+ * ```
  */
 export default class Serve extends BaseCommand {
     #private;
+    /**
+     * The command name
+     */
     static commandName: string;
+    /**
+     * The command description
+     */
     static description: string;
+    /**
+     * Help text for the command
+     */
     static help: string[];
+    /**
+     * Command options configuration
+     */
     static options: CommandOptions;
+    /**
+     * The development server instance
+     */
     devServer: DevServer;
+    /**
+     * Start the server with HMR support
+     */
     hmr?: boolean;
+    /**
+     * Watch filesystem and restart the HTTP server on file change
+     */
     watch?: boolean;
+    /**
+     * Use polling to detect filesystem changes
+     */
     poll?: boolean;
+    /**
+     * Clear the terminal for new logs after file change
+     */
     clear?: boolean;
     /**
      * Runs the HTTP server

package/build/commands/serve.js

@@ -12,16 +12,34 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+import { importAssembler } from "../src/utils.js";
 import { BaseCommand, flags } from "../modules/ace/main.js";
-import { importAssembler, importTypeScript } from "../src/utils.js";
 /**
  * Serve command is used to run the AdonisJS HTTP server during development. The
  * command under the hood runs the "bin/server.ts" file and watches for file
  * system changes
+ *
+ * @example
+ * ```
+ * ace serve
+ * ace serve --watch
+ * ace serve --hmr
+ * ace serve --poll
+ * ace serve --no-clear
+ * ```
  */
 export default class Serve extends BaseCommand {
+    /**
+     * The command name
+     */
     static commandName = 'serve';
+    /**
+     * The command description
+     */
     static description = 'Start the development HTTP server along with the file watcher to perform restarts on file change';
+    /**
+     * Help text for the command
+     */
     static help = [
         'Start the development server with file watcher using the following command.',
         '```',
@@ -39,11 +57,16 @@ export default class Serve extends BaseCommand {
         '{{ binaryName }} serve --assets-args="--debug --base=/public"',
         '```',
     ];
+    /**
+     * Command options configuration
+     */
     static options = {
         staysAlive: true,
     };
     /**
      * Log a development dependency is missing
+     *
+     * @param dependency - The name of the missing dependency
      */
     #logMissingDevelopmentDependency(dependency) {
         this.logger.error([
@@ -96,20 +119,14 @@ export default class Serve extends BaseCommand {
             this.exitCode = 1;
             this.terminate();
         });
-        const ts = await importTypeScript(this.app);
-        if (!ts) {
-            this.#logMissingDevelopmentDependency('typescript');
-            this.exitCode = 1;
-            return;
-        }
         /**
          * Start the development server
          */
         if (this.watch) {
-            await this.devServer.startAndWatch(ts, { poll: this.poll || false });
+            await this.devServer.startAndWatch({ poll: this.poll || false });
         }
         else {
-            await this.devServer.start(ts);
+            await this.devServer.start();
         }
     }
 }

package/build/commands/test.d.ts

@@ -2,29 +2,92 @@ import type { TestRunner } from '@adonisjs/assembler';
 import type { CommandOptions } from '../types/ace.ts';
 import { BaseCommand } from '../modules/ace/main.ts';
 /**
- * Test command is used to run tests with optional file watcher. Under the
- * hood, we run "bin/test.js" file.
+ * Command to run application tests using the Japa test runner.
+ * Supports filtering tests by suites, files, tags, groups, and individual tests.
+ * Can run in watch mode to automatically re-run tests when files change.
+ *
+ * @example
+ * ```
+ * ace test
+ * ace test unit integration
+ * ace test --watch
+ * ace test --files=user.spec.ts
+ * ace test --tags=slow --groups="User tests"
+ * ace test --reporters=spec,dot
+ * ace test --timeout=5000 --retries=2
+ * ```
  */
 export default class Test extends BaseCommand {
     #private;
+    /**
+     * The command name
+     */
     static commandName: string;
+    /**
+     * The command description
+     */
     static description: string;
+    /**
+     * Command options configuration.
+     * Allows unknown flags to be passed to Japa and keeps the process alive.
+     */
     static options: CommandOptions;
+    /**
+     * The test runner instance from the assembler package
+     */
     testsRunner: TestRunner;
+    /**
+     * Test suite names to run. When provided, only tests from the specified suites will be executed
+     */
     suites?: string[];
+    /**
+     * Filter tests by filename patterns
+     */
     files?: string[];
+    /**
+     * Filter tests by tags
+     */
     tags?: string[];
+    /**
+     * Filter tests by parent group title
+     */
     groups?: string[];
+    /**
+     * Filter tests by test title
+     */
     tests?: string[];
+    /**
+     * Specify one or more test reporters to use for output formatting
+     */
     reporters?: string[];
+    /**
+     * Enable watch mode to automatically re-run tests when files change
+     */
     watch?: boolean;
+    /**
+     * Use polling instead of native filesystem events to detect file changes
+     */
     poll?: boolean;
+    /**
+     * Default timeout in milliseconds for all tests
+     */
     timeout?: number;
+    /**
+     * Default number of retries for failed tests
+     */
     retries?: number;
+    /**
+     * Execute only tests that failed during the last run
+     */
     failed?: boolean;
+    /**
+     * Clear the terminal for new logs after file change in watch mode
+     */
     clear?: boolean;
     /**
-     * Runs tests
+     * Execute the test command. Sets up the test runner with all configured options
+     * and filters, then runs tests either once or in watch mode. Handles missing
+     * dependencies and properly configures the test environment.
      */
     run(): Promise<void>;
 }

package/build/commands/test.js

@@ -12,21 +12,46 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+import { importAssembler } from "../src/utils.js";
 import { BaseCommand, flags, args } from "../modules/ace/main.js";
-import { importAssembler, importTypeScript } from "../src/utils.js";
 /**
- * Test command is used to run tests with optional file watcher. Under the
- * hood, we run "bin/test.js" file.
+ * Command to run application tests using the Japa test runner.
+ * Supports filtering tests by suites, files, tags, groups, and individual tests.
+ * Can run in watch mode to automatically re-run tests when files change.
+ *
+ * @example
+ * ```
+ * ace test
+ * ace test unit integration
+ * ace test --watch
+ * ace test --files=user.spec.ts
+ * ace test --tags=slow --groups="User tests"
+ * ace test --reporters=spec,dot
+ * ace test --timeout=5000 --retries=2
+ * ```
  */
 export default class Test extends BaseCommand {
+    /**
+     * The command name
+     */
     static commandName = 'test';
+    /**
+     * The command description
+     */
     static description = 'Run tests along with the file watcher to re-run tests on file change';
+    /**
+     * Command options configuration.
+     * Allows unknown flags to be passed to Japa and keeps the process alive.
+     */
     static options = {
         allowUnknownFlags: true,
         staysAlive: true,
     };
     /**
-     * Log a development dependency is missing
+     * Log an error message when a required development dependency is missing.
+     * Provides helpful instructions for resolving the issue.
+     *
+     * @param dependency - The name of the missing dependency package
      */
     #logMissingDevelopmentDependency(dependency) {
         this.logger.error([
@@ -38,7 +63,10 @@ export default class Test extends BaseCommand {
         ].join('\n'));
     }
     /**
-     * Collection of unknown flags to pass to Japa
+     * Collect unknown flags and format them to pass to the Japa test runner.
+     * Handles boolean flags, arrays, and single values appropriately.
+     *
+     * @returns Array of formatted command-line arguments for Japa
      */
     #getPassthroughFlags() {
         return this.parsed.unknownFlags
@@ -61,7 +89,9 @@ export default class Test extends BaseCommand {
             .flat(2);
     }
     /**
-     * Runs tests
+     * Execute the test command. Sets up the test runner with all configured options
+     * and filters, then runs tests either once or in watch mode. Handles missing
+     * dependencies and properly configures the test environment.
      */
     async run() {
         process.env.NODE_ENV = 'test';
@@ -121,13 +151,7 @@ export default class Test extends BaseCommand {
          * Start the test runner in watch mode
          */
         if (this.watch) {
-            const ts = await importTypeScript(this.app);
-            if (!ts) {
-                this.#logMissingDevelopmentDependency('typescript');
-                this.exitCode = 1;
-                return;
-            }
-            await this.testsRunner.runAndWatch(ts, { poll: this.poll || false });
+            await this.testsRunner.runAndWatch({ poll: this.poll || false });
         }
         else {
             await this.testsRunner.run();

package/build/modules/ace/codemods.d.ts

@@ -75,29 +75,101 @@ export declare class Codemods extends EventEmitter {
      */
     getTsMorphProject(): Promise<CodeTransformer['project'] | undefined>;
     /**
-     * Define validations for the environment variables
+     * Define validations for the environment variables in the start/env.ts file.
+     * This method updates the environment validation schema using the assembler.
+     *
+     * @param validations - Validation schema node for environment variables
+     *
+     * @example
+     * ```ts
+     * await codemods.defineEnvValidations({
+     *   NODE_ENV: 'Env.schema.enum(["development", "production", "test"] as const)',
+     *   PORT: 'Env.schema.number()',
+     *   HOST: 'Env.schema.string({ format: "host" })'
+     * })
+     * ```
      */
     defineEnvValidations(validations: EnvValidationNode): Promise<void>;
     /**
-     * Define validations for the environment variables
+     * Register middleware in the start/kernel.ts file.
+     * This method adds middleware to the specified stack (server, router, or named).
+     *
+     * @param stack - The middleware stack to register to ('server' | 'router' | 'named')
+     * @param middleware - Array of middleware nodes to register
+     *
+     * @example
+     * ```ts
+     * await codemods.registerMiddleware('server', [
+     *   {
+     *     name: 'cors',
+     *     path: '@adonisjs/cors/cors_middleware'
+     *   }
+     * ])
+     * ```
      */
     registerMiddleware(stack: 'server' | 'router' | 'named', middleware: MiddlewareNode[]): Promise<void>;
     /**
-     * Register bouncer policies to the list of policies
-     * collection exported from the "app/policies/main.ts"
-     * file.
+     * Register bouncer policies to the list of policies collection exported from
+     * the "app/policies/main.ts" file. This method adds new policy definitions
+     * to the policies export.
+     *
+     * @param policies - Array of policy nodes to register
+     *
+     * @example
+     * ```ts
+     * await codemods.registerPolicies([
+     *   {
+     *     name: 'UserPolicy',
+     *     path: '#policies/user_policy'
+     *   }
+     * ])
+     * ```
      */
     registerPolicies(policies: BouncerPolicyNode[]): Promise<void>;
     /**
-     * Update RCFile
+     * Update the adonisrc.ts file with new configuration settings.
+     * This method allows modification of the AdonisJS runtime configuration.
+     *
+     * @param params - Parameters for updating the RC file (varies based on update type)
+     *
+     * @example
+     * ```ts
+     * await codemods.updateRcFile((rcFile) => {
+     *   rcFile.addCommand('make:custom')
+     *   rcFile.addPreloadFile('#app/events/main')
+     * })
+     * ```
      */
     updateRcFile(...params: Parameters<CodeTransformer['updateRcFile']>): Promise<void>;
     /**
-     * Register a new Vite plugin in the `vite.config.ts` file
+     * Register a new Vite plugin in the vite.config.ts file.
+     * This method adds plugin configuration to the Vite build configuration.
+     *
+     * @param params - Parameters for adding the Vite plugin (varies based on plugin type)
+     *
+     * @example
+     * ```ts
+     * await codemods.registerVitePlugin({
+     *   name: 'vue',
+     *   import: 'import vue from "@vitejs/plugin-vue"',
+     *   options: '()'
+     * })
+     * ```
      */
     registerVitePlugin(...params: Parameters<CodeTransformer['addVitePlugin']>): Promise<void>;
     /**
-     * Register a new Japa plugin in the `tests/bootstrap.ts` file
+     * Register a new Japa plugin in the tests/bootstrap.ts file.
+     * This method adds plugin configuration to the test runner setup.
+     *
+     * @param params - Parameters for adding the Japa plugin (varies based on plugin type)
+     *
+     * @example
+     * ```ts
+     * await codemods.registerJapaPlugin({
+     *   name: 'expect',
+     *   import: 'import { expect } from "@japa/expect"'
+     * })
+     * ```
      */
     registerJapaPlugin(...params: Parameters<CodeTransformer['addJapaPlugin']>): Promise<void>;
     /**
@@ -143,12 +215,19 @@ export declare class Codemods extends EventEmitter {
         skipReason: string;
     }>;
     /**
-     * Install packages using the correct package manager
-     * You can specify version of each package by setting it in the
-     * name like :
+     * Install packages using the detected or specified package manager.
+     * Automatically detects npm, yarn, or pnpm and installs dependencies accordingly.
+     * You can specify version of each package by setting it in the name like '@adonisjs/lucid@next'.
      *
-     * ```
-     * this.installPackages([{ name: '@adonisjs/lucid@next', isDevDependency: false }])
+     * @param packages - Array of packages with their dependency type
+     * @param packageManager - Optional package manager to use (auto-detected if not provided)
+     *
+     * @example
+     * ```ts
+     * const success = await codemods.installPackages([
+     *   { name: '@adonisjs/lucid', isDevDependency: false },
+     *   { name: '@types/node', isDevDependency: true }
+     * ])
      * ```
      */
     installPackages(packages: {
@@ -156,7 +235,23 @@ export declare class Codemods extends EventEmitter {
         isDevDependency: boolean;
     }[], packageManager?: SupportedPackageManager | 'pnpm@6' | 'deno'): Promise<boolean>;
     /**
-     * List the packages one should install before using the packages
+     * List the packages that should be installed manually.
+     * This method displays installation commands for different package managers
+     * when automatic installation is not available or desired.
+     *
+     * @param packages - Array of packages with their dependency type
+     *
+     * @example
+     * ```ts
+     * await codemods.listPackagesToInstall([
+     *   { name: '@adonisjs/lucid', isDevDependency: false },
+     *   { name: '@types/node', isDevDependency: true }
+     * ])
+     * // Output:
+     * // Please install following packages
+     * // npm i -D @types/node
+     * // npm i @adonisjs/lucid
+     * ```
      */
     listPackagesToInstall(packages: {
         name: string;