📖 Add generated README

Author: guettli

.github/workflows/ci.yml

@@ -34,6 +34,11 @@ jobs:
           go mod tidy
           git diff --exit-code -- go.mod go.sum
 
+      - name: Verify generated README
+        run: |
+          go generate ./...
+          git diff --exit-code -- README.md
+
       - name: Verify formatting
         run: test -z "$(gofmt -l .)"
 

.gitignore

@@ -0,0 +1,2 @@
+.vscode/
+caphcli

README.md

@@ -0,0 +1,86 @@
+# caphcli
+
+`caphcli` is a standalone CLI for CAPH bare-metal provisioning checks.
+
+It currently exposes the `check-bm-servers` command that was extracted from CAPH PR `#1873` and moved into this repository.
+
+## Build
+
+```bash
+go build .
+```
+
+## Required Environment Variables
+
+- `HETZNER_ROBOT_USER` and `HETZNER_ROBOT_PASSWORD` for Hetzner Robot API access.
+- `SSH_KEY_NAME` for the Robot SSH key name to use or create.
+- One of `HETZNER_SSH_PUB_PATH` or `HETZNER_SSH_PUB` for the SSH public key.
+- One of `HETZNER_SSH_PRIV_PATH` or `HETZNER_SSH_PRIV` for the SSH private key.
+
+## Keeping This README Up To Date
+
+The official Cobra helper for generated command docs is `github.com/spf13/cobra/doc`.  
+This repo keeps the help blocks below in sync with the actual command tree via:
+
+```bash
+go generate ./...
+```
+
+That runs `go run ./internal/tools/readmegen`, which rebuilds this README from the live Cobra commands.
+
+## CLI Help
+
+### `caphcli --help`
+
+```text
+CAPH developer and operations CLI
+
+Usage:
+  caphcli [command]
+
+Available Commands:
+  check-bm-servers Validate rescue and provisioning reliability for one bare-metal server
+  completion       Generate the autocompletion script for the specified shell
+  help             Help about any command
+
+Flags:
+  -h, --help   help for caphcli
+
+Use "caphcli [command] --help" for more information about a command.
+```
+
+### `caphcli check-bm-servers --help`
+
+```text
+Validate rescue and provisioning reliability for one HetznerBareMetalHost from a local YAML file.
+
+The command does not talk to Kubernetes. It reads one local YAML file containing
+HetznerBareMetalHost objects and then talks directly to Hetzner Robot plus the
+target server.
+
+Usage:
+  caphcli check-bm-servers [flags]
+
+Examples:
+  caphcli check-bm-servers \
+    --file test/e2e/data/infrastructure-hetzner/v1beta1/bases/hetznerbaremetalhosts.yaml \
+    --name bm-e2e-1731561
+
+Flags:
+      --file string                          Path to a local YAML file containing HetznerBareMetalHost objects (required)
+      --force                                Skip the destructive-action confirmation prompt
+  -h, --help                                 help for check-bm-servers
+      --image-path string                    Installimage IMAGE path for operating system inside the Hetzner rescue system (default "/root/.oldroot/nfs/images/Ubuntu-2404-noble-amd64-base.tar.gz")
+      --name string                          HetznerBareMetalHost metadata.name. Optional if YAML contains exactly one host
+      --poll-interval duration               Polling interval for wait steps (default 10s)
+      --timeout-activate-rescue duration     Timeout for activating rescue boot (default 45s)
+      --timeout-check-disk-rescue duration   Timeout for checking target disks in rescue (default 1m0s)
+      --timeout-ensure-ssh-key duration      Timeout for ensuring SSH key in Robot (default 1m0s)
+      --timeout-fetch-server duration        Timeout for fetching server details from Robot (default 30s)
+      --timeout-install duration             Timeout for one Ubuntu install step (default 9m0s)
+      --timeout-load-input duration          Timeout for input parsing + env loading (default 30s)
+      --timeout-reboot-os duration           Timeout for rebooting into installed OS (default 45s)
+      --timeout-reboot-rescue duration       Timeout for requesting reboot to rescue (default 45s)
+      --timeout-wait-os duration             Timeout for waiting until installed OS is reachable (default 6m0s)
+      --timeout-wait-rescue duration         Timeout for waiting until rescue SSH is reachable (default 6m0s)
+```

generate.go

@@ -0,0 +1,3 @@
+package main
+
+//go:generate go run ./internal/tools/readmegen

internal/cmd/root.go

@@ -13,10 +13,11 @@ func NewRootCommand() *cobra.Command {
 	data.RegisterEmbeddedInstallImageTGZ()
 
 	rootCmd := &cobra.Command{
-		Use:           "caphcli",
-		Short:         "CAPH developer and operations CLI",
-		SilenceUsage:  true,
-		SilenceErrors: false,
+		Use:               "caphcli",
+		Short:             "CAPH developer and operations CLI",
+		DisableAutoGenTag: true,
+		SilenceUsage:      true,
+		SilenceErrors:     false,
 	}
 
 	rootCmd.AddCommand(newCheckBMServersCommand())

internal/tools/readmegen/main.go

@@ -0,0 +1,93 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"strings"
+
+	caphcmd "github.com/syself/caphcli/internal/cmd"
+)
+
+const readmeTemplate = `# caphcli
+
+` + "`caphcli`" + ` is a standalone CLI for CAPH bare-metal provisioning checks.
+
+It currently exposes the ` + "`check-bm-servers`" + ` command that was extracted from CAPH PR ` + "`#1873`" + ` and moved into this repository.
+
+## Build
+
+` + "```bash" + `
+go build .
+` + "```" + `
+
+## Required Environment Variables
+
+- ` + "`HETZNER_ROBOT_USER`" + ` and ` + "`HETZNER_ROBOT_PASSWORD`" + ` for Hetzner Robot API access.
+- ` + "`SSH_KEY_NAME`" + ` for the Robot SSH key name to use or create.
+- One of ` + "`HETZNER_SSH_PUB_PATH`" + ` or ` + "`HETZNER_SSH_PUB`" + ` for the SSH public key.
+- One of ` + "`HETZNER_SSH_PRIV_PATH`" + ` or ` + "`HETZNER_SSH_PRIV`" + ` for the SSH private key.
+
+## Keeping This README Up To Date
+
+The official Cobra helper for generated command docs is ` + "`github.com/spf13/cobra/doc`" + `.  
+This repo keeps the help blocks below in sync with the actual command tree via:
+
+` + "```bash" + `
+go generate ./...
+` + "```" + `
+
+That runs ` + "`go run ./internal/tools/readmegen`" + `, which rebuilds this README from the live Cobra commands.
+
+## CLI Help
+
+### ` + "`caphcli --help`" + `
+
+` + "```text" + `
+{{ROOT_HELP}}
+` + "```" + `
+
+### ` + "`caphcli check-bm-servers --help`" + `
+
+` + "```text" + `
+{{CHECK_HELP}}
+` + "```" + `
+`
+
+func main() {
+	rootHelp, err := renderHelp()
+	if err != nil {
+		fail(err)
+	}
+
+	checkHelp, err := renderHelp("check-bm-servers")
+	if err != nil {
+		fail(err)
+	}
+
+	readme := strings.ReplaceAll(readmeTemplate, "{{ROOT_HELP}}", strings.TrimSpace(rootHelp))
+	readme = strings.ReplaceAll(readme, "{{CHECK_HELP}}", strings.TrimSpace(checkHelp))
+
+	if err := os.WriteFile("README.md", []byte(readme), 0o644); err != nil {
+		fail(fmt.Errorf("write README.md: %w", err))
+	}
+}
+
+func renderHelp(args ...string) (string, error) {
+	rootCmd := caphcmd.NewRootCommand()
+	buf := &bytes.Buffer{}
+	rootCmd.SetOut(buf)
+	rootCmd.SetErr(buf)
+	rootCmd.SetArgs(append(args, "--help"))
+
+	if err := rootCmd.Execute(); err != nil {
+		return "", fmt.Errorf("render help for %q: %w", strings.Join(args, " "), err)
+	}
+
+	return buf.String(), nil
+}
+
+func fail(err error) {
+	_, _ = fmt.Fprintf(os.Stderr, "readmegen: %v\n", err)
+	os.Exit(1)
+}