refactor: delegate mux api CLI to running server via HTTP

Instead of initializing services locally, the api subcommand now
proxies oRPC procedure calls to a running mux server. This avoids
the heavyweight service initialization when using the CLI and
ensures consistent behavior with the server.

Key changes:
- Add proxifyOrpc utility that wraps an oRPC router to forward
  calls via HTTPRPCLink to a remote server
- Lazily import trpc-cli only when api command is invoked
- Remove inline service context creation from CLI entry point
- Enhance Zod 4 schema descriptions for better CLI help output

Author: ThomasK33

src/cli/api.ts

@@ -0,0 +1,24 @@
+/**
+ * API CLI subcommand - delegates to a running mux server via HTTP.
+ *
+ * This module is loaded lazily to avoid pulling in ESM-only dependencies
+ * (trpc-cli) when running other commands like the desktop app.
+ */
+
+import { createCli } from "trpc-cli";
+import { router } from "@/node/orpc/router";
+import { proxifyOrpc } from "./proxifyOrpc";
+import { Command } from "commander";
+
+export async function runApiCli(parent: Command): Promise<void> {
+  const baseUrl = process.env.MUX_SERVER_URL ?? "http://localhost:3000";
+  const authToken = process.env.MUX_AUTH_TOKEN;
+
+  const proxiedRouter = proxifyOrpc(router(), { baseUrl, authToken });
+  const cli = createCli({ router: proxiedRouter }).buildProgram() as Command;
+
+  cli.name("api");
+  cli.description("Interact with the oRPC API via a running server");
+  cli.parent = parent;
+  cli.parse();
+}

src/cli/index.ts

@@ -2,91 +2,51 @@
 
 import { Command } from "commander";
 import { VERSION } from "../version";
-import { createCli } from "trpc-cli";
-import { router } from "@/node/orpc/router";
-import { Config } from "@/node/config";
-import { ServiceContainer } from "@/node/services/serviceContainer";
-import { migrateLegacyMuxHome } from "@/common/constants/paths";
-import type { BrowserWindow } from "electron";
-import type { ORPCContext } from "@/node/orpc/context";
 
-// Minimal BrowserWindow stub for services that expect one (same as server.ts)
-const mockWindow: BrowserWindow = {
-  isDestroyed: () => false,
-  setTitle: () => undefined,
-  webContents: {
-    send: () => undefined,
-    openDevTools: () => undefined,
-  },
-} as unknown as BrowserWindow;
-
-async function createServiceContext(): Promise<ORPCContext> {
-  migrateLegacyMuxHome();
-
-  const config = new Config();
-  const serviceContainer = new ServiceContainer(config);
-  await serviceContainer.initialize();
-  serviceContainer.windowService.setMainWindow(mockWindow);
-
-  return {
-    projectService: serviceContainer.projectService,
-    workspaceService: serviceContainer.workspaceService,
-    providerService: serviceContainer.providerService,
-    terminalService: serviceContainer.terminalService,
-    windowService: serviceContainer.windowService,
-    updateService: serviceContainer.updateService,
-    tokenizerService: serviceContainer.tokenizerService,
-    serverService: serviceContainer.serverService,
-    menuEventService: serviceContainer.menuEventService,
-  };
-}
-
-async function main() {
-  const program = new Command();
-
-  program
-    .name("mux")
-    .description("mux - coder multiplexer")
-    .version(`mux ${VERSION.git_describe} (${VERSION.git_commit})`, "-v, --version");
-
-  program
-    .command("server")
-    .description("Start the HTTP/WebSocket oRPC server")
-    .allowUnknownOption() // server.ts handles its own options via commander
-    .action(() => {
-      // Remove 'server' from args since server.ts has its own commander instance
-      process.argv.splice(2, 1);
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      require("./server");
-    });
-
-  program
-    .command("version")
-    .description("Show version information")
-    .action(() => {
-      console.log(`mux ${VERSION.git_describe} (${VERSION.git_commit})`);
-    });
-
-  // Only initialize services if the 'api' subcommand is being used
-  if (process.argv[2] === "api") {
-    const context = await createServiceContext();
-    program.addCommand(
-      (createCli({ router: router(), context }).buildProgram() as Command)
-        .name("api")
-        .description("Interact with the oRPC API directly")
-    );
-  }
-
-  // Default action: launch desktop app when no subcommand given
-  program.action(() => {
+const program = new Command();
+
+program
+  .name("mux")
+  .description("mux - coder multiplexer")
+  .version(`mux ${VERSION.git_describe} (${VERSION.git_commit})`, "-v, --version");
+
+// Subcommands with their own CLI parsers - disable help interception so --help passes through
+program
+  .command("server")
+  .description("Start the HTTP/WebSocket oRPC server")
+  .helpOption(false)
+  .allowUnknownOption()
+  .allowExcessArguments()
+  .action(() => {
+    process.argv.splice(2, 1);
     // eslint-disable-next-line @typescript-eslint/no-require-imports
-    require("../desktop/main");
+    require("./server");
+  });
+
+program
+  .command("api")
+  .description("Interact with the oRPC API via a running server")
+  .helpOption(false)
+  .allowUnknownOption()
+  .allowExcessArguments()
+  .action(async () => {
+    process.argv.splice(2, 1);
+    // eslint-disable-next-line no-restricted-syntax -- dynamic import needed for ESM-only trpc-cli
+    const { runApiCli } = await import("./api");
+    await runApiCli(program);
   });
 
-  program.parse();
-}
+program
+  .command("version")
+  .description("Show version information")
+  .action(() => {
+    console.log(`mux ${VERSION.git_describe} (${VERSION.git_commit})`);
+  });
 
-main().catch((error) => {
-  console.error("CLI initialization failed:", error);
-  process.exit(1);
+// Default action: launch desktop app when no subcommand given
+program.action(() => {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  require("../desktop/main");
 });
+
+program.parse();