From 8ee8e5e956d046ea296eedcd28c2907ddf8ee3cd Mon Sep 17 00:00:00 2001 From: ek-dyoder Date: Tue, 3 Mar 2026 18:40:54 -0500 Subject: [PATCH] docs: Update contribution guidelines to include README.md review process --- .github/agents/copilot-instructions.md | 12 +- README.md | 188 +++++++++++++++++++++++++ 2 files changed, 199 insertions(+), 1 deletion(-) create mode 100644 README.md diff --git a/.github/agents/copilot-instructions.md b/.github/agents/copilot-instructions.md index 66e940a..1efa940 100644 --- a/.github/agents/copilot-instructions.md +++ b/.github/agents/copilot-instructions.md @@ -176,4 +176,14 @@ After completing any code change, validate in this order: ```powershell .\build.ps1 ``` -4. Report test pass/fail counts and build outcome before considering the task complete. +4. **Update `README.md`** — Review the root `README.md` and update it with any information an admin or end-user would need to know as a result of the changes. This includes but is not limited to: + - New or changed CLI commands, flags, or aliases + - New or changed exit codes + - New dependencies + - Changes to build steps or requirements + - New environment variables or configuration + - Changes to supported platforms + - Changes to the project structure (new packages, renamed files) + - Any new prerequisites or setup steps + - Security-relevant changes (e.g. new permissions required) +5. Report test pass/fail counts and build outcome before considering the task complete. diff --git a/README.md b/README.md new file mode 100644 index 0000000..bf68e47 --- /dev/null +++ b/README.md @@ -0,0 +1,188 @@ +# dns-helper + +A cross-platform CLI tool that resolves hostnames against a specified DNS server and writes the resulting IP-to-hostname mappings into the local hosts file. It manages a clearly delimited block within the hosts file so it can cleanly add and remove only its own entries. + +Built as a single static binary with no runtime dependencies. + +**Copyright (c) 2024 Emberkom LLC** + +## Features + +- Resolve one or more hostnames via a specified DNS server and add them to the system hosts file +- Remove individual hostnames or all managed entries from the hosts file +- Managed block markers ensure only dns-helper's entries are modified — the rest of the hosts file is never touched +- Automatic backup of the hosts file before every write (stored alongside the executable) +- File-based lock prevents concurrent modifications +- Cross-platform: Windows, macOS, and Linux + +## Requirements + +- **Go 1.20** toolchain (this project must not use Go 1.21+ features) +- Administrator / root privileges (required to modify the system hosts file) + +## Installation + +### Build from source + +```powershell +# Clone the repository +git clone +cd dns-helper + +# Build for the current platform +.\build.ps1 + +# Or build optimized release binaries for all platforms +.\build.ps1 -Release -CrossCompile +``` + +The default build output is `build\dns-helper.exe` (Windows). Cross-compiled binaries are named `build\dns-helper--[.exe]`. + +### Release packages + +```powershell +# Build release binaries and create distributable archives +.\build.ps1 -Release -CrossCompile -Package +``` + +Archives are written to `releases\dns-helper---.zip` (Windows) or `.tar.gz` (macOS/Linux). + +## Usage + +> **Note:** dns-helper must be run with elevated privileges (Run as Administrator on Windows, `sudo` on macOS/Linux) because it modifies the system hosts file. + +### Add entries + +Resolve hostnames via a DNS server and add the resulting IP mappings to the hosts file: + +```sh +dns-helper add -host hostname.example.com -server dns.example.com +``` + +Add multiple hostnames at once (comma-separated): + +```sh +dns-helper add -host "host1.example.com,host2.example.com" -server dns.example.com +``` + +Short alias: + +```sh +dns-helper a -host hostname.example.com -server dns.example.com +``` + +### Delete entries + +Remove a specific hostname: + +```sh +dns-helper delete -host hostname.example.com +``` + +Remove multiple hostnames: + +```sh +dns-helper delete -host "host1.example.com,host2.example.com" +``` + +Remove **all** managed entries: + +```sh +dns-helper delete all +``` + +Short aliases: `d`, `del` + +### Command reference + +| Command | Flag | Required | Description | +|---------|------|----------|-------------| +| `add` | `-host` | Yes | Comma-separated hostnames to resolve and add | +| `add` | `-server` | Yes | DNS resolver to query (e.g. `dns.example.com`) | +| `delete` | `-host` | Yes (unless `all`) | Comma-separated hostnames to remove | +| `delete all` | — | — | Removes every entry dns-helper has written | + +### Exit codes + +| Code | Meaning | +|------|---------| +| 0 | Success | +| 1 | Error or partial failure (e.g. one hostname failed to resolve) | + +## How it works + +dns-helper wraps its entries between two marker lines in the hosts file: + +``` +# DNSHelper <<-> START CONFIG +192.0.2.1 hostname.example.com +# DNSHelper <->> END CONFIG +``` + +Only lines within this managed block are ever modified or removed. The rest of the hosts file is preserved exactly as-is. + +Before every write, a backup of the hosts file is saved to the directory containing the dns-helper executable. + +### Hosts file locations + +| Platform | Path | +|----------|------| +| Windows | `%SystemRoot%\System32\drivers\etc\hosts` | +| macOS | `/etc/hosts` | +| Linux | `/etc/hosts` | + +## Project structure + +``` +main.go CLI entry point (add / delete commands, flag parsing) +build.ps1 Build & packaging script +go.mod Module definition (Go 1.20, golang.org/x/net) +hostfile/ + hostfile.go Hosts file parsing, DNSEntry type, add/remove helpers + managed.go Managed block read/write logic + filesystem.go FileSystem interface + OSFileSystem implementation + hostfile_test.go + managed_test.go +lockfile/ + lockfile.go File-based mutex to prevent concurrent modifications + lockfile_test.go +platform/ + platform.go Platform interface — GetHostsFilePath() + platform_windows.go Windows implementation + platform_darwin.go macOS implementation + platform_linux.go Linux implementation + platform_test.go +resolver/ + resolver.go DNS resolution via golang.org/x/net/dns/dnsmessage + resolver_test.go +``` + +## Development + +### Running tests + +```sh +go1.20 test ./... +``` + +### Running tests with coverage + +```sh +go1.20 test -cover ./... +``` + +### Vetting code + +```sh +go1.20 vet ./... +``` + +## Dependencies + +- [`golang.org/x/net`](https://pkg.go.dev/golang.org/x/net) — DNS message parsing (`golang.org/x/net/dns/dnsmessage`) + +No other third-party dependencies. Standard library first. + +## License + +Copyright (c) 2024 Emberkom LLC. All rights reserved.