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>

.gitignore

@@ -0,0 +1,2 @@
+node-lookup
+dist/

.goreleaser.yaml

@@ -0,0 +1,38 @@
+version: 2
+
+project_name: node-lookup
+
+before:
+  hooks:
+    - go mod tidy
+    - go test ./...
+
+builds:
+  - env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - darwin
+    goarch:
+      - amd64
+      - arm64
+    binary: node-lookup
+    ldflags:
+      - -s -w -X main.version={{.Version}}
+
+archives:
+  - formats:
+      - tar.gz
+    name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+
+checksum:
+  name_template: "checksums.txt"
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - "^docs:"
+      - "^test:"
+      - "^ci:"
+      - "^chore:"

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+        args: [--fix=lf]
+
+  - repo: https://github.com/dnephin/pre-commit-golang
+    rev: v0.5.1
+    hooks:
+      - id: go-fmt
+      - id: go-vet
+      - id: go-unit-tests

AGENTS.md

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

Makefile

@@ -0,0 +1,21 @@
+BINARY   := node-lookup
+GOFLAGS  := -ldflags="-s -w"
+
+.PHONY: all build test lint clean install
+
+all: build
+
+build:
+	go build $(GOFLAGS) -o $(BINARY) ./...
+
+test:
+	go test -v -race ./...
+
+lint:
+	golangci-lint run ./...
+
+clean:
+	rm -f $(BINARY)
+
+install:
+	go install $(GOFLAGS) ./...

go.mod

@@ -0,0 +1,10 @@
+module node-lookup
+
+go 1.25.7
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/spf13/cobra v1.10.2 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

go.sum

@@ -0,0 +1,12 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

main.go

@@ -0,0 +1,403 @@
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"sort"
+	"strings"
+	"syscall"
+
+	"github.com/spf13/cobra"
+	"gopkg.in/yaml.v3"
+)
+
+const (
+	defaultPuppetDBURL = "http://puppetdbapi.service.consul:8080/pdb/query/v4/facts"
+	defaultRoleFact    = "enc_role"
+	configFileName     = "config.yaml"
+	appName            = "node-lookup"
+)
+
+// config holds all configurable values. Fields map 1:1 to config file keys,
+// env vars (NODE_LOOKUP_*), and (where applicable) CLI flags.
+type config struct {
+	PuppetDBURL string `yaml:"puppetdb_url"`
+	RoleFact    string `yaml:"role_fact"`
+}
+
+func defaultConfig() config {
+	return config{
+		PuppetDBURL: defaultPuppetDBURL,
+		RoleFact:    defaultRoleFact,
+	}
+}
+
+// configDir returns the XDG_CONFIG_HOME/node-lookup directory.
+func configDir() string {
+	base := os.Getenv("XDG_CONFIG_HOME")
+	if base == "" {
+		home, _ := os.UserHomeDir()
+		base = filepath.Join(home, ".config")
+	}
+	return filepath.Join(base, appName)
+}
+
+// configPath returns the full path to the config file.
+func configPath() string {
+	return filepath.Join(configDir(), configFileName)
+}
+
+// loadConfig reads the config file (if present), then applies env var overrides.
+// Precedence (lowest → highest): defaults < config file < env vars < CLI flags.
+func loadConfig() (config, error) {
+	cfg := defaultConfig()
+
+	path := configPath()
+	data, err := os.ReadFile(path)
+	if err != nil && !os.IsNotExist(err) {
+		return cfg, fmt.Errorf("reading config %s: %w", path, err)
+	}
+	if err == nil {
+		if err := yaml.Unmarshal(data, &cfg); err != nil {
+			return cfg, fmt.Errorf("parsing config %s: %w", path, err)
+		}
+	}
+
+	if v := os.Getenv("NODE_LOOKUP_URL"); v != "" {
+		cfg.PuppetDBURL = v
+	}
+	if v := os.Getenv("NODE_LOOKUP_ROLE_FACT"); v != "" {
+		cfg.RoleFact = v
+	}
+
+	return cfg, nil
+}
+
+// writeDefaultConfig creates the config directory and writes a default config file.
+func writeDefaultConfig() error {
+	dir := configDir()
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return fmt.Errorf("creating config dir: %w", err)
+	}
+
+	path := configPath()
+	if _, err := os.Stat(path); err == nil {
+		return fmt.Errorf("config already exists at %s", path)
+	}
+
+	cfg := defaultConfig()
+	data, _ := yaml.Marshal(cfg)
+	header := []byte("# node-lookup configuration\n# Fields can be overridden with env vars: NODE_LOOKUP_URL, NODE_LOOKUP_ROLE_FACT\n\n")
+	if err := os.WriteFile(path, append(header, data...), 0o644); err != nil {
+		return fmt.Errorf("writing config: %w", err)
+	}
+	fmt.Println("Config written to", path)
+	return nil
+}
+
+type fact struct {
+	Certname string          `json:"certname"`
+	Name     string          `json:"name"`
+	Value    json.RawMessage `json:"value"`
+}
+
+func buildQuery(node, factName, match, partialMatch, roleFact string, showRole bool) string {
+	type filter = []interface{}
+	var filters []filter
+
+	if node != "" {
+		filters = append(filters, filter{"=", "certname", node})
+	}
+	if factName != "" {
+		filters = append(filters, filter{"=", "name", factName})
+	} else if showRole {
+		filters = append(filters, filter{"=", "name", roleFact})
+	}
+
+	if match != "" {
+		filters = append(filters, filter{"=", "value", match})
+	} else if partialMatch != "" {
+		filters = append(filters, filter{"~", "value", partialMatch})
+	}
+
+	if len(filters) == 0 {
+		b, _ := json.Marshal([]interface{}{"=", "name", roleFact})
+		return string(b)
+	}
+
+	combined := make([]interface{}, 0, len(filters)+1)
+	combined = append(combined, "and")
+	for _, f := range filters {
+		combined = append(combined, f)
+	}
+	b, _ := json.Marshal(combined)
+	return string(b)
+}
+
+func queryPuppetDB(puppetDBURL, query string) ([]fact, error) {
+	params := url.Values{}
+	params.Set("query", query)
+	resp, err := http.Get(puppetDBURL + "?" + params.Encode())
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(body))
+	}
+
+	var facts []fact
+	if err := json.NewDecoder(resp.Body).Decode(&facts); err != nil {
+		return nil, fmt.Errorf("decode error: %w", err)
+	}
+	return facts, nil
+}
+
+// valueString returns the fact value as a plain string (unquotes JSON strings,
+// leaves numbers/bools/objects/arrays as compact JSON).
+func valueString(raw json.RawMessage) string {
+	var s string
+	if err := json.Unmarshal(raw, &s); err == nil {
+		return s
+	}
+	return string(raw)
+}
+
+func valueAny(raw json.RawMessage) interface{} {
+	var v interface{}
+	json.Unmarshal(raw, &v)
+	return v
+}
+
+func processResults(facts []fact) []string {
+	out := make([]string, 0, len(facts))
+	for _, f := range facts {
+		out = append(out, f.Certname+" "+valueString(f.Value))
+	}
+	sort.Strings(out)
+	return out
+}
+
+func countResults(lines []string) []string {
+	counts := map[string]int{}
+	for _, line := range lines {
+		parts := strings.SplitN(line, " ", 2)
+		val := line
+		if len(parts) == 2 {
+			val = parts[1]
+		}
+		counts[val]++
+	}
+	out := make([]string, 0, len(counts))
+	for val, n := range counts {
+		out = append(out, fmt.Sprintf("%d: %s", n, val))
+	}
+	sort.Strings(out)
+	return out
+}
+
+func isTerminal(f *os.File) bool {
+	fi, err := f.Stat()
+	if err != nil {
+		return false
+	}
+	return (fi.Mode() & os.ModeCharDevice) != 0
+}
+
+func run(cfg config, nodeName, factName, match, partialMatch string, showRole, nodeOnly, valueOnly, count, ansible, jsonMode bool) error {
+	signal.Ignore(syscall.SIGPIPE)
+
+	if (nodeOnly || valueOnly || count || ansible) && !showRole && factName == "" {
+		return fmt.Errorf("-R or -F must be used with -1, -2, -C, or -A")
+	}
+
+	var allFacts []fact
+	var stdinLines []string
+
+	doQuery := func(node string) error {
+		query := buildQuery(node, factName, match, partialMatch, cfg.RoleFact, showRole)
+		facts, err := queryPuppetDB(cfg.PuppetDBURL, query)
+		if err != nil {
+			return err
+		}
+		allFacts = append(allFacts, facts...)
+		return nil
+	}
+
+	if nodeName == "" && !isTerminal(os.Stdin) {
+		scanner := bufio.NewScanner(os.Stdin)
+		if count {
+			for scanner.Scan() {
+				stdinLines = append(stdinLines, scanner.Text())
+			}
+		} else {
+			for scanner.Scan() {
+				fields := strings.Fields(scanner.Text())
+				if len(fields) == 0 {
+					continue
+				}
+				if err := doQuery(fields[0]); err != nil {
+					fmt.Fprintln(os.Stderr, "error:", err)
+				}
+			}
+		}
+	} else {
+		if err := doQuery(nodeName); err != nil {
+			return err
+		}
+	}
+
+	returnData := processResults(allFacts)
+
+	switch {
+	case jsonMode:
+		hostFactMap := map[string]map[string]interface{}{}
+		for _, f := range allFacts {
+			if _, ok := hostFactMap[f.Certname]; !ok {
+				hostFactMap[f.Certname] = map[string]interface{}{}
+			}
+			key := factName
+			if key == "" {
+				if showRole {
+					key = cfg.RoleFact
+				} else {
+					key = "value"
+				}
+			}
+			hostFactMap[f.Certname][key] = valueAny(f.Value)
+		}
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		enc.SetEscapeHTML(false)
+		enc.Encode(hostFactMap)
+
+	case count:
+		values := stdinLines
+		if len(values) == 0 {
+			values = returnData
+		}
+		fmt.Println(strings.Join(countResults(values), "\n"))
+
+	case ansible:
+		hosts := map[string]interface{}{}
+		for _, line := range returnData {
+			host := strings.Fields(line)[0]
+			hosts[host] = map[string]interface{}{}
+		}
+		inventory := map[string]interface{}{
+			"all": map[string]interface{}{"hosts": hosts},
+		}
+		b, _ := yaml.Marshal(inventory)
+		os.Stdout.Write(b)
+
+	case nodeOnly:
+		for _, line := range returnData {
+			fmt.Println(strings.Fields(line)[0])
+		}
+
+	case valueOnly:
+		for _, line := range returnData {
+			parts := strings.SplitN(line, " ", 2)
+			if len(parts) == 2 {
+				fmt.Println(parts[1])
+			}
+		}
+
+	default:
+		fmt.Println(strings.Join(returnData, "\n"))
+	}
+
+	return nil
+}
+
+func main() {
+	cfg, err := loadConfig()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "config error:", err)
+		os.Exit(1)
+	}
+
+	var (
+		nodeName     string
+		factName     string
+		showRole     bool
+		match        string
+		partialMatch string
+		nodeOnly     bool
+		valueOnly    bool
+		count        bool
+		ansible      bool
+		jsonMode     bool
+		puppetDBURL  string
+	)
+
+	rootCmd := &cobra.Command{
+		Use:   appName,
+		Short: "Query PuppetDB for nodes.",
+		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
+			if cmd.Flags().Changed("url") {
+				cfg.PuppetDBURL = puppetDBURL
+			}
+			return nil
+		},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return run(cfg, nodeName, factName, match, partialMatch, showRole, nodeOnly, valueOnly, count, ansible, jsonMode)
+		},
+		SilenceUsage: true,
+	}
+
+	f := rootCmd.Flags()
+	f.StringVarP(&nodeName, "node", "n", "", "Node name")
+	f.StringVarP(&factName, "fact", "F", "", "Fact name")
+	f.BoolVarP(&showRole, "role", "R", false, "Show role fact ("+defaultRoleFact+" by default)")
+	f.StringVarP(&match, "match", "m", "", "Exact value match")
+	f.StringVar(&partialMatch, "pm", "", "Partial match on value")
+	f.BoolVarP(&nodeOnly, "nodeonly", "1", false, "Show only the node name")
+	f.BoolVarP(&valueOnly, "valueonly", "2", false, "Show only the value")
+	f.BoolVarP(&count, "count", "C", false, "Count fact occurrences")
+	f.BoolVarP(&ansible, "ansible", "A", false, "Output as Ansible inventory")
+	f.BoolVarP(&jsonMode, "json", "j", false, "Emit valid JSON for all output")
+	rootCmd.PersistentFlags().StringVar(&puppetDBURL, "url", cfg.PuppetDBURL, "PuppetDB facts URL (overrides config and NODE_LOOKUP_URL)")
+
+	configCmd := &cobra.Command{
+		Use:   "config",
+		Short: "Manage configuration",
+	}
+
+	configInitCmd := &cobra.Command{
+		Use:   "init",
+		Short: "Write a default config file to " + configPath(),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return writeDefaultConfig()
+		},
+		SilenceUsage: true,
+	}
+
+	configShowCmd := &cobra.Command{
+		Use:   "show",
+		Short: "Print the active configuration",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			fmt.Printf("config file : %s\n", configPath())
+			fmt.Printf("puppetdb_url: %s\n", cfg.PuppetDBURL)
+			fmt.Printf("role_fact   : %s\n", cfg.RoleFact)
+			return nil
+		},
+		SilenceUsage: true,
+	}
+
+	configCmd.AddCommand(configInitCmd, configShowCmd)
+	rootCmd.AddCommand(configCmd)
+
+	if err := rootCmd.Execute(); err != nil {
+		os.Exit(1)
+	}
+}

main_test.go

@@ -0,0 +1,323 @@
+package main
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// ---- helpers ----------------------------------------------------------------
+
+func mustMarshal(v interface{}) []byte {
+	b, err := json.Marshal(v)
+	if err != nil {
+		panic(err)
+	}
+	return b
+}
+
+func newTestServer(t *testing.T, facts []fact) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(facts)
+	}))
+}
+
+func rawJSON(v interface{}) json.RawMessage {
+	b, _ := json.Marshal(v)
+	return json.RawMessage(b)
+}
+
+// ---- buildQuery -------------------------------------------------------------
+
+func TestBuildQuery_NoFilters(t *testing.T) {
+	q := buildQuery("", "", "", "", "enc_role", false)
+	if !strings.Contains(q, "enc_role") {
+		t.Fatalf("expected default role query, got %s", q)
+	}
+}
+
+func TestBuildQuery_Node(t *testing.T) {
+	q := buildQuery("host1", "", "", "", "enc_role", false)
+	if !strings.Contains(q, "certname") || !strings.Contains(q, "host1") {
+		t.Fatalf("unexpected query: %s", q)
+	}
+}
+
+func TestBuildQuery_FactAndMatch(t *testing.T) {
+	q := buildQuery("", "region", "syd1", "", "enc_role", false)
+	if !strings.Contains(q, "region") || !strings.Contains(q, "syd1") {
+		t.Fatalf("unexpected query: %s", q)
+	}
+}
+
+func TestBuildQuery_PartialMatch(t *testing.T) {
+	q := buildQuery("", "enc_role", "", "dns", "enc_role", false)
+	if !strings.Contains(q, "~") || !strings.Contains(q, "dns") {
+		t.Fatalf("expected partial match query, got %s", q)
+	}
+}
+
+func TestBuildQuery_ShowRole(t *testing.T) {
+	q := buildQuery("", "", "", "", "my_role_fact", true)
+	if !strings.Contains(q, "my_role_fact") {
+		t.Fatalf("expected role fact in query, got %s", q)
+	}
+}
+
+func TestBuildQuery_CustomRoleFact(t *testing.T) {
+	q := buildQuery("", "", "", "", "custom_role", true)
+	if !strings.Contains(q, "custom_role") {
+		t.Fatalf("expected custom role fact, got %s", q)
+	}
+}
+
+// ---- valueString ------------------------------------------------------------
+
+func TestValueString_String(t *testing.T) {
+	raw := rawJSON("hello")
+	if got := valueString(raw); got != "hello" {
+		t.Fatalf("expected hello, got %s", got)
+	}
+}
+
+func TestValueString_Number(t *testing.T) {
+	raw := rawJSON(42)
+	if got := valueString(raw); got != "42" {
+		t.Fatalf("expected 42, got %s", got)
+	}
+}
+
+func TestValueString_Object(t *testing.T) {
+	raw := json.RawMessage(`{"a":1}`)
+	got := valueString(raw)
+	if got != `{"a":1}` {
+		t.Fatalf("expected compact JSON, got %s", got)
+	}
+}
+
+// ---- processResults ---------------------------------------------------------
+
+func TestProcessResults_Sorted(t *testing.T) {
+	facts := []fact{
+		{Certname: "z-host", Value: rawJSON("val1")},
+		{Certname: "a-host", Value: rawJSON("val2")},
+	}
+	out := processResults(facts)
+	if out[0] != "a-host val2" || out[1] != "z-host val1" {
+		t.Fatalf("unexpected order: %v", out)
+	}
+}
+
+func TestProcessResults_Empty(t *testing.T) {
+	out := processResults(nil)
+	if len(out) != 0 {
+		t.Fatalf("expected empty, got %v", out)
+	}
+}
+
+// ---- countResults -----------------------------------------------------------
+
+func TestCountResults_Basic(t *testing.T) {
+	lines := []string{
+		"host1 syd1",
+		"host2 syd1",
+		"host3 mel1",
+	}
+	out := countResults(lines)
+	found := map[string]bool{}
+	for _, l := range out {
+		found[l] = true
+	}
+	if !found["2: syd1"] {
+		t.Fatalf("expected '2: syd1' in %v", out)
+	}
+	if !found["1: mel1"] {
+		t.Fatalf("expected '1: mel1' in %v", out)
+	}
+}
+
+func TestCountResults_Sorted(t *testing.T) {
+	lines := []string{"h1 z", "h2 a", "h3 a"}
+	out := countResults(lines)
+	// lexicographic sort: "1: z" < "2: a"
+	if out[0] != "1: z" || out[1] != "2: a" {
+		t.Fatalf("unexpected order: %v", out)
+	}
+}
+
+// ---- queryPuppetDB ----------------------------------------------------------
+
+func TestQueryPuppetDB_Success(t *testing.T) {
+	want := []fact{
+		{Certname: "node1", Name: "enc_role", Value: rawJSON("roles::dns")},
+	}
+	srv := newTestServer(t, want)
+	defer srv.Close()
+
+	got, err := queryPuppetDB(srv.URL+"/pdb/query/v4/facts", `["=","name","enc_role"]`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 1 || got[0].Certname != "node1" {
+		t.Fatalf("unexpected result: %v", got)
+	}
+}
+
+func TestQueryPuppetDB_HTTPError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "not found", http.StatusNotFound)
+	}))
+	defer srv.Close()
+
+	_, err := queryPuppetDB(srv.URL+"/pdb/query/v4/facts", `["=","name","enc_role"]`)
+	if err == nil {
+		t.Fatal("expected error for 404")
+	}
+}
+
+func TestQueryPuppetDB_BadJSON(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("not json"))
+	}))
+	defer srv.Close()
+
+	_, err := queryPuppetDB(srv.URL+"/pdb/query/v4/facts", `["=","name","enc_role"]`)
+	if err == nil {
+		t.Fatal("expected decode error")
+	}
+}
+
+func TestQueryPuppetDB_ConnectionRefused(t *testing.T) {
+	_, err := queryPuppetDB("http://127.0.0.1:1/facts", `["=","name","enc_role"]`)
+	if err == nil {
+		t.Fatal("expected connection error")
+	}
+}
+
+// ---- config -----------------------------------------------------------------
+
+func TestLoadConfig_Defaults(t *testing.T) {
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("NODE_LOOKUP_URL", "")
+	t.Setenv("NODE_LOOKUP_ROLE_FACT", "")
+
+	cfg, err := loadConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.PuppetDBURL != defaultPuppetDBURL {
+		t.Fatalf("expected default URL, got %s", cfg.PuppetDBURL)
+	}
+	if cfg.RoleFact != defaultRoleFact {
+		t.Fatalf("expected default role fact, got %s", cfg.RoleFact)
+	}
+}
+
+func TestLoadConfig_EnvOverride(t *testing.T) {
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("NODE_LOOKUP_URL", "http://custom:9090/facts")
+	t.Setenv("NODE_LOOKUP_ROLE_FACT", "my_role")
+
+	cfg, err := loadConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.PuppetDBURL != "http://custom:9090/facts" {
+		t.Fatalf("env override failed: %s", cfg.PuppetDBURL)
+	}
+	if cfg.RoleFact != "my_role" {
+		t.Fatalf("env override failed: %s", cfg.RoleFact)
+	}
+}
+
+func TestLoadConfig_FileOverride(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+	t.Setenv("NODE_LOOKUP_URL", "")
+	t.Setenv("NODE_LOOKUP_ROLE_FACT", "")
+
+	cfgDir := filepath.Join(dir, appName)
+	os.MkdirAll(cfgDir, 0o755)
+	os.WriteFile(filepath.Join(cfgDir, configFileName), []byte("puppetdb_url: http://file:8080/facts\nrole_fact: file_role\n"), 0o644)
+
+	cfg, err := loadConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.PuppetDBURL != "http://file:8080/facts" {
+		t.Fatalf("file override failed: %s", cfg.PuppetDBURL)
+	}
+	if cfg.RoleFact != "file_role" {
+		t.Fatalf("file override failed: %s", cfg.RoleFact)
+	}
+}
+
+func TestLoadConfig_EnvOverridesFile(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+	t.Setenv("NODE_LOOKUP_URL", "http://env:9999/facts")
+	t.Setenv("NODE_LOOKUP_ROLE_FACT", "")
+
+	cfgDir := filepath.Join(dir, appName)
+	os.MkdirAll(cfgDir, 0o755)
+	os.WriteFile(filepath.Join(cfgDir, configFileName), []byte("puppetdb_url: http://file:8080/facts\n"), 0o644)
+
+	cfg, err := loadConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.PuppetDBURL != "http://env:9999/facts" {
+		t.Fatalf("env should beat file, got %s", cfg.PuppetDBURL)
+	}
+}
+
+func TestLoadConfig_InvalidYAML(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+	t.Setenv("NODE_LOOKUP_URL", "")
+	t.Setenv("NODE_LOOKUP_ROLE_FACT", "")
+
+	cfgDir := filepath.Join(dir, appName)
+	os.MkdirAll(cfgDir, 0o755)
+	os.WriteFile(filepath.Join(cfgDir, configFileName), []byte(":\tinvalid: yaml:\n"), 0o644)
+
+	_, err := loadConfig()
+	if err == nil {
+		t.Fatal("expected error for invalid YAML")
+	}
+}
+
+func TestWriteDefaultConfig(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+
+	if err := writeDefaultConfig(); err != nil {
+		t.Fatal(err)
+	}
+
+	path := filepath.Join(dir, appName, configFileName)
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(data), "puppetdb_url") {
+		t.Fatalf("config file missing puppetdb_url: %s", data)
+	}
+}
+
+func TestWriteDefaultConfig_AlreadyExists(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+
+	writeDefaultConfig()
+	err := writeDefaultConfig()
+	if err == nil {
+		t.Fatal("expected error when config already exists")
+	}
+}