nix-scaffolding

What this skill does

# Nix Project Scaffolding

Create new projects with `flake.nix` and devshell for Python, Rust, or webapp stacks.

## Workflow

1. **Gather basic info:**
   - Project name (used for directory and shell name)
   - Short description (for flake description)
   - Project type: Python / Python+ML / Rust / Webapp

2. **Gather project-specific details:**
   - **Python/Python+ML:** Initial Python dependencies to include (e.g., `pandas`, `pytest`, `fastapi`)
   - **Rust:** Additional system dependencies for `buildInputs` (e.g., `libva`, `glib.dev`)
   - **Webapp:** Any additional tools beyond Node.js + pnpm
   - **All:** Custom shellHook commands, environment variables, or special configurations

3. **Ask for nixpkgs pin:**
   - Ask user which nixpkgs commit to pin in `flake.lock`
   - User may provide a commit hash or reference another project's lock

4. **Create and customize project:**
   - Create project directory
   - Copy appropriate template from `templates/`
   - Replace `{{PROJECT_NAME}}` and `{{PROJECT_DESCRIPTION}}` placeholders
   - **Customize based on gathered details:**
     - Add specified dependencies to packages list
     - Add any custom buildInputs or environment variables
     - Modify shellHook if needed
   - Run `git init`
   - Run `nix flake lock --override-input nixpkgs github:NixOS/nixpkgs/<commit>`

## Templates

| Template | Use when |
|----------|----------|
| `basic-python` | Pure Python projects without ML/CUDA needs |
| `basic-python-ml` | ML/robotics projects needing CUDA and ml-pkgs overlay |
| `basic-rust` | Rust projects (uses crane with full checks) |
| `basic-webapp` | Frontend apps with Node.js + pnpm |
| `pyo3-python` | Python library with Rust backend via PyO3/maturin |
| `esp32` | ESP32 embedded projects with ESP-IDF (C/C++) |

## Template Structure

All templates create:
```
<project>/
  flake.nix           # flake-parts based
  .envrc              # direnv integration (watch_dir nix, use flake)
  nix/
    development.nix   # devShell definition
```

The `pyo3-python` template additionally creates:
```
<project>/
  Cargo.toml          # Rust crate config with pyo3 dependency
  pyproject.toml      # Python project config with maturin build
  nix/
    package.nix       # buildPythonPackage definition
```

The `esp32` template uses flat structure (no nix/ subdirectory):
```
<project>/
  flake.nix           # Re-exports devShells from nixpkgs-esp-dev
  .envrc              # Also sources .envrc.local if exists
  .gitignore          # Ignores build/, sdkconfig, etc.
  CMakeLists.txt      # ESP-IDF project config
  main/
    CMakeLists.txt    # ESP-IDF component config
    main.c            # Entry point with app_main()
```

## Placeholder Reference

| Placeholder | Replace with |
|-------------|--------------|
| `{{PROJECT_NAME}}` | Project name (lowercase, hyphens ok) |
| `{{PROJECT_NAME_UNDERSCORE}}` | Project name with underscores (for Python module names) |
| `{{PROJECT_DESCRIPTION}}` | Short description for flake |

## After Scaffolding

Remind user to:
- Enter the directory and run `direnv allow` (or `nix develop` to verify manually)
- Add project-specific dependencies to `nix/development.nix`
- For Rust: run `cargo init` to create Cargo.toml
- For Webapp: run `pnpm create vite .` or similar to initialize the app
- For PyO3: create `src/lib.rs` with pyo3 module, create `python/<module>/__init__.py`, update hash in `nix/package.nix` after first build
- For ESP32: run `idf.py set-target esp32s3` (or target chip), then `idf.py build` to compile