From ed6f22fd530fe9a051655b8ac8bdb1877d5aafb6 Mon Sep 17 00:00:00 2001 From: Viktor Barzin Date: Thu, 18 Jun 2026 19:12:57 +0000 Subject: [PATCH] homelab: scaffold unified CLI (registry, manifest, claim/release) in infra/cli MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Begin evolving the existing infra/cli into the agent-facing "homelab" CLI decided in the design/grilling session: one composable, JSON-capable surface for the operations agents run over and over (mined from 51k commands across 2,225 past sessions; the infra inner-loop is ~29% of them). v0.1 targets that loop — work/tf/claim — and ships here, in place, in infra/cli. This first slice: - command registry + dispatcher (longest-prefix verb matching) and a `manifest`/`manifest --json` progressive-discovery entrypoint; every verb declares a read|write tier so write-gating can be added later (everything is allowed for now). - claim/release verbs wrapping the existing presence script (not reimplemented), with label-taxonomy validation. - main() front-dispatches the homelab verb surface but falls through to the legacy webhook -use-case path verbatim, so the in-cluster infra-cli image is unaffected. - fix a pre-existing vet error (glog.Infof missing format directive) that blocked `go test`. Co-Authored-By: Claude Opus 4.8 --- cli/cmd_claim.go | 56 +++++++++++++++++++ cli/command.go | 101 ++++++++++++++++++++++++++++++++++ cli/command_test.go | 73 ++++++++++++++++++++++++ cli/homelab.go | 86 +++++++++++++++++++++++++++++ cli/main.go | 12 +++- cli/presence.go | 58 +++++++++++++++++++ cli/presence_test.go | 24 ++++++++ cli/run.go | 17 ++++++ cli/update_viktorbarzin_me.go | 2 +- 9 files changed, 426 insertions(+), 3 deletions(-) create mode 100644 cli/cmd_claim.go create mode 100644 cli/command.go create mode 100644 cli/command_test.go create mode 100644 cli/homelab.go create mode 100644 cli/presence.go create mode 100644 cli/presence_test.go create mode 100644 cli/run.go diff --git a/cli/cmd_claim.go b/cli/cmd_claim.go new file mode 100644 index 00000000..e11a37db --- /dev/null +++ b/cli/cmd_claim.go @@ -0,0 +1,56 @@ +package main + +import ( + "fmt" + "strings" +) + +func claimCommands() []Command { + return []Command{ + {Path: []string{"claim"}, Tier: TierWrite, + Summary: "claim a shared infra resource on the presence board", + Run: runClaim}, + {Path: []string{"release"}, Tier: TierWrite, + Summary: "release a presence claim", + Run: runRelease}, + } +} + +// runClaim parses `: --purpose "..."` in either order (the presence +// script takes the label first, so we can't rely on Go's flag package which +// stops at the first positional). +func runClaim(args []string) error { + var label, purpose string + for i := 0; i < len(args); i++ { + a := args[i] + switch { + case a == "--purpose" || a == "-purpose": + if i+1 < len(args) { + purpose = args[i+1] + i++ + } + case strings.HasPrefix(a, "--purpose="): + purpose = strings.TrimPrefix(a, "--purpose=") + case !strings.HasPrefix(a, "-") && label == "": + label = a + } + } + if label == "" { + return fmt.Errorf(`usage: homelab claim : --purpose "what + why"`) + } + return presenceClaim(label, purpose) +} + +func runRelease(args []string) error { + var label string + for _, a := range args { + if !strings.HasPrefix(a, "-") { + label = a + break + } + } + if label == "" { + return fmt.Errorf("usage: homelab release :") + } + return presenceRelease(label) +} diff --git a/cli/command.go b/cli/command.go new file mode 100644 index 00000000..fd7f4812 --- /dev/null +++ b/cli/command.go @@ -0,0 +1,101 @@ +package main + +import ( + "encoding/json" + "fmt" + "sort" + "strings" +) + +// Tier classifies whether a command observes (read) or mutates (write) state. +// v0.1 allows everything; the tier is recorded so a classifier hook can gate +// writes later without restructuring (see docs/adr/0005). +type Tier string + +const ( + TierRead Tier = "read" + TierWrite Tier = "write" +) + +// Command is one homelab verb. Path is the token sequence that selects it, +// e.g. ["claim"] or ["tf", "plan"]. Run receives the args after the path. +type Command struct { + Path []string + Tier Tier + Summary string + Run func(args []string) error +} + +// dispatch routes args to the command whose Path is the longest matching prefix +// of args, passing the remaining args to its Run. +func dispatch(reg []Command, args []string) error { + best := -1 + bestLen := 0 + for i, c := range reg { + if len(c.Path) > len(args) { + continue + } + match := true + for j, p := range c.Path { + if args[j] != p { + match = false + break + } + } + if match && len(c.Path) >= bestLen { + best = i + bestLen = len(c.Path) + } + } + if best < 0 { + return fmt.Errorf("unknown command: %q", strings.Join(args, " ")) + } + return reg[best].Run(args[bestLen:]) +} + +// name is the space-joined verb path, e.g. "tf plan". +func (c Command) name() string { return strings.Join(c.Path, " ") } + +// sortedByName returns a copy of reg ordered by verb path for stable output. +func sortedByName(reg []Command) []Command { + out := make([]Command, len(reg)) + copy(out, reg) + sort.Slice(out, func(i, j int) bool { return out[i].name() < out[j].name() }) + return out +} + +// manifestText renders one aligned line per command: " ". +// This is the cheap progressive-discovery entrypoint (see docs/adr/0004). +func manifestText(reg []Command) string { + cmds := sortedByName(reg) + width := 0 + for _, c := range cmds { + if n := len(c.name()); n > width { + width = n + } + } + var b strings.Builder + for _, c := range cmds { + fmt.Fprintf(&b, "%-*s %-5s %s\n", width, c.name(), c.Tier, c.Summary) + } + return b.String() +} + +// manifestJSON renders the registry as a JSON array of {command, tier, summary} +// so agents can parse the full surface in one call. +func manifestJSON(reg []Command) (string, error) { + type entry struct { + Command string `json:"command"` + Tier string `json:"tier"` + Summary string `json:"summary"` + } + entries := make([]entry, 0, len(reg)) + for _, c := range sortedByName(reg) { + entries = append(entries, entry{Command: c.name(), Tier: string(c.Tier), Summary: c.Summary}) + } + b, err := json.MarshalIndent(entries, "", " ") + if err != nil { + return "", err + } + return string(b), nil +} diff --git a/cli/command_test.go b/cli/command_test.go new file mode 100644 index 00000000..e686622d --- /dev/null +++ b/cli/command_test.go @@ -0,0 +1,73 @@ +package main + +import ( + "encoding/json" + "reflect" + "strings" + "testing" +) + +// Tracer bullet: the dispatcher must route `homelab ` to the +// command whose Path is the longest matching prefix of the input tokens, and +// hand the command the remaining args. +func TestDispatchRoutesToLongestPrefixMatch(t *testing.T) { + var gotArgs []string + ran := "" + reg := []Command{ + {Path: []string{"claim"}, Tier: TierWrite, Summary: "claim a resource", + Run: func(a []string) error { ran = "claim"; gotArgs = a; return nil }}, + {Path: []string{"tf", "plan"}, Tier: TierRead, Summary: "plan a stack", + Run: func(a []string) error { ran = "tf plan"; gotArgs = a; return nil }}, + } + + if err := dispatch(reg, []string{"tf", "plan", "vault", "--json"}); err != nil { + t.Fatalf("dispatch returned error: %v", err) + } + if ran != "tf plan" { + t.Fatalf("routed to %q, want %q", ran, "tf plan") + } + if want := []string{"vault", "--json"}; !reflect.DeepEqual(gotArgs, want) { + t.Fatalf("command got args %v, want %v", gotArgs, want) + } +} + +func TestDispatchUnknownCommandErrors(t *testing.T) { + reg := []Command{{Path: []string{"claim"}, Run: func(a []string) error { return nil }}} + if err := dispatch(reg, []string{"bogus"}); err == nil { + t.Fatal("expected error for unknown command, got nil") + } +} + +// The manifest is the progressive-discovery entrypoint: one line per command +// showing the full verb path, its tier, and summary, sorted for stable output. +func TestManifestTextListsEveryCommandWithTier(t *testing.T) { + reg := []Command{ + {Path: []string{"tf", "plan"}, Tier: TierRead, Summary: "plan a stack"}, + {Path: []string{"claim"}, Tier: TierWrite, Summary: "claim a resource"}, + } + out := manifestText(reg) + for _, want := range []string{"claim", "tf plan", "read", "write", "plan a stack", "claim a resource"} { + if !strings.Contains(out, want) { + t.Errorf("manifest text missing %q\n---\n%s", want, out) + } + } + // sorted: claim (c) must appear before tf plan (t) + if strings.Index(out, "claim") > strings.Index(out, "tf plan") { + t.Errorf("manifest not sorted by path:\n%s", out) + } +} + +func TestManifestJSONIsParsableAndTagged(t *testing.T) { + reg := []Command{{Path: []string{"tf", "apply"}, Tier: TierWrite, Summary: "apply a stack"}} + out, err := manifestJSON(reg) + if err != nil { + t.Fatalf("manifestJSON error: %v", err) + } + var got []map[string]string + if err := json.Unmarshal([]byte(out), &got); err != nil { + t.Fatalf("manifest JSON not parsable: %v\n%s", err, out) + } + if len(got) != 1 || got[0]["command"] != "tf apply" || got[0]["tier"] != "write" { + t.Fatalf("unexpected manifest JSON: %v", got) + } +} diff --git a/cli/homelab.go b/cli/homelab.go new file mode 100644 index 00000000..6738c37e --- /dev/null +++ b/cli/homelab.go @@ -0,0 +1,86 @@ +package main + +import ( + "fmt" + "strings" +) + +// version is stamped at build time via -ldflags "-X main.version=vX.Y.Z". +var version = "dev" + +// buildRegistry returns every homelab verb. New verb-groups append here. +func buildRegistry() []Command { + var reg []Command + reg = append(reg, claimCommands()...) + return reg +} + +// dispatchTop handles the homelab verb surface. handled=false means the args are +// not a homelab verb, so main() falls back to the legacy -use-case path. +func dispatchTop(args []string) (handled bool, err error) { + if len(args) == 0 { + fmt.Print(usage()) + return true, nil + } + switch args[0] { + case "help", "-h", "--help": + fmt.Print(usage()) + return true, nil + case "version", "--version": + fmt.Println("homelab " + version) + return true, nil + case "manifest": + reg := buildRegistry() + if containsArg(args[1:], "--json") { + out, err := manifestJSON(reg) + if err != nil { + return true, err + } + fmt.Println(out) + return true, nil + } + fmt.Print(manifestText(reg)) + return true, nil + } + if strings.HasPrefix(args[0], "-") { + return false, nil + } + reg := buildRegistry() + if !isCommandGroup(reg, args[0]) { + return false, nil + } + return true, dispatch(reg, args) +} + +func isCommandGroup(reg []Command, group string) bool { + for _, c := range reg { + if len(c.Path) > 0 && c.Path[0] == group { + return true + } + } + return false +} + +func containsArg(args []string, want string) bool { + for _, a := range args { + if a == want { + return true + } + } + return false +} + +func usage() string { + var b strings.Builder + fmt.Fprintf(&b, "homelab %s — unified homelab operations CLI\n\n", version) + b.WriteString("Usage:\n homelab [args]\n\nCommands:\n") + for _, line := range strings.Split(strings.TrimRight(manifestText(buildRegistry()), "\n"), "\n") { + if line != "" { + b.WriteString(" " + line + "\n") + } + } + b.WriteString("\n manifest [--json] list all commands (machine-readable with --json)\n") + b.WriteString(" version print version\n") + b.WriteString("\nLegacy webhook use-cases remain available via -use-case=.\n") + return b.String() +} diff --git a/cli/main.go b/cli/main.go index 3b9fee1c..a53f7672 100644 --- a/cli/main.go +++ b/cli/main.go @@ -26,8 +26,16 @@ var ( ) func main() { - err := run() - if err != nil { + // homelab verb surface (work/tf/claim/...) is tried first; if the args are + // not a homelab verb, fall through to the legacy webhook -use-case path. + if handled, err := dispatchTop(os.Args[1:]); handled { + if err != nil { + fmt.Fprintln(os.Stderr, "homelab: "+err.Error()) + os.Exit(1) + } + return + } + if err := run(); err != nil { glog.Errorf("run failed: %s", err.Error()) os.Exit(255) } diff --git a/cli/presence.go b/cli/presence.go new file mode 100644 index 00000000..bcf054d7 --- /dev/null +++ b/cli/presence.go @@ -0,0 +1,58 @@ +package main + +import ( + "fmt" + "os" + "path/filepath" + "strings" +) + +// validPresenceKinds is the fixed label taxonomy accepted by the presence board. +var validPresenceKinds = []string{"node", "host", "stack", "service", "db", "pvc", "infra"} + +// presenceScript locates the presence CLI — homelab WRAPS it, it does not +// reimplement it. Override with HOMELAB_PRESENCE; defaults to ~/code/scripts/presence. +func presenceScript() string { + if p := os.Getenv("HOMELAB_PRESENCE"); p != "" { + return p + } + home, err := os.UserHomeDir() + if err != nil { + return "presence" + } + return filepath.Join(home, "code", "scripts", "presence") +} + +// validateLabel checks a presence label is : with a known kind. +func validateLabel(label string) error { + parts := strings.SplitN(label, ":", 2) + if len(parts) != 2 || parts[0] == "" || parts[1] == "" { + return fmt.Errorf("label must be : (e.g. stack:vault), got %q", label) + } + for _, k := range validPresenceKinds { + if parts[0] == k { + return nil + } + } + return fmt.Errorf("invalid label kind %q; valid kinds: %s", parts[0], strings.Join(validPresenceKinds, ", ")) +} + +// presenceClaim claims label on the board with a purpose note. +func presenceClaim(label, purpose string) error { + if err := validateLabel(label); err != nil { + return err + } + args := []string{"claim", label} + if purpose != "" { + args = append(args, "--purpose", purpose) + } + return runStreaming(presenceScript(), args...) +} + +// presenceRelease releases a prior claim on label. +func presenceRelease(label string) error { + if err := validateLabel(label); err != nil { + return err + } + return runStreaming(presenceScript(), "release", label) +} diff --git a/cli/presence_test.go b/cli/presence_test.go new file mode 100644 index 00000000..3d1596e1 --- /dev/null +++ b/cli/presence_test.go @@ -0,0 +1,24 @@ +package main + +import "testing" + +func TestValidateLabelAcceptsTaxonomy(t *testing.T) { + good := []string{ + "stack:vault", "service:health", "node:k8s-node1", "db:pg-cluster", + "infra:gpu-operator", "host:proxmox-1", "pvc:dbaas/data", + } + for _, l := range good { + if err := validateLabel(l); err != nil { + t.Errorf("validateLabel(%q) = %v, want nil", l, err) + } + } +} + +func TestValidateLabelRejectsBadLabels(t *testing.T) { + bad := []string{"vault", "stack:", "bogus:x", ":x", "stack", ""} + for _, l := range bad { + if err := validateLabel(l); err == nil { + t.Errorf("validateLabel(%q) = nil, want error", l) + } + } +} diff --git a/cli/run.go b/cli/run.go new file mode 100644 index 00000000..0cbe24f1 --- /dev/null +++ b/cli/run.go @@ -0,0 +1,17 @@ +package main + +import ( + "os" + "os/exec" +) + +// runStreaming executes name with args, wiring std streams to this process so +// the caller sees live output, and returns the command's error (non-nil on +// non-zero exit — preserved so homelab's own exit code reflects the child's). +func runStreaming(name string, args ...string) error { + cmd := exec.Command(name, args...) + cmd.Stdout = os.Stdout + cmd.Stderr = os.Stderr + cmd.Stdin = os.Stdin + return cmd.Run() +} diff --git a/cli/update_viktorbarzin_me.go b/cli/update_viktorbarzin_me.go index 1a693a25..c2c1d3f4 100644 --- a/cli/update_viktorbarzin_me.go +++ b/cli/update_viktorbarzin_me.go @@ -103,6 +103,6 @@ func notifyForIPChange(oldIP, newIP net.IP) error { if err != nil { return errors.Wrapf(err, "Error reading response") } - glog.Infof("Response:", string(responseBody)) + glog.Infof("Response: %s", string(responseBody)) return nil }