feat: add JSONL route formatter for AI agents and improve command descriptions

thetutlage · thetutlage · commit b59a82b2c1b4 · 2026-03-14T21:36:17.000+05:30
Add a new JSONL output format for list:routes that produces one flat JSON
object per line, optimized for machine consumption. Auto-selects JSONL when
running inside an AI agent with no explicit format flag.

Update all command descriptions to include output locations, side effects,
and key flags so AI agents can make better decisions about which command
to use.
diff --git a/commands/add.ts b/commands/add.ts
@@ -33,7 +33,17 @@ export default class Add extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Install and configure one or more packages'
+  static description =
+    'Install and configure one or more AdonisJS packages. Runs npm install followed by the package configure hook'
+
+  static help = [
+    'Use this command instead of manually running npm install + configure separately.',
+    'Accepts shorthand names: "vinejs" for @vinejs/vine, "edge" for edge.js.',
+    '```',
+    '{{ binaryName }} add @adonisjs/lucid',
+    '{{ binaryName }} add @adonisjs/auth @adonisjs/session',
+    '```',
+  ]
   /**
    * Command options configuration
    */
diff --git a/commands/configure.ts b/commands/configure.ts
@@ -36,7 +36,8 @@ export default class Configure extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Configure a package after it has been installed'
+  static description =
+    'Run the configure hook of an already-installed package. Use "add" command instead to both install and configure in one step'
 
   /**
    * Command options configuration.
diff --git a/commands/eject.ts b/commands/eject.ts
@@ -31,7 +31,8 @@ export default class Eject extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Eject scaffolding stubs to your application root'
+  static description =
+    'Copy scaffolding stubs from a package to your application for customization. Stubs are templates used by make:* commands'
 
   /**
    * Path to the stubs directory or a single stub file to eject
diff --git a/commands/env/add.ts b/commands/env/add.ts
@@ -38,7 +38,8 @@ export default class EnvAdd extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Add a new environment variable'
+  static description =
+    'Add a new environment variable to .env, .env.example, and its validation rule to start/env.ts'
 
   /**
    * Command options configuration.
diff --git a/commands/generate_key.ts b/commands/generate_key.ts
@@ -30,7 +30,8 @@ export default class GenerateKey extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Generate a cryptographically secure random application key'
+  static description =
+    'Generate a cryptographically secure APP_KEY and write it to the .env file. Use --show to print without writing'
 
   /**
    * Display the key on the terminal, instead of writing it to .env file
diff --git a/commands/inspect_rcfile.ts b/commands/inspect_rcfile.ts
@@ -28,7 +28,8 @@ export default class InspectRCFile extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Inspect the RC file with its default values'
+  static description =
+    'Display the resolved adonisrc.ts configuration as JSON, including providers, preloads, commands, and meta files'
 
   /**
    * Execute the command to display RC file contents.
diff --git a/commands/list/routes.ts b/commands/list/routes.ts
@@ -36,7 +36,7 @@ export default class ListRoutes extends BaseCommand {
    * The command description
    */
   static description =
-    'List application routes. This command will boot the application in the console environment'
+    'List all registered routes with their HTTP methods, URL patterns, handlers, and middleware'
 
   /**
    * Command options configuration.
@@ -86,6 +86,15 @@ export default class ListRoutes extends BaseCommand {
   @flags.boolean({ description: 'View list of routes as a table' })
   declare table: boolean
 
+  /**
+   * Output routes as JSONL (one JSON object per line), optimized for
+   * machine consumption by AI agents and CLI tools
+   */
+  @flags.boolean({
+    description: 'Get routes as JSONL, one JSON object per line (optimized for AI agents)',
+  })
+  declare jsonl: boolean
+
   /**
    * Execute the command to list application routes.
    * Creates a formatter with the specified filters and outputs routes
@@ -104,6 +113,19 @@ export default class ListRoutes extends BaseCommand {
       }
     )
 
+    /**
+     * Display as JSONL (one JSON object per line).
+     * Auto-selected when running inside an AI agent and no
+     * explicit format flag is provided.
+     */
+    if (this.jsonl || (!this.json && !this.table && this.app.runningInAIAgent)) {
+      const lines = await formatter.formatAsJSONL()
+      for (const line of lines) {
+        this.logger.log(line)
+      }
+      return
+    }
+
     /**
      * Display as JSON
      */
diff --git a/commands/make/command.ts b/commands/make/command.ts
@@ -33,7 +33,7 @@ export default class MakeCommand extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new ace command class'
+  static description = 'Create a new Ace CLI command class in commands/'
 
   /**
    * Name of the command class to create
diff --git a/commands/make/controller.ts b/commands/make/controller.ts
@@ -32,7 +32,8 @@ export default class MakeController extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new HTTP controller class'
+  static description =
+    'Create a new HTTP controller class in app/controllers. Use --resource for CRUD methods or --api for API-only CRUD (no create/edit)'
 
   /**
    * Command options configuration
diff --git a/commands/make/event.ts b/commands/make/event.ts
@@ -32,7 +32,8 @@ export default class MakeEvent extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new event class'
+  static description =
+    'Create a new event class in app/events. Events are dispatched via emitter and handled by listeners'
 
   /**
    * Command options configuration.
diff --git a/commands/make/exception.ts b/commands/make/exception.ts
@@ -32,7 +32,8 @@ export default class MakeException extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new custom exception class'
+  static description =
+    'Create a new custom exception class in app/exceptions with handle and report methods'
 
   /**
    * Command options configuration.
diff --git a/commands/make/listener.ts b/commands/make/listener.ts
@@ -32,7 +32,8 @@ export default class MakeListener extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new event listener class'
+  static description =
+    'Create a new event listener class in app/listeners. Use --event to also generate the event class and bind them together'
 
   /**
    * Command options configuration.
diff --git a/commands/make/middleware.ts b/commands/make/middleware.ts
@@ -35,7 +35,8 @@ export default class MakeMiddleware extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new middleware class for HTTP requests'
+  static description =
+    'Create a new middleware class in app/middleware and register it in start/kernel.ts under the chosen stack (server, router, or named)'
 
   /**
    * Command options configuration
diff --git a/commands/make/preload.ts b/commands/make/preload.ts
@@ -40,7 +40,8 @@ export default class MakePreload extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new preload file inside the start directory'
+  static description =
+    'Create a new preload file in start/ and optionally register it in adonisrc.ts. Preload files run during app boot'
 
   /**
    * Name of the preload file to create
diff --git a/commands/make/provider.ts b/commands/make/provider.ts
@@ -39,7 +39,8 @@ export default class MakeProvider extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new service provider class'
+  static description =
+    'Create a new service provider in providers/ and optionally register it in adonisrc.ts. Providers register IoC container bindings'
 
   /**
    * Name of the service provider to create
diff --git a/commands/make/service.ts b/commands/make/service.ts
@@ -29,7 +29,8 @@ export default class MakeService extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new service class'
+  static description =
+    'Create a new service class in app/services. Services encapsulate reusable business logic outside of controllers'
 
   /**
    * Command options configuration
diff --git a/commands/make/test.ts b/commands/make/test.ts
@@ -31,7 +31,8 @@ export default class MakeTest extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new Japa test file'
+  static description =
+    'Create a new Japa test file in tests/. Use --suite to specify the test suite (unit, functional, etc.)'
 
   /**
    * Name of the test file to create
diff --git a/commands/make/transformer.ts b/commands/make/transformer.ts
@@ -33,7 +33,8 @@ export default class MakeTransformer extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new transformer class'
+  static description =
+    'Create a new transformer class in app/transformers for serializing data in API responses'
 
   /**
    * Command options configuration.
diff --git a/commands/make/validator.ts b/commands/make/validator.ts
@@ -33,7 +33,8 @@ export default class MakeValidator extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new file to define VineJS validators'
+  static description =
+    'Create a new VineJS validator file in app/validators. Use --resource to generate both create and update validation schemas'
 
   /**
    * Command options configuration.
diff --git a/commands/make/view.ts b/commands/make/view.ts
@@ -32,7 +32,7 @@ export default class MakeView extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Create a new Edge.js template file'
+  static description = 'Create a new Edge.js template file in resources/views'
 
   /**
    * Name of the template file to create
diff --git a/commands/repl.ts b/commands/repl.ts
@@ -30,7 +30,8 @@ export default class ReplCommand extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Start a new REPL session'
+  static description =
+    'Start an interactive REPL session with the application booted and IoC container available'
 
   /**
    * Command options configuration.
diff --git a/commands/serve.ts b/commands/serve.ts
@@ -35,7 +35,7 @@ export default class Serve extends BaseCommand {
    * The command description
    */
   static description =
-    'Start the development HTTP server along with the file watcher to perform restarts on file change'
+    'Start the development HTTP server. Use --watch for auto-restart on file change or --hmr for hot module replacement'
 
   /**
    * Help text for the command
diff --git a/commands/test.ts b/commands/test.ts
@@ -38,7 +38,8 @@ export default class Test extends BaseCommand {
   /**
    * The command description
    */
-  static description = 'Run tests along with the file watcher to re-run tests on file change'
+  static description =
+    'Run tests using Japa test runner. Supports filtering by suite, file, tag, and group. Use --watch for re-runs on file change'
 
   /**
    * Command options configuration.
diff --git a/src/cli_formatters/routes_list.ts b/src/cli_formatters/routes_list.ts
@@ -376,6 +376,81 @@ export class RoutesListFormatter {
     })
   }
 
+  /**
+   * Formats middleware info into a compact string representation.
+   * Named middleware with args becomes "name:args", closures use their name as-is.
+   */
+  #formatMiddlewareAsString(middleware: MiddlewareHandlerInfo): string {
+    if (middleware.type === 'named' && middleware.args) {
+      return `${middleware.name}:${middleware.args}`
+    }
+    return middleware.name
+  }
+
+  /**
+   * Formats routes as JSONL (one JSON object per line). Each line is a
+   * self-contained route object with flattened domain, simplified handler,
+   * and middleware as a string array. Optimized for machine consumption
+   * by AI agents and CLI tools.
+   */
+  async formatAsJSONL(): Promise<string[]> {
+    const routes = this.#router.toJSON()
+    const domains = Object.keys(routes)
+    const lines: string[] = []
+
+    for (let domain of domains) {
+      for (let route of routes[domain]) {
+        const serializedRoute = await this.#serializeRoute(route)
+        if (!this.#isAllowedByFilters(serializedRoute)) {
+          continue
+        }
+
+        const handler =
+          serializedRoute.handler.type === 'controller'
+            ? {
+                type: 'controller' as const,
+                module: serializedRoute.handler.moduleNameOrPath,
+                method: serializedRoute.handler.method,
+              }
+            : {
+                type: serializedRoute.handler.name === 'redirectsToRoute'
+                  ? ('redirect' as const)
+                  : ('closure' as const),
+                name: serializedRoute.handler.name,
+                ...(serializedRoute.handler.args ? { args: serializedRoute.handler.args } : {}),
+              }
+
+        const middleware = serializedRoute.middleware.map((m) =>
+          this.#formatMiddlewareAsString(m)
+        )
+
+        for (let method of serializedRoute.methods) {
+          const entry: Record<string, unknown> = {
+            method,
+            pattern: serializedRoute.pattern,
+            handler,
+          }
+
+          if (serializedRoute.name) {
+            entry.name = serializedRoute.name
+          }
+
+          if (domain !== 'root') {
+            entry.domain = domain
+          }
+
+          if (middleware.length > 0) {
+            entry.middleware = middleware
+          }
+
+          lines.push(JSON.stringify(entry))
+        }
+      }
+    }
+
+    return lines
+  }
+
   /**
    * Formats routes as an array of objects. Routes are grouped by
    * domain.
diff --git a/tests/cli_formatters/routes_list.spec.ts b/tests/cli_formatters/routes_list.spec.ts
