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
go.mod         # Go module (module name: node-lookup)
go.sum         # dependency checksums
node-lookup    # compiled binary (not committed)

Build

go build -o node-lookup ./...

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

Running the Tool

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

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

Generate the default config file:

./node-lookup config init

Show the active configuration (after all overrides applied):

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