nib-v1/docs/development.md

Development Guide

Prerequisites

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

Quick Start

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)

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:

./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.

Terminal UI

Run the TUI directly from source:

go run . tui

TUI code lives in internal/tui/. No live-reload — restart manually after changes.

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