# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

nixos-exporter is a Prometheus exporter for NixOS-specific metrics. It exposes system state information that standard exporters don't cover: generation management, flake input freshness, and upgrade status.

**Status**: Implementation complete.

## Build Commands

Run commands through the Nix development shell using `nix develop -c`:

```bash
# Build
nix develop -c go build ./...

# Run tests
nix develop -c go test ./...

# Run single test
nix develop -c go test -run TestName ./path/to/package

# Lint
nix develop -c golangci-lint run

# Vulnerability check
nix develop -c govulncheck ./...

# Test Nix build
nix build

# Run the binary (prefer this over go build + running binary)
# To pass arguments, use -- before them: nix run .#default -- --help
nix run .#default
```

## Testing Procedures

Before committing, run the following checks:

1. `nix develop -c go test ./...` - Unit tests
2. `nix develop -c golangci-lint run` - Linting
3. `nix develop -c govulncheck ./...` - Vulnerability scanning
4. `nix build` - Verify nix build works

## Architecture

Single binary with pluggable collectors:

```
nixos-exporter/
├── main.go                 # Entry point, HTTP server on :9971
├── collector/
│   ├── generation.go       # Core metrics (count, current, booted, age, mismatch)
│   └── flake.go            # Flake input freshness metrics (optional)
└── config/
    └── config.go           # YAML + CLI flag handling
```

### Collectors

**Generation collector** (always enabled): Reads symlinks in `/nix/var/nix/profiles/` and `/run/current-system` to determine generation state.

**Flake collector** (optional): Parses `flake.lock` JSON to extract `lastModified` timestamps per input.

### Configuration

Supports YAML config file, CLI flags (`--listen`, `--collector.flake`, `--flake.lock-path`), and NixOS module integration via `services.prometheus.exporters.nixos`.

## Commit Message Format

Use conventional commit format:

```
feat: add new feature
fix: fix a bug
docs: update documentation
refactor: refactor code without changing behavior
test: add or update tests
chore: maintenance tasks
```

## Key Design Decisions

- Go chosen for mature Prometheus client library and static binary output
- Port 9971 allocated for this exporter
- Follows nixpkgs `services.prometheus.exporters.*` module pattern
- No root required - only reads symlinks and files