# Strudel Development Environment

A Nix-based development setup for [Strudel](https://strudel.cc/), a JavaScript-based live coding environment for algorithmic music composition and performance, inspired by TidalCycles.

## Overview

This repository provides a reproducible development environment for Strudel using Nix and includes the Strudel codebase as a git submodule. It includes:

- **Nix Flake**: Reproducible development environment with Node.js 20, pnpm, and git
- **Makefile**: Convenient shortcuts for common development tasks
- **Git Submodule**: Tracks the official Strudel repository in the `src/` directory
- **Agent Guidelines**: Comprehensive guidelines for AI assistants working with Strudel

## Prerequisites

- [Nix](https://nixos.org/download.html) package manager (version 2.4+ recommended)
- Git

## Quick Start

1. **Clone this repository**:
   ```bash
   git clone <this-repo-url>
   cd strudel
   ```

2. **Initialize and update submodules**:
   ```bash
   make submodules-init submodules-update
   ```

3. **Enter the development environment**:
   ```bash
   make shell
   # or directly: nix develop
   ```

4. **Install dependencies**:
   ```bash
   make install
   ```

5. **Start the development server**:
   ```bash
   make dev
   ```

The Strudel REPL should now be available at `http://localhost:5173` (or similar, check the output).

## Project Structure

```
strudel/
├── src/                    # Strudel codebase (git submodule)
├── AGENTS.md              # Guidelines for AI assistants
├── Makefile               # Development shortcuts
├── flake.nix              # Nix development environment
├── flake.lock             # Nix flake lockfile
└── README.md              # This file
```

## Development Workflow

### Using Makefile (Recommended)

The Makefile provides shortcuts for all common tasks:

```bash
make help              # Show all available targets
make update            # Initialize and update git submodules
make install           # Install dependencies
make dev               # Start development server
make build             # Build the project
make test              # Run tests
make lint              # Run linter
make format            # Format code
make check             # Run all checks
make clean             # Clean build artifacts
make shell             # Enter Nix development shell
```

### Direct Commands

If you prefer direct commands, all operations run within the Nix environment:

```bash
# Enter shell
nix develop

# Install dependencies
pnpm install

# Start dev server
pnpm dev

# Run tests
pnpm test

# etc.
```

## Contributing

- Follow the guidelines in `AGENTS.md` for AI-assisted development
- Use lowercase commit messages
- Ensure all changes pass `make check`
- Test your changes thoroughly

## License

The Strudel codebase in `src/` is licensed under the terms in `src/LICENSE`. This development environment setup is provided as-is for Strudel development.

## Resources

- [Strudel Official Website](https://strudel.cc/)
- [Strudel Workshop](https://strudel.cc/workshop/)
- [Strudel Git Repository](https://codeberg.org/uzu/strudel.git)
- [NixOS](https://nixos.org/)

## Troubleshooting

- **Submodule issues**: Run `make update` to ensure the submodule is properly initialized
- **Dependency issues**: Try `make clean && make install` to reinstall dependencies
- **Nix issues**: Ensure Nix is installed and up-to-date

For more help, refer to the [Strudel documentation](https://strudel.cc/) or check the `AGENTS.md` guidelines.</content>