# Contributing

Thanks for your interest in ComfyUI-AgeShift! This project follows the same
patterns as the rest of the `aadebuger` ComfyUI node packages.

## Dev setup

```bash
git clone https://github.com/aadebuger/ComfyUI-AgeShift.git
cd ComfyUI-AgeShift

# install into your ComfyUI venv
source /path/to/ComfyUI/.venv/bin/activate
uv pip install -e .
```

Restart ComfyUI; the four nodes should appear under category `🎂 AgeShift`.

## Repo layout

```
ComfyUI-AgeShift/
├── __init__.py              # NODE_CLASS_MAPPINGS / DISPLAY_NAME_MAPPINGS
├── nodes/
│   ├── __init__.py          # empty package marker
│   ├── _types.py            # shared constants + age-feature mapping
│   ├── detector_loader.py   # _MODEL_CACHE pattern
│   ├── detect.py
│   └── prompt_builder.py
├── cli/
│   ├── README.md
│   └── age_shift_cli.py     # ComfyClient + build_workflow + main
└── example_workflows/
    ├── age_detect_only.json
    └── age_shift_pulid_flux.json
```

## Adding a new node

1. Drop a new file in `nodes/yourname.py`. Use this skeleton:

   ```python
   class YourNode:
       @classmethod
       def INPUT_TYPES(cls):
           return {"required": {...}, "optional": {...}}

       RETURN_TYPES = (...)
       RETURN_NAMES = (...)
       FUNCTION = "run"
       CATEGORY = "🎂 AgeShift"

       def run(self, ...):
           return (...)
   ```

2. Register it in the top-level `__init__.py`:

   ```python
   from .nodes.yourname import YourNode
   NODE_CLASS_MAPPINGS["YourNode"] = YourNode
   NODE_DISPLAY_NAME_MAPPINGS["YourNode"] = "🎂 Your Node"
   ```

3. Update `cli/age_shift_cli.py` if the new node should be CLI-driven; add a
   `build_*_workflow()` function.

4. Add an example workflow under `example_workflows/`.

5. Bump `CHANGELOG.md`.

## Coding conventions

- **Lazy-import heavy deps** (torch, transformers, PIL) inside the node method,
  not at module top-level. Keeps ComfyUI startup fast.
- **Use `_MODEL_CACHE` for loaders**, keyed by all input args. Implement
  `IS_CHANGED` to reflect that.
- **Strings, not enums for HF model IDs** — gives users a way to swap in
  alternate models without code edits.
- Category prefix is always `🎂 AgeShift`.
- Display names always start with `🎂` for searchability.

## Pull requests

Small focused PRs preferred. Please include:
- A short description of what changed and why.
- A `CHANGELOG.md` entry under `[Unreleased]`.
- If a new node: an example workflow.

## License

By contributing, you agree your contributions are licensed under MIT.