@adonisjs/assembler 8.0.0-next.30 → 8.0.0-next.31

package/README.md

@@ -420,6 +420,266 @@ export const policies = {
 }
 ```
 
+### addValidator
+Create a new validator file or add a validator to an existing file. If the file does not exist, it will be created with the provided contents. If it exists and the export name is not already defined, the validator will be appended to the file.
+
+> [!IMPORTANT]
+> This codemod respects the `validators` directory configured in `adonisrc.ts` and defaults to `app/validators`.
+
+```ts
+const transformer = new CodeTransformer(appRoot)
+
+try {
+  await transformer.addValidator({
+    validatorFileName: 'user.ts',
+    exportName: 'loginValidator',
+    contents: `export const loginValidator = vine.compile(
+  vine.object({
+    email: vine.string().email(),
+    password: vine.string().minLength(8)
+  })
+)`
+  })
+} catch (error) {
+  console.error('Unable to add validator')
+  console.error(error)
+}
+```
+
+Output (app/validators/user.ts)
+
+```ts
+export const loginValidator = vine.compile(
+  vine.object({
+    email: vine.string().email(),
+    password: vine.string().minLength(8)
+  })
+)
+```
+
+### addLimiter
+Create a new rate limiter file or add a limiter to an existing file. If the file does not exist, it will be created with the provided contents. If it exists and the export name is not already defined, the limiter will be appended to the file.
+
+> [!IMPORTANT]
+> Limiters are created in the `start` directory configured in `adonisrc.ts` and defaults to `start`.
+
+```ts
+const transformer = new CodeTransformer(appRoot)
+
+try {
+  await transformer.addLimiter({
+    limiterFileName: 'limiters.ts',
+    exportName: 'apiThrottle',
+    contents: `export const apiThrottle = limiter.define('api', () => {
+  return limiter.allowRequests(10).every('1 minute')
+})`
+  })
+} catch (error) {
+  console.error('Unable to add limiter')
+  console.error(error)
+}
+```
+
+Output (start/limiters.ts)
+
+```ts
+export const apiThrottle = limiter.define('api', () => {
+  return limiter.allowRequests(10).every('1 minute')
+})
+```
+
+### addModelMixins
+Apply one or more mixins to a model class. This wraps the model's extends clause with the `compose` helper and applies the specified mixins.
+
+> [!IMPORTANT]
+> This codemod expects the model file to exist with a default exported class that extends a base class.
+
+```ts
+const transformer = new CodeTransformer(appRoot)
+
+try {
+  await transformer.addModelMixins('user.ts', [
+    {
+      name: 'SoftDeletes',
+      importPath: '@adonisjs/lucid/orm/mixins/soft_deletes',
+      importType: 'named'
+    },
+    {
+      name: 'Sluggable',
+      importPath: '#mixins/sluggable',
+      importType: 'default',
+      args: ['title', '{ strategy: "dbIncrement" }']
+    }
+  ])
+} catch (error) {
+  console.error('Unable to add mixins to model')
+  console.error(error)
+}
+```
+
+Input (app/models/user.ts)
+
+```ts
+import { BaseModel } from '@adonisjs/lucid/orm'
+
+export default class User extends BaseModel {
+  // ...
+}
+```
+
+Output (app/models/user.ts)
+
+```ts
+import { BaseModel } from '@adonisjs/lucid/orm'
+import { compose } from '@adonisjs/core/helpers'
+import { SoftDeletes } from '@adonisjs/lucid/orm/mixins/soft_deletes'
+import Sluggable from '#mixins/sluggable'
+
+export default class User extends compose(BaseModel, SoftDeletes(), Sluggable(title, { strategy: "dbIncrement" })) {
+  // ...
+}
+```
+
+### addControllerMethod
+Create a new controller file or add a method to an existing controller class. If the controller file does not exist, it will be created with the class and method. If it exists and the method is not already defined, the method will be added to the class.
+
+> [!IMPORTANT]
+> This codemod respects the `controllers` directory configured in `adonisrc.ts` and defaults to `app/controllers`.
+
+```ts
+const transformer = new CodeTransformer(appRoot)
+
+try {
+  await transformer.addControllerMethod({
+    controllerFileName: 'users_controller.ts',
+    className: 'UsersController',
+    name: 'destroy',
+    contents: `async destroy({ params, response }: HttpContext) {
+  const user = await User.findOrFail(params.id)
+  await user.delete()
+  return response.noContent()
+}`,
+    imports: [
+      { isType: false, isNamed: true, name: 'HttpContext', path: '@adonisjs/core/http' },
+      { isType: false, isNamed: false, name: 'User', path: '#models/user' }
+    ]
+  })
+} catch (error) {
+  console.error('Unable to add controller method')
+  console.error(error)
+}
+```
+
+Output (app/controllers/users_controller.ts)
+
+```ts
+import type { HttpContext } from '@adonisjs/core/http'
+import User from '#models/user'
+
+export default class UsersController {
+  async destroy({ params, response }: HttpContext) {
+    const user = await User.findOrFail(params.id)
+    await user.delete()
+    return response.noContent()
+  }
+}
+```
+
+### RcFileTransformer additional methods
+
+The `RcFileTransformer` class (accessible via `updateRcFile` callback) now supports additional methods for managing imports and hooks.
+
+#### addNamedImport
+Add a named import to the `adonisrc.ts` file.
+
+```ts
+const transformer = new CodeTransformer(appRoot)
+
+try {
+  await transformer.updateRcFile((rcFile) => {
+    rcFile.addNamedImport('@adonisjs/core/types', ['Middleware', 'Provider'])
+  })
+} catch (error) {
+  console.error('Unable to add named import')
+  console.error(error)
+}
+```
+
+Output
+
+```ts
+import { defineConfig } from '@adonisjs/core/app'
+import { Middleware, Provider } from '@adonisjs/core/types'
+
+export default defineConfig({
+  // ...
+})
+```
+
+#### addDefaultImport
+Add a default import to the `adonisrc.ts` file.
+
+```ts
+const transformer = new CodeTransformer(appRoot)
+
+try {
+  await transformer.updateRcFile((rcFile) => {
+    rcFile.addDefaultImport('#config/database', 'databaseConfig')
+  })
+} catch (error) {
+  console.error('Unable to add default import')
+  console.error(error)
+}
+```
+
+Output
+
+```ts
+import { defineConfig } from '@adonisjs/core/app'
+import databaseConfig from '#config/database'
+
+export default defineConfig({
+  // ...
+})
+```
+
+#### addAssemblerHook
+Add assembler hooks to the `adonisrc.ts` file. Hooks can be added as thunk imports (lazy loaded) or as raw values for direct import references.
+
+```ts
+const transformer = new CodeTransformer(appRoot)
+
+try {
+  await transformer.updateRcFile((rcFile) => {
+    // Add a thunk-style hook (lazy import)
+    rcFile.addAssemblerHook('onBuildStarting', './commands/build_hook.js')
+
+    // Add a raw hook (direct import reference)
+    rcFile.addAssemblerHook('onBuildCompleted', 'buildCompletedHook', true)
+  })
+} catch (error) {
+  console.error('Unable to add assembler hook')
+  console.error(error)
+}
+```
+
+Output
+
+```ts
+import { defineConfig } from '@adonisjs/core/app'
+
+export default defineConfig({
+  hooks: {
+    onBuildStarting: [
+      () => import('./commands/build_hook.js')
+    ],
+    onBuildCompleted: [
+      buildCompletedHook
+    ]
+  }
+})
+```
+
 ## Index generator
 
 The `IndexGenerator` is a core concept in Assembler that is used to watch the filesystem and create barrel files or types from a source directory.

package/build/src/bundler.d.ts

@@ -28,6 +28,7 @@ export declare class Bundler {
         logger: import("@poppinss/cliui").Logger;
         table: (tableOptions?: Partial<import("@poppinss/cliui/types").TableOptions>) => import("@poppinss/cliui").Table;
         tasks: (tasksOptions?: Partial<import("@poppinss/cliui/types").TaskManagerOptions>) => import("@poppinss/cliui").TaskManager;
+        steps: () => import("@poppinss/cliui").Steps;
         icons: {
             tick: string;
             cross: string;
@@ -37,6 +38,7 @@ export declare class Bundler {
             info: string;
             warning: string;
             squareSmallFilled: string;
+            borderVertical: string;
         };
         sticker: () => import("@poppinss/cliui").Instructions;
         instructions: () => import("@poppinss/cliui").Instructions;

package/build/src/code_scanners/routes_scanner/main.d.ts

@@ -27,6 +27,7 @@ export declare class RoutesScanner {
         logger: import("@poppinss/cliui").Logger;
         table: (tableOptions?: Partial<import("@poppinss/cliui/types").TableOptions>) => import("@poppinss/cliui").Table;
         tasks: (tasksOptions?: Partial<import("@poppinss/cliui/types").TaskManagerOptions>) => import("@poppinss/cliui").TaskManager;
+        steps: () => import("@poppinss/cliui").Steps;
         icons: {
             tick: string;
             cross: string;
@@ -36,6 +37,7 @@ export declare class RoutesScanner {
             info: string;
             warning: string;
             squareSmallFilled: string;
+            borderVertical: string;
         };
         sticker: () => import("@poppinss/cliui").Instructions;
         instructions: () => import("@poppinss/cliui").Instructions;

package/build/src/code_transformer/main.d.ts

@@ -1,7 +1,7 @@
 import { installPackage, detectPackageManager } from '@antfu/install-pkg';
 import { Project } from 'ts-morph';
 import { RcFileTransformer } from './rc_file_transformer.ts';
-import type { MiddlewareNode, EnvValidationNode, BouncerPolicyNode } from '../types/code_transformer.ts';
+import type { MiddlewareNode, EnvValidationNode, BouncerPolicyNode, ValidatorNode, LimiterNode, MixinDefinition, ControllerMethodNode } from '../types/code_transformer.ts';
 /**
  * This class is responsible for transforming AdonisJS project code,
  * including updating middleware, environment validations, and other
@@ -100,4 +100,8 @@ export declare class CodeTransformer {
      * @param policies - Array of bouncer policy entries to add
      */
     addPolicies(policies: BouncerPolicyNode[]): Promise<void>;
+    addValidator(definition: ValidatorNode): Promise<void>;
+    addLimiter(definition: LimiterNode): Promise<void>;
+    addModelMixins(modelFileName: string, mixins: MixinDefinition[]): Promise<void>;
+    addControllerMethod(definition: ControllerMethodNode): Promise<void>;
 }

package/build/src/code_transformer/main.js

@@ -1,6 +1,7 @@
 import { t as CodemodException } from "../../codemod_exception-vyN1VXuX.js";
 import { fileURLToPath } from "node:url";
 import { detectPackageManager, installPackage } from "@antfu/install-pkg";
+import { ImportsBag } from "@poppinss/utils";
 import { join } from "node:path";
 import { Node, Project, QuoteKind, SyntaxKind } from "ts-morph";
 const ALLOWED_ENVIRONMENTS = [
@@ -221,7 +222,10 @@ var CodeTransformer = class {
 		return {
 			start: rcFileTransformer.getDirectory("start", "start"),
 			tests: rcFileTransformer.getDirectory("tests", "tests"),
-			policies: rcFileTransformer.getDirectory("policies", "app/policies")
+			policies: rcFileTransformer.getDirectory("policies", "app/policies"),
+			validators: rcFileTransformer.getDirectory("validators", "app/validators"),
+			models: rcFileTransformer.getDirectory("models", "app/models"),
+			controllers: rcFileTransformer.getDirectory("controllers", "app/controllers")
 		};
 	}
 	#addToMiddlewareArray(file, target, middlewareEntry) {
@@ -252,9 +256,8 @@ var CodeTransformer = class {
 		}
 	}
 	#addImportDeclarations(file, importDeclarations) {
-		const existingImports = file.getImportDeclarations();
 		importDeclarations.forEach((importDeclaration) => {
-			const existingImport = existingImports.find((mod) => mod.getModuleSpecifierValue() === importDeclaration.module);
+			const existingImport = file.getImportDeclarations().find((mod) => mod.getModuleSpecifierValue() === importDeclaration.module);
 			if (existingImport && importDeclaration.isNamed) {
 				if (!existingImport.getNamedImports().find((namedImport) => namedImport.getName() === importDeclaration.identifier)) existingImport.addNamedImport(importDeclaration.identifier);
 				return;
@@ -266,6 +269,24 @@ var CodeTransformer = class {
 			});
 		});
 	}
+	#addImportsFromImportInfo(file, imports) {
+		const importsBag = new ImportsBag();
+		for (const importInfo of imports) importsBag.add(importInfo);
+		const importDeclarations = importsBag.toArray().flatMap((moduleImport) => {
+			return (moduleImport.namedImports ?? []).map((symbol) => {
+				return {
+					isNamed: true,
+					module: moduleImport.source,
+					identifier: symbol
+				};
+			}).concat(moduleImport.defaultImport ? [{
+				isNamed: false,
+				module: moduleImport.source,
+				identifier: moduleImport.defaultImport
+			}] : []);
+		});
+		this.#addImportDeclarations(file, importDeclarations);
+	}
 	#addLeadingComment(writer, comment) {
 		if (!comment) return writer.blankLine();
 		return writer.blankLine().writeLine("/*").writeLine(`|----------------------------------------------------------`).writeLine(`| ${comment}`).writeLine(`|----------------------------------------------------------`).writeLine(`*/`);
@@ -363,5 +384,131 @@ var CodeTransformer = class {
 		file.formatText(this.#editorSettings);
 		await file.save();
 	}
+	async addValidator(definition) {
+		const filePath = `${this.getDirectories().validators}/${definition.validatorFileName}`;
+		const validatorFileUrl = join(this.#cwdPath, `./${filePath}`);
+		let file = this.project.getSourceFile(validatorFileUrl);
+		if (!file) try {
+			file = this.project.addSourceFileAtPath(validatorFileUrl);
+		} catch {}
+		if (!file) {
+			file = this.project.createSourceFile(validatorFileUrl, definition.contents);
+			file.formatText(this.#editorSettings);
+			await file.save();
+			return;
+		}
+		if (file.getVariableDeclaration(definition.exportName)) return;
+		file.addStatements(`\n${definition.contents}`);
+		file.formatText(this.#editorSettings);
+		await file.save();
+	}
+	async addLimiter(definition) {
+		const filePath = `${this.getDirectories().start}/${definition.limiterFileName}`;
+		const limiterFileUrl = join(this.#cwdPath, `./${filePath}`);
+		let file = this.project.getSourceFile(limiterFileUrl);
+		if (!file) try {
+			file = this.project.addSourceFileAtPath(limiterFileUrl);
+		} catch {}
+		if (!file) {
+			file = this.project.createSourceFile(limiterFileUrl, definition.contents);
+			file.formatText(this.#editorSettings);
+			await file.save();
+			return;
+		}
+		if (file.getVariableDeclaration(definition.exportName)) return;
+		file.addStatements(`\n${definition.contents}`);
+		file.formatText(this.#editorSettings);
+		await file.save();
+	}
+	async addModelMixins(modelFileName, mixins) {
+		const filePath = `${this.getDirectories().models}/${modelFileName}`;
+		const modelFileUrl = join(this.#cwdPath, `./${filePath}`);
+		let file = this.project.getSourceFile(modelFileUrl);
+		if (!file) try {
+			file = this.project.addSourceFileAtPath(modelFileUrl);
+		} catch {
+			throw new Error(`Could not find source file at path: "${filePath}"`);
+		}
+		const defaultExportSymbol = file.getDefaultExportSymbol();
+		if (!defaultExportSymbol) throw new Error(`Could not find default export in "${filePath}". The model must have a default export class.`);
+		const declarations = defaultExportSymbol.getDeclarations();
+		if (declarations.length === 0) throw new Error(`Could not find default export declaration in "${filePath}".`);
+		const declaration = declarations[0];
+		if (!Node.isClassDeclaration(declaration)) throw new Error(`Default export in "${filePath}" is not a class. The model must be exported as a class.`);
+		const mixinImports = mixins.map((mixin) => {
+			if (mixin.importType === "named") return {
+				source: mixin.importPath,
+				namedImports: [mixin.name]
+			};
+			else return {
+				source: mixin.importPath,
+				defaultImport: mixin.name
+			};
+		});
+		this.#addImportsFromImportInfo(file, mixinImports);
+		const heritageClause = declaration.getHeritageClauseByKind(SyntaxKind.ExtendsKeyword);
+		if (!heritageClause) throw new Error(`Could not find extends clause in "${filePath}".`);
+		const extendsExpression = heritageClause.getTypeNodes()[0];
+		if (!extendsExpression) throw new Error(`Could not find extends expression in "${filePath}".`);
+		const extendsExpressionNode = extendsExpression.getExpression();
+		let composeCall;
+		if (Node.isCallExpression(extendsExpressionNode)) {
+			if (extendsExpressionNode.getExpression().getText() === "compose") composeCall = extendsExpressionNode;
+		}
+		const mixinCalls = mixins.map((mixin) => {
+			const args = mixin.args && mixin.args.length > 0 ? mixin.args.join(", ") : "";
+			return `${mixin.name}(${args})`;
+		});
+		if (composeCall && Node.isCallExpression(composeCall)) {
+			const existingArgsText = composeCall.getArguments().map((arg) => arg.getText());
+			const newMixinCalls = mixinCalls.filter((mixinCall) => {
+				const mixinFunctionName = mixinCall.split("(")[0];
+				return !existingArgsText.some((existingArg) => {
+					return existingArg.includes(`${mixinFunctionName}(`);
+				});
+			});
+			const newArgs = [...existingArgsText, ...newMixinCalls];
+			composeCall.replaceWithText(`compose(${newArgs.join(", ")})`);
+		} else {
+			this.#addImportDeclarations(file, [{
+				isNamed: true,
+				module: "@adonisjs/core/helpers",
+				identifier: "compose"
+			}]);
+			const newExtends = `compose(${extendsExpressionNode.getText()}, ${mixinCalls.join(", ")})`;
+			extendsExpression.replaceWithText(newExtends);
+		}
+		file.formatText(this.#editorSettings);
+		await file.save();
+	}
+	async addControllerMethod(definition) {
+		const filePath = `${this.getDirectories().controllers}/${definition.controllerFileName}`;
+		const controllerFileUrl = join(this.#cwdPath, `./${filePath}`);
+		let file = this.project.getSourceFile(controllerFileUrl);
+		if (!file) try {
+			file = this.project.addSourceFileAtPath(controllerFileUrl);
+		} catch {}
+		if (!file) {
+			const contents = `export default class ${definition.className} {
+  ${definition.contents}
+}`;
+			file = this.project.createSourceFile(controllerFileUrl, contents);
+			if (definition.imports) this.#addImportsFromImportInfo(file, definition.imports);
+			file.formatText(this.#editorSettings);
+			await file.save();
+			return;
+		}
+		const defaultExportSymbol = file.getDefaultExportSymbol();
+		if (!defaultExportSymbol) throw new Error(`Could not find default export in "${filePath}". The controller must have a default export class.`);
+		const declarations = defaultExportSymbol.getDeclarations();
+		if (declarations.length === 0) throw new Error(`Could not find default export declaration in "${filePath}".`);
+		const declaration = declarations[0];
+		if (!Node.isClassDeclaration(declaration)) throw new Error(`Default export in "${filePath}" is not a class. The controller must be exported as a class.`);
+		if (declaration.getMethod(definition.name)) return;
+		if (definition.imports) this.#addImportsFromImportInfo(file, definition.imports);
+		declaration.addMember(definition.contents);
+		file.formatText(this.#editorSettings);
+		await file.save();
+	}
 };
 export { CodeTransformer };

package/build/src/dev_server.d.ts

@@ -25,6 +25,7 @@ export declare class DevServer {
         logger: import("@poppinss/cliui").Logger;
         table: (tableOptions?: Partial<import("@poppinss/cliui/types").TableOptions>) => import("@poppinss/cliui").Table;
         tasks: (tasksOptions?: Partial<import("@poppinss/cliui/types").TaskManagerOptions>) => import("@poppinss/cliui").TaskManager;
+        steps: () => import("@poppinss/cliui").Steps;
         icons: {
             tick: string;
             cross: string;
@@ -34,6 +35,7 @@ export declare class DevServer {
             info: string;
             warning: string;
             squareSmallFilled: string;
+            borderVertical: string;
         };
         sticker: () => import("@poppinss/cliui").Instructions;
         instructions: () => import("@poppinss/cliui").Instructions;

package/build/src/test_runner.d.ts

@@ -32,6 +32,7 @@ export declare class TestRunner {
         logger: import("@poppinss/cliui").Logger;
         table: (tableOptions?: Partial<import("@poppinss/cliui/types").TableOptions>) => import("@poppinss/cliui").Table;
         tasks: (tasksOptions?: Partial<import("@poppinss/cliui/types").TaskManagerOptions>) => import("@poppinss/cliui").TaskManager;
+        steps: () => import("@poppinss/cliui").Steps;
         icons: {
             tick: string;
             cross: string;
@@ -41,6 +42,7 @@ export declare class TestRunner {
             info: string;
             warning: string;
             squareSmallFilled: string;
+            borderVertical: string;
         };
         sticker: () => import("@poppinss/cliui").Instructions;
         instructions: () => import("@poppinss/cliui").Instructions;

package/build/src/types/code_transformer.d.ts

@@ -1,3 +1,4 @@
+import { type ImportInfo } from '@poppinss/utils';
 /**
  * Entry to add a middleware to a given middleware stack via the CodeTransformer.
  * Represents middleware configuration for server, router, or named middleware stacks.
@@ -90,12 +91,130 @@ export type EnvValidationNode = {
      */
     variables: Record<string, string>;
 };
+/**
+ * Configuration for creating a new validator file via CodeTransformer.
+ * Represents the structure needed to generate validator files.
+ *
+ * @example
+ * const validator: ValidatorNode = {
+ *   validatorFileName: 'create_user',
+ *   exportName: 'createUserValidator',
+ *   contents: 'export const createUserValidator = vine.compile(...)'
+ * }
+ */
+export type ValidatorNode = {
+    /** The filename for the validator (without extension) */
+    validatorFileName: string;
+    /** The name of the exported validator constant or function */
+    exportName: string;
+    /** The complete file contents including the validator definition */
+    contents: string;
+};
+/**
+ * Configuration for creating a new rate limiter file via CodeTransformer.
+ * Represents the structure needed to generate limiter files.
+ *
+ * @example
+ * const limiter: LimiterNode = {
+ *   limiterFileName: 'api_throttle',
+ *   exportName: 'apiThrottleLimiter',
+ *   contents: 'export const apiThrottleLimiter = limiter.define(...)'
+ * }
+ */
+export type LimiterNode = {
+    /** The filename for the limiter (without extension) */
+    limiterFileName: string;
+    /** The name of the exported limiter constant or function */
+    exportName: string;
+    /** The complete file contents including the limiter definition */
+    contents: string;
+};
+/**
+ * Definition for applying a mixin to a model class.
+ * Mixins extend model functionality by adding methods, properties, or behaviors.
+ *
+ * @example
+ * const mixin: MixinDefinition = {
+ *   name: 'SoftDeletes',
+ *   importPath: '@adonisjs/lucid/mixins/soft_deletes',
+ *   importType: 'named'
+ * }
+ *
+ * @example
+ * const mixinWithArgs: MixinDefinition = {
+ *   name: 'Sluggable',
+ *   args: ['title', '{ strategy: "dbIncrement" }'],
+ *   importPath: '#mixins/sluggable',
+ *   importType: 'default'
+ * }
+ */
+export type MixinDefinition = {
+    /** The name of the mixin function or class */
+    name: string;
+    /** Optional arguments to pass to the mixin function */
+    args?: string[];
+    /** The import path to the mixin module */
+    importPath: string;
+    /** Whether the mixin is exported as named or default export */
+    importType: 'named' | 'default';
+};
+/**
+ * Configuration for adding a new method to an existing controller class.
+ * Used by CodeTransformer to inject methods into controller files.
+ *
+ * @example
+ * const method: ControllerMethodNode = {
+ *   controllerFileName: 'users_controller',
+ *   className: 'UsersController',
+ *   name: 'destroy',
+ *   contents: 'async destroy({ params, response }: HttpContext) { ... }',
+ *   imports: [
+ *     { isType: false, isNamed: true, name: 'HttpContext', path: '@adonisjs/core/http' }
+ *   ]
+ * }
+ */
+export type ControllerMethodNode = {
+    /** The controller filename (without extension) */
+    controllerFileName: string;
+    /** The name of the controller class */
+    className: string;
+    /** The name of the method to add */
+    name: string;
+    /** The complete method implementation including signature and body */
+    contents: string;
+    /** Optional imports needed by the method */
+    imports?: ImportInfo[];
+};
+/**
+ * Configuration for adding hooks to adonisrc.ts file.
+ * Hooks can be defined as thunks (lazy imports) or direct imports.
+ *
+ * @example
+ * // Thunk style (lazy import)
+ * const thunkHook: HookNode = {
+ *   type: 'thunk',
+ *   path: './commands/migrate.js'
+ * }
+ *
+ * @example
+ * // Import style with named export
+ * const importHook: HookNode = {
+ *   type: 'import',
+ *   path: '#hooks/after_build',
+ *   name: 'afterBuildHook'
+ * }
+ */
 export type HookNode = {
+    /** Hook type: thunk creates a lazy import function */
     type: 'thunk';
+    /** Path to the hook module */
     path: string;
 } | {
+    /** Hook type: import directly imports the hook */
     type: 'import';
+    /** Path to the hook module */
     path: string;
+    /** Optional name of the exported hook (for named exports) */
     name?: string;
 };
 /**

package/build/src/types/common.d.ts

@@ -345,26 +345,91 @@ export interface ShortcutsManagerOptions {
     /** Callback functions for different shortcut actions */
     callbacks: KeyboardShortcutsCallbacks;
 }
+/**
+ * Message sent from the dev server child process to the parent when the server is ready.
+ * Used for IPC communication to notify when the AdonisJS HTTP server has started.
+ *
+ * @example
+ * const message: AdonisJSServerReadyMessage = {
+ *   isAdonisJS: true,
+ *   environment: 'web',
+ *   port: 3333,
+ *   host: 'localhost',
+ *   duration: [0, 150000000] // [seconds, nanoseconds]
+ * }
+ */
 export type AdonisJSServerReadyMessage = {
+    /** Marker to identify AdonisJS-specific messages */
     isAdonisJS: true;
+    /** The environment type (always 'web' for HTTP servers) */
     environment: 'web';
+    /** The port number the server is listening on */
     port: number;
+    /** The host address the server is bound to */
     host: string;
+    /** Optional server startup duration as [seconds, nanoseconds] tuple */
     duration?: [number, number];
 };
+/**
+ * Message sent from the dev server child process when routes are committed.
+ * Contains the file location where routes are defined.
+ *
+ * @example
+ * const message: AdonisJSRoutesSharedMessage = {
+ *   isAdonisJS: true,
+ *   routesFileLocation: '/project/start/routes.ts'
+ * }
+ */
 export type AdonisJSRoutesSharedMessage = {
+    /** Marker to identify AdonisJS-specific messages */
     isAdonisJS: true;
+    /** Absolute path to the routes definition file */
     routesFileLocation: string;
 };
+/**
+ * Messages sent by the hot-hook module for HMR (Hot Module Replacement) communication.
+ * These messages notify the dev server about file system changes and module invalidations.
+ *
+ * @example
+ * // Full reload required
+ * const fullReload: HotHookMessage = {
+ *   type: 'hot-hook:full-reload',
+ *   path: 'app/middleware/auth.ts',
+ *   shouldBeReloadable: false
+ * }
+ *
+ * @example
+ * // Modules invalidated (can be hot-reloaded)
+ * const invalidated: HotHookMessage = {
+ *   type: 'hot-hook:invalidated',
+ *   paths: ['app/controllers/users_controller.ts', 'app/models/user.ts']
+ * }
+ *
+ * @example
+ * // File changed notification
+ * const fileChanged: HotHookMessage = {
+ *   type: 'hot-hook:file-changed',
+ *   path: 'config/database.ts',
+ *   action: 'change'
+ * }
+ */
 export type HotHookMessage = {
+    /** Message type indicating a full server reload is required */
     type: 'hot-hook:full-reload';
+    /** Path to the file that triggered the full reload */
     path: string;
+    /** Whether the file should be hot-reloadable but isn't */
     shouldBeReloadable?: boolean;
 } | {
+    /** Message type indicating modules have been invalidated */
     type: 'hot-hook:invalidated';
+    /** Array of module paths that were invalidated */
     paths: string[];
 } | {
+    /** Message type indicating a file has changed */
     type: 'hot-hook:file-changed';
+    /** Path to the file that changed */
     path: string;
+    /** The type of file system change */
     action: 'change' | 'add' | 'unlink';
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adonisjs/assembler",
   "description": "Provides utilities to run AdonisJS development server and build project for production",
-  "version": "8.0.0-next.30",
+  "version": "8.0.0-next.31",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -42,11 +42,11 @@
     "@adonisjs/tsconfig": "^2.0.0-next.3",
     "@japa/assert": "^4.2.0",
     "@japa/file-system": "^3.0.0",
-    "@japa/runner": "^5.0.0",
+    "@japa/runner": "^5.3.0",
     "@japa/snapshot": "^2.0.10",
-    "@poppinss/ts-exec": "^1.4.1",
+    "@poppinss/ts-exec": "^1.4.2",
     "@release-it/conventional-changelog": "^10.0.4",
-    "@types/node": "^25.0.5",
+    "@types/node": "^25.0.10",
     "@types/picomatch": "^4.0.2",
     "@types/pretty-hrtime": "^1.0.3",
     "c8": "^10.1.3",
@@ -54,17 +54,17 @@
     "del-cli": "^7.0.0",
     "eslint": "^9.39.2",
     "hot-hook": "^0.4.1-next.2",
-    "p-event": "^7.0.2",
-    "prettier": "^3.7.4",
-    "release-it": "^19.2.3",
+    "p-event": "^7.1.0",
+    "prettier": "^3.8.1",
+    "release-it": "^19.2.4",
     "tsdown": "^0.19.0",
-    "typedoc": "^0.28.15",
+    "typedoc": "^0.28.16",
     "typescript": "^5.9.3"
   },
   "dependencies": {
     "@adonisjs/env": "^7.0.0-next.3",
     "@antfu/install-pkg": "^1.1.0",
-    "@ast-grep/napi": "^0.40.4",
+    "@ast-grep/napi": "^0.40.5",
     "@poppinss/cliui": "^6.6.0",
     "@poppinss/hooks": "^7.3.0",
     "@poppinss/utils": "^7.0.0-next.5",