type-watch

# type-watch

Use this skill to keep generated TypeScript types in sync with schema files during development using watch mode.

## Starting watch mode

```
s2t watch
```
Watches all source files listed in s2t.yaml. Regenerates the corresponding output when any source changes. Press Ctrl+C to stop.

### Watch specific inputs only
```
s2t watch user-schema app-db
```

### Watch with web dashboard disabled
```
s2t watch --no-web
```

## How watch mode works

1. s2t reads s2t.yaml and resolves all source file paths
2. chokidar watches each source file for change events
3. When a change is detected, s2t debounces for 200ms (waits for burst saves to settle)
4. s2t runs the generator for that input only
5. If the output is identical to the previous run, status is "unchanged" and no file is written
6. SSE event is pushed to the web dashboard showing the result

## Output format during watch

```
[15:52:00.001] watching 3 inputs for changes...
[15:52:14.200] change detected: schemas/user.json
[15:52:14.400] generating user-schema...
[15:52:14.423] user-schema -> src/types/user.ts (23ms)  +3 lines
```

- Timestamps are local time
- Duration shown in milliseconds
- Line delta shown as "+N lines" or "-N lines" or "unchanged"

## Auto-watch on start

Set the environment variable to always start watch mode:
```bash
S2T_WATCH=1 s2t
```
Or set in your shell profile/dotenv for the project.

## Web dashboard in watch mode

When watching, the web UI at http://localhost:3500 shows:
- A pulsing green "watching" badge in the header
- Live event feed with change detections and generation results
- Input rows update in real time (status badge flickers to "generating" then resolves)
- A "Stop watch" button to exit watch mode from the browser

## Integration with editors

Watch mode plays well with any editor that saves files on change. No editor plugin needed.

### VS Code - save on focus loss
In `.vscode/settings.json`:
```json
{
  "files.autoSave": "onFocusChange"
}
```

### Shell alias for development
```bash
alias dev="pnpm dev & s2t watch"
```

## Debounce behavior

The 200ms debounce means:
- If a schema file is saved multiple times in rapid succession (e.g. format-on-save + your edit), only one generation run fires
- Each distinct source file triggers its own independent debounce timer

## Handling errors in watch mode

If generation fails for an input, s2t:
1. Prints the error to stdout with full detail
2. Updates the input's status to "error" in the web dashboard
3. Continues watching - the next save will retry automatically

Watch mode never exits on error. Fix the schema and save to trigger a retry.

## Stopping watch mode

- Keyboard: Ctrl+C
- Web UI: click "Stop watch" button
- Signal: SIGTERM or SIGINT

On stop, s2t writes a summary line:
```
watch stopped - 14 changes detected, 12 generated, 2 unchanged
```