@formspec/cli

CLI tool for generating JSON Schema and JSON Forms UI Schema from TypeScript source files.

Installation

npm install -D @formspec/cli
# or
pnpm add -D @formspec/cli

Requirements

Package configuration (package.json):

{
  "type": "module"
}

TypeScript configuration (tsconfig.json):

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

Quick Start

# Generate schemas from a TypeScript class with JSDoc constraints
formspec generate ./src/forms.ts UserForm -o ./generated

# Generate schemas from chain DSL exports
formspec generate ./src/forms.ts -o ./generated

# Also emit Canonical IR alongside schemas
formspec generate ./src/forms.ts UserForm --emit-ir -o ./generated

# Validate without writing files
formspec generate ./src/forms.ts UserForm --validate-only

# Preview output paths without writing files
formspec generate ./src/forms.ts UserForm --dry-run -o ./generated

Commands

generate — Build-time Schema Generation

Generate JSON Schema and UI Schema files from TypeScript source files.

formspec generate <file> [className] [options]

Arguments:

• <file> — Path to TypeScript source file
• [className] — Optional class or type name to analyze

Options:

Examples:

# Generate from a class with JSDoc constraint tags
formspec generate ./src/forms.ts UserForm -o ./generated

# Generate from chain DSL exports (requires compiled JS)
tsc && formspec generate ./src/forms.ts -o ./generated

# Generate schemas and also emit Canonical IR
formspec generate ./src/forms.ts UserForm --emit-ir

# Validate only (no file output)
formspec generate ./src/forms.ts UserForm --validate-only

# Preview class and FormSpec output paths without writing files
formspec generate ./src/forms.ts UserForm --dry-run -o ./generated

JSDoc Constraint Tags

The CLI performs static analysis of TypeScript source files. It reads type information directly from the TypeScript compiler and extracts constraint metadata from JSDoc tags:

class UserRegistration {
  /** @DisplayName Full Name */
  name!: string;

  /** @DisplayName Email Address */
  email!: string;

  /**
   * @DisplayName Age
   * @minimum 18
   * @maximum 120
   */
  age?: number;

  /** @DisplayName Country */
  country!: "us" | "ca" | "uk";
}

formspec generate ./src/user-registration.ts UserRegistration -o ./generated

Supported Tags

Type Inference

The CLI automatically infers JSON Schema types from TypeScript:

Chain DSL Support

The CLI also supports FormSpec chain DSL exports:

// forms.ts
import { formspec, field } from "@formspec/dsl";

export const ContactForm = formspec(
  field.text("name", { label: "Name", required: true }),
  field.text("email", { label: "Email", required: true }),
  field.text("message", { label: "Message" })
);

formspec generate ./src/forms.ts -o ./generated

Method Parameter Analysis

The CLI detects InferSchema<typeof X> or InferFormSchema<typeof X> patterns in method parameters:

import { formspec, field, type InferFormSchema } from "@formspec/dsl";

export const ActivateParams = formspec(
  field.number("amount", { label: "Amount", min: 100 }),
  field.number("installments", { min: 2, max: 12 })
);

class PaymentPlan {
  status!: "active" | "paused" | "canceled";

  activate(params: InferFormSchema<typeof ActivateParams>): boolean {
    // ...
  }
}

Output Structure

The CLI writes JSON Schema plus JSON Forms UI Schema files using the current contract:

generated/
├── ClassName/
│   ├── schema.json
│   ├── ui_schema.json
│   ├── instance_methods/
│   │   └── methodName/
│   │       ├── params.schema.json
│   │       ├── params.ui_schema.json (if FormSpec-based)
│   │       └── return_type.schema.json
│   └── static_methods/
│       └── methodName/
│           └── ...
└── formspecs/
    └── ExportName/
        ├── schema.json
        └── ui_schema.json

Troubleshooting

"Could not load compiled module" Warning

This warning appears when the CLI cannot find a compiled JavaScript version of your TypeScript file. The CLI still works — it uses static TypeScript analysis which doesn't require compiled output.

To suppress the warning, compile your TypeScript first:

tsc
formspec generate ./src/forms.ts MyClass -o ./generated

License

UNLICENSED