Refactor command loading to be lazy

- Updated `src/commands/index.ts` to make `loadCommand` return a lazy runner that only `require`s and registers the command when executed or explicitly loaded.
- Updated `src/index.ts` to handle lazy loading in the catch-all command handler by traversing the `client` object and loading the matching command before re-parsing arguments.
- Updated `src/bin/cli.ts` to load all commands when no arguments are provided (global help), ensuring the help text is fully populated.
- Added cycle detection to the `loadAll` logic to handle circular references in the `client` object.

Author: google-labs-jules[bot]

src/bin/cli.ts

@@ -110,6 +110,19 @@ export function cli(pkg: any) {
   if (!handlePreviewToggles(args)) {
     // determine if there are any arguments. if not, display help
     if (!args.length) {
+      const seen = new Set();
+      const loadAll = (obj: any) => {
+        if (seen.has(obj)) return;
+        seen.add(obj);
+        for (const [key, value] of Object.entries(obj)) {
+          if (typeof value === "function" && (value as any).load) {
+            (value as any).load();
+          } else if (typeof value === "object" && value !== null && !Array.isArray(value) && key !== "cli") {
+             loadAll(value);
+          }
+        }
+      };
+      loadAll(client);
       client.cli.help();
     } else {
       cmd = client.cli.parse(process.argv);

src/commands/index.ts

@@ -1,20 +1,36 @@
 import * as experiments from "../experiments";
+import { Command } from "../command";
+
 /**
  * Loads all commands for our parser.
  */
 export function load(client: any): any {
   function loadCommand(name: string) {
     const t0 = process.hrtime.bigint();
-    const { command: cmd } = require(`./${name}`);
-    cmd.register(client);
-    const t1 = process.hrtime.bigint();
-    const diffMS = (t1 - t0) / BigInt(1e6);
-    if (diffMS > 75) {
-      // NOTE: logger.debug doesn't work since it's not loaded yet. Comment out below to debug.
-      // console.error(`Loading ${name} took ${diffMS}ms`);
-    }
 
-    return cmd.runner();
+    const load = () => {
+      const { command: cmd } = require(`./${name}`);
+      cmd.register(client);
+      return cmd.runner();
+    };
+
+    const runner = async (...args: any[]) => {
+      const run = load();
+      return run(...args);
+    };
+
+    // Store the load function on the runner so we can trigger it without running.
+    (runner as any).load = () => {
+      const tStart = process.hrtime.bigint();
+      require(`./${name}`).command.register(client);
+      const tEnd = process.hrtime.bigint();
+      const diff = (tEnd - tStart) / BigInt(1e6);
+      if (diff > 75) {
+         // console.error(`Loading ${name} took ${diff}ms`);
+      }
+    };
+
+    return runner;
   }
 
   const t0 = process.hrtime.bigint();

src/index.ts

@@ -75,9 +75,32 @@ const RENAMED_COMMANDS: Record<string, string> = {
 
 // Default handler, this is called when no other command action matches.
 program.action((_, args) => {
+  const cmd = args[0];
+  const keys = cmd.split(":");
+  let obj = client;
+  let hit = true;
+  for (const key of keys) {
+    if (!obj || typeof obj !== "object") {
+      hit = false;
+      break;
+    }
+    const nextKey = Object.keys(obj).find((k) => k.toLowerCase() === key.toLowerCase());
+    if (!nextKey) {
+      hit = false;
+      break;
+    }
+    obj = (obj as any)[nextKey];
+  }
+
+  if (hit && typeof obj === "function" && (obj as any).load) {
+    (obj as any).load();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (client.cli as any).parse(process.argv);
+    return;
+  }
+
   useConsoleLoggers();
 
-  const cmd = args[0];
   logger.error(clc.bold(clc.red("Error:")), clc.bold(cmd), "is not a Firebase command");
 
   if (RENAMED_COMMANDS[cmd]) {