# Fjson Dart Bean Generator

> Fjson Dart Bean Generator is an Agent Skill for development published in the K3vinb5/unyo-app repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Generate Dart bean classes from JSON and regenerate serialization helpers using the fjson CLI. Use this skill whenever the user needs to create Dart models from API JSON responses, generate @JsonSerializable entity classes, or regenerate .g.dart helper files. Also use when the user mentions FlutterJsonBeanFactory, fjson, json_to_dart, JSON serialization, @JSONField, @JsonSerializable, or needs to add new API response DTOs to the unyo project.

- Skill name: `fjson-dart-bean-generator`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/K3vinb5/unyo-app/blob/HEAD/.agents/skills/fjson-dart-bean-generator/SKILL.md
- Repository: K3vinb5/unyo-app (648 GitHub stars when collected)

## SKILL.md

# fjson CLI — Dart Bean Generator

The fjson CLI generates `@JsonSerializable` Dart entity classes from JSON responses and regenerates `.g.dart` serialization helpers, `json_field.dart`, and `json_convert_content.dart`. It replaces the FlutterJsonBeanFactory IntelliJ plugin for CLI/agent workflows.

The bundled JAR lives inside this skill directory: **`fjson-cli.jar`**. Invoke it as:

```bash
java -jar <path-to-skill>/fjson-cli.jar <command> [options]
```

When running from the unyo project root, the skill is at `.agents/skills/fjson-dart-bean-generator/`:

```bash
java -jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar <command> [options]
```

If you need to rebuild the JAR (rare — only after modifying fjson-cli source):

```bash
cd ../fjson-cli && ./gradlew jar
# Then copy the new JAR into the skill:
cp ../fjson-cli/build/libs/fjson-cli.jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar
```

## Two Commands

| Command | Purpose | When to use |
|---------|---------|-------------|
| `fjson bean` | Create a new entity `.dart` file from JSON | User provides a class name + JSON (string or file) |
| `fjson gen` | Regenerate all `.g.dart` helpers, `json_field.dart`, `json_convert_content.dart` | After adding/modifying any `@JsonSerializable` class |

> **Important**: `fjson bean` **automatically runs** `fjson gen` when invoked inside a Flutter project (one with a `pubspec.yaml`). You do NOT need to run `gen` separately after `bean`.

## `fjson bean` — Generate a new entity from JSON

### Required flags

| Flag | Description | Example |
|------|-------------|---------|
| `--class <Name>` | Root class name (use the API response root name) | `--class MediaResponse` |
| `--json <string>` | Raw JSON string | `--json '{"id":1,"title":"..."}'` |
| `--file <path>` | Path to a `.json` file (alternative to `--json`) | `--file response.json` |

### Optional flags

| Flag | Description | Default | When to use |
|------|-------------|---------|-------------|
| `--output <path>` | Directory for the generated `.dart` file | `./lib` | Direct entity to correct DTO subfolder |
| `--suffix <text>` | Suffix appended to generated class names | `entity` | Leave as default for unyo |
| `--nullable` | Make fields nullable (`Type?`) | off | Rarely needed in unyo |
| `--set-default` | Assign default values to primitive fields | off | **Always use this for unyo DTOs** |
| `--project <path>` | Flutter project root | `.` | Usually not needed from unyo root |

### Typical unyo invocation

```bash
java -jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar bean \
  --class MediaCollectionResponse \
  --json '<paste JSON here>' \
  --output ./lib/core/services/api/dto/anilist/ \
  --set-default
```

Or from a file:

```bash
java -jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar bean \
  --class AnizipEpisodeInfo \
  --file ./response.json \
  --output ./lib/core/services/api/dto/anizip/ \
  --set-default
```

### What gets generated

The command produces a `.dart` file containing:

- A root `@JsonSerializable()` class with `--suffix` appended (e.g., `MediaCollectionResponse` → `MediaCollectionResponseEntity`)
- Nested `@JsonSerializable()` classes for each nested JSON object (e.g., `MediaCollectionResponseDtoPage`)
- `@JSONField(name: 'original_key')` annotations for keys whose Dart naming differs from JSON
- `late` fields with default values (if `--set-default`)
- `fromJson()` factory and `toJson()` method stubs
- `import` of `json_field.dart` and the matching `.g.dart`
- `export` of the matching `.g.dart`

The generated entity **also auto-triggers `fjson gen`**, so the matching `.g.dart`, `json_field.dart`, and `json_convert_content.dart` are all regenerated immediately.

## `fjson gen` — Regenerate all helpers

```bash
java -jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar gen --project .
```

This scans `lib/**/*.dart` for every `@JsonSerializable` class and:

1. Regenerates each `<entity>.g.dart` file in `lib/generated/json/`
2. Rebuilds `lib/generated/json/base/json_field.dart` (annotation definitions)
3. Rebuilds `lib/generated/json/base/json_convert_content.dart` (the `JsonConvert` runtime and `JsonConvertClassCollection` registry with all entity imports)
4. Deletes any stale `.g.dart` files for entities that no longer exist

Run this **after any manual edit** to an entity file (adding/removing/renaming fields).

## Generated File Layout in unyo

```
unyo/
├── lib/core/services/api/dto/
│   └── anilist/
│       └── media_response_entity.dart          ← fjson bean output
└── lib/generated/json/
    ├── media_response_entity.g.dart             ← auto-generated helpers
    ├── media_collection_graphql_entity.g.dart   ← existing
    ├── ...                                      ← all other .g.dart
    └── base/
        ├── json_field.dart                     ← annotations
        └── json_convert_content.dart            ← registry + runtime
```

### Entity file naming convention in unyo

- **Snake_case filenames**: e.g., `media_details_graphql_entity.dart`
- **PascalCase class names**: e.g., `MediaDetailsGraphqlEntity`
- fjson converts PascalCase `--class` names to snake_case filenames automatically
- Always place entities in the correct DTO subfolder: `lib/core/services/api/dto/<provider>/`
  - Providers: `anilist/`, `anizip/`, `aniskip/`, `extensions/`

### Default unyo settings that fjson matches

- `--set-default` is always used → all fields get `= ''`, `= 0`, `= false`, etc.
- `--suffix entity` (default) → class names end with `Entity`
- `flutter_json.generated_path` is `generated/json` in `pubspec.yaml`

## Workflow: Adding a new API response model

1. **Get the JSON** — Either from the user, from a file, or from a GraphQL response
2. **Determine the provider** (anilist, anizip, aniskip, extensions)
3. **Run `fjson bean`** with `--class`, `--json/--file`, `--output`, and `--set-default`:
   ```bash
   java -jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar bean \
     --class NewApiResponse \
     --json '<the JSON>' \
     --output ./lib/core/services/api/dto/anilist/ \
     --set-default
   ```
4. **Verify the output** — Open the generated `.dart` file and check:
   - Class names and field types are correct
   - Nested objects are properly generated as sub-classes
   - `@JSONField(name: ...)` mappings are correct for non-matching keys
5. **Update `json_convert_content.dart`** — Already done automatically by `fjson gen` (triggered by `fjson bean`). Verify the new entity's import is present.
6. **Run analysis** — `flutter analyze` to ensure no issues
7. **If fields need adjustment** — Edit the entity file directly, then re-run `fjson gen`:
   ```bash
   java -jar .agents/skills/fjson-dart-bean-generator/fjson-cli.jar gen --project .
   ```

## Common Pitfalls

- **Wrong `--output` path**: Entity files must go to the correct provider subfolder (`lib/core/services/api/dto/<provider>/`) for the import in `json_convert_content.dart` and `.g.dart` files to resolve correctly.
- **Forgetting `--set-default`**: Without it, fields use `late` without defaults. In unyo, all DTO fields have defaults (except `dynamic`).
- **Running in wrong directory**: Commands assume the current working directory is the unyo project root (where `pubspec.yaml` lives). The `--project` flag overrides this.
- **Class name collision**: If a class name already exists in another entity file, the generated `.g.dart` will have duplicate function names, causing compile errors. Check for existing names before running.
- **JSON with empty arrays**: fjson handles this but cannot infer the element type of an empty `List`. The field will be typed `List<dynamic>` and must be corrected manually.
- **After running `bean` in a non-Flutter directory**: `fjson gen` is skipped. You must manually run it from the project root.

## Cross-references

- **unyo project structure and entity patterns**: See `unyo-domain-data-layer` skill
- **DTO conventions and GraphQL response mapping**: See `unyo-domain-data-layer` skill
- **Rebuilding fjson-cli from source**: See `../fjson-cli/README.md`

---

Source: https://www.openparable.com/skill/development/fjson-dart-bean-generator (OpenParable). Cite the canonical URL above.
