vario-cli

name

vario-cli

description

Expert knowledge for @variojs/cli — the command-line toolchain for the Vario Schema-First UI system. Covers three commands: `vario dev` (file watching with Node.js native fs.watch, auto-validation, auto-codegen pipeline), `vario generate/gen` (Schema→TypeScript code generation: types.ts with inferred state types, schema.ts export), and `vario validate` (Schema validation using @variojs/schema's validateSchemaWithResult). Also covers the programmatic API: startDevServer, generateCode, validateFiles, and their option types. Use this skill whenever the user is working with vario-cli, the vario command, schema file watching, code generation from Vario schema, schema validation, dev server setup, CI pipeline integration, or any @variojs/cli API. Also trigger when user mentions Vario CLI, vario dev, vario gen, vario validate, or wants to set up a Vario development workflow.

Vario-CLI Skill

Expert guide for @variojs/cli — the command-line toolchain for Vario (Schema-First UI Behavior Runtime).

Overview

@variojs/cli
  ├── vario dev       — File watching + auto-validate + codegen pipeline
  ├── vario generate  — Schema → TypeScript code generation
  └── vario validate  — Schema file validation

Dependencies: commander (CLI parsing), @variojs/schema (validation), @variojs/core, @variojs/vue.

Source: packages/vario-cli/src/ — index.ts (CLI entry), dev-server.ts, codegen.ts, validate.ts.

Binary: bin/vario.mjs → #!/usr/bin/env node shebang wrapper.

---

Commands

vario dev — Development Server

Watches schema files and automatically validates + generates code on changes.

vario dev                          # Watch current dir, output to ./generated
vario dev -d ./schemas             # Watch specific directory
vario dev -d ./schemas -o ./types  # Custom output directory

Options:

Flag	Default	Description
-d, --dir <dir>	.	Directory to watch
-o, --output <output>	./generated	Code generation output directory

Behavior:

1. Scans directory for .json, .schema.ts, .schema.js files
2. Validates all found schemas on startup
3. Starts fs.watch() with recursive mode (Node.js native, no chokidar)
4. On file change: 50ms debounce → validate → codegen (if valid JSON)
5. Graceful shutdown on SIGINT/SIGTERM

Programmatic API:

import { startDevServer } from '@variojs/cli'

const server = startDevServer({
  watchDir: './schemas',
  output: './generated'
})

// Later:
server.stop()  // Closes all watchers

interface DevServerOptions {
  port?: number
  host?: string
  open?: boolean
  watchDir?: string
  output?: string
  extensions?: string[]
}

interface ActiveServer {
  watchers: FSWatcher[]
  stop: () => void
}

---

vario generate (alias: gen) — Code Generation

Generates TypeScript files from a Vario schema JSON file.

vario generate --schema ./form.json                      # Output to ./generated
vario gen -t default -o ./types --schema ./form.json     # Custom template & output

Options:

Flag	Default	Description
-t, --template <template>	—	Template name
-o, --output <output>	./generated	Output directory
--schema <schema>	—	Path to schema JSON file

Generated files:

1. types.ts — TypeScript State interface with inferred types:

// Auto-generated by @variojs/cli
export interface State {
  count: number;
  name: string;
  items: unknown[];
  active: boolean;
}

2. schema.ts — Schema constant export:

// Auto-generated by @variojs/cli
export const schema = { /* parsed JSON */ } as const

Type inference logic (inferTsType):

JS Value	Inferred TS Type
null	null
string	string
number	number
boolean	boolean
[1, 2, 3]	number[]
["a", "b"]	string[]
[]	unknown[]
{}	unknown

Programmatic API:

import { generateCode } from '@variojs/cli'

generateCode({
  schema: './form.json',
  output: './types',
  template: 'default'
})

---

vario validate — Schema Validation

Validates schema files using @variojs/schema's validateSchemaWithResult.

vario validate schema1.json schema2.json    # Validate multiple files
vario validate ./schemas/*.json             # Glob pattern

Arguments: One or more file paths (only .json files are processed).

Exit codes: 0 = all valid, 1 = validation failures.

Output:

Validating 3 file(s)...
  ✓ schema1.json
  ✗ schema2.json
    - Schema node must have a non-empty "type" field
  ✓ schema3.json

✗ 1 file(s) failed validation

Programmatic API:

import { validateFiles } from '@variojs/cli'

const result = validateFiles(['schema1.json', 'schema2.json'])
// result.valid: boolean
// result.fileResults: Array<{ file, valid, errors: string[] }>

import type { ValidationOptions } from '@variojs/schema'
export type ValidateOptions = ValidationOptions
// Available options: validateExpressions, validatePaths, customValidators, maxDepth

interface ValidateResult {
  valid: boolean
  fileResults: Array<{
    file: string
    valid: boolean
    errors: string[]
  }>
}

---

CI / Pipeline Integration

{
  "scripts": {
    "dev": "vario dev -d ./schemas",
    "generate": "vario gen --schema ./schema.json -o ./src/generated",
    "validate": "vario validate ./schemas/*.json",
    "ci:check": "vario validate ./schemas/*.json && pnpm test"
  }
}

---

Key Constraints

• ESM-only package ("type": "module")
• Node.js native fs.watch for file monitoring (no chokidar dependency)
• Build: tsup, es2022, output to dist/
• Tests: packages/vario-cli/__tests__/ (6 tests), Vitest