refactor(cli): improve help output with hierarchical schema descriptions

Enhance the proxifyOrpc schema description system to produce readable,
hierarchical help output for complex Zod schemas. Previously, the CLI
showed raw JSON Schema (anyOf, oneOf) for unions and nested objects.

Key changes:
- Add hierarchical YAML-like formatting for nested objects
- Separate required/optional fields with clear headers
- Handle discriminated unions by showing variant labels
- Detect common discriminators (type/kind/tag) in plain unions
- Replace complex fields with z.any().describe() to prevent trpc-cli
  from appending JSON Schema noise to descriptions
- Convert void/undefined inputs to empty object schema for proper
  JSON Schema conversion
- Preserve _zod property for Zod 4 detection in trpc-cli
- Simplify api.ts by removing function wrapper and module-level init
- Rename "oRPC API" to "mux API" for consistency

Author: ThomasK33

src/cli/api.ts

@@ -8,17 +8,14 @@
 import { createCli } from "trpc-cli";
 import { router } from "@/node/orpc/router";
 import { proxifyOrpc } from "./proxifyOrpc";
-import { Command } from "commander";
+import type { 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 baseUrl = process.env.MUX_SERVER_URL ?? "http://localhost:3000";
+const authToken = process.env.MUX_SERVER_AUTH_TOKEN;
 
-  const proxiedRouter = proxifyOrpc(router(), { baseUrl, authToken });
-  const cli = createCli({ router: proxiedRouter }).buildProgram() as Command;
+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();
-}
+cli.name("mux api");
+cli.description("Interact with the mux API via a running server");
+cli.parse();

src/cli/index.ts

@@ -25,15 +25,14 @@ program
 
 program
   .command("api")
-  .description("Interact with the oRPC API via a running server")
+  .description("Interact with the mux API via a running server")
   .helpOption(false)
   .allowUnknownOption()
   .allowExcessArguments()
-  .action(async () => {
+  .action(() => {
     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);
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    require("./api");
   });
 
 program

src/cli/proxifyOrpc.test.ts

@@ -0,0 +1,194 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import * as zod4Core from "zod/v4/core";
+import { router } from "@/node/orpc/router";
+import { proxifyOrpc } from "./proxifyOrpc";
+
+describe("proxifyOrpc schema enhancement", () => {
+  describe("describeZodType", () => {
+    // Helper to get description from a schema via JSON Schema conversion
+    function getJsonSchemaDescription(schema: z.ZodTypeAny): string | undefined {
+      const jsonSchema = zod4Core.toJSONSchema(schema, {
+        io: "input",
+        unrepresentable: "any",
+        override: (ctx) => {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+          const meta = (ctx.zodSchema as any).meta?.();
+          if (meta) Object.assign(ctx.jsonSchema, meta);
+        },
+      });
+      return jsonSchema.description;
+    }
+
+    test("described object schema has description in JSON Schema", () => {
+      const schema = z.object({ foo: z.string() }).describe("Test description");
+      const desc = getJsonSchemaDescription(schema);
+      expect(desc).toBe("Test description");
+    });
+
+    test("enum values are preserved in JSON Schema", () => {
+      const schema = z.enum(["a", "b", "c"]);
+      const jsonSchema = zod4Core.toJSONSchema(schema, {
+        io: "input",
+        unrepresentable: "any",
+      });
+      expect(jsonSchema.enum).toEqual(["a", "b", "c"]);
+    });
+
+    test("optional fields are marked in JSON Schema", () => {
+      const schema = z.object({
+        required: z.string(),
+        optional: z.string().optional(),
+      });
+      const jsonSchema = zod4Core.toJSONSchema(schema, {
+        io: "input",
+        unrepresentable: "any",
+        override: (ctx) => {
+          if (ctx.zodSchema?.constructor?.name === "ZodOptional") {
+            ctx.jsonSchema.optional = true;
+          }
+        },
+      });
+      expect(jsonSchema.required).toContain("required");
+      expect(jsonSchema.required).not.toContain("optional");
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+      expect((jsonSchema.properties as any)?.optional?.optional).toBe(true);
+    });
+  });
+
+  describe("void schema handling", () => {
+    test("void schema converts to empty JSON Schema object", () => {
+      // In the actual proxifyOrpc, void schemas are converted to z.object({})
+      const emptyObj = z.object({});
+      const jsonSchema = zod4Core.toJSONSchema(emptyObj, {
+        io: "input",
+        unrepresentable: "any",
+      });
+      expect(jsonSchema.type).toBe("object");
+      expect(jsonSchema.properties).toEqual({});
+    });
+  });
+
+  describe("nested object descriptions", () => {
+    test("described nested object preserves description", () => {
+      const nested = z
+        .object({
+          field1: z.string(),
+          field2: z.number(),
+        })
+        .describe("Required: field1: string, field2: number");
+
+      const parent = z.object({
+        nested,
+      });
+
+      const jsonSchema = zod4Core.toJSONSchema(parent, {
+        io: "input",
+        unrepresentable: "any",
+        override: (ctx) => {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+          const meta = (ctx.zodSchema as any).meta?.();
+          if (meta) Object.assign(ctx.jsonSchema, meta);
+        },
+      });
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+      const nestedJsonSchema = (jsonSchema.properties as any)?.nested;
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      expect(nestedJsonSchema?.description).toBe("Required: field1: string, field2: number");
+    });
+  });
+});
+
+describe("proxifyOrpc CLI help output", () => {
+  test("workspace resume-stream shows options description", () => {
+    const r = router();
+    const proxied = proxifyOrpc(r, { baseUrl: "http://localhost:8080" });
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    const resumeStream = (proxied as any).workspace?.resumeStream;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    const inputSchema = resumeStream?.["~orpc"]?.inputSchema;
+
+    // The options field should have a description
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    const optionsField = inputSchema?.def?.shape?.options;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    expect(optionsField?.description).toBeDefined();
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    expect(optionsField?.description).toContain("model: string");
+  });
+
+  test("workspace list has empty object schema (no options)", () => {
+    const r = router();
+    const proxied = proxifyOrpc(r, { baseUrl: "http://localhost:8080" });
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    const listProc = (proxied as any).workspace?.list;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    const inputSchema = listProc?.["~orpc"]?.inputSchema;
+
+    // void input should be converted to empty object
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    expect(inputSchema?.def?.type).toBe("object");
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-argument
+    expect(Object.keys(inputSchema?.def?.shape ?? {})).toHaveLength(0);
+  });
+
+  test("enhanced schema preserves _zod property for JSON Schema conversion", () => {
+    const r = router();
+    const proxied = proxifyOrpc(r, { baseUrl: "http://localhost:8080" });
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    const resumeStream = (proxied as any).workspace?.resumeStream;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    const inputSchema = resumeStream?.["~orpc"]?.inputSchema;
+
+    // Must have _zod for trpc-cli to detect Zod 4
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    expect(inputSchema?._zod).toBeDefined();
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    expect(inputSchema?._zod?.version?.major).toBe(4);
+
+    // _zod.def should have the enhanced shape
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    const zodDefOptions = inputSchema?._zod?.def?.shape?.options;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    expect(zodDefOptions?.description).toBeDefined();
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    expect(zodDefOptions?.description).toContain("model: string");
+  });
+
+  test("JSON Schema for options includes description", () => {
+    const r = router();
+    const proxied = proxifyOrpc(r, { baseUrl: "http://localhost:8080" });
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    const resumeStream = (proxied as any).workspace?.resumeStream;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    const inputSchema = resumeStream?.["~orpc"]?.inputSchema;
+
+    // Convert to JSON Schema (what trpc-cli does)
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+    const jsonSchema = zod4Core.toJSONSchema(inputSchema, {
+      io: "input",
+      unrepresentable: "any",
+      override: (ctx) => {
+        if (ctx.zodSchema?.constructor?.name === "ZodOptional") {
+          ctx.jsonSchema.optional = true;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+        const meta = (ctx.zodSchema as any).meta?.();
+        if (meta) Object.assign(ctx.jsonSchema, meta);
+      },
+    });
+
+    // The options property should have a description
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    const optionsJsonSchema = (jsonSchema.properties as any)?.options;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    expect(optionsJsonSchema?.description).toBeDefined();
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    expect(optionsJsonSchema?.description).toContain("model: string");
+  });
+});