# Development Guide

This guide covers setting up the development environment for contributing to the Nogic CLI.

## Prerequisites

- Python 3.11+
- [UV](https://docs.astral.sh/uv/) package manager

### Installing UV

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv
```

## Setup

### 1. Clone the repository

```bash
git clone https://github.com/nogic/cli.git
cd cli
```

### 2. Install dependencies

```bash
uv sync
```

This creates a virtual environment in `.venv/` and installs all dependencies.

### 3. Configure environment

Copy the example environment file:

```bash
cp .env.example .env
```

Edit `.env` with your development settings:

```bash
NOGIC_API_URL=http://localhost:8000
NOGIC_API_KEY=your-dev-api-key
```

## Running the CLI

### Using UV (recommended)

```bash
uv run nogic --help
uv run nogic hello world
```

### Using the virtual environment directly

```bash
source .venv/bin/activate
python -m nogic.main --help
```

### As an editable install

```bash
uv pip install -e .
nogic --help
```

## Project Structure

```
cli/
├── src/nogic/
│   ├── __init__.py          # Package version
│   ├── main.py              # CLI entry point
│   ├── config.py            # Configuration management
│   ├── api/
│   │   └── client.py        # Backend API client
│   ├── commands/
│   │   ├── hello.py         # Demo commands
│   │   ├── login.py         # Authentication
│   │   ├── projects.py      # Project management
│   │   ├── init.py          # Project initialization
│   │   ├── sync.py          # One-time sync
│   │   └── watch.py         # File watcher
│   └── watcher/
│       ├── monitor.py       # Filesystem monitoring
│       ├── storage.py       # SQLite file tracking
│       └── sync.py          # Sync service
├── pyproject.toml           # Package configuration
├── uv.lock                  # Dependency lock file
└── .env.example             # Environment template
```

## Adding a New Command

1. Create a new file in `src/nogic/commands/`:

```python
# src/nogic/commands/mycommand.py
import click

@click.command()
@click.argument("name", default="World")
def mycommand(name: str):
    """Description of my command."""
    click.echo(f"Hello, {name}!")
```

2. Register it in `src/nogic/main.py`:

```python
from nogic.commands import mycommand

cli.add_command(mycommand.mycommand)
```

3. Test the command:

```bash
uv run nogic mycommand --help
```

## Dependencies

### Core Dependencies

| Package | Purpose |
|---------|---------|
| `click` | CLI framework |
| `watchdog` | Filesystem monitoring |
| `httpx` | HTTP client |
| `python-dotenv` | Environment configuration |

### Adding Dependencies

```bash
uv add package-name
```

### Removing Dependencies

```bash
uv remove package-name
```

## Building

### Build a wheel

```bash
uv build
```

Output will be in `dist/`.

### Install from built wheel

```bash
uv pip install dist/nogic-*.whl
```

## Code Style

- Follow PEP 8 guidelines
- Use type hints where possible
- Keep functions focused and small
- Use Click's built-in error handling

## Testing Commands Locally

```bash
# Test login flow
uv run nogic login

# Test project initialization
uv run nogic init /tmp/test-project --name "Test"

# Test file watching
uv run nogic watch /tmp/test-project

# Test sync
uv run nogic sync /tmp/test-project
```

## Debugging

### Enable verbose output

Most commands will print status information. For debugging API calls, check the backend logs.

### Check configuration

```bash
# View global config
cat ~/.nogic/config.json

# View project config
cat .nogic/config.json
```

### Inspect the local database

```bash
sqlite3 .nogic/nogic.db ".tables"
sqlite3 .nogic/nogic.db "SELECT * FROM files LIMIT 10;"
```
