schema-generate

# schema-generate

Use this skill when you need to generate or regenerate TypeScript type definitions from schema sources.

## Commands

### Generate all inputs
```
s2t generate
```
Runs all configured inputs and writes output files. Exits 0 if all succeed, 1 if any fail.

### Generate specific inputs
```
s2t generate user-schema openapi-spec
```
Runs only the listed input IDs. Useful in CI to regenerate after a schema change.

### Check what would be generated (list)
```
s2t list
```
Shows all inputs with their current status (success/unchanged/error) and output paths.

## s2t.yaml format

```yaml
inputs:
  - id: user-schema
    type: json-schema        # json-schema | openapi | sqlite
    source: schemas/user.json
    output: src/types/user.ts

  - id: openapi-spec
    type: openapi
    source: openapi.yaml
    output: src/types/api.ts

  - id: app-db
    type: sqlite
    source: ./app.db
    output: src/types/db.ts
```

### Input types

- `json-schema` - JSON Schema draft-07 processed via json-schema-to-typescript
- `openapi` - OpenAPI 3.x or Swagger 2.x parsed via @apidevtools/swagger-parser, component schemas converted to TS interfaces
- `sqlite` - SQLite database inspected via PRAGMA table_info; each table becomes a `Db<TableName>` interface

## Output file conventions

- JSON Schema: interfaces use the schema `title` if present, otherwise the definition key
- OpenAPI: schemas section becomes interfaces; path parameter and query parameter types also generated
- SQLite: each table gets a `Db<PascalCase>` interface; columns map INTEGER -> number, TEXT -> string, REAL -> number, BLOB -> Buffer, NULL -> null

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | All inputs generated or unchanged |
| 1 | One or more inputs failed |

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| S2T_PORT | 3500 | Web UI port |
| S2T_WATCH | 0 | Set to 1 to auto-start watch mode |
| S2T_WEB_ENABLED | 1 | Set to 0 to disable web dashboard |

## Web dashboard

Start with web UI:
```
s2t generate          # generates then exits
s2t serve             # starts web dashboard only (port 3500)
```

The web UI at http://localhost:3500 shows all inputs with status badges, output previews, diff views, and generation history.

## Common patterns

### CI - fail if types are out of date
```bash
s2t generate
git diff --exit-code src/types/
```

### After changing a schema file
```bash
s2t generate user-schema
# or let watch mode handle it automatically
```

### Inspect generated output
```bash
cat src/types/user.ts
# or view in web dashboard: http://localhost:3500
```

### View diff between last two runs
```bash
s2t diff user-schema
```