node-lookup/AGENTS.md

# AGENTS.md

## Project Overview

`node-lookup` is a Go CLI tool that queries a PuppetDB API to retrieve and filter node facts.

## Structure

```
main.go             # entire application source
main_test.go        # unit tests (mock PuppetDB via httptest, no live deps)
go.mod              # Go module (module name: node-lookup)
go.sum              # dependency checksums
Makefile            # build / test / lint / completions / rpm / version-bump targets
packaging/nfpm.yaml # nfpm spec (envsubst-templated) for the RPM
scripts/build-rpm.sh # generates completions + packages the RPM with nfpm
.woodpecker/        # CI: build, test, pre-commit (PR) + release (tag)
dist/               # build output: binary, completions, RPM (not committed)
```

## Build

```bash
make build          # -> dist/node-lookup (CGO disabled, static)
# or directly:
go build -o node-lookup ./...
```

Requires Go 1.21+. Dependencies: `github.com/spf13/cobra` (CLI), `gopkg.in/yaml.v3` (Ansible output).

## Packaging (RPM)

```bash
make rpm            # build the binary + package it into dist/*.rpm via nfpm
```

`scripts/build-rpm.sh` generates bash/zsh/fish completions from the built binary
and bundles them alongside `/usr/bin/node-lookup`. On a `v*` tag the release
pipeline builds the RPM and `PUT`s it to the artifactapi `rpm-internal` repo.

## Shell completions

Cobra provides a `completion` subcommand:

```bash
node-lookup completion bash   # or zsh / fish / powershell
```

The RPM installs completions to the standard system paths
(`/usr/share/bash-completion/completions/`, `/usr/share/zsh/site-functions/`,
`/usr/share/fish/vendor_completions.d/`), so they work automatically once
installed. To load ad-hoc in the current shell, e.g. zsh:
`source <(node-lookup completion zsh)`.

## Running the Tool

```bash
./node-lookup --help
./node-lookup -R                          # show all nodes with role fact
./node-lookup -n <hostname>               # lookup a specific node
./node-lookup -F <fact_name>              # filter by fact name
./node-lookup -m <value>                  # exact value match (-m)
./node-lookup -pm <value>                 # partial/regex match (-p -m combined)
./node-lookup -im <value>                 # inverse exact match (-i -m combined)
./node-lookup -ipm <value>                # inverse partial match (-i -p -m combined)
./node-lookup -R -1                       # node names only
./node-lookup -R -2                       # values only
./node-lookup -R -C                       # count occurrences
./node-lookup -R -A                       # output as Ansible YAML inventory
./node-lookup -j                          # output as JSON { host → { fact → value } }
./node-lookup --url http://host:8080/...  # override PuppetDB URL for this invocation
echo -e "node1\nnode2" | ./node-lookup -R # pipe node names via stdin
```

## Configuration

Precedence (lowest → highest): **defaults < config file < env vars < `--url` flag**

### Config file

XDG location: `$XDG_CONFIG_HOME/node-lookup/config.yaml` (default: `~/.config/node-lookup/config.yaml`)

```yaml
puppetdb_url: http://puppetdbapi.service.consul:8080/pdb/query/v4/facts
role_fact: enc_role
```

Generate the default config file:
```bash
./node-lookup config init
```

Show the active configuration (after all overrides applied):
```bash
./node-lookup config show
```

### Environment variables

| Variable | Config key | Description |
|---|---|---|
| `NODE_LOOKUP_URL` | `puppetdb_url` | PuppetDB facts endpoint |
| `NODE_LOOKUP_ROLE_FACT` | `role_fact` | Fact name used by `-R` flag |

### CLI flag

`--url <url>` overrides the PuppetDB URL for a single invocation (highest precedence).

## Code Patterns

- **`loadConfig()`**: reads config file → applies env vars → returns `config` struct. Called once at startup in `main()`.
- **`buildQuery()`**: returns a PuppetDB PQL-compatible JSON array string. Uses `roleFact` from config (not hardcoded). Match modifiers: `-p` (partial/regex, uses `~` op), `-i` (inverse, wraps with `not`), composable.
- **`queryPuppetDB(url, query)`**: takes the URL as a parameter — never reads globals.
- **`processResults()`**: iterates facts, returns sorted `"certname value"` strings. JSON string values are unquoted; other JSON types rendered as compact JSON.
- **Output modes**: JSON (`-j`), count (`-C`), Ansible YAML (`-A`), node-only (`-1`), value-only (`-2`), default (node + value).
- **Stdin support**: `stdinReader()` reads node names from stdin only when it is a real pipe/redirect carrying data (and no `-n` given). Terminals, `/dev/null`, and empty/closed pipes fall through to a normal query — so running without a TTY (e.g. invoked by an agent or CI) behaves like an interactive run instead of consuming empty input.
- **SIGPIPE handling**: `signal.Ignore(syscall.SIGPIPE)` so pipes to `head` etc. work cleanly.

## CLI Framework

Uses [Cobra](https://github.com/spf13/cobra). Root command is the query command. `config` is a subcommand with `init` and `show` sub-subcommands.

## Testing

```bash
make test           # go test -v -race ./...
```

`main_test.go` covers query construction (all `-m`/`-p`/`-i` combinations), value
rendering, result processing/counting, config precedence (defaults < file < env),
`writeDefaultConfig`, the `stdinReader` no-TTY behavior, and every `run()` output
mode (default, `-1`, `-2`, `-C`, `-j`, `-A`, `-a`). PuppetDB is stubbed with
`httptest` — no live Consul/PuppetDB access is required.

## Gotchas

- `-1`, `-2`, `-C`, and `-A` all require `-R` or `-F`; the tool exits with an error otherwise.
- `-C` (count) with stdin reads all lines as pre-fetched `"node value"` output for counting — it does **not** query PuppetDB per line.
- JSON output (`-j`) builds `{ hostname: { factname: value } }` where the fact key is the `-F` value, the `role_fact` config value (if `-R`), or `"value"` as fallback.
- `config init` fails if the config file already exists (will not overwrite).