feat(serve): add TLS support with --tls-cert and --tls-key flags

Adds make cert target for self-signed dev certs and development guide.
2026-05-17 14:53:14 -04:00
parent 805467486b
commit dd8878ebcf
4 changed files with 123 additions and 5 deletions
@@ -0,0 +1,87 @@
+# 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