unkinben
e18fa8e4f3
Query PuppetDB for node facts via CLI. Replaces the original Python script. - XDG config (~/.config/node-lookup/config.yaml) with env var overrides - All flags from original tool preserved (-n, -F, -R, -m, --pm, -1, -2, -C, -A, -j) - config init / config show subcommands - Unit tests (23), Makefile, GoReleaser config, pre-commit hooks 💘 Generated with Crush Assisted-by: Claude Sonnet 4.6 via Crush <crush@charm.land>
100 lines
3.8 KiB
Markdown
100 lines
3.8 KiB
Markdown
# 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
|
|
go.mod # Go module (module name: node-lookup)
|
|
go.sum # dependency checksums
|
|
node-lookup # compiled binary (not committed)
|
|
```
|
|
|
|
## Build
|
|
|
|
```bash
|
|
go build -o node-lookup ./...
|
|
```
|
|
|
|
Requires Go 1.21+. Dependencies: `github.com/spf13/cobra` (CLI), `gopkg.in/yaml.v3` (Ansible output).
|
|
|
|
## 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
|
|
./node-lookup --pm <pattern> # partial/regex match on value
|
|
./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).
|
|
- **`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**: when stdin is not a TTY and no `-n` is given, node names are read line-by-line and queried individually (one HTTP request per node).
|
|
- **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
|
|
|
|
No test suite exists. Manual testing requires access to the Consul/PuppetDB environment or a mock HTTP server.
|
|
|
|
## 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).
|