PoC: Automatically document command JSON output schemas

[gonzaloriestra]

Why

Commands that return JSON should expose their result contract in --help without manually duplicating TypeScript definitions in their descriptions.

What

• adds a reusable defineJsonOutputSchema helper backed by Zod
• renders declared schemas as TypeScript interfaces
• makes BaseCommand automatically append those interfaces to command descriptions

Testing

The next PRs add schema contracts for some commands. Running the command help (-h) should show them.

Example:

  With `--json`, the command returns `StoreListResult`, described by these TypeScript types:

  ```ts
  interface StoreListResult {
    stores: StoreListEntry[]
    organization?: StoreListOrganization
    notice?: string
    truncated?: boolean
  }

  interface StoreListEntry {
    id?: string
    store: string
    createdAt: string
    organizationId: string
    organizationName: string
    name?: string
    type?: string
  }

  interface StoreListOrganization {
    id: string
    name: string
  }
  ```

[gonzaloriestra]

• PoC: typed result contract for app:function:info #8288
• PoC: typed result contract for store:execute #8243
• PoC: typed result contract for store:list #8242
• PoC: Automatically document command JSON output schemas #8283 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

packages/cli-kit/dist/public/node/json-output-schema.d.ts

import { ZodTypeAny, type z } from 'zod';
export interface JsonOutputSchema<TSchema extends ZodTypeAny = ZodTypeAny> {
    readonly name: string;
    readonly schema: TSchema;
    readonly definitions: Readonly<Record<string, ZodTypeAny>>;
}
export type InferJsonOutputSchema<TOutputSchema extends JsonOutputSchema> = z.infer<TOutputSchema['schema']>;
interface DefineJsonOutputSchemaOptions<TSchema extends ZodTypeAny> {
    name: string;
    schema: TSchema;
    definitions?: Readonly<Record<string, ZodTypeAny>>;
}
/**
 * Defines the runtime schema and named types for a command's JSON output.
 *
 * @param options - The root schema name, schema, and any named nested schemas.
 * @returns Command metadata that can also be used to infer and validate the output type.
 */
export declare function defineJsonOutputSchema<TSchema extends ZodTypeAny>(options: DefineJsonOutputSchemaOptions<TSchema>): JsonOutputSchema<TSchema>;
/**
 * Renders a command JSON output schema as TypeScript interfaces for help text.
 *
 * @param outputSchema - The command's JSON output schema metadata.
 * @returns TypeScript interfaces describing the command's JSON output.
 */
export declare function renderJsonOutputSchema(outputSchema: JsonOutputSchema): string;
export {};

Existing type declarations

packages/cli-kit/dist/public/node/base-command.d.ts

@@ -1,3 +1,4 @@
+import { type JsonOutputSchema } from './json-output-schema.js';
 import { Command } from '@oclif/core';
 import { OutputFlags, Input, ParserOutput, FlagInput, OutputArgs } from '@oclif/core/parser';
 export type ArgOutput = OutputArgs<any>;
@@ -10,6 +11,8 @@ export interface NonTTYFlagRequirement {
 }
 declare abstract class BaseCommand extends Command {
     static baseFlags: FlagInput<{}>;
+    static descriptionWithMarkdown?: string;
+    static get jsonOutputSchema(): JsonOutputSchema | undefined;
     static nonTTYFlagRequirements(_flags: FlagOutput): NonTTYFlagRequirement[];
     static descriptionWithoutMarkdown(): string | undefined;
     static analyticsNameOverride(): string | undefined;