Initial commit: Go rewrite of node-lookup

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>
2026-03-21 23:26:19 +11:00
commit e18fa8e4f3
9 changed files with 925 additions and 0 deletions
@@ -0,0 +1,99 @@
+# 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).