# Development Guide

## Prerequisites

- Go 1.24+
- [air](https://github.com/air-verse/air) (live-reload, install: `go install github.com/air-verse/air@latest`)
- OpenSSL (for dev TLS certs)

## Quick Start

```sh
make cert       # one-time: generate self-signed TLS cert
make watch      # start dev server with live-reload (HTTP, port 4444)
```

## Make Targets

### Build

| Target | Description |
|--------|-------------|
| `make build` | Compile production binary (`./nib`) |
| `make dev` | Run dev server from source (HTTP, port 4444) |
| `make watch` | Live-reload dev server via air — auto-rebuilds on save |

### Quality

| Target | Description |
|--------|-------------|
| `make test` | Run all tests |
| `make test-v` | Run all tests with verbose output |
| `make test-cover` | Run tests with per-function coverage report |
| `make lint` | Run vet + format check |
| `make vet` | Static analysis via `go vet` |
| `make fmt` | Auto-format all Go files |
| `make fmt-check` | Check formatting without modifying (CI-friendly) |

### Utility

| Target | Description |
|--------|-------------|
| `make cert` | Generate self-signed dev TLS cert in `certs/` (valid 365 days) |
| `make clean` | Remove build artifacts |
| `make tidy` | Tidy and verify Go module dependencies |
| `make run ARGS="..."` | Build then run with custom args |
| `make help` | List all targets |

## TLS

nib supports TLS via `--tls-cert` and `--tls-key` flags on the `serve` command.

### Dev (self-signed)

```sh
make cert
make run ARGS="serve --tls-cert certs/dev.crt --tls-key certs/dev.key"
```

Serves HTTPS on port 4443. Browser will warn about the self-signed cert — accept once.

This is needed for features that require a secure context (e.g. clipboard API).

### Production

For production, use a reverse proxy (Caddy, nginx) with real certificates in front of nib's HTTP server. Alternatively, pass real cert/key paths directly:

```sh
./nib serve --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem
```

### Port Defaults

| Mode | Default Port |
|------|-------------|
| HTTP | 4444 |
| HTTPS | 4443 |

Override with `--port` or the `NIB_PORT` environment variable.

## Typical Workflow

1. `make cert` — once, generates dev TLS cert
2. `make watch` — start coding, air rebuilds on save
3. Edit code, save, changes appear automatically
4. `make test` — verify nothing broke
5. `make lint` — check formatting and vet
6. Commit and push